Line data Source code
1 1 : /* 2 : * Copyright (c) 2016 Intel Corporation. 3 : * 4 : * SPDX-License-Identifier: Apache-2.0 5 : */ 6 : 7 : /** 8 : * @file 9 : * @brief Crypto Cipher structure definitions 10 : * 11 : * This file contains the Crypto Abstraction layer structures. 12 : * 13 : * [Experimental] Users should note that the Structures can change 14 : * as a part of ongoing development. 15 : */ 16 : 17 : #ifndef ZEPHYR_INCLUDE_CRYPTO_CIPHER_H_ 18 : #define ZEPHYR_INCLUDE_CRYPTO_CIPHER_H_ 19 : 20 : #include <zephyr/device.h> 21 : #include <zephyr/sys/util.h> 22 : /** 23 : * @addtogroup crypto_cipher 24 : * @{ 25 : */ 26 : 27 : 28 : /** Cipher Algorithm */ 29 0 : enum cipher_algo { 30 : CRYPTO_CIPHER_ALGO_AES = 1, 31 : }; 32 : 33 : /** Cipher Operation */ 34 0 : enum cipher_op { 35 : CRYPTO_CIPHER_OP_DECRYPT = 0, 36 : CRYPTO_CIPHER_OP_ENCRYPT = 1, 37 : }; 38 : 39 : /** 40 : * Possible cipher mode options. 41 : * 42 : * More to be added as required. 43 : */ 44 0 : enum cipher_mode { 45 : CRYPTO_CIPHER_MODE_ECB = 1, 46 : CRYPTO_CIPHER_MODE_CBC = 2, 47 : CRYPTO_CIPHER_MODE_CTR = 3, 48 : CRYPTO_CIPHER_MODE_CCM = 4, 49 : CRYPTO_CIPHER_MODE_GCM = 5, 50 : }; 51 : 52 : /* Forward declarations */ 53 : struct cipher_aead_pkt; 54 : struct cipher_ctx; 55 : struct cipher_pkt; 56 : 57 0 : typedef int (*block_op_t)(struct cipher_ctx *ctx, struct cipher_pkt *pkt); 58 : 59 : /* Function signatures for encryption/ decryption using standard cipher modes 60 : * like CBC, CTR, CCM. 61 : */ 62 0 : typedef int (*cbc_op_t)(struct cipher_ctx *ctx, struct cipher_pkt *pkt, 63 : uint8_t *iv); 64 : 65 0 : typedef int (*ctr_op_t)(struct cipher_ctx *ctx, struct cipher_pkt *pkt, 66 : uint8_t *ctr); 67 : 68 0 : typedef int (*ccm_op_t)(struct cipher_ctx *ctx, struct cipher_aead_pkt *pkt, 69 : uint8_t *nonce); 70 : 71 0 : typedef int (*gcm_op_t)(struct cipher_ctx *ctx, struct cipher_aead_pkt *pkt, 72 : uint8_t *nonce); 73 : 74 0 : struct cipher_ops { 75 : 76 0 : enum cipher_mode cipher_mode; 77 : 78 : union { 79 0 : block_op_t block_crypt_hndlr; 80 0 : cbc_op_t cbc_crypt_hndlr; 81 0 : ctr_op_t ctr_crypt_hndlr; 82 0 : ccm_op_t ccm_crypt_hndlr; 83 0 : gcm_op_t gcm_crypt_hndlr; 84 0 : }; 85 : }; 86 : 87 0 : struct ccm_params { 88 0 : uint16_t tag_len; 89 0 : uint16_t nonce_len; 90 : }; 91 : 92 0 : struct ctr_params { 93 : /* CTR mode counter is a split counter composed of iv and counter 94 : * such that ivlen + ctr_len = keylen 95 : */ 96 0 : uint32_t ctr_len; 97 : }; 98 : 99 0 : struct gcm_params { 100 0 : uint16_t tag_len; 101 0 : uint16_t nonce_len; 102 : }; 103 : 104 : /** 105 : * Structure encoding session parameters. 106 : * 107 : * Refer to comments for individual fields to know the contract 108 : * in terms of who fills what and when w.r.t begin_session() call. 109 : */ 110 1 : struct cipher_ctx { 111 : 112 : /** Place for driver to return function pointers to be invoked per 113 : * cipher operation. To be populated by crypto driver on return from 114 : * begin_session() based on the algo/mode chosen by the app. 115 : */ 116 1 : struct cipher_ops ops; 117 : 118 : /** To be populated by the app before calling begin_session() */ 119 : union { 120 : /* Cryptographic key to be used in this session */ 121 0 : const uint8_t *bit_stream; 122 : /* For cases where key is protected and is not 123 : * available to caller 124 : */ 125 0 : void *handle; 126 1 : } key; 127 : 128 : /** The device driver instance this crypto context relates to. Will be 129 : * populated by the begin_session() API. 130 : */ 131 1 : const struct device *device; 132 : 133 : /** If the driver supports multiple simultaneously crypto sessions, this 134 : * will identify the specific driver state this crypto session relates 135 : * to. Since dynamic memory allocation is not possible, it is 136 : * suggested that at build time drivers allocate space for the 137 : * max simultaneous sessions they intend to support. To be populated 138 : * by the driver on return from begin_session(). 139 : */ 140 1 : void *drv_sessn_state; 141 : 142 : /** Place for the user app to put info relevant stuff for resuming when 143 : * completion callback happens for async ops. Totally managed by the 144 : * app. 145 : */ 146 1 : void *app_sessn_state; 147 : 148 : /** Cypher mode parameters, which remain constant for all ops 149 : * in a session. To be populated by the app before calling 150 : * begin_session(). 151 : */ 152 : union { 153 0 : struct ccm_params ccm_info; 154 0 : struct ctr_params ctr_info; 155 0 : struct gcm_params gcm_info; 156 1 : } mode_params; 157 : 158 : /** Cryptographic keylength in bytes. To be populated by the app 159 : * before calling begin_session() 160 : */ 161 1 : uint16_t keylen; 162 : 163 : /** How certain fields are to be interpreted for this session. 164 : * (A bitmask of CAP_* below.) 165 : * To be populated by the app before calling begin_session(). 166 : * An app can obtain the capability flags supported by a hw/driver 167 : * by calling crypto_query_hwcaps(). 168 : */ 169 1 : uint16_t flags; 170 : }; 171 : 172 : /** 173 : * Structure encoding IO parameters of one cryptographic 174 : * operation like encrypt/decrypt. 175 : * 176 : * The fields which has not been explicitly called out has to 177 : * be filled up by the app before making the cipher_xxx_op() 178 : * call. 179 : */ 180 1 : struct cipher_pkt { 181 : 182 : /** Start address of input buffer */ 183 1 : uint8_t *in_buf; 184 : 185 : /** Bytes to be operated upon */ 186 1 : int in_len; 187 : 188 : /** Start of the output buffer, to be allocated by 189 : * the application. Can be NULL for in-place ops. To be populated 190 : * with contents by the driver on return from op / async callback. 191 : */ 192 1 : uint8_t *out_buf; 193 : 194 : /** Size of the out_buf area allocated by the application. Drivers 195 : * should not write past the size of output buffer. 196 : */ 197 1 : int out_buf_max; 198 : 199 : /** To be populated by driver on return from cipher_xxx_op() and 200 : * holds the size of the actual result. 201 : */ 202 1 : int out_len; 203 : 204 : /** Context this packet relates to. This can be useful to get the 205 : * session details, especially for async ops. Will be populated by the 206 : * cipher_xxx_op() API based on the ctx parameter. 207 : */ 208 1 : struct cipher_ctx *ctx; 209 : }; 210 : 211 : /** 212 : * Structure encoding IO parameters in AEAD (Authenticated Encryption 213 : * with Associated Data) scenario like in CCM. 214 : * 215 : * App has to furnish valid contents prior to making cipher_ccm_op() call. 216 : */ 217 1 : struct cipher_aead_pkt { 218 : /* IO buffers for encryption. This has to be supplied by the app. */ 219 0 : struct cipher_pkt *pkt; 220 : 221 : /** 222 : * Start address for Associated Data. This has to be supplied by app. 223 : */ 224 1 : uint8_t *ad; 225 : 226 : /** Size of Associated Data. This has to be supplied by the app. */ 227 1 : uint32_t ad_len; 228 : 229 : /** Start address for the auth hash. For an encryption op this will 230 : * be populated by the driver when it returns from cipher_ccm_op call. 231 : * For a decryption op this has to be supplied by the app. 232 : */ 233 1 : uint8_t *tag; 234 : }; 235 : 236 : /* Prototype for the application function to be invoked by the crypto driver 237 : * on completion of an async request. The app may get the session context 238 : * via the pkt->ctx field. For CCM ops the encompassing AEAD packet may be 239 : * accessed via container_of(). The type of a packet can be determined via 240 : * pkt->ctx.ops.mode . 241 : */ 242 0 : typedef void (*cipher_completion_cb)(struct cipher_pkt *completed, int status); 243 : 244 : /** 245 : * @} 246 : */ 247 : #endif /* ZEPHYR_INCLUDE_CRYPTO_CIPHER_H_ */
