Cipher

Crypto Cipher APIs. More...

Data Structures
struct	cipher_ops
struct	ccm_params
struct	ctr_params
struct	gcm_params
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)
typedef int(*	cbc_op_t) (struct cipher_ctx *ctx, struct cipher_pkt *pkt, uint8_t *iv)
typedef int(*	ctr_op_t) (struct cipher_ctx *ctx, struct cipher_pkt *pkt, uint8_t *ctr)
typedef int(*	ccm_op_t) (struct cipher_ctx *ctx, struct cipher_aead_pkt *pkt, uint8_t *nonce)
typedef int(*	gcm_op_t) (struct cipher_ctx *ctx, struct cipher_aead_pkt *pkt, uint8_t *nonce)
typedef void(*	cipher_completion_cb) (struct cipher_pkt *completed, int status)

Enumerations
enum	cipher_algo { CRYPTO_CIPHER_ALGO_AES = 1 }
	Cipher Algorithm. More...
enum	cipher_op { CRYPTO_CIPHER_OP_DECRYPT = 0 , CRYPTO_CIPHER_OP_ENCRYPT = 1 }
	Cipher Operation. 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>

cbc_op_t

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

#include <zephyr/crypto/cipher.h>

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>

cipher_completion_cb

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

#include <zephyr/crypto/cipher.h>

ctr_op_t

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

#include <zephyr/crypto/cipher.h>

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>

Enumeration Type Documentation

cipher_algo

enum cipher_algo

#include <zephyr/crypto/cipher.h>

Cipher Algorithm.

Enumerator
CRYPTO_CIPHER_ALGO_AES

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
CRYPTO_CIPHER_MODE_CBC
CRYPTO_CIPHER_MODE_CTR
CRYPTO_CIPHER_MODE_CCM
CRYPTO_CIPHER_MODE_GCM

cipher_op

enum cipher_op

#include <zephyr/crypto/cipher.h>

Cipher Operation.

Enumerator
CRYPTO_CIPHER_OP_DECRYPT
CRYPTO_CIPHER_OP_ENCRYPT

Function Documentation

cipher_begin_session()

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  )

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()

static 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()

static 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()

static 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()

static 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()

static 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()

static 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()

static 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.