ChibiOS/HAL 9.0.0
hal_crypto.h
Go to the documentation of this file.
1/*
2 ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio
3
4 Licensed under the Apache License, Version 2.0 (the "License");
5 you may not use this file except in compliance with the License.
6 You may obtain a copy of the License at
7
8 http://www.apache.org/licenses/LICENSE-2.0
9
10 Unless required by applicable law or agreed to in writing, software
11 distributed under the License is distributed on an "AS IS" BASIS,
12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 See the License for the specific language governing permissions and
14 limitations under the License.
15*/
16
17/**
18 * @file hal_crypto.h
19 * @brief Cryptographic Driver macros and structures.
20 *
21 * @addtogroup CRYPTO
22 * @{
23 */
24
25#ifndef HAL_CRYPTO_H
26#define HAL_CRYPTO_H
27
28#if (HAL_USE_CRY == TRUE) || defined(__DOXYGEN__)
29
30/*===========================================================================*/
31/* Driver constants. */
32/*===========================================================================*/
33
34/*===========================================================================*/
35/* Driver pre-compile time settings. */
36/*===========================================================================*/
37
38/**
39 * @brief Enables the SW fall-back of the cryptographic driver.
40 * @details When enabled, this option, activates a fall-back software
41 * implementation for algorithms not supported by the underlying
42 * hardware.
43 * @note Fall-back implementations may not be present for all algorithms.
44 */
45#if !defined(HAL_CRY_USE_FALLBACK) || defined(__DOXYGEN__)
46#define HAL_CRY_USE_FALLBACK FALSE
47#endif
48
49/**
50 * @brief Makes the driver forcibly use the fall-back implementations.
51 * @note If enabled then the LLD driver is not included at all.
52 */
53#if !defined(HAL_CRY_ENFORCE_FALLBACK) || defined(__DOXYGEN__)
54#define HAL_CRY_ENFORCE_FALLBACK FALSE
55#endif
56
57/*===========================================================================*/
58/* Derived constants and error checks. */
59/*===========================================================================*/
60
61#if HAL_CRY_ENFORCE_FALLBACK == TRUE
62#undef HAL_CRY_USE_FALLBACK
63#define HAL_CRY_USE_FALLBACK TRUE
64#endif
65
66/*===========================================================================*/
67/* Driver data structures and types. */
68/*===========================================================================*/
69
70/**
71 * @brief Size, in bits, of a crypto field or message.
72 * @note It is assumed, for simplicity, that this type is equivalent to
73 * a @p size_t.
74 */
75typedef size_t bitsize_t;
76
77/**
78 * @brief Driver state machine possible states.
79 */
80typedef enum {
81 CRY_UNINIT = 0, /**< Not initialized. */
82 CRY_STOP = 1, /**< Stopped. */
83 CRY_READY = 2 /**< Ready. */
85
86/**
87 * @brief Driver error codes.
88 */
89typedef enum {
90 CRY_NOERROR = 0, /**< No error. */
91 CRY_ERR_INV_ALGO = 1, /**< Invalid cypher/mode. */
92 CRY_ERR_INV_KEY_SIZE = 2, /**< Invalid key size. */
93 CRY_ERR_INV_KEY_TYPE = 3, /**< Invalid key type. */
94 CRY_ERR_INV_KEY_ID = 4, /**< Invalid key identifier. */
95 CRY_ERR_AUTH_FAILED = 5, /**< Failed authentication. */
96 CRY_ERR_OP_FAILURE = 6 /**< Failed operation. */
98
99/**
100 * @brief Type of an algorithm identifier.
101 * @note It is only used to determine the key required for operations.
102 */
103typedef enum {
105 cry_algo_aes, /**< AES 128, 192, 256 bits. */
106 cry_algo_des, /**< DES 56, TDES 112, 168 bits.*/
107 cry_algo_hmac /**< HMAC variable size. */
109
110#if HAL_CRY_ENFORCE_FALLBACK == FALSE
111/* Use the defined low level driver.*/
112#include "hal_crypto_lld.h"
113
114#if !defined(CRY_LLD_SUPPORTS_AES) || \
115 !defined(CRY_LLD_SUPPORTS_AES_ECB) || \
116 !defined(CRY_LLD_SUPPORTS_AES_CBC) || \
117 !defined(CRY_LLD_SUPPORTS_AES_CFB) || \
118 !defined(CRY_LLD_SUPPORTS_AES_CTR) || \
119 !defined(CRY_LLD_SUPPORTS_AES_GCM) || \
120 !defined(CRY_LLD_SUPPORTS_DES) || \
121 !defined(CRY_LLD_SUPPORTS_DES_ECB) || \
122 !defined(CRY_LLD_SUPPORTS_DES_CBC) || \
123 !defined(CRY_LLD_SUPPORTS_SHA1) || \
124 !defined(CRY_LLD_SUPPORTS_SHA256) || \
125 !defined(CRY_LLD_SUPPORTS_SHA512) || \
126 !defined(CRY_LLD_SUPPORTS_HMAC_SHA256) || \
127 !defined(CRY_LLD_SUPPORTS_HMAC_SHA512)
128#error "CRYPTO LLD does not export the required switches"
129#endif
130
131#else /* HAL_CRY_ENFORCE_FALLBACK == TRUE */
132/* No LLD at all, using the standalone mode.*/
133
134#define CRY_LLD_SUPPORTS_AES FALSE
135#define CRY_LLD_SUPPORTS_AES_ECB FALSE
136#define CRY_LLD_SUPPORTS_AES_CBC FALSE
137#define CRY_LLD_SUPPORTS_AES_CFB FALSE
138#define CRY_LLD_SUPPORTS_AES_CTR FALSE
139#define CRY_LLD_SUPPORTS_AES_GCM FALSE
140#define CRY_LLD_SUPPORTS_DES FALSE
141#define CRY_LLD_SUPPORTS_DES_ECB FALSE
142#define CRY_LLD_SUPPORTS_DES_CBC FALSE
143#define CRY_LLD_SUPPORTS_SHA1 FALSE
144#define CRY_LLD_SUPPORTS_SHA256 FALSE
145#define CRY_LLD_SUPPORTS_SHA512 FALSE
146#define CRY_LLD_SUPPORTS_HMAC_SHA256 FALSE
147#define CRY_LLD_SUPPORTS_HMAC_SHA512 FALSE
148
149typedef uint_fast8_t crykey_t;
150
151typedef struct CRYDriver CRYDriver;
152
153typedef struct {
154 uint32_t dummy;
155} CRYConfig;
156
157struct CRYDriver {
159 const CRYConfig *config;
160};
161#endif /* HAL_CRY_ENFORCE_FALLBACK == TRUE */
162
163/* The fallback header is included only if required by settings.*/
164#if HAL_CRY_USE_FALLBACK == TRUE
165#include "hal_crypto_fallback.h"
166#endif
167
168#if (HAL_CRY_USE_FALLBACK == FALSE) && (CRY_LLD_SUPPORTS_SHA1 == FALSE)
169/* Stub @p SHA1Context structure type declaration. It is not provided by
170 the LLD and the fallback is not enabled.*/
171typedef struct {
172 uint32_t dummy;
174#endif
175
176#if (HAL_CRY_USE_FALLBACK == FALSE) && (CRY_LLD_SUPPORTS_SHA256 == FALSE)
177/* Stub @p SHA256Context structure type declaration. It is not provided by
178 the LLD and the fallback is not enabled.*/
179typedef struct {
180 uint32_t dummy;
182#endif
183
184#if (HAL_CRY_USE_FALLBACK == FALSE) && (CRY_LLD_SUPPORTS_SHA512 == FALSE)
185/* Stub @p SHA512Context structure type declaration. It is not provided by
186 the LLD and the fallback is not enabled.*/
187typedef struct {
188 uint32_t dummy;
190#endif
191
192#if (HAL_CRY_USE_FALLBACK == FALSE) && (CRY_LLD_SUPPORTS_HMAC_SHA256 == FALSE)
193/* Stub @p HMACSHA256Context structure type declaration. It is not provided by
194 the LLD and the fallback is not enabled.*/
195typedef struct {
196 uint32_t dummy;
198#endif
199
200#if (HAL_CRY_USE_FALLBACK == FALSE) && (CRY_LLD_SUPPORTS_HMAC_SHA512 == FALSE)
201/* Stub @p HMACSHA512Context structure type declaration. It is not provided by
202 the LLD and the fallback is not enabled.*/
203typedef struct {
204 uint32_t dummy;
206#endif
207
208/*===========================================================================*/
209/* Driver macros. */
210/*===========================================================================*/
211
212/**
213 * @name Low level driver helper macros
214 * @{
215 */
216/** @} */
217
218/*===========================================================================*/
219/* External declarations. */
220/*===========================================================================*/
221
222#ifdef __cplusplus
223extern "C" {
224#endif
225 void cryInit(void);
226 void cryObjectInit(CRYDriver *cryp);
227 msg_t cryStart(CRYDriver *cryp, const CRYConfig *config);
228 void cryStop(CRYDriver *cryp);
230 size_t size,
231 const uint8_t *keyp);
233 crykey_t key_id,
234 const uint8_t *in,
235 uint8_t *out);
237 crykey_t key_id,
238 const uint8_t *in,
239 uint8_t *out);
241 crykey_t key_id,
242 size_t size,
243 const uint8_t *in,
244 uint8_t *out);
246 crykey_t key_id,
247 size_t size,
248 const uint8_t *in,
249 uint8_t *out);
251 crykey_t key_id,
252 size_t size,
253 const uint8_t *in,
254 uint8_t *out,
255 const uint8_t *iv);
257 crykey_t key_id,
258 size_t size,
259 const uint8_t *in,
260 uint8_t *out,
261 const uint8_t *iv);
263 crykey_t key_id,
264 size_t size,
265 const uint8_t *in,
266 uint8_t *out,
267 const uint8_t *iv);
269 crykey_t key_id,
270 size_t size,
271 const uint8_t *in,
272 uint8_t *out,
273 const uint8_t *iv);
275 crykey_t key_id,
276 size_t size,
277 const uint8_t *in,
278 uint8_t *out,
279 const uint8_t *iv);
281 crykey_t key_id,
282 size_t size,
283 const uint8_t *in,
284 uint8_t *out,
285 const uint8_t *iv);
287 crykey_t key_id,
288 size_t auth_size,
289 const uint8_t *auth_in,
290 size_t text_size,
291 const uint8_t *text_in,
292 uint8_t *text_out,
293 const uint8_t *iv,
294 size_t tag_size,
295 uint8_t *tag_out);
297 crykey_t key_id,
298 size_t auth_size,
299 const uint8_t *auth_in,
300 size_t text_size,
301 const uint8_t *text_in,
302 uint8_t *text_out,
303 const uint8_t *iv,
304 size_t tag_size,
305 const uint8_t *tag_in);
307 size_t size,
308 const uint8_t *keyp);
310 crykey_t key_id,
311 const uint8_t *in,
312 uint8_t *out);
314 crykey_t key_id,
315 const uint8_t *in,
316 uint8_t *out);
318 crykey_t key_id,
319 size_t size,
320 const uint8_t *in,
321 uint8_t *out);
323 crykey_t key_id,
324 size_t size,
325 const uint8_t *in,
326 uint8_t *out);
328 crykey_t key_id,
329 size_t size,
330 const uint8_t *in,
331 uint8_t *out,
332 const uint8_t *iv);
334 crykey_t key_id,
335 size_t size,
336 const uint8_t *in,
337 uint8_t *out,
338 const uint8_t *iv);
341 size_t size, const uint8_t *in);
343 uint8_t *out);
346 size_t size, const uint8_t *in);
348 uint8_t *out);
351 size_t size, const uint8_t *in);
353 uint8_t *out);
355 size_t size,
356 const uint8_t *keyp);
358 HMACSHA256Context *hmacsha256ctxp);
360 HMACSHA256Context *hmacsha256ctxp,
361 size_t size,
362 const uint8_t *in);
364 HMACSHA256Context *hmacsha256ctxp,
365 uint8_t *out);
367 HMACSHA512Context *hmacsha512ctxp);
369 HMACSHA512Context *hmacsha512ctxp,
370 size_t size,
371 const uint8_t *in);
373 HMACSHA512Context *hmacsha512ctxp,
374 uint8_t *out);
375#ifdef __cplusplus
376}
377#endif
378
379#endif /* HAL_USE_CRYPTO == TRUE */
380
381#endif /* HAL_CRYPTO_H */
382
383/** @} */
cryerror_t crySHA256Update(CRYDriver *cryp, SHA256Context *sha256ctxp, size_t size, const uint8_t *in)
Hash update using SHA256.
cryerror_t cryDecryptDES(CRYDriver *cryp, crykey_t key_id, const uint8_t *in, uint8_t *out)
Decryption of a single block using (T)DES.
Definition hal_crypto.c:948
cryerror_t crySHA512Final(CRYDriver *cryp, SHA512Context *sha512ctxp, uint8_t *out)
Hash finalization using SHA512.
cryerror_t crySHA512Update(CRYDriver *cryp, SHA512Context *sha512ctxp, size_t size, const uint8_t *in)
Hash update using SHA512.
cryerror_t cryEncryptAES(CRYDriver *cryp, crykey_t key_id, const uint8_t *in, uint8_t *out)
Encryption of a single block using AES.
Definition hal_crypto.c:205
cryerror_t cryEncryptAES_GCM(CRYDriver *cryp, crykey_t key_id, size_t auth_size, const uint8_t *auth_in, size_t text_size, const uint8_t *text_in, uint8_t *text_out, const uint8_t *iv, size_t tag_size, uint8_t *tag_out)
Encryption operation using AES-GCM.
Definition hal_crypto.c:727
cryerror_t cryEncryptDES_ECB(CRYDriver *cryp, crykey_t key_id, size_t size, const uint8_t *in, uint8_t *out)
Encryption operation using (T)DES-ECB.
Definition hal_crypto.c:997
cryerror_t cryEncryptAES_ECB(CRYDriver *cryp, crykey_t key_id, size_t size, const uint8_t *in, uint8_t *out)
Encryption operation using AES-ECB.
Definition hal_crypto.c:300
cryalgorithm_t
Type of an algorithm identifier.
Definition hal_crypto.h:103
cryerror_t cryDecryptDES_CBC(CRYDriver *cryp, crykey_t key_id, size_t size, const uint8_t *in, uint8_t *out, const uint8_t *iv)
Decryption operation using (T)DES-CBC.
cryerror_t crySHA1Init(CRYDriver *cryp, SHA1Context *sha1ctxp)
Hash initialization using SHA1.
cryerror_t cryEncryptAES_CBC(CRYDriver *cryp, crykey_t key_id, size_t size, const uint8_t *in, uint8_t *out, const uint8_t *iv)
Encryption operation using AES-CBC.
Definition hal_crypto.c:405
cryerror_t cryHMACSHA512Init(CRYDriver *cryp, HMACSHA512Context *hmacsha512ctxp)
Hash initialization using HMAC_SHA512.
cryerror_t cryHMACSHA256Update(CRYDriver *cryp, HMACSHA256Context *hmacsha256ctxp, size_t size, const uint8_t *in)
Hash update using HMAC.
cryerror_t cryDecryptAES_GCM(CRYDriver *cryp, crykey_t key_id, size_t auth_size, const uint8_t *auth_in, size_t text_size, const uint8_t *text_in, uint8_t *text_out, const uint8_t *iv, size_t tag_size, const uint8_t *tag_in)
Decryption operation using AES-GCM.
Definition hal_crypto.c:800
cryerror_t cryLoadDESTransientKey(CRYDriver *cryp, size_t size, const uint8_t *keyp)
Initializes the DES transient key.
Definition hal_crypto.c:859
cryerror_t cryDecryptAES(CRYDriver *cryp, crykey_t key_id, const uint8_t *in, uint8_t *out)
Decryption of a single block using AES.
Definition hal_crypto.c:251
void cryObjectInit(CRYDriver *cryp)
Initializes the standard part of a CRYDriver structure.
Definition hal_crypto.c:70
size_t bitsize_t
Size, in bits, of a crypto field or message.
Definition hal_crypto.h:75
cryerror_t cryDecryptAES_CFB(CRYDriver *cryp, crykey_t key_id, size_t size, const uint8_t *in, uint8_t *out, const uint8_t *iv)
Decryption operation using AES-CFB.
Definition hal_crypto.c:564
cryerror_t cryEncryptAES_CFB(CRYDriver *cryp, crykey_t key_id, size_t size, const uint8_t *in, uint8_t *out, const uint8_t *iv)
Encryption operation using AES-CFB.
Definition hal_crypto.c:512
uint32_t crykey_t
CRY key identifier type.
cryerror_t cryDecryptDES_ECB(CRYDriver *cryp, crykey_t key_id, size_t size, const uint8_t *in, uint8_t *out)
Decryption operation using (T)DES-ECB.
cryerror_t cryEncryptAES_CTR(CRYDriver *cryp, crykey_t key_id, size_t size, const uint8_t *in, uint8_t *out, const uint8_t *iv)
Encryption operation using AES-CTR.
Definition hal_crypto.c:617
cryerror_t cryDecryptAES_CBC(CRYDriver *cryp, crykey_t key_id, size_t size, const uint8_t *in, uint8_t *out, const uint8_t *iv)
Decryption operation using AES-CBC.
Definition hal_crypto.c:460
cryerror_t crySHA1Update(CRYDriver *cryp, SHA1Context *sha1ctxp, size_t size, const uint8_t *in)
Hash update using SHA1.
cryerror_t cryHMACSHA512Final(CRYDriver *cryp, HMACSHA512Context *hmacsha512ctxp, uint8_t *out)
Hash finalization using HMAC.
void cryInit(void)
Cryptographic Driver initialization.
Definition hal_crypto.c:56
cryerror_t crySHA256Final(CRYDriver *cryp, SHA256Context *sha256ctxp, uint8_t *out)
Hash finalization using SHA256.
crystate_t
Driver state machine possible states.
Definition hal_crypto.h:80
cryerror_t cryDecryptAES_CTR(CRYDriver *cryp, crykey_t key_id, size_t size, const uint8_t *in, uint8_t *out, const uint8_t *iv)
Decryption operation using AES-CTR.
Definition hal_crypto.c:670
cryerror_t cryLoadHMACTransientKey(CRYDriver *cryp, size_t size, const uint8_t *keyp)
Initializes the HMAC transient key.
cryerror_t cryHMACSHA256Final(CRYDriver *cryp, HMACSHA256Context *hmacsha256ctxp, uint8_t *out)
Hash finalization using HMAC.
cryerror_t crySHA1Final(CRYDriver *cryp, SHA1Context *sha1ctxp, uint8_t *out)
Hash finalization using SHA1.
cryerror_t crySHA256Init(CRYDriver *cryp, SHA256Context *sha256ctxp)
Hash initialization using SHA256.
cryerror_t
Driver error codes.
Definition hal_crypto.h:89
cryerror_t crySHA512Init(CRYDriver *cryp, SHA512Context *sha512ctxp)
Hash initialization using SHA512.
void cryStop(CRYDriver *cryp)
Deactivates the cryptographic peripheral.
Definition hal_crypto.c:129
cryerror_t cryHMACSHA512Update(CRYDriver *cryp, HMACSHA512Context *hmacsha512ctxp, size_t size, const uint8_t *in)
Hash update using HMAC.
cryerror_t cryLoadAESTransientKey(CRYDriver *cryp, size_t size, const uint8_t *keyp)
Initializes the AES transient key.
Definition hal_crypto.c:163
cryerror_t cryDecryptAES_ECB(CRYDriver *cryp, crykey_t key_id, size_t size, const uint8_t *in, uint8_t *out)
Decryption operation using AES-ECB.
Definition hal_crypto.c:352
cryerror_t cryEncryptDES_CBC(CRYDriver *cryp, crykey_t key_id, size_t size, const uint8_t *in, uint8_t *out, const uint8_t *iv)
Encryption operation using (T)DES-CBC.
cryerror_t cryEncryptDES(CRYDriver *cryp, crykey_t key_id, const uint8_t *in, uint8_t *out)
Encryption of a single block using (T)DES.
Definition hal_crypto.c:901
msg_t cryStart(CRYDriver *cryp, const CRYConfig *config)
Configures and activates the cryptographic peripheral.
Definition hal_crypto.c:89
cryerror_t cryHMACSHA256Init(CRYDriver *cryp, HMACSHA256Context *hmacsha256ctxp)
Hash initialization using HMAC_SHA256.
@ cry_algo_none
Definition hal_crypto.h:104
@ cry_algo_des
Definition hal_crypto.h:106
@ cry_algo_aes
Definition hal_crypto.h:105
@ cry_algo_hmac
Definition hal_crypto.h:107
@ CRY_READY
Definition hal_crypto.h:83
@ CRY_UNINIT
Definition hal_crypto.h:81
@ CRY_STOP
Definition hal_crypto.h:82
@ CRY_ERR_INV_KEY_SIZE
Definition hal_crypto.h:92
@ CRY_ERR_AUTH_FAILED
Definition hal_crypto.h:95
@ CRY_NOERROR
Definition hal_crypto.h:90
@ CRY_ERR_INV_ALGO
Definition hal_crypto.h:91
@ CRY_ERR_OP_FAILURE
Definition hal_crypto.h:96
@ CRY_ERR_INV_KEY_ID
Definition hal_crypto.h:94
@ CRY_ERR_INV_KEY_TYPE
Definition hal_crypto.h:93
int32_t msg_t
Type of a message.
Definition osal.h:159
PLATFORM cryptographic subsystem low level driver header.
USBOutEndpointState out
OUT EP0 state.
Definition hal_usb_lld.c:61
USBInEndpointState in
IN EP0 state.
Definition hal_usb_lld.c:57
Driver configuration structure.
Structure representing an CRY driver.
const CRYConfig * config
Current configuration data.
crystate_t state
Driver state.
Type of a HMAC_SHA256 context.
Definition hal_crypto.h:195
Type of a HMAC_SHA512 context.
Definition hal_crypto.h:203
Type of a SHA1 context.
Definition hal_crypto.h:171
uint32_t dummy
Definition hal_crypto.h:172
Type of a SHA256 context.
Definition hal_crypto.h:179
uint32_t dummy
Definition hal_crypto.h:180
Type of a SHA512 context.
Definition hal_crypto.h:187
uint32_t dummy
Definition hal_crypto.h:188