# Welcome to Cifra’s documentation!

Contents:

## Library configuration

### Macros

`CF_SIDE_CHANNEL_PROTECTION`

  Define this as 1 if you need all available side channel protections. This option may alter the ABI.

  This has a non-trivial performance penalty. Where a side-channel free option is cheap or free (like checking a MAC) this is always done in a side-channel free way.

  The default is on for all available protections.

`CF_TIME_SIDE_CHANNEL_PROTECTION`

  Define this as 1 if you need timing/branch prediction side channel protection.

  You probably want this. The default is on.

`CF_CACHE_SIDE_CHANNEL_PROTECTION`

  Define this as 1 if you need cache side channel protection.

  If you have a microcontroller with no cache, you can turn this off without negative effects.

  The default is on. This will have some performance impact, especially on AES.

## General block cipher description

This allows us to implement block cipher modes which can work with different block ciphers.

### Macros

`CF_MAXBLOCK`

  The maximum block cipher blocksize we support, in bytes.

### Types

`cf_prp_block`

  Block processing function type.

  The in and out blocks may alias.

  Return type: | void
  Parameters: | ctx – block cipher-specific context object. in – input block. out – output block.

`cf_prp`

  Describes an PRP in a general way.

  `cf_prp.blocksz`

  Block size in bytes. Must be no more than `CF_MAXBLOCK`.

  `cf_prp.encrypt`

  Block encryption function.

  `cf_prp.decrypt`

  Block decryption function.

## General hash function description

This allows us to make use of hash functions without depending on a specific one. This is useful in implementing, for example, HMAC.

### Macros

`CF_CHASH_MAXCTX`

  The maximum size of a `cf_chash_ctx`. This allows use to put a structure in automatic storage that can store working data for any supported hash function.

`CF_CHASH_MAXBLK`

  Maximum hash function block size (in bytes).

`CF_MAXHASH`

  Maximum hash function output (in bytes).

### Types

`cf_chash_init`

  Hashing initialisation function type.

  Functions of this type should initialise the context in preparation for hashing a message with cf_chash_update functions.

  Return type: | void
  Parameters: | ctx – hash function-specific context structure.

`cf_chash_update`

  Hashing data processing function type.

  Functions of this type hash count bytes of data at data, updating the contents of ctx.

  Return type: | void
  Parameters: | ctx – hash function-specific context structure. data – input data to hash. count – number of bytes to hash.

`cf_chash_digest`

  Hashing completion function type.

  Functions of this type complete a hashing operation, writing `cf_chash.hashsz` bytes to hash.

  This function does not change ctx – any padding which needs doing must be done seperately (in a copy of ctx, say).

  This means you can interlave _update and _digest calls to learn H(A) and H(A || B) without hashing A twice.

  Return type: | void
  Parameters: | ctx – hash function-specific context structure. hash – location to write hash result.

`cf_chash`

  This type describes an incremental hash function in an abstract way.

  `cf_chash.hashsz`

  The hash function’s output, in bytes.

  `cf_chash.blocksz`

  The hash function’s internal block size, in bytes.

  `cf_chash.init`

  Context initialisation function.

  `cf_chash:update`

  Data processing function.

  `cf_chash:digest`

  Completion function.

`cf_chash_ctx`

  A type usable with any cf_chash as a context.

### Functions

void `cf_hash`(const cf_chash *h, const void *m, size_t nm, uint8_t *out)

  One shot hashing: out = h(m).

  Using the hash function h, nm bytes at m are hashed and h->hashsz bytes of result is written to the buffer out.

  Parameters: | h – hash function description. m – message buffer. nm – message length. out – hash result buffer (written).

## The AES block cipher

This is a small, simple implementation of AES. Key expansion is done first, filling in a `cf_aes_context`. Then encryption and decryption can be performed as desired.

Usually you don’t want to use AES directly; you should use it via a block cipher mode.

### Macros

`AES_BLOCKSZ`

  AES has a 128-bit block size. This quantity is in bytes.

`AES128_ROUNDS`

`AES192_ROUNDS`

`AES256_ROUNDS`

  Round counts for different key sizes.

`CF_AES_MAXROUNDS`

  You can reduce the maximum number of rounds this implementation supports. This reduces the storage needed by `cf_aes_context`.

  The default is `AES256_ROUNDS` and is good for all key sizes.

`CF_AES_ENCRYPT_ONLY`

  Define this to 1 if you don’t need to decrypt anything. This saves space. `cf_aes_decrypt()` calls abort(3).

### Types

`cf_aes_context`

  This type represents an expanded AES key. Create one using `cf_aes_init()`, make use of one using `cf_aes_encrypt()` or `cf_aes_decrypt()`.

  The contents of this structure are equivalent to the original key material. You should clean the contents of this structure with `cf_aes_finish()` when you’re done.

  `cf_aes_context.rounds`

  Number of rounds to use, set by `cf_aes_init()`.

  This depends on the original key size, and will be `AES128_ROUNDS`, `AES192_ROUNDS` or `AES256_ROUNDS`.

  `cf_aes_context.ks`

  Expanded key material. Filled in by `cf_aes_init()`.

### Functions

void `cf_aes_init`(cf_aes_context *ctx, const uint8_t *key, size_t nkey)

  This function does AES key expansion. It destroys existing contents of `ctx`.

  Parameters: | ctx – expanded key context, filled in by this function. key – pointer to key material, of `nkey` bytes. nkey – length of key material. Must be 16, 24 or 32.

void `cf_aes_encrypt`(const cf_aes_context *ctx, const uint8_t in[AES_BLOCKSZ], uint8_t out[AES_BLOCKSZ])

  Encrypts the given block, from `in` to `out`. These may alias.

  Fails at runtime if `ctx` is invalid.

  Parameters: | ctx – expanded key context in – input block (read) out – output block (written)

void `cf_aes_decrypt`(const cf_aes_context *ctx, const uint8_t in[AES_BLOCKSZ], uint8_t out[AES_BLOCKSZ])

  Decrypts the given block, from `in` to `out`. These may alias.

  Fails at runtime if `ctx` is invalid.

  Parameters: | ctx – expanded key context in – input block (read) out – output block (written)

void `cf_aes_finish`(cf_aes_context *ctx)

  Erase scheduled key material.

  Call this when you’re done to erase the round keys.

### Values

const cf_prp `cf_aes`

  Abstract interface to AES. See `cf_prp` for more information.

## The NORX AEAD cipher

This is an implementation of NORX32-4-1 with a one-shot interface. NORX is a CAESAR candidate with a core similar to ChaCha20 and a sponge structure like Keccak.

This is NORX v2.0. It is not compatible with earlier versions.

NORX32 uses a 128-bit key. Each encryption requires a 64-bit nonce. An encryption processes one sequence of additional data (‘header’), followed by encryption of the plaintext, followed by processing a second sequence of additional data (‘trailer’). It outputs a 128-bit tag.

### Functions

void `cf_norx32_encrypt`(const uint8_t key[16], const uint8_t nonce[8], const uint8_t *header, size_t nheader, const uint8_t *plaintext, size_t nbytes, const uint8_t *trailer, size_t ntrailer, uint8_t *ciphertext, uint8_t tag[16])

  NORX32-4-1 one-shot encryption interface.

  Parameters: | key – key material. nonce – per-message nonce. header – header buffer. nheader – number of header bytes. plaintext – plaintext bytes to be encrypted. nbytes – number of plaintext/ciphertext bytes. trailer – trailer buffer. ntrailer – number of trailer bytes. ciphertext – ciphertext output buffer, nbytes in length. tag – authentication tag output buffer.

int `cf_norx32_decrypt`(const uint8_t key[16], const uint8_t nonce[8], const uint8_t *header, size_t nheader, const uint8_t *ciphertext, size_t nbytes, const uint8_t *trailer, size_t ntrailer, const uint8_t tag[16], uint8_t *plaintext)

  NORX32-4-1 one-shot decryption interface.

  Returns: | 0 on success, non-zero on error. Plaintext is zeroed on error.
  Parameters: | key – key material. nonce – per-message nonce. header – header buffer. nheader – number of header bytes. ciphertext – ciphertext bytes to be decrypted. nbytes – number of plaintext/ciphertext bytes. trailer – trailer buffer. ntrailer – number of trailer bytes. plaintext – plaintext output buffer, nbytes in length. tag – authentication tag output buffer.

## The Salsa20/Chacha20 stream ciphers

These are similar stream ciphers by djb.

A reduced round variant of Salsa20 (Salsa20/12) was selected as a finalist of the eSTREAM stream cipher competition. This implementation does the full 20 rounds.

ChaCha20 is fundamentally like Salsa20, but has a tweaked round function to improve security margin without damaging performance.

### Types

`cf_salsa20_ctx`

  Incremental interface to Salsa20.

  `cf_salsa20_ctx.key0`

  Half of key material.

  `cf_salsa20_ctx.key1`

  Half of key material.

  `cf_salsa20_ctx.nonce`

  Nonce and counter block.

  `cf_salsa20_ctx.constant`

  Per-key-length constants.

  `cf_salsa20_ctx.block`

  Buffer for unused key stream material.

  `cf_salsa20_ctx.nblock`

  Number of bytes at end of block that can be used as key stream.

`cf_chacha20_ctx`

  Incremental interface to Chacha20. This structure is identical to `cf_salsa20_ctx`.

### Functions

void `cf_salsa20_init`(cf_salsa20_ctx *ctx, const uint8_t *key, size_t nkey, const uint8_t nonce[8])

  Salsa20 initialisation function.

  Parameters: | ctx – salsa20 context. key – key material. nkey – length of key in bytes, either 16 or 32. nonce – per-message nonce.

void `cf_chacha20_init`(cf_chacha20_ctx *ctx, const uint8_t *key, size_t nkey, const uint8_t nonce[8])

  Chacha20 initialisation function.

  Parameters: | ctx – chacha20 context (written). key – key material. nkey – length of key in bytes, either 16 or 32. nonce – per-message nonce.

void `cf_chacha20_init_custom`(cf_chacha20_ctx *ctx, const uint8_t *key, size_t nkey, const uint8_t nonce[16], size_t ncounter)

  Chacha20 initialisation function. This version gives full control over the whole initial nonce value, and the size of the counter. The counter is always at the front of the nonce.

  Parameters: | ctx – chacha20 context (written). key – key material. nkey – length of key in bytes, either 16 or 32. nonce – per-message nonce. ncounter bytes at the start are the block counter. ncounter – length, in bytes, of the counter portion of the nonce.

void `cf_salsa20_cipher`(cf_salsa20_ctx *ctx, const uint8_t *input, uint8_t *output, size_t count)

  Salsa20 encryption/decryption function.

  Parameters: | ctx – salsa20 context. input – input data buffer (read), count bytes long. output – output data buffer (written), count bytes long.

void `cf_chacha20_cipher`(cf_chacha20_ctx *ctx, const uint8_t *input, uint8_t *output, size_t count)

  Chacha20 encryption/decryption function.

  Parameters: | ctx – chacha20 context. input – input data buffer (read), count bytes long. output – output data buffer (written), count bytes long.

## Block cipher modes

### CBC mode

This implementation allows encryption or decryption of whole blocks in CBC mode. It does not offer a byte-wise incremental interface, or do any padding.

This mode provides no useful integrity and should not be used directly.

#### Types

`cf_cbc`

  This structure binds together the things needed to encrypt/decrypt whole blocks in CBC mode.

  `cf_cbc.prp`

  How to encrypt or decrypt blocks. This could be, for example, `cf_aes`.

  `cf_cbc.prpctx`

  Private data for prp functions. For a prp of cf_aes, this would be a pointer to a `cf_aes_context` instance.

  `cf_cbc.block`

  The IV or last ciphertext block.

#### Functions

void `cf_cbc_init`(cf_cbc *ctx, const cf_prp *prp, void *prpctx, const uint8_t iv[CF_MAXBLOCK])

  Initialise CBC encryption/decryption context using selected prp, prp context and IV.

void `cf_cbc_encrypt`(cf_cbc *ctx, const uint8_t *input, uint8_t *output, size_t blocks)

  Encrypt blocks in CBC mode. input and output must point to blocks * ctx->prp->blocksz bytes of storage (and may alias).

void `cf_cbc_decrypt`(cf_cbc *ctx, const uint8_t *input, uint8_t *output, size_t blocks)

  Decrypt blocks in CBC mode. input and output must point to blocks * ctx->prp->blocksz bytes of storage (and may alias).

### Counter mode

This implementation allows incremental encryption/decryption of messages. Encryption and decryption are the same operation.

The counter is always big-endian, but has configurable location and size within the nonce block. The counter wraps, so you should make sure the length of a message with a given nonce doesn’t cause nonce reuse.

This mode provides no integrity and should not be used directly.

#### Types

`cf_ctr`
  `cf_ctr.prp`

  How to encrypt or decrypt blocks. This could be, for example, `cf_aes`.

  `cf_ctr.prpctx`

  Private data for prp functions. For a prp of cf_aes, this would be a pointer to a `cf_aes_context` instance.

  `cf_ctr.nonce`

  The next block to encrypt to get another block of key stream.

  `cf_ctr.keymat`

  The current block of key stream.

  `cf_ctr.nkeymat`

  The number of bytes at the end of `keymat` that are so-far unused. If this is zero, all the bytes are used up and/or of undefined value.

  `cf_ctr.counter_offset`

  The offset (in bytes) of the counter block within the nonce.

  `cf_ctr.counter_width`

  The width (in bytes) of the counter block in the nonce.

#### Functions

void `cf_ctr_init`(cf_ctr *ctx, const cf_prp *prp, void *prpctx, const uint8_t nonce[CF_MAXBLOCK])

  Initialise CTR encryption/decryption context using selected prp and nonce. (nb, this only increments the whole nonce as a big endian block)

void `cf_ctr_custom_counter`(cf_ctr *ctx, size_t offset, size_t width)

  Set the location and width of the nonce counter.

  eg. offset = 12, width = 4 means the counter is mod 2^32 and placed at the end of the nonce.

void `cf_ctr_cipher`(cf_ctr *ctx, const uint8_t *input, uint8_t *output, size_t bytes)

  Encrypt or decrypt bytes in CTR mode. input and output may alias and must point to specified number of bytes.

void `cf_ctr_discard_block`(cf_ctr *ctx)

  Discards the rest of this block of key stream.

### CBC-MAC

This is a incremental interface to computing a CBC-MAC tag over a message.

It optionally pads the message with PKCS#5/PKCS#7 padding – if you don’t do this, messages must be an exact number of blocks long.

You shouldn’t use this directly because it isn’t secure for variable-length messages. Use CMAC instead.

#### Types

`cf_cbcmac_stream`

  Stream interface to CBC-MAC signing.

  `cf_cbcmac.prp`

  How to encrypt or decrypt blocks. This could be, for example, `cf_aes`.

  `cf_cbcmac.prpctx`

  Private data for prp functions. For a prp of cf_aes, this would be a pointer to a `cf_aes_context` instance.

  `cf_cbcmac.cbc`

  CBC data.

  `cf_cbcmac.buffer`

  Buffer for data which can’t be processed until we have a full block.

  `cf_cbcmac.used`

  How many bytes at the front of `buffer` are valid.

#### Functions

void `cf_cbcmac_stream_init`(cf_cbcmac_stream *ctx, const cf_prp *prp, void *prpctx)

  Initialise CBC-MAC signing context using selected prp.

void `cf_cbcmac_stream_reset`(cf_cbcmac_stream *ctx)

  Reset the streaming signing context, to sign a new message.

void `cf_cbcmac_stream_update`(cf_cbcmac_stream *ctx, const uint8_t *data, size_t ndata)

  Process ndata bytes at data.

void `cf_cbcmac_stream_finish_block_zero`(cf_cbcmac_stream *ctx)

  Finish the current block of data by adding zeroes. Does nothing if there are no bytes awaiting processing.

void `cf_cbcmac_stream_nopad_final`(cf_cbcmac_stream *ctx, uint8_t out[CF_MAXBLOCK])

  Output the MAC to ctx->prp->blocksz bytes at out. ctx->used must be zero: the inputed message must be an exact number of blocks.

void `cf_cbcmac_stream_pad_final`(cf_cbcmac_stream *ctx, uint8_t out[CF_MAXBLOCK])

  Output the MAC to ctx->prp->blocksz bytes at out.

  The message is padded with PKCS#5 padding.

### CMAC

This is both a one-shot and incremental interface to computing a CMAC tag over a message.

The one-shot interface separates out the per-key computation, so if you need to compute lots of MACs with one key you don’t pay that cost more than once.

CMAC is a good choice for a symmetric MAC.

#### Types

`cf_cmac`

  One-shot interface to CMAC signing.

  `cf_cmac.prp`

  How to encrypt or decrypt blocks. This could be, for example, `cf_aes`.

  `cf_cmac.prpctx`

  Private data for prp functions. For a prp of cf_aes, this would be a pointer to a `cf_aes_context` instance.

  `cf_cmac.B`

  The XOR offset for the last message block if it is a complete block (also known as K1).

  `cf_cmac.P`

  The XOR offset for the last message block if it is a partial block (also known as K2).

`cf_cmac_stream`

  Stream interface to CMAC signing.

  Input data in arbitrary chunks using `cf_cmac_stream_update()`. The last bit of data must be signalled with the isfinal flag to that function, and the data cannot be zero length unless the whole message is empty.

  `cf_cmac_stream.cmac`

  CMAC one-shot data.

  `cf_cmac_stream.cbc`

  CBC block encryption data.

  `cf_cmac_stream.buffer`

  Buffer for data which can’t be processed until we have a full block.

  `cf_cmac_stream.used`

  How many bytes at the front of `buffer` are valid.

  `cf_cmac_stream.processed`

  How many bytes in total we’ve processed. This is used to correctly process empty messages.

  `cf_cmac_stream.finalised`

  A flag set when the final chunk of the message has been processed. Only when this flag is set can you get the MAC out.

#### Functions

void `cf_cmac_init`(cf_cmac *ctx, const cf_prp *prp, void *prpctx)

  Initialise CMAC signing context using selected prp.

void `cf_cmac_sign`(cf_cmac *ctx, const uint8_t *data, size_t bytes, uint8_t out[CF_MAXBLOCK])

  CMAC sign the given data. The MAC is written to ctx->prp->blocksz bytes at out. This is a one-shot function.

void `cf_cmac_stream_init`(cf_cmac_stream *ctx, const cf_prp *prp, void *prpctx)

  Initialise CMAC streaming signing context using selected prp.

void `cf_cmac_stream_reset`(cf_cmac_stream *ctx)

  Reset the streaming signing context, to sign a new message.

void `cf_cmac_stream_update`(cf_cmac_stream *ctx, const uint8_t *data, size_t ndata, int isfinal)

  Process ndata bytes at data. isfinal is non-zero if this is the last piece of data.

void `cf_cmac_stream_final`(cf_cmac_stream *ctx, uint8_t out[CF_MAXBLOCK])

  Output the MAC to ctx->cmac->prp->blocksz bytes at out. cf_cmac_stream_update with isfinal non-zero must have been called since the last _init/_reset.

### EAX

The EAX authenticated encryption mode. This is a one-shot interface.

EAX is a pretty respectable and fast AEAD mode.

#### Functions

void `cf_eax_encrypt`(const cf_prp *prp, void *prpctx, const uint8_t *plain, size_t nplain, const uint8_t *header, size_t nheader, const uint8_t *nonce, size_t nnonce, uint8_t *cipher, uint8_t *tag, size_t ntag)

  EAX authenticated encryption.

  This function does not fail.

  Parameters: | prp/prpctx – describe the block cipher to use. plain – message plaintext. nplain – length of message. May be zero. header – additionally authenticated data (AAD). nheader – length of AAD. May be zero. nonce – nonce. This must not repeat for a given key. nnonce – length of nonce. The nonce can be any length. cipher – ciphertext output. nplain bytes are written here. tag – authentication tag. ntag bytes are written here. ntag – authentication tag length. This must be non-zero and no greater than prp->blocksz.

int `cf_eax_decrypt`(const cf_prp *prp, void *prpctx, const uint8_t *cipher, size_t ncipher, const uint8_t *header, size_t nheader, const uint8_t *nonce, size_t nnonce, const uint8_t *tag, size_t ntag, uint8_t *plain)

  EAX authenticated decryption.

  Returns: | 0 on success, non-zero on error. Nothing is written to plain on error.
  Parameters: | prp/prpctx – describe the block cipher to use. cipher – message ciphertext. ncipher – message length. header – additionally authenticated data (AAD). nheader – length of AAD. nonce – nonce. nnonce – length of nonce. tag – authentication tag. ntag bytes are read from here. ntag – authentication tag length. plain – plaintext output. ncipher bytes are written here.

### GCM

The GCM (‘Galois counter mode’) authenticated encryption mode. This is a one-shot interface.

GCM is a reasonably respectable AEAD mode. It’s somewhat more complex than EAX, and side channel-free implementations can be quite slow.

#### Functions

void `cf_gcm_encrypt`(const cf_prp *prp, void *prpctx, const uint8_t *plain, size_t nplain, const uint8_t *header, size_t nheader, const uint8_t *nonce, size_t nnonce, uint8_t *cipher, uint8_t *tag, size_t ntag)

  GCM authenticated encryption.

  This function does not fail.

  Parameters: | prp/prpctx – describe the block cipher to use. plain – message plaintext. nplain – length of message. May be zero. header – additionally authenticated data (AAD). nheader – length of AAD. May be zero. nonce – nonce. This must not repeat for a given key. nnonce – length of nonce. The nonce can be any length, but 12 bytes is strongly recommended. cipher – ciphertext output. nplain bytes are written here. tag – authentication tag. ntag bytes are written here. ntag – authentication tag length. This must be non-zero and no greater than prp->blocksz.

  This function does not fail.

int `cf_gcm_decrypt`(const cf_prp *prp, void *prpctx, const uint8_t *cipher, size_t ncipher, const uint8_t *header, size_t nheader, const uint8_t *nonce, size_t nnonce, const uint8_t *tag, size_t ntag, uint8_t *plain)

  GCM authenticated decryption.

  Returns: | 0 on success, non-zero on error. Nothing is written to plain on error.
  Parameters: | prp – describe the block cipher to use. prpctx – describe the block cipher to use. cipher – message ciphertext. ncipher – message length. header – additionally authenticated data (AAD). nheader – length of AAD. nonce – nonce. nnonce – length of nonce. tag – authentication tag. ntag bytes are read from here. ntag – authentication tag length. plain – plaintext output. ncipher bytes are written here.

### CCM

The CCM (‘Counter with CBC-MAC’) authenticated encryption mode. CCM is a widely used AEAD mode (in IPSec, WPA2, Bluetooth, etc.)

It works (at a high level) by just gluing together CTR and CBC-MAC modes (in MAC-then-encrypt mode) and then fixing the problems inherent with CBC-MAC in over-complicated ways.

This is a one-shot interface, which is good because the underlying mechanism isn’t actually online: you need to know the message length before you start, or do everything in two passes.

#### Functions

void `cf_ccm_encrypt`(const cf_prp *prp, void *prpctx, const uint8_t *plain, size_t nplain, size_t L, const uint8_t *header, size_t nheader, const uint8_t *nonce, size_t nnonce, uint8_t *cipher, uint8_t *tag, size_t ntag)

  CCM authenticated encryption.

  This function does not fail.

  Parameters: | prp/prpctx – describe the block cipher to use. plain – message plaintext. nplain – length of message. May be zero. Must meet the constraints placed on it by L. L – length of the message length encoding. This must be in the interval [2,8] and gives a maximum message size of 28L bytes. header – additionally authenticated data (AAD). nheader – length of AAD. May be zero. nonce – nonce. This must not repeat for a given key. nnonce – length of nonce. Must be exactly 15 - L bytes for a 128-bit block cipher. cipher – ciphertext output. nplain bytes are written here. tag – authentication tag. ntag bytes are written here. ntag – authentication tag length. This must be 4, 6, 8, 10, 12, 14 or 16.

int `cf_ccm_decrypt`(const cf_prp *prp, void *prpctx, const uint8_t *cipher, size_t ncipher, size_t L, const uint8_t *header, size_t nheader, const uint8_t *nonce, size_t nnonce, const uint8_t *tag, size_t ntag, uint8_t *plain)

  CCM authenticated decryption.

  Returns: | 0 on success, non-zero on error. Plain is cleared on error.
  Parameters: | prp – describe the block cipher to use. prpctx – describe the block cipher to use. cipher – message ciphertext. ncipher – length of message. L – length of the message length encoding. See `cf_ccm_encrypt()`. header – additionally authenticated data (AAD). nheader – length of AAD. nonce – nonce. nnonce – length of nonce. tag – authentication tag. ntag bytes are read from here. ntag – authentication tag length. This must be 4, 6, 8, 10, 12, 14 or 16. plain – plaintext output. ncipher bytes are written here.

### OCB

OCB is an authenticated encryption mode by Phil Rogaway.

This is version 3, as standardised in RFC7253. It’s defined only for block ciphers with a 128-bit block size.

This is a one-shot interface.

#### Functions

void `cf_ocb_encrypt`(const cf_prp *prp, void *prpctx, const uint8_t *plain, size_t nplain, const uint8_t *header, size_t nheader, const uint8_t *nonce, size_t nnonce, uint8_t *cipher, uint8_t *tag, size_t ntag)

  OCB authenticated encryption.

  This function does not fail.

  Parameters: | prp/prpctx – describe the block cipher to use. plain – message plaintext. nplain – length of message. May be zero. header – additionally authenticated data (AAD). nheader – length of AAD. May be zero. nonce – nonce. This must not repeat for a given key. nnonce – length of nonce. Must be 15 or fewer bytes. cipher – ciphertext output. nplain bytes are written here. tag – authentication tag. ntag bytes are written here. ntag – authentication tag length. Must be 16 or fewer bytes.

int `cf_ocb_decrypt`(const cf_prp *prp, void *prpctx, const uint8_t *cipher, size_t ncipher, const uint8_t *header, size_t nheader, const uint8_t *nonce, size_t nnonce, const uint8_t *tag, size_t ntag, uint8_t *plain)

  OCB authenticated decryption.

  Returns: | 0 on success, non-zero on error. plain is cleared on error.
  Parameters: | prp – describe the block cipher to use. prpctx – describe the block cipher to use. cipher – message ciphertext. ncipher – length of message. header – additionally authenticated data (AAD). nheader – length of AAD. nonce – nonce. nnonce – length of nonce. tag – authentication tag. ntag bytes are read from here. ntag – authentication tag length. plain – plaintext output. ncipher bytes are written here.

## HMAC

This is a one-shot and incremental interface to computing HMAC with any hash function.

(Note: HMAC with SHA3 is possible, but is probably not a sensible thing to want.)

### Types

`cf_hmac_ctx`

  HMAC incremental interface context.

  `cf_hmac_ctx.hash`

  Hash function description.

  `cf_hmac_ctx.inner`

  Inner hash computation.

  `cf_hmac_ctx.outer`

  Outer hash computation.

### Functions

void `cf_hmac_init`(cf_hmac_ctx *ctx, const cf_chash *hash, const uint8_t *key, size_t nkey)

  Set up ctx for computing a HMAC using the given hash and key.

void `cf_hmac_update`(cf_hmac_ctx *ctx, const void *data, size_t ndata)

  Input data.

void `cf_hmac_finish`(cf_hmac_ctx *ctx, uint8_t *out)

  Finish and compute HMAC. ctx->hash->hashsz bytes are written to out.

void `cf_hmac`(const uint8_t *key, size_t nkey, const uint8_t *msg, size_t nmsg, uint8_t *out, const cf_chash *hash)

  One shot interface: compute HMAC_hash(key, msg), writing the answer (which is hash->hashsz long) to out.

  This function does not fail.

## Poly1305

This is an incremental interface to computing the poly1305 single shot MAC.

Note: construct Poly1305-AES with this by taking a 16 byte nonce and encrypting it, and then using the result as an input to this function.

### Types

`cf_poly1305`

  Poly1305 incremental interface context.

  `cf_poly1305.h`

  Current accumulator.

  `cf_poly1305.r`

  Block multiplier.

  `cf_poly1305.s`

  Final XOR offset.

  `cf_poly1305.partial`

  Unprocessed input.

  `cf_poly1305.npartial`

  Number of bytes of unprocessed input.

### Functions

void `cf_poly1305_init`(cf_poly1305 *ctx, const uint8_t r[16], const uint8_t s[16])

  Sets up ctx ready to compute a new MAC.

  In Poly1305-AES, r is the second half of the 32-byte key. s is a nonce encrypted under the first half of the key.

  Parameters: | ctx – context (written) r – MAC key. s – preprocessed nonce.

void `cf_poly1305_update`(cf_poly1305 *ctx, const uint8_t *data, size_t nbytes)

  Processes nbytes at data. Copies the data if there isn’t enough to make a full block.

void `cf_poly1305_finish`(cf_poly1305 *ctx, uint8_t out[16])

  Finishes the operation, writing 16 bytes to out.

  This destroys ctx.

## The ChaCha20-Poly1305 AEAD construction

This is a composition of the ChaCha20 stream cipher and the Poly1305 polynomial MAC to form an AEAD. It’s specified for use in TLS in the form of RFC7539.

It uses a 256-bit key and a 96-bit nonce.

This is a one-shot interface.

### Functions

void `cf_chacha20poly1305_encrypt`(const uint8_t key[32], const uint8_t nonce[12], const uint8_t *header, size_t nheader, const uint8_t *plaintext, size_t nbytes, uint8_t *ciphertext, uint8_t tag[16])

  ChaCha20-Poly1305 authenticated encryption.

  Parameters: | key – key material. nonce – per-message nonce. header – header buffer. nheader – number of header bytes. plaintext – plaintext bytes to be encrypted. nbytes – number of plaintext/ciphertext bytes. ciphertext – ciphertext output buffer, nbytes in length. tag – authentication tag output buffer.

int `cf_chacha20poly1305_decrypt`(const uint8_t key[32], const uint8_t nonce[12], const uint8_t *header, size_t nheader, const uint8_t *ciphertext, size_t nbytes, const uint8_t tag[16], uint8_t *plaintext)

  ChaCha20-Poly1305 authenticated decryption.

  Returns: | 0 on success, non-zero on error. Plaintext is zeroed on error.
  Parameters: | key – key material. nonce – per-message nonce. header – header buffer. nheader – number of header bytes. ciphertext – ciphertext bytes to be decrypted. nbytes – number of plaintext/ciphertext bytes. plaintext – plaintext output buffer, nbytes in length. tag – authentication tag output buffer.

## PBKDF2-HMAC

This is PBKDF2 as described by PKCS#5/RFC2898 with HMAC as the PRF.

### Functions

void `cf_pbkdf2_hmac`(const uint8_t *pw, size_t npw, const uint8_t *salt, size_t nsalt, uint32_t iterations, uint8_t *out, size_t nout, const cf_chash *hash)

  This computes PBKDF2-HMAC with the given hash functon.

  Parameters: | pw – password input buffer. npw – password length. salt – salt input buffer. nsalt – salt length. iterations – non-zero iteration count. Tune this for performance/security tradeoff. out – key material output buffer. nout bytes are written here. nout – key material length. hash – hash function description.

## SHA1

You shouldn’t use this for anything new.

### Macros

`CF_SHA1_HASHSZ`

  The output size of SHA1: 20 bytes.

`CF_SHA1_BLOCKSZ`

  The block size of SHA1: 64 bytes.

### Types

`cf_sha1_context`

  Incremental SHA1 hashing context.

  `cf_sha1_context.H`

  Intermediate values.

  `cf_sha1_context.partial`

  Unprocessed input.

  `cf_sha1_context.npartial`

  Number of bytes of unprocessed input.

  `cf_sha1_context.blocks`

  Number of full blocks processed.

### Functions

void `cf_sha1_init`(cf_sha1_context *ctx)

  Sets up ctx ready to hash a new message.

void `cf_sha1_update`(cf_sha1_context *ctx, const void *data, size_t nbytes)

  Hashes nbytes at data. Copies the data if there isn’t enough to make a full block.

void `cf_sha1_digest`(const cf_sha1_context *ctx, uint8_t hash[CF_SHA1_HASHSZ])

  Finishes the hash operation, writing CF_SHA1_HASHSZ bytes to hash.

  This leaves ctx unchanged.

void `cf_sha1_digest_final`(cf_sha1_context *ctx, uint8_t hash[CF_SHA1_HASHSZ])

  Finishes the hash operation, writing CF_SHA1_HASHSZ bytes to hash.

  This destroys ctx, but uses less stack than `cf_sha1_digest()`.

### Values

`cf_sha1`

  Abstract interface to SHA1. See `cf_chash` for more information.

## SHA224/SHA256

### Macros

`CF_SHA224_HASHSZ`

  The output size of SHA224: 28 bytes.

`CF_SHA224_BLOCKSZ`

  The block size of SHA224: 64 bytes.

`CF_SHA256_HASHSZ`

  The output size of SHA256: 32 bytes.

`CF_SHA256_BLOCKSZ`

  The block size of SHA256: 64 bytes.

### Types

`cf_sha256_context`

  Incremental SHA256 hashing context.

  `cf_sha256_context.H`

  Intermediate values.

  `cf_sha256_context.partial`

  Unprocessed input.

  `cf_sha256_context.npartial`

  Number of bytes of unprocessed input.

  `cf_sha256_context.blocks`

  Number of full blocks processed.

### Functions

void `cf_sha256_init`(cf_sha256_context *ctx)

  Sets up ctx ready to hash a new message.

void `cf_sha256_update`(cf_sha256_context *ctx, const void *data, size_t nbytes)

  Hashes nbytes at data. Copies the data if there isn’t enough to make a full block.

void `cf_sha256_digest`(const cf_sha256_context *ctx, uint8_t hash[CF_SHA256_HASHSZ])

  Finishes the hash operation, writing CF_SHA256_HASHSZ bytes to hash.

  This leaves ctx unchanged.

void `cf_sha256_digest_final`(cf_sha256_context *ctx, uint8_t hash[CF_SHA256_HASHSZ])

  Finishes the hash operation, writing CF_SHA256_HASHSZ bytes to hash.

  This destroys ctx, but uses less stack than `cf_sha256_digest()`.

void `cf_sha224_init`(cf_sha256_context *ctx)

  Sets up ctx ready to hash a new message.

  nb. SHA224 uses SHA256’s underlying types.

void `cf_sha224_update`(cf_sha256_context *ctx, const void *data, size_t nbytes)

  Hashes nbytes at data. Copies the data if there isn’t enough to make a full block.

void `cf_sha224_digest`(const cf_sha256_context *ctx, uint8_t hash[CF_SHA224_HASHSZ])

  Finishes the hash operation, writing CF_SHA224_HASHSZ bytes to hash.

  This leaves ctx unchanged.

void `cf_sha224_digest_final`(cf_sha256_context *ctx, uint8_t hash[CF_SHA224_HASHSZ])

  Finishes the hash operation, writing CF_SHA224_HASHSZ bytes to hash.

  This destroys ctx, but uses less stack than `cf_sha224_digest()`.

### Values

`cf_sha224`

  Abstract interface to SHA224. See `cf_chash` for more information.

`cf_sha256`

  Abstract interface to SHA256. See `cf_chash` for more information.

## SHA384/SHA512

### Macros

`CF_SHA384_HASHSZ`

  The output size of SHA384: 48 bytes.

`CF_SHA384_BLOCKSZ`

  The block size of SHA384: 128 bytes.

`CF_SHA512_HASHSZ`

  The output size of SHA512: 64 bytes.

`CF_SHA512_BLOCKSZ`

  The block size of SHA512: 128 bytes.

### Types

`cf_sha512_context`

  Incremental SHA512 hashing context.

  `cf_sha512_context.H`

  Intermediate values.

  `cf_sha512_context.partial`

  Unprocessed input.

  `cf_sha512_context.npartial`

  Number of bytes of unprocessed input.

  `cf_sha512_context.blocks`

  Number of full blocks processed.

### Functions

void `cf_sha512_init`(cf_sha512_context *ctx)

  Sets up ctx ready to hash a new message.

void `cf_sha512_update`(cf_sha512_context *ctx, const void *data, size_t nbytes)

  Hashes nbytes at data. Copies the data if there isn’t enough to make a full block.

void `cf_sha512_digest`(const cf_sha512_context *ctx, uint8_t hash[CF_SHA512_HASHSZ])

  Finishes the hash operation, writing CF_SHA512_HASHSZ bytes to hash.

  This leaves ctx unchanged.

void `cf_sha512_digest_final`(cf_sha512_context *ctx, uint8_t hash[CF_SHA512_HASHSZ])

  Finishes the hash operation, writing CF_SHA512_HASHSZ bytes to hash.

  This destroys ctx, but uses less stack than `cf_sha512_digest()`.

void `cf_sha384_init`(cf_sha512_context *ctx)

  Sets up ctx ready to hash a new message.

  nb. SHA384 uses SHA512’s underlying types.

void `cf_sha384_update`(cf_sha512_context *ctx, const void *data, size_t nbytes)

  Hashes nbytes at data. Copies the data if there isn’t enough to make a full block.

void `cf_sha384_digest`(const cf_sha512_context *ctx, uint8_t hash[CF_SHA384_HASHSZ])

  Finishes the hash operation, writing CF_SHA384_HASHSZ bytes to hash.

  This leaves ctx unchanged.

void `cf_sha384_digest_final`(cf_sha512_context *ctx, uint8_t hash[CF_SHA384_HASHSZ])

  Finishes the hash operation, writing CF_SHA384_HASHSZ bytes to hash.

  This destroys ctx, but uses less stack than `cf_sha384_digest()`.

### Values

`cf_sha384`

  Abstract interface to SHA384. See `cf_chash` for more information.

`cf_sha512`

  Abstract interface to SHA512. See `cf_chash` for more information.

## SHA3/Keccak

This implementation is compatible with FIPS 202, rather than the original Keccak submission.

### Macros

`CF_SHA3_224_HASHSZ`

  The output size of SHA3-224: 28 bytes.

`CF_SHA3_256_HASHSZ`

  The output size of SHA3-256: 32 bytes.

`CF_SHA3_384_HASHSZ`

  The output size of SHA3-384: 48 bytes.

`CF_SHA3_512_HASHSZ`

  The output size of SHA3-512: 64 bytes.

`CF_SHA3_224_BLOCKSZ`

  The block size of SHA3-224.

`CF_SHA3_256_BLOCKSZ`

  The block size of SHA3-256.

`CF_SHA3_384_BLOCKSZ`

  The block size of SHA3-384.

`CF_SHA3_512_BLOCKSZ`

  The block size of SHA3-512.

### Types

`cf_sha3_context`

  Incremental SHA3 hashing context.

  `cf_sha3_context.A`

  Intermediate state.

  `cf_sha3_context.partial`

  Unprocessed input.

  `cf_sha3_context.npartial`

  Number of bytes of unprocessed input.

  `cf_sha3_context.rate`

  Sponge absorption rate.

  `cf_sha3_context.rate`

  Sponge capacity.

### Functions

void `cf_sha3_224_init`(cf_sha3_context *ctx)

void `cf_sha3_256_init`(cf_sha3_context *ctx)

void `cf_sha3_384_init`(cf_sha3_context *ctx)

void `cf_sha3_512_init`(cf_sha3_context *ctx)

  Sets up ctx ready to hash a new message.

void `cf_sha3_224_update`(cf_sha3_context *ctx, const void *data, size_t nbytes)

void `cf_sha3_256_update`(cf_sha3_context *ctx, const void *data, size_t nbytes)

void `cf_sha3_384_update`(cf_sha3_context *ctx, const void *data, size_t nbytes)

void `cf_sha3_512_update`(cf_sha3_context *ctx, const void *data, size_t nbytes)

  Hashes nbytes at data. Copies the data for processing later if there isn’t enough to make a full block.

void `cf_sha3_224_digest`(const cf_sha3_context *ctx, uint8_t hash[CF_SHA3_224_HASHSZ])

void `cf_sha3_256_digest`(const cf_sha3_context *ctx, uint8_t hash[CF_SHA3_256_HASHSZ])

void `cf_sha3_384_digest`(const cf_sha3_context *ctx, uint8_t hash[CF_SHA3_384_HASHSZ])

void `cf_sha3_512_digest`(const cf_sha3_context *ctx, uint8_t hash[CF_SHA3_512_HASHSZ])

  Finishes the hashing operation, writing result to hash.

  This leaves ctx unchanged.

void `cf_sha3_224_digest_final`(cf_sha3_context *ctx, uint8_t hash[CF_SHA3_224_HASHSZ])

void `cf_sha3_256_digest_final`(cf_sha3_context *ctx, uint8_t hash[CF_SHA3_256_HASHSZ])

void `cf_sha3_384_digest_final`(cf_sha3_context *ctx, uint8_t hash[CF_SHA3_384_HASHSZ])

void `cf_sha3_512_digest_final`(cf_sha3_context *ctx, uint8_t hash[CF_SHA3_512_HASHSZ])

  Finishes the hashing operation, writing result to hash.

  This destroys the contents of ctx.

### Values

`cf_sha3_224`

`cf_sha3_256`

`cf_sha3_384`

`cf_sha3_512`

  Abstract interface to SHA3 functions. See `cf_chash` for more information.

## Hash_DRBG

This is Hash_DRBG from SP800-90A rev 1, with SHA256 as the underlying hash function.

This generator enforces a reseed_interval of 2^32-1: use `cf_hash_drbg_sha256_needs_reseed()` to check whether you need to reseed before use, and reseed using `cf_hash_drbg_sha256_reseed()`. If you try to use the generator when it thinks it needs reseeding, it will call abort.

Internally it enforces a max_number_of_bits_per_request of 2^19 bits. It sorts out chunking up multiple requests for you though, so feel free to ask for more than 2^16 bytes at a time. If you provide additional input when doing that, it is added only once, on the first subrequest.

It does not enforce any max_length or max_personalization_string_length.

### Types

`cf_hash_drbg_sha256`

  Hash_DRBG with SHA256 context.

  `cf_hash_drbg_sha256.V`

  Current internal state.

  `cf_hash_drbg_sha256.C`

  Current update offset.

  `cf_hash_drbg_sha256.reseed_counter`

  Current number of times entropy has been extracted from generator.

### Functions

void `cf_hash_drbg_sha256_init`(cf_hash_drbg_sha256 *ctx, const void *entropy, size_t nentropy, const void *nonce, size_t nnonce, const void *persn, size_t npersn)

  Initialises the generator state ctx, using the provided entropy, nonce and personalisation string persn.

uint32_t `cf_hash_drbg_sha256_needs_reseed`(const cf_hash_drbg_sha256 *ctx)

  Returns non-zero if the generator needs reseeding. If this function returns non-zero, the next `cf_hash_drbg_sha256_gen()` or `cf_hash_drbg_sha256_gen_additional()` call will call abort.

void `cf_hash_drbg_sha256_reseed`(cf_hash_drbg_sha256 *ctx, const void *entropy, size_t nentropy, const void *addnl, size_t naddnl)

  Reseeds the generator with the given entropy and additional data addnl.

void `cf_hash_drbg_sha256_gen`(cf_hash_drbg_sha256 *ctx, void *out, size_t nout)

  Generates pseudo-random output, writing nout bytes at out. This function aborts if the generator needs seeding.

void `cf_hash_drbg_sha256_gen_additional`(cf_hash_drbg_sha256 *ctx, const void *addnl, size_t naddnl, void *out, size_t nout)

  Generates pseudo-random output, writing nout bytes at out. At the same time, addnl is input to the generator as further entropy. This function aborts if the generator needs seeding.

## HMAC_DRBG

This is HMAC_DRBG from SP800-90a r1 with any hash function.

This generator enforces a reseed_interval of 2^32-1: use `cf_hmac_drbg_needs_reseed()` to check whether you need to reseed before use, and reseed using `cf_hmac_drbg_reseed()`. If you try to use the generator when it thinks it needs reseeding, it will call abort.

Internally it enforces a max_number_of_bits_per_request of 2^19 bits. It sorts out chunking up multiple requests for you though, so feel free to ask for more than 2^16 bytes at a time. If you provide additional input when doing that, it is added only once, on the first subrequest.

It does not enforce any max_length or max_personalization_string_length.

### Types

`cf_hmac_drbg`

  HMAC_DRBG context.

  `cf_hmac_drbg.V`

  Current internal state.

  `cf_hmac_drbg.hmac`

  Current HMAC context, with key scheduled in it.

  `cf_hmac_drbg.reseed_counter`

  Current number of times entropy has been extracted from generator.

### Functions

void `cf_hmac_drbg_init`(cf_hmac_drbg *ctx, const cf_chash *hash, const void *entropy, size_t nentropy, const void *nonce, size_t nnonce, const void *persn, size_t npersn)

  Initialises the generator state ctx, using the provided entropy, nonce and personalisation string persn.

uint32_t `cf_hmac_drbg_needs_reseed`(const cf_hmac_drbg *ctx)

  Returns non-zero if the generator needs reseeding. If this function returns non-zero, the next `cf_hmac_drbg_gen()` or `cf_hmac_drbg_gen_additional()` call will call abort.

void `cf_hmac_drbg_reseed`(cf_hmac_drbg *ctx, const void *entropy, size_t nentropy, const void *addnl, size_t naddnl)

  Reseeds the generator with the given entropy and additional data addnl.

void `cf_hmac_drbg_gen`(cf_hmac_drbg *ctx, void *out, size_t nout)

  Generates pseudo-random output, writing nout bytes at out. This function aborts if the generator needs seeding.

void `cf_hmac_drbg_gen_additional`(cf_hmac_drbg *ctx, const void *addnl, size_t naddnl, void *out, size_t nout)

  Generates pseudo-random output, writing nout bytes at out. At the same time, addnl is input to the generator as further entropy. This function aborts if the generator needs seeding.

## Index

- Index

Read the Docs v: latest

Versions
  latest

Downloads
  pdf
  htmlzip
  epub

On Read the Docs
  Project Home
  Builds

Free document hosting provided by Read the Docs.