Loading...
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 | /*
* 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 ZEPHYR_INCLUDE_CRYPTO_CIPHER_STRUCTS_H_
#define ZEPHYR_INCLUDE_CRYPTO_CIPHER_STRUCTS_H_
#include <device.h>
#include <sys/util.h>
/**
* @addtogroup crypto_cipher
* @{
*/
/** Cipher Algorithm */
enum cipher_algo {
CRYPTO_CIPHER_ALGO_AES = 1,
};
/** Cipher Operation */
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,
CRYPTO_CIPHER_MODE_GCM = 5,
};
/* 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,
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);
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;
gcm_op_t gcm_crypt_hndlr;
};
};
struct ccm_params {
uint16_t tag_len;
uint16_t nonce_len;
};
struct ctr_params {
/* CTR mode counter is a split counter composed of iv and counter
* such that ivlen + ctr_len = keylen
*/
uint32_t ctr_len;
};
struct gcm_params {
uint16_t tag_len;
uint16_t nonce_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 */
uint8_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.
*/
const 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 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 user app to put info relevant stuff for resuming when
* completion callback happens for async ops. Totally managed by the
* app.
*/
void *app_sessn_state;
/** Cypher 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;
struct gcm_params gcm_info;
} mode_params;
/** Cryptographic keylength in bytes. To be populated by the app
* before calling begin_session()
*/
uint16_t keylen;
/** How certain fields are to be interpreted for this session.
* (A bitmask of CAP_* below.)
* 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().
*/
uint16_t flags;
};
/* cipher_ctx.flags values. Not all drivers support all flags.
* A user 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)
/** Don't prefix IV to cipher blocks */
#define CAP_NO_IV_PREFIX BIT(8)
/* 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 */
uint8_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.
*/
uint8_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, especially 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.
*/
uint8_t *ad;
/** Size of Associated Data. This has to be supplied by the app. */
uint32_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.
*/
uint8_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 encompassing AEAD packet may be
* 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 /* ZEPHYR_INCLUDE_CRYPTO_CIPHER_STRUCTS_H_ */
|