aes.h File Reference

This file contains AES definitions and functions. More...

#include "mbedtls/config.h"
#include <stddef.h>
#include <stdint.h>

Go to the source code of this file.

Data Structures
struct	mbedtls_aes_context
	The AES context-type definition. More...

Macros
#define	MBEDTLS_AES_ENCRYPT   1
	AES encryption. More...
#define	MBEDTLS_AES_DECRYPT   0
	AES decryption. More...
#define	MBEDTLS_ERR_AES_INVALID_KEY_LENGTH   -0x0020
	Invalid key length. More...
#define	MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH   -0x0022
	Invalid data input length. More...
#define	MBEDTLS_ERR_AES_BAD_INPUT_DATA   -0x0021
	Invalid input data. More...
#define	MBEDTLS_ERR_AES_FEATURE_UNAVAILABLE   -0x0023
	Feature not available. More...
#define	MBEDTLS_ERR_AES_HW_ACCEL_FAILED   -0x0025
	AES hardware accelerator failed. More...
#define	MBEDTLS_DEPRECATED

Functions
void	mbedtls_aes_init (mbedtls_aes_context *ctx)
	This function initializes the specified AES context. More...
void	mbedtls_aes_free (mbedtls_aes_context *ctx)
	This function releases and clears the specified AES context. More...
int	mbedtls_aes_setkey_enc (mbedtls_aes_context *ctx, const unsigned char *key, unsigned int keybits)
	This function sets the encryption key. More...
int	mbedtls_aes_setkey_dec (mbedtls_aes_context *ctx, const unsigned char *key, unsigned int keybits)
	This function sets the decryption key. More...
int	mbedtls_aes_crypt_ecb (mbedtls_aes_context *ctx, int mode, const unsigned char input[16], unsigned char output[16])
	This function performs an AES single-block encryption or decryption operation. More...
int	mbedtls_internal_aes_encrypt (mbedtls_aes_context *ctx, const unsigned char input[16], unsigned char output[16])
	Internal AES block encryption function. More...
int	mbedtls_internal_aes_decrypt (mbedtls_aes_context *ctx, const unsigned char input[16], unsigned char output[16])
	Internal AES block decryption function. More...
MBEDTLS_DEPRECATED void	mbedtls_aes_encrypt (mbedtls_aes_context *ctx, const unsigned char input[16], unsigned char output[16])
	Deprecated internal AES block encryption function without return value. More...
MBEDTLS_DEPRECATED void	mbedtls_aes_decrypt (mbedtls_aes_context *ctx, const unsigned char input[16], unsigned char output[16])
	Deprecated internal AES block decryption function without return value. More...

Detailed Description

This file contains AES definitions and functions.

The Advanced Encryption Standard (AES) specifies a FIPS-approved cryptographic algorithm that can be used to protect electronic data.

The AES algorithm is a symmetric block cipher that can encrypt and decrypt information. For more information, see FIPS Publication 197: Advanced Encryption Standard and ISO/IEC 18033-2:2006: Information technology – Security techniques – Encryption algorithms – Part 2: Asymmetric ciphers.

The AES-XTS block mode is standardized by NIST SP 800-38E https://nvlpubs.nist.gov/nistpubs/legacy/sp/nistspecialpublication800-38e.pdf and described in detail by IEEE P1619 https://ieeexplore.ieee.org/servlet/opac?punumber=4375278.

Macro Definition Documentation

#define MBEDTLS_AES_DECRYPT   0

AES decryption.

#define MBEDTLS_AES_ENCRYPT   1

AES encryption.

#define MBEDTLS_ERR_AES_BAD_INPUT_DATA   -0x0021

Invalid input data.

#define MBEDTLS_ERR_AES_FEATURE_UNAVAILABLE   -0x0023

Feature not available.

For example, an unsupported AES key size.

#define MBEDTLS_ERR_AES_HW_ACCEL_FAILED   -0x0025

AES hardware accelerator failed.

#define MBEDTLS_ERR_AES_INVALID_INPUT_LENGTH   -0x0022

Invalid data input length.

#define MBEDTLS_ERR_AES_INVALID_KEY_LENGTH   -0x0020

Invalid key length.

Function Documentation

int mbedtls_aes_crypt_ecb	(	mbedtls_aes_context *	ctx,
		int	mode,
		const unsigned char	input[16],
		unsigned char	output[16]
	)

This function performs an AES single-block encryption or decryption operation.

It performs the operation defined in the mode parameter (encrypt or decrypt), on the input data buffer defined in the input parameter.

mbedtls_aes_init(), and either mbedtls_aes_setkey_enc() or mbedtls_aes_setkey_dec() must be called before the first call to this API with the same context.

Parameters

ctx	The AES context to use for encryption or decryption. It must be initialized and bound to a key.
mode	The AES operation: MBEDTLS_AES_ENCRYPT or MBEDTLS_AES_DECRYPT.
input	The buffer holding the input data. It must be readable and at least 16 Bytes long.
output	The buffer where the output data will be written. It must be writeable and at least 16 Bytes long.

Returns

0 on success.

MBEDTLS_DEPRECATED void mbedtls_aes_decrypt	(	mbedtls_aes_context *	ctx,
		const unsigned char	input[16],
		unsigned char	output[16]
	)

Deprecated internal AES block decryption function without return value.

Deprecated:

Superseded by mbedtls_internal_aes_decrypt()

Parameters

ctx	The AES context to use for decryption.
input	Ciphertext block.
output	Output (plaintext) block.

MBEDTLS_DEPRECATED void mbedtls_aes_encrypt	(	mbedtls_aes_context *	ctx,
		const unsigned char	input[16],
		unsigned char	output[16]
	)

Deprecated internal AES block encryption function without return value.

Deprecated:

Superseded by mbedtls_internal_aes_encrypt()

Parameters

ctx	The AES context to use for encryption.
input	Plaintext block.
output	Output (ciphertext) block.

void mbedtls_aes_free

(

mbedtls_aes_context *

ctx

)

This function releases and clears the specified AES context.

Parameters

ctx	The AES context to clear. If this is NULL, this function does nothing. Otherwise, the context must have been at least initialized.

void mbedtls_aes_init

(

mbedtls_aes_context *

ctx

)

This function initializes the specified AES context.

It must be the first API called before using the context.

Parameters

ctx	The AES context to initialize. This must not be NULL.

int mbedtls_aes_setkey_dec	(	mbedtls_aes_context *	ctx,
		const unsigned char *	key,
		unsigned int	keybits
	)

This function sets the decryption key.

Parameters

ctx	The AES context to which the key should be bound. It must be initialized.
key	The decryption key. This must be a readable buffer of size keybits bits.
keybits	The size of data passed. Valid options are: 128 bits 192 bits 256 bits

Returns

0 on success.

MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure.

int mbedtls_aes_setkey_enc	(	mbedtls_aes_context *	ctx,
		const unsigned char *	key,
		unsigned int	keybits
	)

This function sets the encryption key.

Parameters

ctx	The AES context to which the key should be bound. It must be initialized.
key	The encryption key. This must be a readable buffer of size keybits bits.
keybits	The size of data passed in bits. Valid options are: 128 bits 192 bits 256 bits

Returns

0 on success.

MBEDTLS_ERR_AES_INVALID_KEY_LENGTH on failure.

int mbedtls_internal_aes_decrypt	(	mbedtls_aes_context *	ctx,
		const unsigned char	input[16],
		unsigned char	output[16]
	)

Internal AES block decryption function.

This is only exposed to allow overriding it using see MBEDTLS_AES_DECRYPT_ALT.

Parameters

ctx	The AES context to use for decryption.
input	The ciphertext block.
output	The output (plaintext) block.

Returns

0 on success.

int mbedtls_internal_aes_encrypt	(	mbedtls_aes_context *	ctx,
		const unsigned char	input[16],
		unsigned char	output[16]
	)

Internal AES block encryption function.

This is only exposed to allow overriding it using MBEDTLS_AES_ENCRYPT_ALT.

Parameters

ctx	The AES context to use for encryption.
input	The plaintext block.
output	The output (ciphertext) block.

Returns

0 on success.