xref: /openbmc/linux/include/crypto/skcipher.h (revision 0edbfea5)
1 /*
2  * Symmetric key ciphers.
3  *
4  * Copyright (c) 2007-2015 Herbert Xu <herbert@gondor.apana.org.au>
5  *
6  * This program is free software; you can redistribute it and/or modify it
7  * under the terms of the GNU General Public License as published by the Free
8  * Software Foundation; either version 2 of the License, or (at your option)
9  * any later version.
10  *
11  */
12 
13 #ifndef _CRYPTO_SKCIPHER_H
14 #define _CRYPTO_SKCIPHER_H
15 
16 #include <linux/crypto.h>
17 #include <linux/kernel.h>
18 #include <linux/slab.h>
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 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 /**
43  *	struct skcipher_givcrypt_request - Crypto request with IV generation
44  *	@seq: Sequence number for IV generation
45  *	@giv: Space for generated IV
46  *	@creq: The crypto request itself
47  */
48 struct skcipher_givcrypt_request {
49 	u64 seq;
50 	u8 *giv;
51 
52 	struct ablkcipher_request creq;
53 };
54 
55 struct crypto_skcipher {
56 	int (*setkey)(struct crypto_skcipher *tfm, const u8 *key,
57 	              unsigned int keylen);
58 	int (*encrypt)(struct skcipher_request *req);
59 	int (*decrypt)(struct skcipher_request *req);
60 
61 	unsigned int ivsize;
62 	unsigned int reqsize;
63 	unsigned int keysize;
64 
65 	struct crypto_tfm base;
66 };
67 
68 #define SKCIPHER_REQUEST_ON_STACK(name, tfm) \
69 	char __##name##_desc[sizeof(struct skcipher_request) + \
70 		crypto_skcipher_reqsize(tfm)] CRYPTO_MINALIGN_ATTR; \
71 	struct skcipher_request *name = (void *)__##name##_desc
72 
73 static inline struct crypto_ablkcipher *skcipher_givcrypt_reqtfm(
74 	struct skcipher_givcrypt_request *req)
75 {
76 	return crypto_ablkcipher_reqtfm(&req->creq);
77 }
78 
79 static inline int crypto_skcipher_givencrypt(
80 	struct skcipher_givcrypt_request *req)
81 {
82 	struct ablkcipher_tfm *crt =
83 		crypto_ablkcipher_crt(skcipher_givcrypt_reqtfm(req));
84 	return crt->givencrypt(req);
85 };
86 
87 static inline int crypto_skcipher_givdecrypt(
88 	struct skcipher_givcrypt_request *req)
89 {
90 	struct ablkcipher_tfm *crt =
91 		crypto_ablkcipher_crt(skcipher_givcrypt_reqtfm(req));
92 	return crt->givdecrypt(req);
93 };
94 
95 static inline void skcipher_givcrypt_set_tfm(
96 	struct skcipher_givcrypt_request *req, struct crypto_ablkcipher *tfm)
97 {
98 	req->creq.base.tfm = crypto_ablkcipher_tfm(tfm);
99 }
100 
101 static inline struct skcipher_givcrypt_request *skcipher_givcrypt_cast(
102 	struct crypto_async_request *req)
103 {
104 	return container_of(ablkcipher_request_cast(req),
105 			    struct skcipher_givcrypt_request, creq);
106 }
107 
108 static inline struct skcipher_givcrypt_request *skcipher_givcrypt_alloc(
109 	struct crypto_ablkcipher *tfm, gfp_t gfp)
110 {
111 	struct skcipher_givcrypt_request *req;
112 
113 	req = kmalloc(sizeof(struct skcipher_givcrypt_request) +
114 		      crypto_ablkcipher_reqsize(tfm), gfp);
115 
116 	if (likely(req))
117 		skcipher_givcrypt_set_tfm(req, tfm);
118 
119 	return req;
120 }
121 
122 static inline void skcipher_givcrypt_free(struct skcipher_givcrypt_request *req)
123 {
124 	kfree(req);
125 }
126 
127 static inline void skcipher_givcrypt_set_callback(
128 	struct skcipher_givcrypt_request *req, u32 flags,
129 	crypto_completion_t compl, void *data)
130 {
131 	ablkcipher_request_set_callback(&req->creq, flags, compl, data);
132 }
133 
134 static inline void skcipher_givcrypt_set_crypt(
135 	struct skcipher_givcrypt_request *req,
136 	struct scatterlist *src, struct scatterlist *dst,
137 	unsigned int nbytes, void *iv)
138 {
139 	ablkcipher_request_set_crypt(&req->creq, src, dst, nbytes, iv);
140 }
141 
142 static inline void skcipher_givcrypt_set_giv(
143 	struct skcipher_givcrypt_request *req, u8 *giv, u64 seq)
144 {
145 	req->giv = giv;
146 	req->seq = seq;
147 }
148 
149 /**
150  * DOC: Symmetric Key Cipher API
151  *
152  * Symmetric key cipher API is used with the ciphers of type
153  * CRYPTO_ALG_TYPE_SKCIPHER (listed as type "skcipher" in /proc/crypto).
154  *
155  * Asynchronous cipher operations imply that the function invocation for a
156  * cipher request returns immediately before the completion of the operation.
157  * The cipher request is scheduled as a separate kernel thread and therefore
158  * load-balanced on the different CPUs via the process scheduler. To allow
159  * the kernel crypto API to inform the caller about the completion of a cipher
160  * request, the caller must provide a callback function. That function is
161  * invoked with the cipher handle when the request completes.
162  *
163  * To support the asynchronous operation, additional information than just the
164  * cipher handle must be supplied to the kernel crypto API. That additional
165  * information is given by filling in the skcipher_request data structure.
166  *
167  * For the symmetric key cipher API, the state is maintained with the tfm
168  * cipher handle. A single tfm can be used across multiple calls and in
169  * parallel. For asynchronous block cipher calls, context data supplied and
170  * only used by the caller can be referenced the request data structure in
171  * addition to the IV used for the cipher request. The maintenance of such
172  * state information would be important for a crypto driver implementer to
173  * have, because when calling the callback function upon completion of the
174  * cipher operation, that callback function may need some information about
175  * which operation just finished if it invoked multiple in parallel. This
176  * state information is unused by the kernel crypto API.
177  */
178 
179 static inline struct crypto_skcipher *__crypto_skcipher_cast(
180 	struct crypto_tfm *tfm)
181 {
182 	return container_of(tfm, struct crypto_skcipher, base);
183 }
184 
185 /**
186  * crypto_alloc_skcipher() - allocate symmetric key cipher handle
187  * @alg_name: is the cra_name / name or cra_driver_name / driver name of the
188  *	      skcipher cipher
189  * @type: specifies the type of the cipher
190  * @mask: specifies the mask for the cipher
191  *
192  * Allocate a cipher handle for an skcipher. The returned struct
193  * crypto_skcipher is the cipher handle that is required for any subsequent
194  * API invocation for that skcipher.
195  *
196  * Return: allocated cipher handle in case of success; IS_ERR() is true in case
197  *	   of an error, PTR_ERR() returns the error code.
198  */
199 struct crypto_skcipher *crypto_alloc_skcipher(const char *alg_name,
200 					      u32 type, u32 mask);
201 
202 static inline struct crypto_tfm *crypto_skcipher_tfm(
203 	struct crypto_skcipher *tfm)
204 {
205 	return &tfm->base;
206 }
207 
208 /**
209  * crypto_free_skcipher() - zeroize and free cipher handle
210  * @tfm: cipher handle to be freed
211  */
212 static inline void crypto_free_skcipher(struct crypto_skcipher *tfm)
213 {
214 	crypto_destroy_tfm(tfm, crypto_skcipher_tfm(tfm));
215 }
216 
217 /**
218  * crypto_has_skcipher() - Search for the availability of an skcipher.
219  * @alg_name: is the cra_name / name or cra_driver_name / driver name of the
220  *	      skcipher
221  * @type: specifies the type of the cipher
222  * @mask: specifies the mask for the cipher
223  *
224  * Return: true when the skcipher is known to the kernel crypto API; false
225  *	   otherwise
226  */
227 static inline int crypto_has_skcipher(const char *alg_name, u32 type,
228 					u32 mask)
229 {
230 	return crypto_has_alg(alg_name, crypto_skcipher_type(type),
231 			      crypto_skcipher_mask(mask));
232 }
233 
234 static inline const char *crypto_skcipher_driver_name(
235 	struct crypto_skcipher *tfm)
236 {
237 	return crypto_tfm_alg_driver_name(crypto_skcipher_tfm(tfm));
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 static inline unsigned int crypto_skcipher_ivsize(struct crypto_skcipher *tfm)
250 {
251 	return tfm->ivsize;
252 }
253 
254 /**
255  * crypto_skcipher_blocksize() - obtain block size of cipher
256  * @tfm: cipher handle
257  *
258  * The block size for the skcipher referenced with the cipher handle is
259  * returned. The caller may use that information to allocate appropriate
260  * memory for the data returned by the encryption or decryption operation
261  *
262  * Return: block size of cipher
263  */
264 static inline unsigned int crypto_skcipher_blocksize(
265 	struct crypto_skcipher *tfm)
266 {
267 	return crypto_tfm_alg_blocksize(crypto_skcipher_tfm(tfm));
268 }
269 
270 static inline unsigned int crypto_skcipher_alignmask(
271 	struct crypto_skcipher *tfm)
272 {
273 	return crypto_tfm_alg_alignmask(crypto_skcipher_tfm(tfm));
274 }
275 
276 static inline u32 crypto_skcipher_get_flags(struct crypto_skcipher *tfm)
277 {
278 	return crypto_tfm_get_flags(crypto_skcipher_tfm(tfm));
279 }
280 
281 static inline void crypto_skcipher_set_flags(struct crypto_skcipher *tfm,
282 					       u32 flags)
283 {
284 	crypto_tfm_set_flags(crypto_skcipher_tfm(tfm), flags);
285 }
286 
287 static inline void crypto_skcipher_clear_flags(struct crypto_skcipher *tfm,
288 						 u32 flags)
289 {
290 	crypto_tfm_clear_flags(crypto_skcipher_tfm(tfm), flags);
291 }
292 
293 /**
294  * crypto_skcipher_setkey() - set key for cipher
295  * @tfm: cipher handle
296  * @key: buffer holding the key
297  * @keylen: length of the key in bytes
298  *
299  * The caller provided key is set for the skcipher referenced by the cipher
300  * handle.
301  *
302  * Note, the key length determines the cipher type. Many block ciphers implement
303  * different cipher modes depending on the key size, such as AES-128 vs AES-192
304  * vs. AES-256. When providing a 16 byte key for an AES cipher handle, AES-128
305  * is performed.
306  *
307  * Return: 0 if the setting of the key was successful; < 0 if an error occurred
308  */
309 static inline int crypto_skcipher_setkey(struct crypto_skcipher *tfm,
310 					 const u8 *key, unsigned int keylen)
311 {
312 	return tfm->setkey(tfm, key, keylen);
313 }
314 
315 static inline bool crypto_skcipher_has_setkey(struct crypto_skcipher *tfm)
316 {
317 	return tfm->keysize;
318 }
319 
320 static inline unsigned int crypto_skcipher_default_keysize(
321 	struct crypto_skcipher *tfm)
322 {
323 	return tfm->keysize;
324 }
325 
326 /**
327  * crypto_skcipher_reqtfm() - obtain cipher handle from request
328  * @req: skcipher_request out of which the cipher handle is to be obtained
329  *
330  * Return the crypto_skcipher handle when furnishing an skcipher_request
331  * data structure.
332  *
333  * Return: crypto_skcipher handle
334  */
335 static inline struct crypto_skcipher *crypto_skcipher_reqtfm(
336 	struct skcipher_request *req)
337 {
338 	return __crypto_skcipher_cast(req->base.tfm);
339 }
340 
341 /**
342  * crypto_skcipher_encrypt() - encrypt plaintext
343  * @req: reference to the skcipher_request handle that holds all information
344  *	 needed to perform the cipher operation
345  *
346  * Encrypt plaintext data using the skcipher_request handle. That data
347  * structure and how it is filled with data is discussed with the
348  * skcipher_request_* functions.
349  *
350  * Return: 0 if the cipher operation was successful; < 0 if an error occurred
351  */
352 static inline int crypto_skcipher_encrypt(struct skcipher_request *req)
353 {
354 	struct crypto_skcipher *tfm = crypto_skcipher_reqtfm(req);
355 
356 	return tfm->encrypt(req);
357 }
358 
359 /**
360  * crypto_skcipher_decrypt() - decrypt ciphertext
361  * @req: reference to the skcipher_request handle that holds all information
362  *	 needed to perform the cipher operation
363  *
364  * Decrypt ciphertext data using the skcipher_request handle. That data
365  * structure and how it is filled with data is discussed with the
366  * skcipher_request_* functions.
367  *
368  * Return: 0 if the cipher operation was successful; < 0 if an error occurred
369  */
370 static inline int crypto_skcipher_decrypt(struct skcipher_request *req)
371 {
372 	struct crypto_skcipher *tfm = crypto_skcipher_reqtfm(req);
373 
374 	return tfm->decrypt(req);
375 }
376 
377 /**
378  * DOC: Symmetric Key Cipher Request Handle
379  *
380  * The skcipher_request data structure contains all pointers to data
381  * required for the symmetric key cipher operation. This includes the cipher
382  * handle (which can be used by multiple skcipher_request instances), pointer
383  * to plaintext and ciphertext, asynchronous callback function, etc. It acts
384  * as a handle to the skcipher_request_* API calls in a similar way as
385  * skcipher handle to the crypto_skcipher_* API calls.
386  */
387 
388 /**
389  * crypto_skcipher_reqsize() - obtain size of the request data structure
390  * @tfm: cipher handle
391  *
392  * Return: number of bytes
393  */
394 static inline unsigned int crypto_skcipher_reqsize(struct crypto_skcipher *tfm)
395 {
396 	return tfm->reqsize;
397 }
398 
399 /**
400  * skcipher_request_set_tfm() - update cipher handle reference in request
401  * @req: request handle to be modified
402  * @tfm: cipher handle that shall be added to the request handle
403  *
404  * Allow the caller to replace the existing skcipher handle in the request
405  * data structure with a different one.
406  */
407 static inline void skcipher_request_set_tfm(struct skcipher_request *req,
408 					    struct crypto_skcipher *tfm)
409 {
410 	req->base.tfm = crypto_skcipher_tfm(tfm);
411 }
412 
413 static inline struct skcipher_request *skcipher_request_cast(
414 	struct crypto_async_request *req)
415 {
416 	return container_of(req, struct skcipher_request, base);
417 }
418 
419 /**
420  * skcipher_request_alloc() - allocate request data structure
421  * @tfm: cipher handle to be registered with the request
422  * @gfp: memory allocation flag that is handed to kmalloc by the API call.
423  *
424  * Allocate the request data structure that must be used with the skcipher
425  * encrypt and decrypt API calls. During the allocation, the provided skcipher
426  * handle is registered in the request data structure.
427  *
428  * Return: allocated request handle in case of success, or NULL if out of memory
429  */
430 static inline struct skcipher_request *skcipher_request_alloc(
431 	struct crypto_skcipher *tfm, gfp_t gfp)
432 {
433 	struct skcipher_request *req;
434 
435 	req = kmalloc(sizeof(struct skcipher_request) +
436 		      crypto_skcipher_reqsize(tfm), gfp);
437 
438 	if (likely(req))
439 		skcipher_request_set_tfm(req, tfm);
440 
441 	return req;
442 }
443 
444 /**
445  * skcipher_request_free() - zeroize and free request data structure
446  * @req: request data structure cipher handle to be freed
447  */
448 static inline void skcipher_request_free(struct skcipher_request *req)
449 {
450 	kzfree(req);
451 }
452 
453 static inline void skcipher_request_zero(struct skcipher_request *req)
454 {
455 	struct crypto_skcipher *tfm = crypto_skcipher_reqtfm(req);
456 
457 	memzero_explicit(req, sizeof(*req) + crypto_skcipher_reqsize(tfm));
458 }
459 
460 /**
461  * skcipher_request_set_callback() - set asynchronous callback function
462  * @req: request handle
463  * @flags: specify zero or an ORing of the flags
464  *         CRYPTO_TFM_REQ_MAY_BACKLOG the request queue may back log and
465  *	   increase the wait queue beyond the initial maximum size;
466  *	   CRYPTO_TFM_REQ_MAY_SLEEP the request processing may sleep
467  * @compl: callback function pointer to be registered with the request handle
468  * @data: The data pointer refers to memory that is not used by the kernel
469  *	  crypto API, but provided to the callback function for it to use. Here,
470  *	  the caller can provide a reference to memory the callback function can
471  *	  operate on. As the callback function is invoked asynchronously to the
472  *	  related functionality, it may need to access data structures of the
473  *	  related functionality which can be referenced using this pointer. The
474  *	  callback function can access the memory via the "data" field in the
475  *	  crypto_async_request data structure provided to the callback function.
476  *
477  * This function allows setting the callback function that is triggered once the
478  * cipher operation completes.
479  *
480  * The callback function is registered with the skcipher_request handle and
481  * must comply with the following template
482  *
483  *	void callback_function(struct crypto_async_request *req, int error)
484  */
485 static inline void skcipher_request_set_callback(struct skcipher_request *req,
486 						 u32 flags,
487 						 crypto_completion_t compl,
488 						 void *data)
489 {
490 	req->base.complete = compl;
491 	req->base.data = data;
492 	req->base.flags = flags;
493 }
494 
495 /**
496  * skcipher_request_set_crypt() - set data buffers
497  * @req: request handle
498  * @src: source scatter / gather list
499  * @dst: destination scatter / gather list
500  * @cryptlen: number of bytes to process from @src
501  * @iv: IV for the cipher operation which must comply with the IV size defined
502  *      by crypto_skcipher_ivsize
503  *
504  * This function allows setting of the source data and destination data
505  * scatter / gather lists.
506  *
507  * For encryption, the source is treated as the plaintext and the
508  * destination is the ciphertext. For a decryption operation, the use is
509  * reversed - the source is the ciphertext and the destination is the plaintext.
510  */
511 static inline void skcipher_request_set_crypt(
512 	struct skcipher_request *req,
513 	struct scatterlist *src, struct scatterlist *dst,
514 	unsigned int cryptlen, void *iv)
515 {
516 	req->src = src;
517 	req->dst = dst;
518 	req->cryptlen = cryptlen;
519 	req->iv = iv;
520 }
521 
522 #endif	/* _CRYPTO_SKCIPHER_H */
523 
524