Line data Source code
1 : /* SPDX-License-Identifier: GPL-2.0-or-later */
2 : /*
3 : * Symmetric key ciphers.
4 : *
5 : * Copyright (c) 2007-2015 Herbert Xu <herbert@gondor.apana.org.au>
6 : */
7 :
8 : #ifndef _CRYPTO_SKCIPHER_H
9 : #define _CRYPTO_SKCIPHER_H
10 :
11 : #include <linux/crypto.h>
12 : #include <linux/kernel.h>
13 : #include <linux/slab.h>
14 :
15 : /**
16 : * struct skcipher_request - Symmetric key cipher request
17 : * @cryptlen: Number of bytes to encrypt or decrypt
18 : * @iv: Initialisation Vector
19 : * @src: Source SG list
20 : * @dst: Destination SG list
21 : * @base: Underlying async request
22 : * @__ctx: Start of private context data
23 : */
24 : struct skcipher_request {
25 : unsigned int cryptlen;
26 :
27 : u8 *iv;
28 :
29 : struct scatterlist *src;
30 : struct scatterlist *dst;
31 :
32 : struct crypto_async_request base;
33 :
34 : void *__ctx[] CRYPTO_MINALIGN_ATTR;
35 : };
36 :
37 : struct crypto_skcipher {
38 : unsigned int reqsize;
39 :
40 : struct crypto_tfm base;
41 : };
42 :
43 : struct crypto_sync_skcipher {
44 : struct crypto_skcipher base;
45 : };
46 :
47 : /**
48 : * struct skcipher_alg - symmetric key cipher definition
49 : * @min_keysize: Minimum key size supported by the transformation. This is the
50 : * smallest key length supported by this transformation algorithm.
51 : * This must be set to one of the pre-defined values as this is
52 : * not hardware specific. Possible values for this field can be
53 : * found via git grep "_MIN_KEY_SIZE" include/crypto/
54 : * @max_keysize: Maximum key size supported by the transformation. This is the
55 : * largest key length supported by this transformation algorithm.
56 : * This must be set to one of the pre-defined values as this is
57 : * not hardware specific. Possible values for this field can be
58 : * found via git grep "_MAX_KEY_SIZE" include/crypto/
59 : * @setkey: Set key for the transformation. This function is used to either
60 : * program a supplied key into the hardware or store the key in the
61 : * transformation context for programming it later. Note that this
62 : * function does modify the transformation context. This function can
63 : * be called multiple times during the existence of the transformation
64 : * object, so one must make sure the key is properly reprogrammed into
65 : * the hardware. This function is also responsible for checking the key
66 : * length for validity. In case a software fallback was put in place in
67 : * the @cra_init call, this function might need to use the fallback if
68 : * the algorithm doesn't support all of the key sizes.
69 : * @encrypt: Encrypt a scatterlist of blocks. This function is used to encrypt
70 : * the supplied scatterlist containing the blocks of data. The crypto
71 : * API consumer is responsible for aligning the entries of the
72 : * scatterlist properly and making sure the chunks are correctly
73 : * sized. In case a software fallback was put in place in the
74 : * @cra_init call, this function might need to use the fallback if
75 : * the algorithm doesn't support all of the key sizes. In case the
76 : * key was stored in transformation context, the key might need to be
77 : * re-programmed into the hardware in this function. This function
78 : * shall not modify the transformation context, as this function may
79 : * be called in parallel with the same transformation object.
80 : * @decrypt: Decrypt a single block. This is a reverse counterpart to @encrypt
81 : * and the conditions are exactly the same.
82 : * @init: Initialize the cryptographic transformation object. This function
83 : * is used to initialize the cryptographic transformation object.
84 : * This function is called only once at the instantiation time, right
85 : * after the transformation context was allocated. In case the
86 : * cryptographic hardware has some special requirements which need to
87 : * be handled by software, this function shall check for the precise
88 : * requirement of the transformation and put any software fallbacks
89 : * in place.
90 : * @exit: Deinitialize the cryptographic transformation object. This is a
91 : * counterpart to @init, used to remove various changes set in
92 : * @init.
93 : * @ivsize: IV size applicable for transformation. The consumer must provide an
94 : * IV of exactly that size to perform the encrypt or decrypt operation.
95 : * @chunksize: Equal to the block size except for stream ciphers such as
96 : * CTR where it is set to the underlying block size.
97 : * @walksize: Equal to the chunk size except in cases where the algorithm is
98 : * considerably more efficient if it can operate on multiple chunks
99 : * in parallel. Should be a multiple of chunksize.
100 : * @base: Definition of a generic crypto algorithm.
101 : *
102 : * All fields except @ivsize are mandatory and must be filled.
103 : */
104 : struct skcipher_alg {
105 : int (*setkey)(struct crypto_skcipher *tfm, const u8 *key,
106 : unsigned int keylen);
107 : int (*encrypt)(struct skcipher_request *req);
108 : int (*decrypt)(struct skcipher_request *req);
109 : int (*init)(struct crypto_skcipher *tfm);
110 : void (*exit)(struct crypto_skcipher *tfm);
111 :
112 : unsigned int min_keysize;
113 : unsigned int max_keysize;
114 : unsigned int ivsize;
115 : unsigned int chunksize;
116 : unsigned int walksize;
117 :
118 : struct crypto_alg base;
119 : };
120 :
121 : #define MAX_SYNC_SKCIPHER_REQSIZE 384
122 : /*
123 : * This performs a type-check against the "tfm" argument to make sure
124 : * all users have the correct skcipher tfm for doing on-stack requests.
125 : */
126 : #define SYNC_SKCIPHER_REQUEST_ON_STACK(name, tfm) \
127 : char __##name##_desc[sizeof(struct skcipher_request) + \
128 : MAX_SYNC_SKCIPHER_REQSIZE + \
129 : (!(sizeof((struct crypto_sync_skcipher *)1 == \
130 : (typeof(tfm))1))) \
131 : ] CRYPTO_MINALIGN_ATTR; \
132 : struct skcipher_request *name = (void *)__##name##_desc
133 :
134 : /**
135 : * DOC: Symmetric Key Cipher API
136 : *
137 : * Symmetric key cipher API is used with the ciphers of type
138 : * CRYPTO_ALG_TYPE_SKCIPHER (listed as type "skcipher" in /proc/crypto).
139 : *
140 : * Asynchronous cipher operations imply that the function invocation for a
141 : * cipher request returns immediately before the completion of the operation.
142 : * The cipher request is scheduled as a separate kernel thread and therefore
143 : * load-balanced on the different CPUs via the process scheduler. To allow
144 : * the kernel crypto API to inform the caller about the completion of a cipher
145 : * request, the caller must provide a callback function. That function is
146 : * invoked with the cipher handle when the request completes.
147 : *
148 : * To support the asynchronous operation, additional information than just the
149 : * cipher handle must be supplied to the kernel crypto API. That additional
150 : * information is given by filling in the skcipher_request data structure.
151 : *
152 : * For the symmetric key cipher API, the state is maintained with the tfm
153 : * cipher handle. A single tfm can be used across multiple calls and in
154 : * parallel. For asynchronous block cipher calls, context data supplied and
155 : * only used by the caller can be referenced the request data structure in
156 : * addition to the IV used for the cipher request. The maintenance of such
157 : * state information would be important for a crypto driver implementer to
158 : * have, because when calling the callback function upon completion of the
159 : * cipher operation, that callback function may need some information about
160 : * which operation just finished if it invoked multiple in parallel. This
161 : * state information is unused by the kernel crypto API.
162 : */
163 :
164 0 : static inline struct crypto_skcipher *__crypto_skcipher_cast(
165 : struct crypto_tfm *tfm)
166 : {
167 0 : return container_of(tfm, struct crypto_skcipher, base);
168 : }
169 :
170 : /**
171 : * crypto_alloc_skcipher() - allocate symmetric key cipher handle
172 : * @alg_name: is the cra_name / name or cra_driver_name / driver name of the
173 : * skcipher cipher
174 : * @type: specifies the type of the cipher
175 : * @mask: specifies the mask for the cipher
176 : *
177 : * Allocate a cipher handle for an skcipher. The returned struct
178 : * crypto_skcipher is the cipher handle that is required for any subsequent
179 : * API invocation for that skcipher.
180 : *
181 : * Return: allocated cipher handle in case of success; IS_ERR() is true in case
182 : * of an error, PTR_ERR() returns the error code.
183 : */
184 : struct crypto_skcipher *crypto_alloc_skcipher(const char *alg_name,
185 : u32 type, u32 mask);
186 :
187 : struct crypto_sync_skcipher *crypto_alloc_sync_skcipher(const char *alg_name,
188 : u32 type, u32 mask);
189 :
190 0 : static inline struct crypto_tfm *crypto_skcipher_tfm(
191 : struct crypto_skcipher *tfm)
192 : {
193 0 : return &tfm->base;
194 : }
195 :
196 : /**
197 : * crypto_free_skcipher() - zeroize and free cipher handle
198 : * @tfm: cipher handle to be freed
199 : */
200 0 : static inline void crypto_free_skcipher(struct crypto_skcipher *tfm)
201 : {
202 0 : crypto_destroy_tfm(tfm, crypto_skcipher_tfm(tfm));
203 : }
204 :
205 0 : static inline void crypto_free_sync_skcipher(struct crypto_sync_skcipher *tfm)
206 : {
207 0 : crypto_free_skcipher(&tfm->base);
208 : }
209 :
210 : /**
211 : * crypto_has_skcipher() - Search for the availability of an skcipher.
212 : * @alg_name: is the cra_name / name or cra_driver_name / driver name of the
213 : * skcipher
214 : * @type: specifies the type of the skcipher
215 : * @mask: specifies the mask for the skcipher
216 : *
217 : * Return: true when the skcipher is known to the kernel crypto API; false
218 : * otherwise
219 : */
220 : int crypto_has_skcipher(const char *alg_name, u32 type, u32 mask);
221 :
222 : static inline const char *crypto_skcipher_driver_name(
223 : struct crypto_skcipher *tfm)
224 : {
225 : return crypto_tfm_alg_driver_name(crypto_skcipher_tfm(tfm));
226 : }
227 :
228 0 : static inline struct skcipher_alg *crypto_skcipher_alg(
229 : struct crypto_skcipher *tfm)
230 : {
231 0 : return container_of(crypto_skcipher_tfm(tfm)->__crt_alg,
232 : struct skcipher_alg, base);
233 : }
234 :
235 : static inline unsigned int crypto_skcipher_alg_ivsize(struct skcipher_alg *alg)
236 : {
237 : return alg->ivsize;
238 : }
239 :
240 : /**
241 : * crypto_skcipher_ivsize() - obtain IV size
242 : * @tfm: cipher handle
243 : *
244 : * The size of the IV for the skcipher referenced by the cipher handle is
245 : * returned. This IV size may be zero if the cipher does not need an IV.
246 : *
247 : * Return: IV size in bytes
248 : */
249 0 : static inline unsigned int crypto_skcipher_ivsize(struct crypto_skcipher *tfm)
250 : {
251 0 : return crypto_skcipher_alg(tfm)->ivsize;
252 : }
253 :
254 : static inline unsigned int crypto_sync_skcipher_ivsize(
255 : struct crypto_sync_skcipher *tfm)
256 : {
257 : return crypto_skcipher_ivsize(&tfm->base);
258 : }
259 :
260 : /**
261 : * crypto_skcipher_blocksize() - obtain block size of cipher
262 : * @tfm: cipher handle
263 : *
264 : * The block size for the skcipher referenced with the cipher handle is
265 : * returned. The caller may use that information to allocate appropriate
266 : * memory for the data returned by the encryption or decryption operation
267 : *
268 : * Return: block size of cipher
269 : */
270 0 : static inline unsigned int crypto_skcipher_blocksize(
271 : struct crypto_skcipher *tfm)
272 : {
273 0 : return crypto_tfm_alg_blocksize(crypto_skcipher_tfm(tfm));
274 : }
275 :
276 : static inline unsigned int crypto_skcipher_alg_chunksize(
277 : struct skcipher_alg *alg)
278 : {
279 : return alg->chunksize;
280 : }
281 :
282 : /**
283 : * crypto_skcipher_chunksize() - obtain chunk size
284 : * @tfm: cipher handle
285 : *
286 : * The block size is set to one for ciphers such as CTR. However,
287 : * you still need to provide incremental updates in multiples of
288 : * the underlying block size as the IV does not have sub-block
289 : * granularity. This is known in this API as the chunk size.
290 : *
291 : * Return: chunk size in bytes
292 : */
293 : static inline unsigned int crypto_skcipher_chunksize(
294 : struct crypto_skcipher *tfm)
295 : {
296 : return crypto_skcipher_alg_chunksize(crypto_skcipher_alg(tfm));
297 : }
298 :
299 : static inline unsigned int crypto_sync_skcipher_blocksize(
300 : struct crypto_sync_skcipher *tfm)
301 : {
302 : return crypto_skcipher_blocksize(&tfm->base);
303 : }
304 :
305 0 : static inline unsigned int crypto_skcipher_alignmask(
306 : struct crypto_skcipher *tfm)
307 : {
308 0 : return crypto_tfm_alg_alignmask(crypto_skcipher_tfm(tfm));
309 : }
310 :
311 0 : static inline u32 crypto_skcipher_get_flags(struct crypto_skcipher *tfm)
312 : {
313 0 : return crypto_tfm_get_flags(crypto_skcipher_tfm(tfm));
314 : }
315 :
316 0 : static inline void crypto_skcipher_set_flags(struct crypto_skcipher *tfm,
317 : u32 flags)
318 : {
319 0 : crypto_tfm_set_flags(crypto_skcipher_tfm(tfm), flags);
320 0 : }
321 :
322 0 : static inline void crypto_skcipher_clear_flags(struct crypto_skcipher *tfm,
323 : u32 flags)
324 : {
325 0 : crypto_tfm_clear_flags(crypto_skcipher_tfm(tfm), flags);
326 : }
327 :
328 : static inline u32 crypto_sync_skcipher_get_flags(
329 : struct crypto_sync_skcipher *tfm)
330 : {
331 : return crypto_skcipher_get_flags(&tfm->base);
332 : }
333 :
334 : static inline void crypto_sync_skcipher_set_flags(
335 : struct crypto_sync_skcipher *tfm, u32 flags)
336 : {
337 : crypto_skcipher_set_flags(&tfm->base, flags);
338 : }
339 :
340 : static inline void crypto_sync_skcipher_clear_flags(
341 : struct crypto_sync_skcipher *tfm, u32 flags)
342 : {
343 : crypto_skcipher_clear_flags(&tfm->base, flags);
344 : }
345 :
346 : /**
347 : * crypto_skcipher_setkey() - set key for cipher
348 : * @tfm: cipher handle
349 : * @key: buffer holding the key
350 : * @keylen: length of the key in bytes
351 : *
352 : * The caller provided key is set for the skcipher referenced by the cipher
353 : * handle.
354 : *
355 : * Note, the key length determines the cipher type. Many block ciphers implement
356 : * different cipher modes depending on the key size, such as AES-128 vs AES-192
357 : * vs. AES-256. When providing a 16 byte key for an AES cipher handle, AES-128
358 : * is performed.
359 : *
360 : * Return: 0 if the setting of the key was successful; < 0 if an error occurred
361 : */
362 : int crypto_skcipher_setkey(struct crypto_skcipher *tfm,
363 : const u8 *key, unsigned int keylen);
364 :
365 : static inline int crypto_sync_skcipher_setkey(struct crypto_sync_skcipher *tfm,
366 : const u8 *key, unsigned int keylen)
367 : {
368 : return crypto_skcipher_setkey(&tfm->base, key, keylen);
369 : }
370 :
371 : static inline unsigned int crypto_skcipher_min_keysize(
372 : struct crypto_skcipher *tfm)
373 : {
374 : return crypto_skcipher_alg(tfm)->min_keysize;
375 : }
376 :
377 0 : static inline unsigned int crypto_skcipher_max_keysize(
378 : struct crypto_skcipher *tfm)
379 : {
380 0 : return crypto_skcipher_alg(tfm)->max_keysize;
381 : }
382 :
383 : /**
384 : * crypto_skcipher_reqtfm() - obtain cipher handle from request
385 : * @req: skcipher_request out of which the cipher handle is to be obtained
386 : *
387 : * Return the crypto_skcipher handle when furnishing an skcipher_request
388 : * data structure.
389 : *
390 : * Return: crypto_skcipher handle
391 : */
392 0 : static inline struct crypto_skcipher *crypto_skcipher_reqtfm(
393 : struct skcipher_request *req)
394 : {
395 0 : return __crypto_skcipher_cast(req->base.tfm);
396 : }
397 :
398 : static inline struct crypto_sync_skcipher *crypto_sync_skcipher_reqtfm(
399 : struct skcipher_request *req)
400 : {
401 : struct crypto_skcipher *tfm = crypto_skcipher_reqtfm(req);
402 :
403 : return container_of(tfm, struct crypto_sync_skcipher, base);
404 : }
405 :
406 : /**
407 : * crypto_skcipher_encrypt() - encrypt plaintext
408 : * @req: reference to the skcipher_request handle that holds all information
409 : * needed to perform the cipher operation
410 : *
411 : * Encrypt plaintext data using the skcipher_request handle. That data
412 : * structure and how it is filled with data is discussed with the
413 : * skcipher_request_* functions.
414 : *
415 : * Return: 0 if the cipher operation was successful; < 0 if an error occurred
416 : */
417 : int crypto_skcipher_encrypt(struct skcipher_request *req);
418 :
419 : /**
420 : * crypto_skcipher_decrypt() - decrypt ciphertext
421 : * @req: reference to the skcipher_request handle that holds all information
422 : * needed to perform the cipher operation
423 : *
424 : * Decrypt ciphertext data using the skcipher_request handle. That data
425 : * structure and how it is filled with data is discussed with the
426 : * skcipher_request_* functions.
427 : *
428 : * Return: 0 if the cipher operation was successful; < 0 if an error occurred
429 : */
430 : int crypto_skcipher_decrypt(struct skcipher_request *req);
431 :
432 : /**
433 : * DOC: Symmetric Key Cipher Request Handle
434 : *
435 : * The skcipher_request data structure contains all pointers to data
436 : * required for the symmetric key cipher operation. This includes the cipher
437 : * handle (which can be used by multiple skcipher_request instances), pointer
438 : * to plaintext and ciphertext, asynchronous callback function, etc. It acts
439 : * as a handle to the skcipher_request_* API calls in a similar way as
440 : * skcipher handle to the crypto_skcipher_* API calls.
441 : */
442 :
443 : /**
444 : * crypto_skcipher_reqsize() - obtain size of the request data structure
445 : * @tfm: cipher handle
446 : *
447 : * Return: number of bytes
448 : */
449 0 : static inline unsigned int crypto_skcipher_reqsize(struct crypto_skcipher *tfm)
450 : {
451 0 : return tfm->reqsize;
452 : }
453 :
454 : /**
455 : * skcipher_request_set_tfm() - update cipher handle reference in request
456 : * @req: request handle to be modified
457 : * @tfm: cipher handle that shall be added to the request handle
458 : *
459 : * Allow the caller to replace the existing skcipher handle in the request
460 : * data structure with a different one.
461 : */
462 : static inline void skcipher_request_set_tfm(struct skcipher_request *req,
463 : struct crypto_skcipher *tfm)
464 : {
465 : req->base.tfm = crypto_skcipher_tfm(tfm);
466 : }
467 :
468 : static inline void skcipher_request_set_sync_tfm(struct skcipher_request *req,
469 : struct crypto_sync_skcipher *tfm)
470 : {
471 : skcipher_request_set_tfm(req, &tfm->base);
472 : }
473 :
474 : static inline struct skcipher_request *skcipher_request_cast(
475 : struct crypto_async_request *req)
476 : {
477 : return container_of(req, struct skcipher_request, base);
478 : }
479 :
480 : /**
481 : * skcipher_request_alloc() - allocate request data structure
482 : * @tfm: cipher handle to be registered with the request
483 : * @gfp: memory allocation flag that is handed to kmalloc by the API call.
484 : *
485 : * Allocate the request data structure that must be used with the skcipher
486 : * encrypt and decrypt API calls. During the allocation, the provided skcipher
487 : * handle is registered in the request data structure.
488 : *
489 : * Return: allocated request handle in case of success, or NULL if out of memory
490 : */
491 : static inline struct skcipher_request *skcipher_request_alloc(
492 : struct crypto_skcipher *tfm, gfp_t gfp)
493 : {
494 : struct skcipher_request *req;
495 :
496 : req = kmalloc(sizeof(struct skcipher_request) +
497 : crypto_skcipher_reqsize(tfm), gfp);
498 :
499 : if (likely(req))
500 : skcipher_request_set_tfm(req, tfm);
501 :
502 : return req;
503 : }
504 :
505 : /**
506 : * skcipher_request_free() - zeroize and free request data structure
507 : * @req: request data structure cipher handle to be freed
508 : */
509 : static inline void skcipher_request_free(struct skcipher_request *req)
510 : {
511 : kfree_sensitive(req);
512 : }
513 :
514 : static inline void skcipher_request_zero(struct skcipher_request *req)
515 : {
516 : struct crypto_skcipher *tfm = crypto_skcipher_reqtfm(req);
517 :
518 : memzero_explicit(req, sizeof(*req) + crypto_skcipher_reqsize(tfm));
519 : }
520 :
521 : /**
522 : * skcipher_request_set_callback() - set asynchronous callback function
523 : * @req: request handle
524 : * @flags: specify zero or an ORing of the flags
525 : * CRYPTO_TFM_REQ_MAY_BACKLOG the request queue may back log and
526 : * increase the wait queue beyond the initial maximum size;
527 : * CRYPTO_TFM_REQ_MAY_SLEEP the request processing may sleep
528 : * @compl: callback function pointer to be registered with the request handle
529 : * @data: The data pointer refers to memory that is not used by the kernel
530 : * crypto API, but provided to the callback function for it to use. Here,
531 : * the caller can provide a reference to memory the callback function can
532 : * operate on. As the callback function is invoked asynchronously to the
533 : * related functionality, it may need to access data structures of the
534 : * related functionality which can be referenced using this pointer. The
535 : * callback function can access the memory via the "data" field in the
536 : * crypto_async_request data structure provided to the callback function.
537 : *
538 : * This function allows setting the callback function that is triggered once the
539 : * cipher operation completes.
540 : *
541 : * The callback function is registered with the skcipher_request handle and
542 : * must comply with the following template::
543 : *
544 : * void callback_function(struct crypto_async_request *req, int error)
545 : */
546 : static inline void skcipher_request_set_callback(struct skcipher_request *req,
547 : u32 flags,
548 : crypto_completion_t compl,
549 : void *data)
550 : {
551 : req->base.complete = compl;
552 : req->base.data = data;
553 : req->base.flags = flags;
554 : }
555 :
556 : /**
557 : * skcipher_request_set_crypt() - set data buffers
558 : * @req: request handle
559 : * @src: source scatter / gather list
560 : * @dst: destination scatter / gather list
561 : * @cryptlen: number of bytes to process from @src
562 : * @iv: IV for the cipher operation which must comply with the IV size defined
563 : * by crypto_skcipher_ivsize
564 : *
565 : * This function allows setting of the source data and destination data
566 : * scatter / gather lists.
567 : *
568 : * For encryption, the source is treated as the plaintext and the
569 : * destination is the ciphertext. For a decryption operation, the use is
570 : * reversed - the source is the ciphertext and the destination is the plaintext.
571 : */
572 : static inline void skcipher_request_set_crypt(
573 : struct skcipher_request *req,
574 : struct scatterlist *src, struct scatterlist *dst,
575 : unsigned int cryptlen, void *iv)
576 : {
577 : req->src = src;
578 : req->dst = dst;
579 : req->cryptlen = cryptlen;
580 : req->iv = iv;
581 : }
582 :
583 : #endif /* _CRYPTO_SKCIPHER_H */
584 :
|
