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 enum cipher_algo { 30 CRYPTO_CIPHER_ALGO_AES = 1, 31 }; 32 33 /** Cipher Operation */ 34 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 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 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 typedef int (*cbc_op_t)(struct cipher_ctx *ctx, struct cipher_pkt *pkt, 63 uint8_t *iv); 64 65 typedef int (*ctr_op_t)(struct cipher_ctx *ctx, struct cipher_pkt *pkt, 66 uint8_t *ctr); 67 68 typedef int (*ccm_op_t)(struct cipher_ctx *ctx, struct cipher_aead_pkt *pkt, 69 uint8_t *nonce); 70 71 typedef int (*gcm_op_t)(struct cipher_ctx *ctx, struct cipher_aead_pkt *pkt, 72 uint8_t *nonce); 73 74 struct cipher_ops { 75 76 enum cipher_mode cipher_mode; 77 78 union { 79 block_op_t block_crypt_hndlr; 80 cbc_op_t cbc_crypt_hndlr; 81 ctr_op_t ctr_crypt_hndlr; 82 ccm_op_t ccm_crypt_hndlr; 83 gcm_op_t gcm_crypt_hndlr; 84 }; 85 }; 86 87 struct ccm_params { 88 uint16_t tag_len; 89 uint16_t nonce_len; 90 }; 91 92 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 uint32_t ctr_len; 97 }; 98 99 struct gcm_params { 100 uint16_t tag_len; 101 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 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 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 const uint8_t *bit_stream; 122 /* For cases where key is protected and is not 123 * available to caller 124 */ 125 void *handle; 126 } key; 127 128 /** The device driver instance this crypto context relates to. Will be 129 * populated by the begin_session() API. 130 */ 131 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 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 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 struct ccm_params ccm_info; 154 struct ctr_params ctr_info; 155 struct gcm_params gcm_info; 156 } mode_params; 157 158 /** Cryptographic keylength in bytes. To be populated by the app 159 * before calling begin_session() 160 */ 161 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 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 struct cipher_pkt { 181 182 /** Start address of input buffer */ 183 uint8_t *in_buf; 184 185 /** Bytes to be operated upon */ 186 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 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 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 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 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 struct cipher_aead_pkt { 218 /* IO buffers for encryption. This has to be supplied by the app. */ 219 struct cipher_pkt *pkt; 220 221 /** 222 * Start address for Associated Data. This has to be supplied by app. 223 */ 224 uint8_t *ad; 225 226 /** Size of Associated Data. This has to be supplied by the app. */ 227 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 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 typedef void (*cipher_completion_cb)(struct cipher_pkt *completed, int status); 243 244 /** 245 * @} 246 */ 247 #endif /* ZEPHYR_INCLUDE_CRYPTO_CIPHER_H_ */ 248
