| /* |
| * 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. |
| */ |
| |
| #ifndef __CRYPTO_CIPHER_STRUCTS_H__ |
| #define __CRYPTO_CIPHER_STRUCTS_H__ |
| |
| #include <device.h> |
| #include <misc/util.h> |
| |
| enum cipher_algo { |
| CRYPTO_CIPHER_ALGO_AES = 1, |
| }; |
| |
| enum cipher_op { |
| CRYPTO_CIPHER_OP_DECRYPT = 0, |
| CRYPTO_CIPHER_OP_ENCRYPT = 1, |
| }; |
| |
| /* Possible cipher mode options. More to be |
| * added as required. |
| */ |
| |
| enum cipher_mode { |
| CRYPTO_CIPHER_MODE_ECB = 1, |
| CRYPTO_CIPHER_MODE_CBC = 2, |
| CRYPTO_CIPHER_MODE_CTR = 3, |
| CRYPTO_CIPHER_MODE_CCM = 4, |
| }; |
| |
| /* 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_OPAQUE_KEY_HNDL BIT(0) |
| #define CAP_RAW_KEY BIT(1) |
| |
| /* TBD to define */ |
| #define CAP_KEY_LOADING_API BIT(2) |
| |
| /* Whether the output is placed in separate buffer or not */ |
| #define CAP_INPLACE_OPS BIT(3) |
| #define CAP_SEPARATE_IO_BUFS BIT(4) |
| |
| /* 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 */ |
| #define CAP_AUTONONCE BIT(7) |
| |
| |
| /* 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__ */ |