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_ */
|
