blob: 02772a2f64e3ae0bd8067b2b0a221116c38b2ed1 [file] [log] [blame]
* Copyright (c) 2016 Intel Corporation.
* SPDX-License-Identifier: Apache-2.0
* @file
* @brief Crypto Cipher structure definitions
* This file contains the Crypto Abstraction layer structures.
* [Experimental] Users should note that the Structures can change
* as a part of ongoing development.
#include <device.h>
#include <misc/util.h>
enum cipher_algo {
enum cipher_op {
/* Possible cipher mode options. More to be
* added as required.
enum cipher_mode {
/* Forward declarations */
struct cipher_aead_pkt;
struct cipher_ctx;
struct cipher_pkt;
typedef int (*block_op_t)(struct cipher_ctx *ctx, struct cipher_pkt *pkt);
/* Function signatures for encryption/ decryption using standard cipher modes
* like CBC, CTR, CCM.
typedef int (*cbc_op_t)(struct cipher_ctx *ctx, struct cipher_pkt *pkt,
u8_t *iv);
typedef int (*ctr_op_t)(struct cipher_ctx *ctx, struct cipher_pkt *pkt,
u8_t *ctr);
typedef int (*ccm_op_t)(struct cipher_ctx *ctx, struct cipher_aead_pkt *pkt,
u8_t *nonce);
struct cipher_ops {
enum cipher_mode cipher_mode;
union {
block_op_t block_crypt_hndlr;
cbc_op_t cbc_crypt_hndlr;
ctr_op_t ctr_crypt_hndlr;
ccm_op_t ccm_crypt_hndlr;
struct ccm_params {
u16_t tag_len;
u16_t nonce_len;
struct ctr_params {
/* CTR mode counter is a split counter composed of iv and counter
* such that ivlen + ctr_len = keylen
u32_t ctr_len;
/* 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.
struct cipher_ctx {
/* 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.
struct cipher_ops ops;
/* To be populated by the app before calling begin_session() */
union {
/* Cryptographic key to be used in this session */
u8_t *bit_stream;
/* For cases where key is protected and is not
* available to caller
void *handle;
} key;
/* The device driver instance this crypto context relates to. Will be
* populated by the begin_session() API.
struct device *device;
/* 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 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 *drv_sessn_state;
/* Place for the app to put info relevant stuff for resuming when
* completion call back happens for async ops. Totally managed by the
* app.
void *app_sessn_state;
/* Standard mode parameters, which remain constant for all ops
* in a session. To be populated by the app before calling
* begin_session()
union {
struct ccm_params ccm_info;
struct ctr_params ctr_info;
} mode_params;
/* Cryptographic keylength in bytes. To be populated by the app
* before calling begin_session()
u16_t keylen;
/* How certain fields are to be interpreted for this sesssion.
* To be populated by the app before calling begin_session().
* An app can obtain the capability flags supported by a hw/driver
* by calling cipher_query_hwcaps(). (A bitmask of CAP_* below)
u16_t flags;
/* Various cipher_ctx.flags options. Not all drivers support all flags.
* An app can query the supported hw / driver
* capabilities via provided API (cipher_query_hwcaps()), and choose a
* supported config during the session setup.
#define CAP_RAW_KEY BIT(1)
/* TBD to define */
/* Whether the output is placed in separate buffer or not */
/* 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
#define CAP_SYNC_OPS BIT(5)
#define CAP_ASYNC_OPS BIT(6)
/* Whether the hardware/driver supports autononce feature */
/* More flags to be added as necessary */
/* 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_pkt {
/* Start address of Input buffer */
u8_t *in_buf;
/* Bytes to be operated upon */
int in_len;
/* 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
u8_t *out_buf;
/* Size of the out_buf area allocated by the application. Drivers should
* not write past the size of output buffer
int out_buf_max;
/* To be populated by driver on return from cipher_xxx_op() and
* holds the size of the actual result
int out_len;
/* Context this packet relates to. This can be useful to get the
* session details esp for async ops. Will be populated by the
* cipher_xxx_op() API based on the ctx parameter
struct cipher_ctx *ctx;
/* 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.
struct cipher_aead_pkt {
/* IO buffers for Encryption. This has to be supplied by the app */
struct cipher_pkt *pkt;
/* Start address for Associated data. This has to be supplied by app */
u8_t *ad;
/* Size of Associated data. This has to be supplied by the app */
u32_t ad_len;
/* 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.
u8_t *tag;
/* Prototype for the application function to be invoked by the crypto driver
* on completion of an async request. The app may get the session context
* via the pkt->ctx field. For ccm ops the encopassing AEAD packet maybe
* accessed via container_of(). The type of a packet can be determined via
* pkt->ctx.ops.mode
typedef void (*crypto_completion_cb)(struct cipher_pkt *completed, int status);
#endif /* __CRYPTO_CIPHER_STRUCTS_H__ */