2 * Symmetric key ciphers.
4 * Copyright (c) 2007-2015 Herbert Xu <herbert@gondor.apana.org.au>
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)
13 #ifndef _CRYPTO_SKCIPHER_H
14 #define _CRYPTO_SKCIPHER_H
16 #include <linux/crypto.h>
17 #include <linux/kernel.h>
18 #include <linux/slab.h>
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
29 struct skcipher_request
{
30 unsigned int cryptlen
;
34 struct scatterlist
*src
;
35 struct scatterlist
*dst
;
37 struct crypto_async_request base
;
39 void *__ctx
[] CRYPTO_MINALIGN_ATTR
;
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
48 struct skcipher_givcrypt_request
{
52 struct ablkcipher_request creq
;
55 struct crypto_skcipher
{
56 int (*setkey
)(struct crypto_skcipher
*tfm
, const u8
*key
,
58 int (*encrypt
)(struct skcipher_request
*req
);
59 int (*decrypt
)(struct skcipher_request
*req
);
65 struct crypto_tfm base
;
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
111 * @exit: Deinitialize the cryptographic transformation object. This is a
112 * counterpart to @init, used to remove various changes set in
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.
119 * All fields except @ivsize are mandatory and must be filled.
121 struct skcipher_alg
{
122 int (*setkey
)(struct crypto_skcipher
*tfm
, const u8
*key
,
123 unsigned int keylen
);
124 int (*encrypt
)(struct skcipher_request
*req
);
125 int (*decrypt
)(struct skcipher_request
*req
);
126 int (*init
)(struct crypto_skcipher
*tfm
);
127 void (*exit
)(struct crypto_skcipher
*tfm
);
129 unsigned int min_keysize
;
130 unsigned int max_keysize
;
132 unsigned int chunksize
;
134 struct crypto_alg base
;
137 #define SKCIPHER_REQUEST_ON_STACK(name, tfm) \
138 char __##name##_desc[sizeof(struct skcipher_request) + \
139 crypto_skcipher_reqsize(tfm)] CRYPTO_MINALIGN_ATTR; \
140 struct skcipher_request *name = (void *)__##name##_desc
143 * DOC: Symmetric Key Cipher API
145 * Symmetric key cipher API is used with the ciphers of type
146 * CRYPTO_ALG_TYPE_SKCIPHER (listed as type "skcipher" in /proc/crypto).
148 * Asynchronous cipher operations imply that the function invocation for a
149 * cipher request returns immediately before the completion of the operation.
150 * The cipher request is scheduled as a separate kernel thread and therefore
151 * load-balanced on the different CPUs via the process scheduler. To allow
152 * the kernel crypto API to inform the caller about the completion of a cipher
153 * request, the caller must provide a callback function. That function is
154 * invoked with the cipher handle when the request completes.
156 * To support the asynchronous operation, additional information than just the
157 * cipher handle must be supplied to the kernel crypto API. That additional
158 * information is given by filling in the skcipher_request data structure.
160 * For the symmetric key cipher API, the state is maintained with the tfm
161 * cipher handle. A single tfm can be used across multiple calls and in
162 * parallel. For asynchronous block cipher calls, context data supplied and
163 * only used by the caller can be referenced the request data structure in
164 * addition to the IV used for the cipher request. The maintenance of such
165 * state information would be important for a crypto driver implementer to
166 * have, because when calling the callback function upon completion of the
167 * cipher operation, that callback function may need some information about
168 * which operation just finished if it invoked multiple in parallel. This
169 * state information is unused by the kernel crypto API.
172 static inline struct crypto_skcipher
*__crypto_skcipher_cast(
173 struct crypto_tfm
*tfm
)
175 return container_of(tfm
, struct crypto_skcipher
, base
);
179 * crypto_alloc_skcipher() - allocate symmetric key cipher handle
180 * @alg_name: is the cra_name / name or cra_driver_name / driver name of the
182 * @type: specifies the type of the cipher
183 * @mask: specifies the mask for the cipher
185 * Allocate a cipher handle for an skcipher. The returned struct
186 * crypto_skcipher is the cipher handle that is required for any subsequent
187 * API invocation for that skcipher.
189 * Return: allocated cipher handle in case of success; IS_ERR() is true in case
190 * of an error, PTR_ERR() returns the error code.
192 struct crypto_skcipher
*crypto_alloc_skcipher(const char *alg_name
,
195 static inline struct crypto_tfm
*crypto_skcipher_tfm(
196 struct crypto_skcipher
*tfm
)
202 * crypto_free_skcipher() - zeroize and free cipher handle
203 * @tfm: cipher handle to be freed
205 static inline void crypto_free_skcipher(struct crypto_skcipher
*tfm
)
207 crypto_destroy_tfm(tfm
, crypto_skcipher_tfm(tfm
));
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
214 * @type: specifies the type of the cipher
215 * @mask: specifies the mask for the cipher
217 * Return: true when the skcipher is known to the kernel crypto API; false
220 static inline int crypto_has_skcipher(const char *alg_name
, u32 type
,
223 return crypto_has_alg(alg_name
, crypto_skcipher_type(type
),
224 crypto_skcipher_mask(mask
));
228 * crypto_has_skcipher2() - Search for the availability of an skcipher.
229 * @alg_name: is the cra_name / name or cra_driver_name / driver name of the
231 * @type: specifies the type of the skcipher
232 * @mask: specifies the mask for the skcipher
234 * Return: true when the skcipher is known to the kernel crypto API; false
237 int crypto_has_skcipher2(const char *alg_name
, u32 type
, u32 mask
);
239 static inline const char *crypto_skcipher_driver_name(
240 struct crypto_skcipher
*tfm
)
242 return crypto_tfm_alg_driver_name(crypto_skcipher_tfm(tfm
));
245 static inline struct skcipher_alg
*crypto_skcipher_alg(
246 struct crypto_skcipher
*tfm
)
248 return container_of(crypto_skcipher_tfm(tfm
)->__crt_alg
,
249 struct skcipher_alg
, base
);
252 static inline unsigned int crypto_skcipher_alg_ivsize(struct skcipher_alg
*alg
)
254 if ((alg
->base
.cra_flags
& CRYPTO_ALG_TYPE_MASK
) ==
255 CRYPTO_ALG_TYPE_BLKCIPHER
)
256 return alg
->base
.cra_blkcipher
.ivsize
;
258 if (alg
->base
.cra_ablkcipher
.encrypt
)
259 return alg
->base
.cra_ablkcipher
.ivsize
;
265 * crypto_skcipher_ivsize() - obtain IV size
266 * @tfm: cipher handle
268 * The size of the IV for the skcipher referenced by the cipher handle is
269 * returned. This IV size may be zero if the cipher does not need an IV.
271 * Return: IV size in bytes
273 static inline unsigned int crypto_skcipher_ivsize(struct crypto_skcipher
*tfm
)
278 static inline unsigned int crypto_skcipher_alg_chunksize(
279 struct skcipher_alg
*alg
)
281 if ((alg
->base
.cra_flags
& CRYPTO_ALG_TYPE_MASK
) ==
282 CRYPTO_ALG_TYPE_BLKCIPHER
)
283 return alg
->base
.cra_blocksize
;
285 if (alg
->base
.cra_ablkcipher
.encrypt
)
286 return alg
->base
.cra_blocksize
;
288 return alg
->chunksize
;
292 * crypto_skcipher_chunksize() - obtain chunk size
293 * @tfm: cipher handle
295 * The block size is set to one for ciphers such as CTR. However,
296 * you still need to provide incremental updates in multiples of
297 * the underlying block size as the IV does not have sub-block
298 * granularity. This is known in this API as the chunk size.
300 * Return: chunk size in bytes
302 static inline unsigned int crypto_skcipher_chunksize(
303 struct crypto_skcipher
*tfm
)
305 return crypto_skcipher_alg_chunksize(crypto_skcipher_alg(tfm
));
309 * crypto_skcipher_blocksize() - obtain block size of cipher
310 * @tfm: cipher handle
312 * The block size for the skcipher referenced with the cipher handle is
313 * returned. The caller may use that information to allocate appropriate
314 * memory for the data returned by the encryption or decryption operation
316 * Return: block size of cipher
318 static inline unsigned int crypto_skcipher_blocksize(
319 struct crypto_skcipher
*tfm
)
321 return crypto_tfm_alg_blocksize(crypto_skcipher_tfm(tfm
));
324 static inline unsigned int crypto_skcipher_alignmask(
325 struct crypto_skcipher
*tfm
)
327 return crypto_tfm_alg_alignmask(crypto_skcipher_tfm(tfm
));
330 static inline u32
crypto_skcipher_get_flags(struct crypto_skcipher
*tfm
)
332 return crypto_tfm_get_flags(crypto_skcipher_tfm(tfm
));
335 static inline void crypto_skcipher_set_flags(struct crypto_skcipher
*tfm
,
338 crypto_tfm_set_flags(crypto_skcipher_tfm(tfm
), flags
);
341 static inline void crypto_skcipher_clear_flags(struct crypto_skcipher
*tfm
,
344 crypto_tfm_clear_flags(crypto_skcipher_tfm(tfm
), flags
);
348 * crypto_skcipher_setkey() - set key for cipher
349 * @tfm: cipher handle
350 * @key: buffer holding the key
351 * @keylen: length of the key in bytes
353 * The caller provided key is set for the skcipher referenced by the cipher
356 * Note, the key length determines the cipher type. Many block ciphers implement
357 * different cipher modes depending on the key size, such as AES-128 vs AES-192
358 * vs. AES-256. When providing a 16 byte key for an AES cipher handle, AES-128
361 * Return: 0 if the setting of the key was successful; < 0 if an error occurred
363 static inline int crypto_skcipher_setkey(struct crypto_skcipher
*tfm
,
364 const u8
*key
, unsigned int keylen
)
366 return tfm
->setkey(tfm
, key
, keylen
);
369 static inline bool crypto_skcipher_has_setkey(struct crypto_skcipher
*tfm
)
374 static inline unsigned int crypto_skcipher_default_keysize(
375 struct crypto_skcipher
*tfm
)
381 * crypto_skcipher_reqtfm() - obtain cipher handle from request
382 * @req: skcipher_request out of which the cipher handle is to be obtained
384 * Return the crypto_skcipher handle when furnishing an skcipher_request
387 * Return: crypto_skcipher handle
389 static inline struct crypto_skcipher
*crypto_skcipher_reqtfm(
390 struct skcipher_request
*req
)
392 return __crypto_skcipher_cast(req
->base
.tfm
);
396 * crypto_skcipher_encrypt() - encrypt plaintext
397 * @req: reference to the skcipher_request handle that holds all information
398 * needed to perform the cipher operation
400 * Encrypt plaintext data using the skcipher_request handle. That data
401 * structure and how it is filled with data is discussed with the
402 * skcipher_request_* functions.
404 * Return: 0 if the cipher operation was successful; < 0 if an error occurred
406 static inline int crypto_skcipher_encrypt(struct skcipher_request
*req
)
408 struct crypto_skcipher
*tfm
= crypto_skcipher_reqtfm(req
);
410 return tfm
->encrypt(req
);
414 * crypto_skcipher_decrypt() - decrypt ciphertext
415 * @req: reference to the skcipher_request handle that holds all information
416 * needed to perform the cipher operation
418 * Decrypt ciphertext data using the skcipher_request handle. That data
419 * structure and how it is filled with data is discussed with the
420 * skcipher_request_* functions.
422 * Return: 0 if the cipher operation was successful; < 0 if an error occurred
424 static inline int crypto_skcipher_decrypt(struct skcipher_request
*req
)
426 struct crypto_skcipher
*tfm
= crypto_skcipher_reqtfm(req
);
428 return tfm
->decrypt(req
);
432 * DOC: Symmetric Key Cipher Request Handle
434 * The skcipher_request data structure contains all pointers to data
435 * required for the symmetric key cipher operation. This includes the cipher
436 * handle (which can be used by multiple skcipher_request instances), pointer
437 * to plaintext and ciphertext, asynchronous callback function, etc. It acts
438 * as a handle to the skcipher_request_* API calls in a similar way as
439 * skcipher handle to the crypto_skcipher_* API calls.
443 * crypto_skcipher_reqsize() - obtain size of the request data structure
444 * @tfm: cipher handle
446 * Return: number of bytes
448 static inline unsigned int crypto_skcipher_reqsize(struct crypto_skcipher
*tfm
)
454 * skcipher_request_set_tfm() - update cipher handle reference in request
455 * @req: request handle to be modified
456 * @tfm: cipher handle that shall be added to the request handle
458 * Allow the caller to replace the existing skcipher handle in the request
459 * data structure with a different one.
461 static inline void skcipher_request_set_tfm(struct skcipher_request
*req
,
462 struct crypto_skcipher
*tfm
)
464 req
->base
.tfm
= crypto_skcipher_tfm(tfm
);
467 static inline struct skcipher_request
*skcipher_request_cast(
468 struct crypto_async_request
*req
)
470 return container_of(req
, struct skcipher_request
, base
);
474 * skcipher_request_alloc() - allocate request data structure
475 * @tfm: cipher handle to be registered with the request
476 * @gfp: memory allocation flag that is handed to kmalloc by the API call.
478 * Allocate the request data structure that must be used with the skcipher
479 * encrypt and decrypt API calls. During the allocation, the provided skcipher
480 * handle is registered in the request data structure.
482 * Return: allocated request handle in case of success, or NULL if out of memory
484 static inline struct skcipher_request
*skcipher_request_alloc(
485 struct crypto_skcipher
*tfm
, gfp_t gfp
)
487 struct skcipher_request
*req
;
489 req
= kmalloc(sizeof(struct skcipher_request
) +
490 crypto_skcipher_reqsize(tfm
), gfp
);
493 skcipher_request_set_tfm(req
, tfm
);
499 * skcipher_request_free() - zeroize and free request data structure
500 * @req: request data structure cipher handle to be freed
502 static inline void skcipher_request_free(struct skcipher_request
*req
)
507 static inline void skcipher_request_zero(struct skcipher_request
*req
)
509 struct crypto_skcipher
*tfm
= crypto_skcipher_reqtfm(req
);
511 memzero_explicit(req
, sizeof(*req
) + crypto_skcipher_reqsize(tfm
));
515 * skcipher_request_set_callback() - set asynchronous callback function
516 * @req: request handle
517 * @flags: specify zero or an ORing of the flags
518 * CRYPTO_TFM_REQ_MAY_BACKLOG the request queue may back log and
519 * increase the wait queue beyond the initial maximum size;
520 * CRYPTO_TFM_REQ_MAY_SLEEP the request processing may sleep
521 * @compl: callback function pointer to be registered with the request handle
522 * @data: The data pointer refers to memory that is not used by the kernel
523 * crypto API, but provided to the callback function for it to use. Here,
524 * the caller can provide a reference to memory the callback function can
525 * operate on. As the callback function is invoked asynchronously to the
526 * related functionality, it may need to access data structures of the
527 * related functionality which can be referenced using this pointer. The
528 * callback function can access the memory via the "data" field in the
529 * crypto_async_request data structure provided to the callback function.
531 * This function allows setting the callback function that is triggered once the
532 * cipher operation completes.
534 * The callback function is registered with the skcipher_request handle and
535 * must comply with the following template
537 * void callback_function(struct crypto_async_request *req, int error)
539 static inline void skcipher_request_set_callback(struct skcipher_request
*req
,
541 crypto_completion_t
compl,
544 req
->base
.complete
= compl;
545 req
->base
.data
= data
;
546 req
->base
.flags
= flags
;
550 * skcipher_request_set_crypt() - set data buffers
551 * @req: request handle
552 * @src: source scatter / gather list
553 * @dst: destination scatter / gather list
554 * @cryptlen: number of bytes to process from @src
555 * @iv: IV for the cipher operation which must comply with the IV size defined
556 * by crypto_skcipher_ivsize
558 * This function allows setting of the source data and destination data
559 * scatter / gather lists.
561 * For encryption, the source is treated as the plaintext and the
562 * destination is the ciphertext. For a decryption operation, the use is
563 * reversed - the source is the ciphertext and the destination is the plaintext.
565 static inline void skcipher_request_set_crypt(
566 struct skcipher_request
*req
,
567 struct scatterlist
*src
, struct scatterlist
*dst
,
568 unsigned int cryptlen
, void *iv
)
572 req
->cryptlen
= cryptlen
;
576 #endif /* _CRYPTO_SKCIPHER_H */