Crypto¶
Overview¶
API Reference¶
-
group
crypto_cipher
Crypto Cipher APIs.
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
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)¶
Enums
Functions
-
int
cipher_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().
- Return
bitmask of supported options.
- Parameters
dev
: Pointer to the device structure for the driver instance.
-
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.
- Return
0 on success, negative errno code on fail.
- 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 AESmode
: The cipher mode to be used in this session. e.g CBC, CTRoptype
: Whether we should encrypt or decrypt in this session
-
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.
- Return
0 on success, negative errno code on fail.
- Parameters
dev
: Pointer to the device structure for the driver instance.ctx
: Pointer to the crypto context structure of the session to be freed.
-
int
cipher_callback_set
(const struct device *dev, crypto_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 crypto_do_op(). Based on crypto device hardware semantics, this is likely to be invoked from an ISR context.
- Return
0 on success, -ENOTSUP if the driver does not support async op, negative errno code on other error.
- Parameters
dev
: Pointer to the device structure for the driver instance.cb
: Pointer to application callback to be called by the driver.
-
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.
- Return
0 on success, negative errno code on fail.
- Parameters
ctx
: Pointer to the crypto context of this op.pkt
: Structure holding the input/output buffer pointers.
-
int
cipher_cbc_op
(struct cipher_ctx *ctx, struct cipher_pkt *pkt, uint8_t *iv)¶ Perform Cipher Block Chaining (CBC) crypto operation.
- Return
0 on success, negative errno code on fail.
- 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.
-
int
cipher_ctr_op
(struct cipher_ctx *ctx, struct cipher_pkt *pkt, uint8_t *iv)¶ Perform Counter (CTR) mode crypto operation.
- Return
0 on success, negative errno code on fail.
- 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.
-
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.
- Return
0 on success, negative errno code on fail.
- 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.
-
int
cipher_gcm_op
(struct cipher_ctx *ctx, struct cipher_aead_pkt *pkt, uint8_t *nonce)¶ Perform Galois/Counter Mode (GCM) crypto operation.
- Return
0 on success, negative errno code on fail.
- 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.
-
struct
crypto_driver_api
¶ - #include <cipher.h>
-
struct
cipher_ops
¶ - #include <cipher_structs.h>
-
struct
ccm_params
¶ - #include <cipher_structs.h>
-
struct
ctr_params
¶ - #include <cipher_structs.h>
-
struct
gcm_params
¶ - #include <cipher_structs.h>
-
struct
cipher_ctx
¶ - #include <cipher_structs.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.
-
union
cipher_ctx
.
key
¶ To be populated by the app before calling begin_session()
-
union
cipher_ctx
.
mode_params
¶ Cypher mode parameters, which remain constant for all ops in a session. To be populated by the app before calling begin_session().
-
struct
cipher_pkt
¶ - #include <cipher_structs.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.
-
struct
cipher_aead_pkt
¶ - #include <cipher_structs.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.
-