Authenticated encryption¶

These APIs provide support for authenticated encryption and decryption.

AES-CCM¶

This API provides support for AES in the CCM mode of operation.

struct aes_ccm_key¶: A key prepared for AES-CCM encryption and decryption

Definition:

struct aes_ccm_key {
};

Members

struct aes_ccm_ctx¶: Context for incrementally en/decrypting a message

Definition:

struct aes_ccm_ctx {
};

Members

int aes_ccm_preparekey(struct aes_ccm_key *key, const u8 *in_key, size_t key_len, size_t authtag_len)¶: Prepare a key for AES-CCM encryption and decryption

Parameters

struct aes_ccm_key *key: (output) The key structure to initialize
const u8 *in_key: The raw AES-CCM key
size_t key_len: Length of the raw key in bytes: 16, 24, or 32
size_t authtag_len: Length of the authentication tag in bytes: 4, 6, 8, 10, 12, 14, or 16. 16 is recommended.

Description

Users should use memzero_explicit() to zeroize the key struct at the end of its lifetime. (But if this function fails, zeroization is unnecessary.)

Context

Any context.

Return

0 on success
-EINVAL if either of the lengths is invalid

int aes_ccm_encrypt(u8 *dst, const u8 *src, size_t data_len, u8 *authtag, const u8 *ad, size_t ad_len, const u8 *nonce, size_t nonce_len, const struct aes_ccm_key *key)¶: Encrypt a message with AES-CCM

Parameters

u8 *dst: The destination ciphertext data. Can be in-place or out-of-place. For other overlaps the behavior is unspecified.
const u8 *src: The source plaintext data
size_t data_len: Length of plaintext in bytes (and ciphertext excluding the tag): at most 2^(120 - (8 * nonce_len)) - 1
u8 *authtag: The output authentication tag. Length is the authtag_len that was passed to aes_ccm_preparekey(). Usually protocols using AES-CCM put the tag at the end of the ciphertext, in which case this should be set to dst + data_len and dst must have room for the tag.
const u8 *ad: The associated data
size_t ad_len: Length of associated data in bytes
const u8 *nonce: The nonce. All (key, nonce) pairs used MUST be distinct.
size_t nonce_len: Length of the nonce in bytes: between 7 and 13 inclusive
const struct aes_ccm_key *key: The key, already prepared using aes_ccm_preparekey()

Context

Any context.

Return

0 on success
-EINVAL if nonce_len is invalid
-EOVERFLOW if data_len is too large for the selected nonce_len

int aes_ccm_decrypt(u8 *dst, const u8 *src, size_t data_len, const u8 *authtag, const u8 *ad, size_t ad_len, const u8 *nonce, size_t nonce_len, const struct aes_ccm_key *key)¶: Decrypt a message with AES-CCM

Parameters

u8 *dst: The destination plaintext data. Can be in-place or out-of-place. For other overlaps the behavior is unspecified.
const u8 *src: The source ciphertext data
size_t data_len: Length of plaintext in bytes (and ciphertext excluding the tag): at most 2^(120 - (8 * nonce_len)) - 1
const u8 *authtag: The stored authentication tag. Length is the authtag_len that was passed to aes_ccm_preparekey(). Usually protocols using AES-CCM put the tag at the end of the ciphertext, in which case this should be set to src + data_len and src must have room for the tag.
const u8 *ad: The associated data
size_t ad_len: Length of associated data in bytes
const u8 *nonce: The nonce
size_t nonce_len: Length of the nonce in bytes: between 7 and 13 inclusive
const struct aes_ccm_key *key: The key, already prepared using aes_ccm_preparekey()

Context

Any context.

Return

0 on success. This is the only case where any decrypted or associated data can be used.
-EBADMSG if the message is inauthentic
-EINVAL if nonce_len is invalid
-EOVERFLOW if data_len is too large for the selected nonce_len

int aes_ccm_init(struct aes_ccm_ctx *ctx, u64 data_len, u64 ad_len, const u8 *nonce, size_t nonce_len, const struct aes_ccm_key *key)¶: Initialize context for incremental AES-CCM encryption or decryption

Parameters

struct aes_ccm_ctx *ctx: The context to initialize
u64 data_len: Length of the en/decrypted data that will be provided in bytes: at most 2^(120 - (8 * nonce_len)) - 1
u64 ad_len: Length of the associated data that will be provided in bytes
const u8 *nonce: The nonce. All (key, nonce) pairs used for encryption MUST be distinct.
size_t nonce_len: Length of the nonce in bytes: between 7 and 13 inclusive
const struct aes_ccm_key *key: The key, already prepared using aes_ccm_preparekey(). Note that a pointer to the key is saved in the context, so the key must live at least as long as the context.

Description

Unlike AES-GCM, AES-CCM requires the total lengths of the associated data and the en/decrypted data to be known during initialization. Callers MUST ensure that these lengths are correct.

If this function returns success, the context should be zeroized at the end of its lifetime. Normally that happens in aes_ccm_encrypt_final() or aes_ccm_decrypt_final(), but callers that abandon a context without finalizing it should explicitly zeroize it.

IMPORTANT: Callers that are decrypting MUST NOT assume that any decrypted or associated data is authentic until the authentication tag has been verified. This incremental API is provided solely to support callers that can’t efficiently use the one-shot functions due to using a nonlinear data layout.

For incremental AES-CCM encryption, use:

aes_ccm_init()
aes_ccm_auth_update() (any number of times)
aes_ccm_encrypt_update() (any number of times)
aes_ccm_encrypt_final()

For incremental AES-CCM decryption, use:

aes_ccm_init()
aes_ccm_auth_update() (any number of times)
aes_ccm_decrypt_update() (any number of times)
aes_ccm_decrypt_final()

Context

Any context.

Return

0 on success
-EINVAL if nonce_len is invalid
-EOVERFLOW if data_len is too large for the selected nonce_len

void aes_ccm_auth_update(struct aes_ccm_ctx *ctx, const u8 *ad, size_t len)¶: Incrementally process AES-CCM associated data

Parameters

struct aes_ccm_ctx *ctx: An AES-CCM context
const u8 *ad: The associated data
size_t len: Length of the associated data in bytes

Description

IMPORTANT: Callers MUST NOT assume that any decrypted or associated data is authentic until the authentication tag has been verified.

The total length of the associated data (over all calls to this function) MUST match the ad_len that was passed to aes_ccm_init().

Context

Any context.

void aes_ccm_encrypt_update(struct aes_ccm_ctx *ctx, u8 *dst, const u8 *src, size_t len)¶: Incrementally encrypt data with AES-CCM

Parameters

struct aes_ccm_ctx *ctx: An AES-CCM context
u8 *dst: The destination buffer. Can be in-place or out-of-place. For other overlaps the behavior is unspecified.
const u8 *src: The source plaintext data
size_t len: Number of bytes to encrypt

Description

This can be called only after all associated data has been processed.

The total length of the encrypted data (over all calls to this function) MUST match the data_len that was passed to aes_ccm_init().

Context

Any context.

void aes_ccm_decrypt_update(struct aes_ccm_ctx *ctx, u8 *dst, const u8 *src, size_t len)¶: Incrementally decrypt data with AES-CCM

Parameters

struct aes_ccm_ctx *ctx: An AES-CCM context
u8 *dst: The destination buffer. Can be in-place or out-of-place. For other overlaps the behavior is unspecified.
const u8 *src: The source ciphertext data (not including auth tag)
size_t len: Number of bytes to decrypt

Description

This can be called only after all associated data has been processed.

The total length of the decrypted data (over all calls to this function) MUST match the data_len that was passed to aes_ccm_init().

IMPORTANT: Callers MUST NOT assume that any decrypted or associated data is authentic until the authentication tag has been verified.

Context

Any context.

void aes_ccm_encrypt_final(struct aes_ccm_ctx *ctx, u8 *authtag)¶: Finish encrypting a message with AES-CCM

Parameters

struct aes_ccm_ctx *ctx: An AES-CCM context
u8 *authtag: The output authentication tag. Length is the authtag_len that was passed to aes_ccm_preparekey().

Description

This also zeroizes ctx, so the caller doesn’t need to do it.

Context

Any context.

int aes_ccm_decrypt_final(struct aes_ccm_ctx *ctx, const u8 *authtag)¶: Finish decrypting a message with AES-CCM

Parameters

struct aes_ccm_ctx *ctx: An AES-CCM context
const u8 *authtag: The stored authentication tag. Length is the authtag_len that was passed to aes_ccm_preparekey().

Description

This also zeroizes ctx, so the caller doesn’t need to do it.

Context

Any context.

Return

0 on success. This is the only case where any decrypted or associated data can be used.
-EBADMSG if the message is inauthentic

AES-GCM¶

This API provides support for AES in the GCM mode of operation.

struct aes_gcm_key¶: A key prepared for AES-GCM encryption and decryption

Definition:

struct aes_gcm_key {
};

Members

struct aes_gcm_ctx¶: Context for incrementally en/decrypting a message

Definition:

struct aes_gcm_ctx {
};

Members

int aes_gcm_preparekey(struct aes_gcm_key *key, const u8 *in_key, size_t key_len, size_t authtag_len)¶: Prepare a key for AES-GCM encryption and decryption

Parameters

struct aes_gcm_key *key: (output) The key structure to initialize
const u8 *in_key: The raw AES-GCM key
size_t key_len: Length of the raw key in bytes: 16, 24, or 32
size_t authtag_len: Length of the authentication tag in bytes: 4, 8, 12, 13, 14, 15, or 16. 16 is recommended.

Description

Users should use memzero_explicit() to zeroize the key struct at the end of its lifetime. (But if this function fails, zeroization is unnecessary.)

Context

Any context.

Return

0 on success
-EINVAL if either of the lengths is invalid

void aes_gcm_encrypt(u8 *dst, const u8 *src, size_t data_len, u8 *authtag, const u8 *ad, size_t ad_len, const u8 nonce[static 12], const struct aes_gcm_key *key)¶: Encrypt a message with AES-GCM

Parameters

u8 *dst: The destination ciphertext data. Can be in-place or out-of-place. For other overlaps the behavior is unspecified.
const u8 *src: The source plaintext data
size_t data_len: Length of plaintext in bytes (and ciphertext excluding the tag): at most 2^36 - 32
u8 *authtag: The output authentication tag. Length is the authtag_len that was passed to aes_gcm_preparekey(). Usually protocols using AES-GCM put the tag at the end of the ciphertext, in which case this should be set to dst + data_len and dst must have room for the tag.
const u8 *ad: The associated data
size_t ad_len: Length of associated data in bytes: at most 2^61 - 1
const u8 nonce[static 12]: The 12-byte nonce. All (key, nonce) pairs used MUST be distinct.
const struct aes_gcm_key *key: The key, already prepared using aes_gcm_preparekey()

Description

For AES-GMAC (i.e., AES-GCM without any data en/decrypted), use dst=NULL, src=NULL, and data_len=0 to generate the AES-GMAC value.

Context

Any context.

int aes_gcm_decrypt(u8 *dst, const u8 *src, size_t data_len, const u8 *authtag, const u8 *ad, size_t ad_len, const u8 nonce[static 12], const struct aes_gcm_key *key)¶: Decrypt a message with AES-GCM

Parameters

u8 *dst: The destination plaintext data. Can be in-place or out-of-place. For other overlaps the behavior is unspecified.
const u8 *src: The source ciphertext data
size_t data_len: Length of plaintext in bytes (and ciphertext excluding the tag): at most 2^36 - 32
const u8 *authtag: The stored authentication tag. Length is the authtag_len that was passed to aes_gcm_preparekey(). Usually protocols using AES-GCM put the tag at the end of the ciphertext, in which case this should be set to src + data_len and src must have room for the tag.
const u8 *ad: The associated data
size_t ad_len: Length of associated data in bytes: at most 2^61 - 1
const u8 nonce[static 12]: The 12-byte nonce
const struct aes_gcm_key *key: The key, already prepared using aes_gcm_preparekey()

Description

For AES-GMAC (i.e., AES-GCM without any data en/decrypted), use dst=NULL, src=NULL, and data_len=0 to verify the AES-GMAC value.

Context

Any context.

Return

0 on success. This is the only case where any decrypted or associated data can be used.
-EBADMSG if the message is inauthentic

void aes_gcm_init(struct aes_gcm_ctx *ctx, const u8 nonce[static 12], const struct aes_gcm_key *key)¶: Initialize context for incremental AES-GCM encryption or decryption, or for AES-GMAC computation

Parameters

struct aes_gcm_ctx *ctx: The context to initialize
const u8 nonce[static 12]: The 12-byte nonce. All (key, nonce) pairs used for encryption or MAC generation MUST be distinct.
const struct aes_gcm_key *key: The key, already prepared using aes_gcm_preparekey(). Note that a pointer to the key is saved in the context, so the key must live at least as long as the context.

Description

The context should be zeroized at the end of its lifetime. Normally that happens in aes_gcm_encrypt_final() or aes_gcm_decrypt_final(), but callers that abandon a context without finalizing it should explicitly zeroize it.

IMPORTANT: Callers that are decrypting data or computing a GMAC value for verification MUST NOT assume that any decrypted or associated data is authentic until the authentication tag has been verified. This incremental API is provided solely to support callers that can’t efficiently use the one-shot functions due to using a nonlinear data layout.

For incremental AES-GCM encryption, use:

aes_gcm_init()
aes_gcm_auth_update() (any number of times)
aes_gcm_encrypt_update() (any number of times)
aes_gcm_encrypt_final()

For incremental AES-GCM decryption, use:

aes_gcm_init()
aes_gcm_auth_update() (any number of times)
aes_gcm_decrypt_update() (any number of times)
aes_gcm_decrypt_final()

AES-GMAC is just AES-GCM with zero bytes en/decrypted. For incremental AES-GMAC computation, use:

aes_gcm_init()
aes_gcm_auth_update() (any number of times)
aes_gcm_encrypt_final() to return the computed tag to the caller, or aes_gcm_decrypt_final() to directly verify the computed tag

Context

Any context.

void aes_gcm_auth_update(struct aes_gcm_ctx *ctx, const u8 *ad, size_t len)¶: Incrementally process AES-GCM associated data

Parameters

struct aes_gcm_ctx *ctx: An AES-GCM context
const u8 *ad: The associated data
size_t len: Number of bytes provided. The caller must ensure that the total associated data length doesn’t exceed GCM’s limit of 2^61 - 1.

Description

IMPORTANT: Callers MUST NOT assume that any decrypted or associated data is authentic until the authentication tag has been verified.

Context

Any context.

void aes_gcm_encrypt_update(struct aes_gcm_ctx *ctx, u8 *dst, const u8 *src, size_t len)¶: Incrementally encrypt data with AES-GCM

Parameters

struct aes_gcm_ctx *ctx: An AES-GCM context
u8 *dst: The destination buffer. Can be in-place or out-of-place. For other overlaps the behavior is unspecified.
const u8 *src: The source plaintext data
size_t len: Number of bytes to encrypt. The caller must ensure that the total number of bytes encrypted doesn’t exceed GCM’s limit of 2^36 - 32.

Description

This can be called only after all associated data has been processed.

Context

Any context.

void aes_gcm_decrypt_update(struct aes_gcm_ctx *ctx, u8 *dst, const u8 *src, size_t len)¶: Incrementally decrypt data with AES-GCM

Parameters

struct aes_gcm_ctx *ctx: An AES-GCM context
u8 *dst: The destination buffer. Can be in-place or out-of-place. For other overlaps the behavior is unspecified.
const u8 *src: The source ciphertext data (not including auth tag)
size_t len: Number of bytes to decrypt. The caller must ensure that the total number of bytes decrypted doesn’t exceed GCM’s limit of 2^36 - 32.

Description

This can be called only after all associated data has been processed.

IMPORTANT: Callers MUST NOT assume that any decrypted or associated data is authentic until the authentication tag has been verified.

Context

Any context.

void aes_gcm_encrypt_final(struct aes_gcm_ctx *ctx, u8 *authtag)¶: Finish encrypting a message with AES-GCM

Parameters

struct aes_gcm_ctx *ctx: An AES-GCM context
u8 *authtag: The output authentication tag. Length is the authtag_len that was passed to aes_gcm_preparekey().

Description

This also zeroizes ctx, so the caller doesn’t need to do it.

Context

Any context.

int aes_gcm_decrypt_final(struct aes_gcm_ctx *ctx, const u8 *authtag)¶: Finish decrypting a message with AES-GCM

Parameters

struct aes_gcm_ctx *ctx: An AES-GCM context
const u8 *authtag: The stored authentication tag. Length is the authtag_len that was passed to aes_gcm_preparekey().

Description

This also zeroizes ctx, so the caller doesn’t need to do it.

Context

Any context.

Return

0 on success. This is the only case where any decrypted or associated data can be used.
-EBADMSG if the message is inauthentic

The Linux Kernel

Contents

This Page

Authenticated encryption¶

AES-CCM¶

AES-GCM¶