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 18struct 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 */ 29struct 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 42struct crypto_skcipher { 43 unsigned int reqsize; 44 45 struct crypto_tfm base; 46}; 47 48struct 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 */ 60struct 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 */ 126struct 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 190static 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 */ 210struct crypto_skcipher *crypto_alloc_skcipher(const char *alg_name, 211 u32 type, u32 mask); 212 213struct crypto_sync_skcipher *crypto_alloc_sync_skcipher(const char *alg_name, 214 u32 type, u32 mask); 215 216static 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 */ 228static inline void crypto_free_skcipher(struct crypto_skcipher *tfm) 229{ 230 crypto_destroy_tfm(tfm, crypto_skcipher_tfm(tfm)); 231} 232 233static 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 */ 248int crypto_has_skcipher(const char *alg_name, u32 type, u32 mask); 249 250static 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 256static 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 263static 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 */ 277static inline unsigned int crypto_skcipher_ivsize(struct crypto_skcipher *tfm) 278{ 279 return crypto_skcipher_alg(tfm)->ivsize; 280} 281 282static 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 */ 298static inline unsigned int crypto_skcipher_blocksize( 299 struct crypto_skcipher *tfm) 300{ 301 return crypto_tfm_alg_blocksize(crypto_skcipher_tfm(tfm)); 302} 303 304static 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 */ 321static inline unsigned int crypto_skcipher_chunksize( 322 struct crypto_skcipher *tfm) 323{ 324 return crypto_skcipher_alg_chunksize(crypto_skcipher_alg(tfm)); 325} 326 327static inline unsigned int crypto_sync_skcipher_blocksize( 328 struct crypto_sync_skcipher *tfm) 329{ 330 return crypto_skcipher_blocksize(&tfm->base); 331} 332 333static inline unsigned int crypto_skcipher_alignmask( 334 struct crypto_skcipher *tfm) 335{ 336 return crypto_tfm_alg_alignmask(crypto_skcipher_tfm(tfm)); 337} 338 339static inline u32 crypto_skcipher_get_flags(struct crypto_skcipher *tfm) 340{ 341 return crypto_tfm_get_flags(crypto_skcipher_tfm(tfm)); 342} 343 344static 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 350static 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 356static inline u32 crypto_sync_skcipher_get_flags( 357 struct crypto_sync_skcipher *tfm) 358{ 359 return crypto_skcipher_get_flags(&tfm->base); 360} 361 362static 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 368static 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 */ 390int crypto_skcipher_setkey(struct crypto_skcipher *tfm, 391 const u8 *key, unsigned int keylen); 392 393static 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 399static inline unsigned int crypto_skcipher_min_keysize( 400 struct crypto_skcipher *tfm) 401{ 402 return crypto_skcipher_alg(tfm)->min_keysize; 403} 404 405static 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 */ 420static inline struct crypto_skcipher *crypto_skcipher_reqtfm( 421 struct skcipher_request *req) 422{ 423 return __crypto_skcipher_cast(req->base.tfm); 424} 425 426static 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 */ 445int 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 */ 458int 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 */ 477static 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 */ 490static 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 496static 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 502static 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 */ 519static 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 */ 537static inline void skcipher_request_free(struct skcipher_request *req) 538{ 539 kfree_sensitive(req); 540} 541 542static 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 */ 574static 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 */ 600static 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 613