Zephyr Project API 3.7.0
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
crypto.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2016 Intel Corporation.
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 */
6
17#ifndef ZEPHYR_INCLUDE_CRYPTO_H_
18#define ZEPHYR_INCLUDE_CRYPTO_H_
19
20#include <zephyr/device.h>
21#include <errno.h>
22#include <zephyr/sys/util.h>
23#include <zephyr/sys/__assert.h>
24#include <zephyr/crypto/hash.h>
25#include "cipher.h"
26
37/* ctx.flags values. Not all drivers support all flags.
38 * A user app can query the supported hw / driver
39 * capabilities via provided API (crypto_query_hwcaps()), and choose a
40 * supported config during the session setup.
41 */
42#define CAP_OPAQUE_KEY_HNDL BIT(0)
43#define CAP_RAW_KEY BIT(1)
44
45/* TBD to define */
46#define CAP_KEY_LOADING_API BIT(2)
47
49#define CAP_INPLACE_OPS BIT(3)
50#define CAP_SEPARATE_IO_BUFS BIT(4)
51
56#define CAP_SYNC_OPS BIT(5)
57#define CAP_ASYNC_OPS BIT(6)
58
60#define CAP_AUTONONCE BIT(7)
61
63#define CAP_NO_IV_PREFIX BIT(8)
64
65/* More flags to be added as necessary */
66
68__subsystem struct crypto_driver_api {
69 int (*query_hw_caps)(const struct device *dev);
70
71 /* Setup a crypto session */
72 int (*cipher_begin_session)(const struct device *dev, struct cipher_ctx *ctx,
73 enum cipher_algo algo, enum cipher_mode mode,
74 enum cipher_op op_type);
75
76 /* Tear down an established session */
77 int (*cipher_free_session)(const struct device *dev, struct cipher_ctx *ctx);
78
79 /* Register async crypto op completion callback with the driver */
80 int (*cipher_async_callback_set)(const struct device *dev,
82
83 /* Setup a hash session */
84 int (*hash_begin_session)(const struct device *dev, struct hash_ctx *ctx,
85 enum hash_algo algo);
86 /* Tear down an established hash session */
87 int (*hash_free_session)(const struct device *dev, struct hash_ctx *ctx);
88 /* Register async hash op completion callback with the driver */
89 int (*hash_async_callback_set)(const struct device *dev,
91};
92
93/* Following are the public API a user app may call.
94 * The first two relate to crypto "session" setup / teardown. Further we
95 * have four cipher mode specific (CTR, CCM, CBC ...) calls to perform the
96 * actual crypto operation in the context of a session. Also we have an
97 * API to provide the callback for async operations.
98 */
99
111static inline int crypto_query_hwcaps(const struct device *dev)
112{
113 struct crypto_driver_api *api;
114 int tmp;
115
116 api = (struct crypto_driver_api *) dev->api;
117
118 tmp = api->query_hw_caps(dev);
119
120 __ASSERT((tmp & (CAP_OPAQUE_KEY_HNDL | CAP_RAW_KEY)) != 0,
121 "Driver should support at least one key type: RAW/Opaque");
122
123 __ASSERT((tmp & (CAP_INPLACE_OPS | CAP_SEPARATE_IO_BUFS)) != 0,
124 "Driver should support at least one IO buf type: Inplace/separate");
125
126 __ASSERT((tmp & (CAP_SYNC_OPS | CAP_ASYNC_OPS)) != 0,
127 "Driver should support at least one op-type: sync/async");
128 return tmp;
129
130}
131
162static inline int cipher_begin_session(const struct device *dev,
163 struct cipher_ctx *ctx,
164 enum cipher_algo algo,
165 enum cipher_mode mode,
166 enum cipher_op optype)
167{
168 struct crypto_driver_api *api;
170
171 api = (struct crypto_driver_api *) dev->api;
172 ctx->device = dev;
173 ctx->ops.cipher_mode = mode;
174
176 __ASSERT(flags != 0U, "Keytype missing: RAW Key or OPAQUE handle");
177 __ASSERT(flags != (CAP_OPAQUE_KEY_HNDL | CAP_RAW_KEY),
178 "conflicting options for keytype");
179
181 __ASSERT(flags != 0U, "IO buffer type missing");
183 "conflicting options for IO buffer type");
184
185 flags = (ctx->flags & (CAP_SYNC_OPS | CAP_ASYNC_OPS));
186 __ASSERT(flags != 0U, "sync/async type missing");
187 __ASSERT(flags != (CAP_SYNC_OPS | CAP_ASYNC_OPS),
188 "conflicting options for sync/async");
189
190 return api->cipher_begin_session(dev, ctx, algo, mode, optype);
191}
192
204static inline int cipher_free_session(const struct device *dev,
205 struct cipher_ctx *ctx)
206{
207 struct crypto_driver_api *api;
208
209 api = (struct crypto_driver_api *) dev->api;
210
211 return api->cipher_free_session(dev, ctx);
212}
213
228static inline int cipher_callback_set(const struct device *dev,
230{
231 struct crypto_driver_api *api;
232
233 api = (struct crypto_driver_api *) dev->api;
234
235 if (api->cipher_async_callback_set) {
236 return api->cipher_async_callback_set(dev, cb);
237 }
238
239 return -ENOTSUP;
240
241}
242
252static inline int cipher_block_op(struct cipher_ctx *ctx,
253 struct cipher_pkt *pkt)
254{
255 __ASSERT(ctx->ops.cipher_mode == CRYPTO_CIPHER_MODE_ECB, "ECB mode "
256 "session invoking a different mode handler");
257
258 pkt->ctx = ctx;
259 return ctx->ops.block_crypt_hndlr(ctx, pkt);
260}
261
273static inline int cipher_cbc_op(struct cipher_ctx *ctx,
274 struct cipher_pkt *pkt, uint8_t *iv)
275{
276 __ASSERT(ctx->ops.cipher_mode == CRYPTO_CIPHER_MODE_CBC, "CBC mode "
277 "session invoking a different mode handler");
278
279 pkt->ctx = ctx;
280 return ctx->ops.cbc_crypt_hndlr(ctx, pkt, iv);
281}
282
300static inline int cipher_ctr_op(struct cipher_ctx *ctx,
301 struct cipher_pkt *pkt, uint8_t *iv)
302{
303 __ASSERT(ctx->ops.cipher_mode == CRYPTO_CIPHER_MODE_CTR, "CTR mode "
304 "session invoking a different mode handler");
305
306 pkt->ctx = ctx;
307 return ctx->ops.ctr_crypt_hndlr(ctx, pkt, iv);
308}
309
322static inline int cipher_ccm_op(struct cipher_ctx *ctx,
323 struct cipher_aead_pkt *pkt, uint8_t *nonce)
324{
325 __ASSERT(ctx->ops.cipher_mode == CRYPTO_CIPHER_MODE_CCM, "CCM mode "
326 "session invoking a different mode handler");
327
328 pkt->pkt->ctx = ctx;
329 return ctx->ops.ccm_crypt_hndlr(ctx, pkt, nonce);
330}
331
344static inline int cipher_gcm_op(struct cipher_ctx *ctx,
345 struct cipher_aead_pkt *pkt, uint8_t *nonce)
346{
347 __ASSERT(ctx->ops.cipher_mode == CRYPTO_CIPHER_MODE_GCM, "GCM mode "
348 "session invoking a different mode handler");
349
350 pkt->pkt->ctx = ctx;
351 return ctx->ops.gcm_crypt_hndlr(ctx, pkt, nonce);
352}
353
354
384static inline int hash_begin_session(const struct device *dev,
385 struct hash_ctx *ctx,
386 enum hash_algo algo)
387{
389 struct crypto_driver_api *api;
390
391 api = (struct crypto_driver_api *) dev->api;
392 ctx->device = dev;
393
395 __ASSERT(flags != 0U, "IO buffer type missing");
397 "conflicting options for IO buffer type");
398
399 flags = (ctx->flags & (CAP_SYNC_OPS | CAP_ASYNC_OPS));
400 __ASSERT(flags != 0U, "sync/async type missing");
401 __ASSERT(flags != (CAP_SYNC_OPS | CAP_ASYNC_OPS),
402 "conflicting options for sync/async");
403
404
405 return api->hash_begin_session(dev, ctx, algo);
406}
407
419static inline int hash_free_session(const struct device *dev,
420 struct hash_ctx *ctx)
421{
422 struct crypto_driver_api *api;
423
424 api = (struct crypto_driver_api *) dev->api;
425
426 return api->hash_free_session(dev, ctx);
427}
428
443static inline int hash_callback_set(const struct device *dev,
445{
446 struct crypto_driver_api *api;
447
448 api = (struct crypto_driver_api *) dev->api;
449
450 if (api->hash_async_callback_set) {
451 return api->hash_async_callback_set(dev, cb);
452 }
453
454 return -ENOTSUP;
455
456}
457
466static inline int hash_compute(struct hash_ctx *ctx, struct hash_pkt *pkt)
467{
468 pkt->ctx = ctx;
469
470 return ctx->hash_hndlr(ctx, pkt, true);
471}
472
485static inline int hash_update(struct hash_ctx *ctx, struct hash_pkt *pkt)
486{
487 pkt->ctx = ctx;
488
489 return ctx->hash_hndlr(ctx, pkt, false);
490}
491
496#endif /* ZEPHYR_INCLUDE_CRYPTO_H_ */
Crypto Cipher structure definitions.
System error numbers.
static int cipher_block_op(struct cipher_ctx *ctx, struct cipher_pkt *pkt)
Perform single-block crypto operation (ECB cipher mode).
Definition crypto.h:252
void(* cipher_completion_cb)(struct cipher_pkt *completed, int status)
Definition cipher.h:242
static int cipher_begin_session(const struct device *dev, struct cipher_ctx *ctx, enum cipher_algo algo, enum cipher_mode mode, enum cipher_op optype)
Setup a crypto session.
Definition crypto.h:162
cipher_op
Cipher Operation.
Definition cipher.h:34
static int cipher_cbc_op(struct cipher_ctx *ctx, struct cipher_pkt *pkt, uint8_t *iv)
Perform Cipher Block Chaining (CBC) crypto operation.
Definition crypto.h:273
static int cipher_gcm_op(struct cipher_ctx *ctx, struct cipher_aead_pkt *pkt, uint8_t *nonce)
Perform Galois/Counter Mode (GCM) crypto operation.
Definition crypto.h:344
static int cipher_ccm_op(struct cipher_ctx *ctx, struct cipher_aead_pkt *pkt, uint8_t *nonce)
Perform Counter with CBC-MAC (CCM) mode crypto operation.
Definition crypto.h:322
cipher_algo
Cipher Algorithm.
Definition cipher.h:29
static int cipher_free_session(const struct device *dev, struct cipher_ctx *ctx)
Cleanup a crypto session.
Definition crypto.h:204
static int cipher_callback_set(const struct device *dev, cipher_completion_cb cb)
Registers an async crypto op completion callback with the driver.
Definition crypto.h:228
cipher_mode
Possible cipher mode options.
Definition cipher.h:44
static int cipher_ctr_op(struct cipher_ctx *ctx, struct cipher_pkt *pkt, uint8_t *iv)
Perform Counter (CTR) mode crypto operation.
Definition crypto.h:300
@ CRYPTO_CIPHER_MODE_GCM
Definition cipher.h:49
@ CRYPTO_CIPHER_MODE_ECB
Definition cipher.h:45
@ CRYPTO_CIPHER_MODE_CCM
Definition cipher.h:48
@ CRYPTO_CIPHER_MODE_CTR
Definition cipher.h:47
@ CRYPTO_CIPHER_MODE_CBC
Definition cipher.h:46
void(* hash_completion_cb)(struct hash_pkt *completed, int status)
Definition hash.h:114
static int hash_compute(struct hash_ctx *ctx, struct hash_pkt *pkt)
Perform a cryptographic hash function.
Definition crypto.h:466
static int hash_begin_session(const struct device *dev, struct hash_ctx *ctx, enum hash_algo algo)
Setup a hash session.
Definition crypto.h:384
static int hash_callback_set(const struct device *dev, hash_completion_cb cb)
Registers an async hash completion callback with the driver.
Definition crypto.h:443
hash_algo
Hash algorithm.
Definition hash.h:26
static int hash_free_session(const struct device *dev, struct hash_ctx *ctx)
Cleanup a hash session.
Definition crypto.h:419
static int hash_update(struct hash_ctx *ctx, struct hash_pkt *pkt)
Perform a cryptographic multipart hash operation.
Definition crypto.h:485
#define CAP_SYNC_OPS
These denotes if the output (completion of a cipher_xxx_op) is conveyed by the op function returning,...
Definition crypto.h:56
#define CAP_INPLACE_OPS
Whether the output is placed in separate buffer or not.
Definition crypto.h:49
#define CAP_ASYNC_OPS
Definition crypto.h:57
#define CAP_OPAQUE_KEY_HNDL
Definition crypto.h:42
#define CAP_SEPARATE_IO_BUFS
Definition crypto.h:50
#define CAP_RAW_KEY
Definition crypto.h:43
static int crypto_query_hwcaps(const struct device *dev)
Query the crypto hardware capabilities.
Definition crypto.h:111
#define ENOTSUP
Unsupported value.
Definition errno.h:114
Crypto Hash APIs.
flags
Definition parser.h:96
__UINT32_TYPE__ uint32_t
Definition stdint.h:90
__UINT8_TYPE__ uint8_t
Definition stdint.h:88
Structure encoding IO parameters in AEAD (Authenticated Encryption with Associated Data) scenario lik...
Definition cipher.h:217
struct cipher_pkt * pkt
Definition cipher.h:219
Structure encoding session parameters.
Definition cipher.h:110
const struct device * device
The device driver instance this crypto context relates to.
Definition cipher.h:131
uint16_t flags
How certain fields are to be interpreted for this session.
Definition cipher.h:169
struct cipher_ops ops
Place for driver to return function pointers to be invoked per cipher operation.
Definition cipher.h:116
block_op_t block_crypt_hndlr
Definition cipher.h:79
gcm_op_t gcm_crypt_hndlr
Definition cipher.h:83
enum cipher_mode cipher_mode
Definition cipher.h:76
cbc_op_t cbc_crypt_hndlr
Definition cipher.h:80
ctr_op_t ctr_crypt_hndlr
Definition cipher.h:81
ccm_op_t ccm_crypt_hndlr
Definition cipher.h:82
Structure encoding IO parameters of one cryptographic operation like encrypt/decrypt.
Definition cipher.h:180
struct cipher_ctx * ctx
Context this packet relates to.
Definition cipher.h:208
Crypto driver API definition.
Definition crypto.h:68
int(* query_hw_caps)(const struct device *dev)
Definition crypto.h:69
int(* cipher_async_callback_set)(const struct device *dev, cipher_completion_cb cb)
Definition crypto.h:80
int(* hash_begin_session)(const struct device *dev, struct hash_ctx *ctx, enum hash_algo algo)
Definition crypto.h:84
int(* cipher_free_session)(const struct device *dev, struct cipher_ctx *ctx)
Definition crypto.h:77
int(* hash_async_callback_set)(const struct device *dev, hash_completion_cb cb)
Definition crypto.h:89
int(* hash_free_session)(const struct device *dev, struct hash_ctx *ctx)
Definition crypto.h:87
int(* cipher_begin_session)(const struct device *dev, struct cipher_ctx *ctx, enum cipher_algo algo, enum cipher_mode mode, enum cipher_op op_type)
Definition crypto.h:72
Runtime device structure (in ROM) per driver instance.
Definition device.h:403
const void * api
Address of the API structure exposed by the device instance.
Definition device.h:409
Structure encoding session parameters.
Definition hash.h:47
hash_op_t hash_hndlr
Hash handler set up when the session begins.
Definition hash.h:65
uint16_t flags
How certain fields are to be interpreted for this session.
Definition hash.h:78
const struct device * device
The device driver instance this crypto context relates to.
Definition hash.h:51
Structure encoding IO parameters of a hash operation.
Definition hash.h:88
struct hash_ctx * ctx
Context this packet relates to.
Definition hash.h:107
Misc utilities.