Cipher

Crypto Cipher APIs. More...

Data Structures
struct	crypto_driver_api
struct	cipher_ops
struct	ccm_params
struct	ctr_params
struct	gcm_params
struct	cipher_ctx
struct	cipher_pkt
struct	cipher_aead_pkt

Macros
#define	CAP_OPAQUE_KEY_HNDL   BIT(0)
#define	CAP_RAW_KEY   BIT(1)
#define	CAP_KEY_LOADING_API   BIT(2)
#define	CAP_INPLACE_OPS   BIT(3)
#define	CAP_SEPARATE_IO_BUFS   BIT(4)
#define	CAP_SYNC_OPS   BIT(5)
#define	CAP_ASYNC_OPS   BIT(6)
#define	CAP_AUTONONCE   BIT(7)
#define	CAP_NO_IV_PREFIX   BIT(8)

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(*	crypto_completion_cb) (struct cipher_pkt *completed, int status)

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

Functions
static int	cipher_query_hwcaps (const struct device *dev)
	Query the crypto hardware capabilities. More...
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. More...
static int	cipher_free_session (const struct device *dev, struct cipher_ctx *ctx)
	Cleanup a crypto session. More...
static int	cipher_callback_set (const struct device *dev, crypto_completion_cb cb)
	Registers an async crypto op completion callback with the driver. More...
static int	cipher_block_op (struct cipher_ctx *ctx, struct cipher_pkt *pkt)
	Perform single-block crypto operation (ECB cipher mode). This should not be overloaded to operate on multiple blocks for security reasons. More...
static int	cipher_cbc_op (struct cipher_ctx *ctx, struct cipher_pkt *pkt, uint8_t *iv)
	Perform Cipher Block Chaining (CBC) crypto operation. More...
static int	cipher_ctr_op (struct cipher_ctx *ctx, struct cipher_pkt *pkt, uint8_t *iv)
	Perform Counter (CTR) mode crypto operation. More...
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. More...
static int	cipher_gcm_op (struct cipher_ctx *ctx, struct cipher_aead_pkt *pkt, uint8_t *nonce)
	Perform Galois/Counter Mode (GCM) crypto operation. More...

Detailed Description

Crypto Cipher APIs.

Macro Definition Documentation

CAP_ASYNC_OPS

#define CAP_ASYNC_OPS   BIT(6)

#include <include/crypto/cipher_structs.h>

CAP_AUTONONCE

#define CAP_AUTONONCE   BIT(7)

#include <include/crypto/cipher_structs.h>

Whether the hardware/driver supports autononce feature

CAP_INPLACE_OPS

#define CAP_INPLACE_OPS   BIT(3)

#include <include/crypto/cipher_structs.h>

Whether the output is placed in separate buffer or not

CAP_KEY_LOADING_API

#define CAP_KEY_LOADING_API   BIT(2)

#include <include/crypto/cipher_structs.h>

CAP_NO_IV_PREFIX

#define CAP_NO_IV_PREFIX   BIT(8)

#include <include/crypto/cipher_structs.h>

Don't prefix IV to cipher blocks

CAP_OPAQUE_KEY_HNDL

#define CAP_OPAQUE_KEY_HNDL   BIT(0)

#include <include/crypto/cipher_structs.h>

CAP_RAW_KEY

#define CAP_RAW_KEY   BIT(1)

#include <include/crypto/cipher_structs.h>

CAP_SEPARATE_IO_BUFS

#define CAP_SEPARATE_IO_BUFS   BIT(4)

#include <include/crypto/cipher_structs.h>

CAP_SYNC_OPS

#define CAP_SYNC_OPS   BIT(5)

#include <include/crypto/cipher_structs.h>

These denotes if the output (completion of a cipher_xxx_op) is conveyed by the op function returning, or it is conveyed by an async notification

Typedef Documentation

block_op_t

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

#include <include/crypto/cipher_structs.h>

cbc_op_t

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

#include <include/crypto/cipher_structs.h>

ccm_op_t

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

#include <include/crypto/cipher_structs.h>

crypto_completion_cb

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

#include <include/crypto/cipher_structs.h>

ctr_op_t

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

#include <include/crypto/cipher_structs.h>

gcm_op_t

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

#include <include/crypto/cipher_structs.h>

Enumeration Type Documentation

cipher_algo

enum cipher_algo

#include <include/crypto/cipher_structs.h>

Cipher Algorithm

Enumerator
CRYPTO_CIPHER_ALGO_AES

cipher_mode

enum cipher_mode

#include <include/crypto/cipher_structs.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 <include/crypto/cipher_structs.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 <include/crypto/cipher.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 <include/crypto/cipher.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, crypto_completion_cb  cb  )

inlinestatic

#include <include/crypto/cipher.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 crypto_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 <include/crypto/cipher.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 <include/crypto/cipher.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, Assosciated 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 <include/crypto/cipher.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 <include/crypto/cipher.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 <include/crypto/cipher.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.

cipher_query_hwcaps()

static int cipher_query_hwcaps ( const struct device *  dev )

inlinestatic

#include <include/crypto/cipher.h>

Query the crypto hardware capabilities.

This API is used by the app to query the capabilities supported by the crypto device. Based on this the app can specify a subset of the supported options to be honored for a session during cipher_begin_session().

Parameters

dev	Pointer to the device structure for the driver instance.

Returns

bitmask of supported options.