File blowfish.h

Blowfish block cipher.

Defines

MBEDTLS_BLOWFISH_ENCRYPT
MBEDTLS_BLOWFISH_DECRYPT
MBEDTLS_BLOWFISH_MAX_KEY_BITS
MBEDTLS_BLOWFISH_MIN_KEY_BITS
MBEDTLS_BLOWFISH_ROUNDS

Rounds to use. When increasing this value, make sure to extend the initialisation vectors

MBEDTLS_BLOWFISH_BLOCKSIZE
MBEDTLS_ERR_BLOWFISH_BAD_INPUT_DATA

Bad input data.

MBEDTLS_ERR_BLOWFISH_INVALID_INPUT_LENGTH

Invalid data input length.

MBEDTLS_ERR_BLOWFISH_HW_ACCEL_FAILED

Blowfish hardware accelerator failed.

Functions

void mbedtls_blowfish_init(mbedtls_blowfish_context *ctx)

Initialize a Blowfish context.

Parameters

ctx – The Blowfish context to be initialized. This must not be NULL.

void mbedtls_blowfish_free(mbedtls_blowfish_context *ctx)

Clear a Blowfish context.

Parameters

ctx – The Blowfish context to be cleared. This may be NULL, in which case this function returns immediately. If it is not NULL, it must point to an initialized Blowfish context.

int mbedtls_blowfish_setkey(mbedtls_blowfish_context *ctx, const unsigned char *key, unsigned int keybits)

Perform a Blowfish key schedule operation.

Parameters

  • ctx – The Blowfish context to perform the key schedule on.

  • key – The encryption key. This must be a readable buffer of length keybits Bits.

  • keybits – The length of key in Bits. This must be between 32 and 448 and a multiple of 8.

Returns

0 if successful.

Returns

A negative error code on failure.

int mbedtls_blowfish_crypt_ecb(mbedtls_blowfish_context *ctx, int mode, const unsigned char input[MBEDTLS_BLOWFISH_BLOCKSIZE], unsigned char output[MBEDTLS_BLOWFISH_BLOCKSIZE])

Perform a Blowfish-ECB block encryption/decryption operation.

Parameters

  • ctx – The Blowfish context to use. This must be initialized and bound to a key.

  • mode – The mode of operation. Possible values are MBEDTLS_BLOWFISH_ENCRYPT for encryption, or MBEDTLS_BLOWFISH_DECRYPT for decryption.

  • input – The input block. This must be a readable buffer of size 8 Bytes.

  • output – The output block. This must be a writable buffer of size 8 Bytes.

Returns

0 if successful.

Returns

A negative error code on failure.

int mbedtls_blowfish_crypt_cbc(mbedtls_blowfish_context *ctx, int mode, size_t length, unsigned char iv[MBEDTLS_BLOWFISH_BLOCKSIZE], const unsigned char *input, unsigned char *output)

Perform a Blowfish-CBC buffer encryption/decryption operation.

Note

Upon exit, the content of the IV is updated so that you can call the function same function again on the following block(s) of data and get the same result as if it was encrypted in one call. This allows a “streaming” usage. If on the other hand you need to retain the contents of the IV, you should either save it manually or use the cipher module instead.

Parameters

  • ctx – The Blowfish context to use. This must be initialized and bound to a key.

  • mode – The mode of operation. Possible values are MBEDTLS_BLOWFISH_ENCRYPT for encryption, or MBEDTLS_BLOWFISH_DECRYPT for decryption.

  • length – The length of the input data in Bytes. This must be multiple of 8.

  • iv – The initialization vector. This must be a read/write buffer of length 8 Bytes. It is updated by this function.

  • input – The input data. This must be a readable buffer of length length Bytes.

  • output – The output data. This must be a writable buffer of length length Bytes.

Returns

0 if successful.

Returns

A negative error code on failure.

int mbedtls_blowfish_crypt_cfb64(mbedtls_blowfish_context *ctx, int mode, size_t length, size_t *iv_off, unsigned char iv[MBEDTLS_BLOWFISH_BLOCKSIZE], const unsigned char *input, unsigned char *output)

Perform a Blowfish CFB buffer encryption/decryption operation.

Note

Upon exit, the content of the IV is updated so that you can call the function same function again on the following block(s) of data and get the same result as if it was encrypted in one call. This allows a “streaming” usage. If on the other hand you need to retain the contents of the IV, you should either save it manually or use the cipher module instead.

Parameters

  • ctx – The Blowfish context to use. This must be initialized and bound to a key.

  • mode – The mode of operation. Possible values are MBEDTLS_BLOWFISH_ENCRYPT for encryption, or MBEDTLS_BLOWFISH_DECRYPT for decryption.

  • length – The length of the input data in Bytes.

  • iv_off – The offset in the initialization vector. The value pointed to must be smaller than 8 Bytes. It is updated by this function to support the aforementioned streaming usage.

  • iv – The initialization vector. This must be a read/write buffer of size 8 Bytes. It is updated after use.

  • input – The input data. This must be a readable buffer of length length Bytes.

  • output – The output data. This must be a writable buffer of length length Bytes.

Returns

0 if successful.

Returns

A negative error code on failure.

int mbedtls_blowfish_crypt_ctr(mbedtls_blowfish_context *ctx, size_t length, size_t *nc_off, unsigned char nonce_counter[MBEDTLS_BLOWFISH_BLOCKSIZE], unsigned char stream_block[MBEDTLS_BLOWFISH_BLOCKSIZE], const unsigned char *input, unsigned char *output)

Perform a Blowfish-CTR buffer encryption/decryption operation.

There are two common strategies for managing nonces with CTR:

  1. You can handle everything as a single message processed over successive calls to this function. In that case, you want to set nonce_counter and nc_off to 0 for the first call, and then preserve the values of nonce_counter, nc_off and stream_block across calls to this function as they will be updated by this function.

With this strategy, you must not encrypt more than 2**64 blocks of data with the same key.

  1. You can encrypt separate messages by dividing the nonce_counter buffer in two areas: the first one used for a per-message nonce, handled by yourself, and the second one updated by this function internally.

For example, you might reserve the first 4 bytes for the per-message nonce, and the last 4 bytes for internal use. In that case, before calling this function on a new message you need to set the first 4 bytes of nonce_counter to your chosen nonce value, the last 4 to 0, and nc_off to 0 (which will cause stream_block to be ignored). That way, you can encrypt at most 2**32 messages of up to 2**32 blocks each with the same key.

The per-message nonce (or information sufficient to reconstruct it) needs to be communicated with the ciphertext and must be unique. The recommended way to ensure uniqueness is to use a message counter.

Note that for both strategies, sizes are measured in blocks and that a Blowfish block is 8 bytes.

Warning

You must never reuse a nonce value with the same key. Doing so would void the encryption for the two messages encrypted with the same nonce and key.

Warning

Upon return, stream_block contains sensitive data. Its content must not be written to insecure storage and should be securely discarded as soon as it’s no longer needed.

Parameters

  • ctx – The Blowfish context to use. This must be initialized and bound to a key.

  • length – The length of the input data in Bytes.

  • nc_off – The offset in the current stream_block (for resuming within current cipher stream). The offset pointer should be 0 at the start of a stream and must be smaller than 8. It is updated by this function.

  • nonce_counter – The 64-bit nonce and counter. This must point to a read/write buffer of length 8 Bytes.

  • stream_block – The saved stream-block for resuming. This must point to a read/write buffer of length 8 Bytes.

  • input – The input data. This must be a readable buffer of length length Bytes.

  • output – The output data. This must be a writable buffer of length length Bytes.

Returns

0 if successful.

Returns

A negative error code on failure.