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