Crypto APIs
Overview
API Reference
Generic API for crypto drivers
- group crypto
Crypto APIs.
- Since
1.7
- Version
1.0.0
Defines
-
CAP_OPAQUE_KEY_HNDL
-
CAP_RAW_KEY
-
CAP_KEY_LOADING_API
-
CAP_INPLACE_OPS
Whether the output is placed in separate buffer or not.
-
CAP_SEPARATE_IO_BUFS
-
CAP_SYNC_OPS
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.
-
CAP_ASYNC_OPS
-
CAP_AUTONONCE
Whether the hardware/driver supports autononce feature.
-
CAP_NO_IV_PREFIX
Don’t prefix IV to cipher blocks.
Functions
-
static inline int crypto_query_hwcaps(const struct device *dev)
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.
-
struct crypto_driver_api
- #include <crypto.h>
Crypto driver API definition.
Ciphers API
- group crypto_cipher
Crypto Cipher APIs.
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)
Enums
Functions
-
static inline 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.
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.
-
static inline int cipher_free_session(const struct device *dev, struct cipher_ctx *ctx)
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.
-
static inline int cipher_callback_set(const struct device *dev, cipher_completion_cb cb)
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.
-
static inline 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.
- 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.
-
static inline int cipher_cbc_op(struct cipher_ctx *ctx, struct cipher_pkt *pkt, uint8_t *iv)
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.
-
static inline int cipher_ctr_op(struct cipher_ctx *ctx, struct cipher_pkt *pkt, uint8_t *iv)
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.
-
static inline 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.
- 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.
-
static inline int cipher_gcm_op(struct cipher_ctx *ctx, struct cipher_aead_pkt *pkt, uint8_t *nonce)
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.
-
struct cipher_ops
- #include <cipher.h>
-
struct ccm_params
- #include <cipher.h>
-
struct ctr_params
- #include <cipher.h>
-
struct gcm_params
- #include <cipher.h>
-
struct cipher_ctx
- #include <cipher.h>
Structure encoding session parameters.
Refer to comments for individual fields to know the contract in terms of who fills what and when w.r.t begin_session() call.
Public Members
-
struct cipher_ops ops
Place for driver to return function pointers to be invoked per cipher operation.
To be populated by crypto driver on return from begin_session() based on the algo/mode chosen by the app.
-
union cipher_ctx.[anonymous] key
To be populated by the app before calling begin_session()
-
const struct device *device
The device driver instance this crypto context relates to.
Will be populated by the begin_session() API.
-
void *drv_sessn_state
If the driver supports multiple simultaneously crypto sessions, this will identify the specific driver state this crypto session relates to.
Since dynamic memory allocation is not possible, it is suggested that at build time drivers allocate space for the max simultaneous sessions they intend to support. To be populated by the driver on return from begin_session().
-
void *app_sessn_state
Place for the user app to put info relevant stuff for resuming when completion callback happens for async ops.
Totally managed by the app.
-
union cipher_ctx.[anonymous] mode_params
Cypher mode parameters, which remain constant for all ops in a session.
To be populated by the app before calling begin_session().
-
uint16_t keylen
Cryptographic keylength in bytes.
To be populated by the app before calling begin_session()
-
uint16_t flags
How certain fields are to be interpreted for this session.
(A bitmask of CAP_* below.) To be populated by the app before calling begin_session(). An app can obtain the capability flags supported by a hw/driver by calling crypto_query_hwcaps().
-
struct cipher_ops ops
-
struct cipher_pkt
- #include <cipher.h>
Structure encoding IO parameters of one cryptographic operation like encrypt/decrypt.
The fields which has not been explicitly called out has to be filled up by the app before making the cipher_xxx_op() call.
Public Members
-
uint8_t *in_buf
Start address of input buffer.
-
int in_len
Bytes to be operated upon.
-
uint8_t *out_buf
Start of the output buffer, to be allocated by the application.
Can be NULL for in-place ops. To be populated with contents by the driver on return from op / async callback.
-
int out_buf_max
Size of the out_buf area allocated by the application.
Drivers should not write past the size of output buffer.
-
int out_len
To be populated by driver on return from cipher_xxx_op() and holds the size of the actual result.
-
struct cipher_ctx *ctx
Context this packet relates to.
This can be useful to get the session details, especially for async ops. Will be populated by the cipher_xxx_op() API based on the ctx parameter.
-
uint8_t *in_buf
-
struct cipher_aead_pkt
- #include <cipher.h>
Structure encoding IO parameters in AEAD (Authenticated Encryption with Associated Data) scenario like in CCM.
App has to furnish valid contents prior to making cipher_ccm_op() call.
Public Members
-
uint8_t *ad
Start address for Associated Data.
This has to be supplied by app.
-
uint32_t ad_len
Size of Associated Data.
This has to be supplied by the app.
-
uint8_t *tag
Start address for the auth hash.
For an encryption op this will be populated by the driver when it returns from cipher_ccm_op call. For a decryption op this has to be supplied by the app.
-
uint8_t *ad
-
typedef int (*block_op_t)(struct cipher_ctx *ctx, struct cipher_pkt *pkt)