Cipher

Crypto Cipher APIs. More...

Files
file	cipher.h
	Crypto Cipher structure definitions.

Data Structures
struct	cipher_ops
	Cipher operation handlers selected for a session. More...
struct	ccm_params
	CCM mode session parameters. More...
struct	ctr_params
	CTR mode session parameters. More...
struct	gcm_params
	GCM mode session parameters. More...
struct	cipher_ctx
	Structure encoding session parameters. More...
struct	cipher_pkt
	Structure encoding IO parameters of one cryptographic operation like encrypt/decrypt. More...
struct	cipher_aead_pkt
	Structure encoding IO parameters in AEAD (Authenticated Encryption with Associated Data) scenario like in CCM. More...

Typedefs
typedef int(*	block_op_t) (struct cipher_ctx *ctx, struct cipher_pkt *pkt)
	Perform an ECB block cipher operation.
typedef int(*	cbc_op_t) (struct cipher_ctx *ctx, struct cipher_pkt *pkt, uint8_t *iv)
	Perform a CBC cipher operation.
typedef int(*	ctr_op_t) (struct cipher_ctx *ctx, struct cipher_pkt *pkt, uint8_t *ctr)
	Perform a CTR cipher operation.
typedef int(*	ccm_op_t) (struct cipher_ctx *ctx, struct cipher_aead_pkt *pkt, uint8_t *nonce)
	Perform a CCM authenticated cipher operation.
typedef int(*	gcm_op_t) (struct cipher_ctx *ctx, struct cipher_aead_pkt *pkt, uint8_t *nonce)
	Perform a GCM authenticated cipher operation.
typedef void(*	cipher_completion_cb) (struct cipher_pkt *completed, int status)
	Handle completion of an asynchronous cipher request.

Enumerations
enum	cipher_algo { CRYPTO_CIPHER_ALGO_AES = 1 }
	Cipher algorithms. More...
enum	cipher_op { CRYPTO_CIPHER_OP_DECRYPT = 0 , CRYPTO_CIPHER_OP_ENCRYPT = 1 }
	Cipher operation types. More...
enum	cipher_mode {   CRYPTO_CIPHER_MODE_ECB = 1 , CRYPTO_CIPHER_MODE_CBC = 2 , CRYPTO_CIPHER_MODE_CTR = 3 , CRYPTO_CIPHER_MODE_CCM = 4 ,   CRYPTO_CIPHER_MODE_GCM = 5 }
	Possible cipher mode options. More...

Functions
static int	cipher_begin_session (const struct device *dev, struct cipher_ctx *ctx, enum cipher_algo algo, enum cipher_mode mode, enum cipher_op optype)
	Setup a crypto session.
static int	cipher_free_session (const struct device *dev, struct cipher_ctx *ctx)
	Cleanup a crypto session.
static int	cipher_callback_set (const struct device *dev, cipher_completion_cb cb)
	Registers an async crypto op completion callback with the driver.
static int	cipher_block_op (struct cipher_ctx *ctx, struct cipher_pkt *pkt)
	Perform single-block crypto operation (ECB cipher mode).
static int	cipher_cbc_op (struct cipher_ctx *ctx, struct cipher_pkt *pkt, uint8_t *iv)
	Perform Cipher Block Chaining (CBC) crypto operation.
static int	cipher_ctr_op (struct cipher_ctx *ctx, struct cipher_pkt *pkt, uint8_t *iv)
	Perform Counter (CTR) mode crypto operation.
static int	cipher_ccm_op (struct cipher_ctx *ctx, struct cipher_aead_pkt *pkt, uint8_t *nonce)
	Perform Counter with CBC-MAC (CCM) mode crypto operation.
static int	cipher_gcm_op (struct cipher_ctx *ctx, struct cipher_aead_pkt *pkt, uint8_t *nonce)
	Perform Galois/Counter Mode (GCM) crypto operation.

Detailed Description

Crypto Cipher APIs.

Typedef Documentation

block_op_t

typedef int(* block_op_t) (struct cipher_ctx *ctx, struct cipher_pkt *pkt)

#include <zephyr/crypto/cipher.h>

Perform an ECB block cipher operation.

Parameters

ctx	Cipher session context.
pkt	Packet containing input and output buffers.

Return values

0	Operation completed successfully.
-errno	Negative errno code on failure.

cbc_op_t

typedef int(* cbc_op_t) (struct cipher_ctx *ctx, struct cipher_pkt *pkt, uint8_t *iv)

#include <zephyr/crypto/cipher.h>

Perform a CBC cipher operation.

Parameters

ctx	Cipher session context.
pkt	Packet containing input and output buffers.
iv	Initialization vector for this operation. The buffer must remain valid for the duration of the operation.

Return values

0	Operation completed successfully.
-errno	Negative errno code on failure.

ccm_op_t

typedef int(* ccm_op_t) (struct cipher_ctx *ctx, struct cipher_aead_pkt *pkt, uint8_t *nonce)

#include <zephyr/crypto/cipher.h>

Perform a CCM authenticated cipher operation.

Parameters

ctx	Cipher session context.
pkt	Packet containing input, output, associated data, and authentication tag buffers.
nonce	Nonce for this operation. The buffer must remain valid for the duration of the operation.

Return values

0	Operation completed successfully.
-errno	Negative errno code on failure.

cipher_completion_cb

typedef void(* cipher_completion_cb) (struct cipher_pkt *completed, int status)

#include <zephyr/crypto/cipher.h>

Handle completion of an asynchronous cipher request.

The application can get the session context from the completed packet's ctx field. For AEAD operations, the encompassing AEAD packet can be accessed with container_of(). The packet type can be determined from the session cipher mode.

Parameters

completed	Completed cipher packet.
status	Completion status. A value of 0 indicates success and a negative errno code indicates failure.

ctr_op_t

typedef int(* ctr_op_t) (struct cipher_ctx *ctx, struct cipher_pkt *pkt, uint8_t *ctr)

#include <zephyr/crypto/cipher.h>

Perform a CTR cipher operation.

Parameters

ctx	Cipher session context.
pkt	Packet containing input and output buffers.
ctr	Initial counter bytes for this operation. For split-counter sessions, this is the IV portion supplied by the application.

Return values

0	Operation completed successfully.
-errno	Negative errno code on failure.

gcm_op_t

typedef int(* gcm_op_t) (struct cipher_ctx *ctx, struct cipher_aead_pkt *pkt, uint8_t *nonce)

#include <zephyr/crypto/cipher.h>

Perform a GCM authenticated cipher operation.

Parameters

ctx	Cipher session context.
pkt	Packet containing input, output, associated data, and authentication tag buffers.
nonce	Nonce for this operation. The buffer must remain valid for the duration of the operation.

Return values

0	Operation completed successfully.
-errno	Negative errno code on failure.

Enumeration Type Documentation

cipher_algo

enum cipher_algo

#include <zephyr/crypto/cipher.h>

Cipher algorithms.

Enumerator
CRYPTO_CIPHER_ALGO_AES	Advanced Encryption Standard.

cipher_mode

enum cipher_mode

#include <zephyr/crypto/cipher.h>

Possible cipher mode options.

More to be added as required.

Enumerator
CRYPTO_CIPHER_MODE_ECB	Electronic Codebook mode.
CRYPTO_CIPHER_MODE_CBC	Cipher Block Chaining mode.
CRYPTO_CIPHER_MODE_CTR	Counter mode.
CRYPTO_CIPHER_MODE_CCM	Counter with CBC-MAC mode.
CRYPTO_CIPHER_MODE_GCM	Galois/Counter mode.

cipher_op

enum cipher_op

#include <zephyr/crypto/cipher.h>

Cipher operation types.

Enumerator
CRYPTO_CIPHER_OP_DECRYPT	Decrypt input data.
CRYPTO_CIPHER_OP_ENCRYPT	Encrypt input data.

Function Documentation

cipher_begin_session()

int cipher_begin_session ( const struct device * dev, struct cipher_ctx * ctx, enum cipher_algo algo, enum cipher_mode mode, enum cipher_op optype )

inlinestatic

#include <zephyr/crypto/crypto.h>

Setup a crypto session.

Initializes one time parameters, like the session key, algorithm and cipher mode which may remain constant for all operations in the session. The state may be cached in hardware and/or driver data state variables.

Parameters

dev	Pointer to the device structure for the driver instance.
ctx	Pointer to the context structure. Various one time parameters like key, keylength, etc. are supplied via this structure. The structure documentation specifies which fields are to be populated by the app before making this call.
algo	The crypto algorithm to be used in this session. e.g AES
mode	The cipher mode to be used in this session. e.g CBC, CTR
optype	Whether we should encrypt or decrypt in this session

Returns

0 on success, negative errno code on fail.

cipher_block_op()

int cipher_block_op ( struct cipher_ctx * ctx, struct cipher_pkt * pkt )

inlinestatic

#include <zephyr/crypto/crypto.h>

Perform single-block crypto operation (ECB cipher mode).

This should not be overloaded to operate on multiple blocks for security reasons.

Parameters

ctx	Pointer to the crypto context of this op.
pkt	Structure holding the input/output buffer pointers.

Returns

0 on success, negative errno code on fail.

cipher_callback_set()

int cipher_callback_set ( const struct device * dev, cipher_completion_cb cb )

inlinestatic

#include <zephyr/crypto/crypto.h>

Registers an async crypto op completion callback with the driver.

The application can register an async crypto op completion callback handler to be invoked by the driver, on completion of a prior request submitted via cipher_do_op(). Based on crypto device hardware semantics, this is likely to be invoked from an ISR context.

Parameters

dev	Pointer to the device structure for the driver instance.
cb	Pointer to application callback to be called by the driver.

Returns

0 on success, -ENOTSUP if the driver does not support async op, negative errno code on other error.

cipher_cbc_op()

int cipher_cbc_op ( struct cipher_ctx * ctx, struct cipher_pkt * pkt, uint8_t * iv )

inlinestatic

#include <zephyr/crypto/crypto.h>

Perform Cipher Block Chaining (CBC) crypto operation.

Parameters

ctx	Pointer to the crypto context of this op.
pkt	Structure holding the input/output buffer pointers.
iv	Initialization Vector (IV) for the operation. Same IV value should not be reused across multiple operations (within a session context) for security.

Returns

0 on success, negative errno code on fail.

cipher_ccm_op()

int cipher_ccm_op ( struct cipher_ctx * ctx, struct cipher_aead_pkt * pkt, uint8_t * nonce )

inlinestatic

#include <zephyr/crypto/crypto.h>

Perform Counter with CBC-MAC (CCM) mode crypto operation.

Parameters

ctx	Pointer to the crypto context of this op.
pkt	Structure holding the input/output, Associated Data (AD) and auth tag buffer pointers.
nonce	Nonce for the operation. Same nonce value should not be reused across multiple operations (within a session context) for security.

Returns

0 on success, negative errno code on fail.

cipher_ctr_op()

int cipher_ctr_op ( struct cipher_ctx * ctx, struct cipher_pkt * pkt, uint8_t * iv )

inlinestatic

#include <zephyr/crypto/crypto.h>

Perform Counter (CTR) mode crypto operation.

Parameters

ctx	Pointer to the crypto context of this op.
pkt	Structure holding the input/output buffer pointers.
iv	Initialization Vector (IV) for the operation. We use a split counter formed by appending IV and ctr. Consequently ivlen = keylen - ctrlen. 'ctrlen' is specified during session setup through the 'ctx.mode_params.ctr_params.ctr_len' parameter. IV should not be reused across multiple operations (within a session context) for security. The non-IV part of the split counter is transparent to the caller and is fully managed by the crypto provider.

Returns

0 on success, negative errno code on fail.

cipher_free_session()

int cipher_free_session ( const struct device * dev, struct cipher_ctx * ctx )

inlinestatic

#include <zephyr/crypto/crypto.h>

Cleanup a crypto session.

Clears the hardware and/or driver state of a previous session.

Parameters

dev	Pointer to the device structure for the driver instance.
ctx	Pointer to the crypto context structure of the session to be freed.

Returns

0 on success, negative errno code on fail.

cipher_gcm_op()

int cipher_gcm_op ( struct cipher_ctx * ctx, struct cipher_aead_pkt * pkt, uint8_t * nonce )

inlinestatic

#include <zephyr/crypto/crypto.h>

Perform Galois/Counter Mode (GCM) crypto operation.

Parameters

ctx	Pointer to the crypto context of this op.
pkt	Structure holding the input/output, Associated Data (AD) and auth tag buffer pointers.
nonce	Nonce for the operation. Same nonce value should not be reused across multiple operations (within a session context) for security.

Returns

0 on success, negative errno code on fail.