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 /** 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 * @base: Definition of a generic crypto algorithm. 122 * 123 * All fields except @ivsize are mandatory and must be filled. 124 */ 125 struct skcipher_alg { 126 int (*setkey)(struct crypto_skcipher *tfm, const u8 *key, 127 unsigned int keylen); 128 int (*encrypt)(struct skcipher_request *req); 129 int (*decrypt)(struct skcipher_request *req); 130 int (*init)(struct crypto_skcipher *tfm); 131 void (*exit)(struct crypto_skcipher *tfm); 132 133 unsigned int min_keysize; 134 unsigned int max_keysize; 135 unsigned int ivsize; 136 unsigned int chunksize; 137 unsigned int walksize; 138 139 struct crypto_alg base; 140 }; 141 142 #define SKCIPHER_REQUEST_ON_STACK(name, tfm) \ 143 char __##name##_desc[sizeof(struct skcipher_request) + \ 144 crypto_skcipher_reqsize(tfm)] CRYPTO_MINALIGN_ATTR; \ 145 struct skcipher_request *name = (void *)__##name##_desc 146 147 /** 148 * DOC: Symmetric Key Cipher API 149 * 150 * Symmetric key cipher API is used with the ciphers of type 151 * CRYPTO_ALG_TYPE_SKCIPHER (listed as type "skcipher" in /proc/crypto). 152 * 153 * Asynchronous cipher operations imply that the function invocation for a 154 * cipher request returns immediately before the completion of the operation. 155 * The cipher request is scheduled as a separate kernel thread and therefore 156 * load-balanced on the different CPUs via the process scheduler. To allow 157 * the kernel crypto API to inform the caller about the completion of a cipher 158 * request, the caller must provide a callback function. That function is 159 * invoked with the cipher handle when the request completes. 160 * 161 * To support the asynchronous operation, additional information than just the 162 * cipher handle must be supplied to the kernel crypto API. That additional 163 * information is given by filling in the skcipher_request data structure. 164 * 165 * For the symmetric key cipher API, the state is maintained with the tfm 166 * cipher handle. A single tfm can be used across multiple calls and in 167 * parallel. For asynchronous block cipher calls, context data supplied and 168 * only used by the caller can be referenced the request data structure in 169 * addition to the IV used for the cipher request. The maintenance of such 170 * state information would be important for a crypto driver implementer to 171 * have, because when calling the callback function upon completion of the 172 * cipher operation, that callback function may need some information about 173 * which operation just finished if it invoked multiple in parallel. This 174 * state information is unused by the kernel crypto API. 175 */ 176 177 static inline struct crypto_skcipher *__crypto_skcipher_cast( 178 struct crypto_tfm *tfm) 179 { 180 return container_of(tfm, struct crypto_skcipher, base); 181 } 182 183 /** 184 * crypto_alloc_skcipher() - allocate symmetric key cipher handle 185 * @alg_name: is the cra_name / name or cra_driver_name / driver name of the 186 * skcipher cipher 187 * @type: specifies the type of the cipher 188 * @mask: specifies the mask for the cipher 189 * 190 * Allocate a cipher handle for an skcipher. The returned struct 191 * crypto_skcipher is the cipher handle that is required for any subsequent 192 * API invocation for that skcipher. 193 * 194 * Return: allocated cipher handle in case of success; IS_ERR() is true in case 195 * of an error, PTR_ERR() returns the error code. 196 */ 197 struct crypto_skcipher *crypto_alloc_skcipher(const char *alg_name, 198 u32 type, u32 mask); 199 200 static inline struct crypto_tfm *crypto_skcipher_tfm( 201 struct crypto_skcipher *tfm) 202 { 203 return &tfm->base; 204 } 205 206 /** 207 * crypto_free_skcipher() - zeroize and free cipher handle 208 * @tfm: cipher handle to be freed 209 */ 210 static inline void crypto_free_skcipher(struct crypto_skcipher *tfm) 211 { 212 crypto_destroy_tfm(tfm, crypto_skcipher_tfm(tfm)); 213 } 214 215 /** 216 * crypto_has_skcipher() - Search for the availability of an skcipher. 217 * @alg_name: is the cra_name / name or cra_driver_name / driver name of the 218 * skcipher 219 * @type: specifies the type of the cipher 220 * @mask: specifies the mask for the cipher 221 * 222 * Return: true when the skcipher is known to the kernel crypto API; false 223 * otherwise 224 */ 225 static inline int crypto_has_skcipher(const char *alg_name, u32 type, 226 u32 mask) 227 { 228 return crypto_has_alg(alg_name, crypto_skcipher_type(type), 229 crypto_skcipher_mask(mask)); 230 } 231 232 /** 233 * crypto_has_skcipher2() - Search for the availability of an skcipher. 234 * @alg_name: is the cra_name / name or cra_driver_name / driver name of the 235 * skcipher 236 * @type: specifies the type of the skcipher 237 * @mask: specifies the mask for the skcipher 238 * 239 * Return: true when the skcipher is known to the kernel crypto API; false 240 * otherwise 241 */ 242 int crypto_has_skcipher2(const char *alg_name, u32 type, u32 mask); 243 244 static inline const char *crypto_skcipher_driver_name( 245 struct crypto_skcipher *tfm) 246 { 247 return crypto_tfm_alg_driver_name(crypto_skcipher_tfm(tfm)); 248 } 249 250 static inline struct skcipher_alg *crypto_skcipher_alg( 251 struct crypto_skcipher *tfm) 252 { 253 return container_of(crypto_skcipher_tfm(tfm)->__crt_alg, 254 struct skcipher_alg, base); 255 } 256 257 static inline unsigned int crypto_skcipher_alg_ivsize(struct skcipher_alg *alg) 258 { 259 if ((alg->base.cra_flags & CRYPTO_ALG_TYPE_MASK) == 260 CRYPTO_ALG_TYPE_BLKCIPHER) 261 return alg->base.cra_blkcipher.ivsize; 262 263 if (alg->base.cra_ablkcipher.encrypt) 264 return alg->base.cra_ablkcipher.ivsize; 265 266 return alg->ivsize; 267 } 268 269 /** 270 * crypto_skcipher_ivsize() - obtain IV size 271 * @tfm: cipher handle 272 * 273 * The size of the IV for the skcipher referenced by the cipher handle is 274 * returned. This IV size may be zero if the cipher does not need an IV. 275 * 276 * Return: IV size in bytes 277 */ 278 static inline unsigned int crypto_skcipher_ivsize(struct crypto_skcipher *tfm) 279 { 280 return tfm->ivsize; 281 } 282 283 static inline unsigned int crypto_skcipher_alg_chunksize( 284 struct skcipher_alg *alg) 285 { 286 if ((alg->base.cra_flags & CRYPTO_ALG_TYPE_MASK) == 287 CRYPTO_ALG_TYPE_BLKCIPHER) 288 return alg->base.cra_blocksize; 289 290 if (alg->base.cra_ablkcipher.encrypt) 291 return alg->base.cra_blocksize; 292 293 return alg->chunksize; 294 } 295 296 static inline unsigned int crypto_skcipher_alg_walksize( 297 struct skcipher_alg *alg) 298 { 299 if ((alg->base.cra_flags & CRYPTO_ALG_TYPE_MASK) == 300 CRYPTO_ALG_TYPE_BLKCIPHER) 301 return alg->base.cra_blocksize; 302 303 if (alg->base.cra_ablkcipher.encrypt) 304 return alg->base.cra_blocksize; 305 306 return alg->walksize; 307 } 308 309 /** 310 * crypto_skcipher_chunksize() - obtain chunk size 311 * @tfm: cipher handle 312 * 313 * The block size is set to one for ciphers such as CTR. However, 314 * you still need to provide incremental updates in multiples of 315 * the underlying block size as the IV does not have sub-block 316 * granularity. This is known in this API as the chunk size. 317 * 318 * Return: chunk size in bytes 319 */ 320 static inline unsigned int crypto_skcipher_chunksize( 321 struct crypto_skcipher *tfm) 322 { 323 return crypto_skcipher_alg_chunksize(crypto_skcipher_alg(tfm)); 324 } 325 326 /** 327 * crypto_skcipher_walksize() - obtain walk size 328 * @tfm: cipher handle 329 * 330 * In some cases, algorithms can only perform optimally when operating on 331 * multiple blocks in parallel. This is reflected by the walksize, which 332 * must be a multiple of the chunksize (or equal if the concern does not 333 * apply) 334 * 335 * Return: walk size in bytes 336 */ 337 static inline unsigned int crypto_skcipher_walksize( 338 struct crypto_skcipher *tfm) 339 { 340 return crypto_skcipher_alg_walksize(crypto_skcipher_alg(tfm)); 341 } 342 343 /** 344 * crypto_skcipher_blocksize() - obtain block size of cipher 345 * @tfm: cipher handle 346 * 347 * The block size for the skcipher referenced with the cipher handle is 348 * returned. The caller may use that information to allocate appropriate 349 * memory for the data returned by the encryption or decryption operation 350 * 351 * Return: block size of cipher 352 */ 353 static inline unsigned int crypto_skcipher_blocksize( 354 struct crypto_skcipher *tfm) 355 { 356 return crypto_tfm_alg_blocksize(crypto_skcipher_tfm(tfm)); 357 } 358 359 static inline unsigned int crypto_skcipher_alignmask( 360 struct crypto_skcipher *tfm) 361 { 362 return crypto_tfm_alg_alignmask(crypto_skcipher_tfm(tfm)); 363 } 364 365 static inline u32 crypto_skcipher_get_flags(struct crypto_skcipher *tfm) 366 { 367 return crypto_tfm_get_flags(crypto_skcipher_tfm(tfm)); 368 } 369 370 static inline void crypto_skcipher_set_flags(struct crypto_skcipher *tfm, 371 u32 flags) 372 { 373 crypto_tfm_set_flags(crypto_skcipher_tfm(tfm), flags); 374 } 375 376 static inline void crypto_skcipher_clear_flags(struct crypto_skcipher *tfm, 377 u32 flags) 378 { 379 crypto_tfm_clear_flags(crypto_skcipher_tfm(tfm), flags); 380 } 381 382 /** 383 * crypto_skcipher_setkey() - set key for cipher 384 * @tfm: cipher handle 385 * @key: buffer holding the key 386 * @keylen: length of the key in bytes 387 * 388 * The caller provided key is set for the skcipher referenced by the cipher 389 * handle. 390 * 391 * Note, the key length determines the cipher type. Many block ciphers implement 392 * different cipher modes depending on the key size, such as AES-128 vs AES-192 393 * vs. AES-256. When providing a 16 byte key for an AES cipher handle, AES-128 394 * is performed. 395 * 396 * Return: 0 if the setting of the key was successful; < 0 if an error occurred 397 */ 398 static inline int crypto_skcipher_setkey(struct crypto_skcipher *tfm, 399 const u8 *key, unsigned int keylen) 400 { 401 return tfm->setkey(tfm, key, keylen); 402 } 403 404 static inline unsigned int crypto_skcipher_default_keysize( 405 struct crypto_skcipher *tfm) 406 { 407 return tfm->keysize; 408 } 409 410 /** 411 * crypto_skcipher_reqtfm() - obtain cipher handle from request 412 * @req: skcipher_request out of which the cipher handle is to be obtained 413 * 414 * Return the crypto_skcipher handle when furnishing an skcipher_request 415 * data structure. 416 * 417 * Return: crypto_skcipher handle 418 */ 419 static inline struct crypto_skcipher *crypto_skcipher_reqtfm( 420 struct skcipher_request *req) 421 { 422 return __crypto_skcipher_cast(req->base.tfm); 423 } 424 425 /** 426 * crypto_skcipher_encrypt() - encrypt plaintext 427 * @req: reference to the skcipher_request handle that holds all information 428 * needed to perform the cipher operation 429 * 430 * Encrypt plaintext data using the skcipher_request handle. That data 431 * structure and how it is filled with data is discussed with the 432 * skcipher_request_* functions. 433 * 434 * Return: 0 if the cipher operation was successful; < 0 if an error occurred 435 */ 436 static inline int crypto_skcipher_encrypt(struct skcipher_request *req) 437 { 438 struct crypto_skcipher *tfm = crypto_skcipher_reqtfm(req); 439 440 if (crypto_skcipher_get_flags(tfm) & CRYPTO_TFM_NEED_KEY) 441 return -ENOKEY; 442 443 return tfm->encrypt(req); 444 } 445 446 /** 447 * crypto_skcipher_decrypt() - decrypt ciphertext 448 * @req: reference to the skcipher_request handle that holds all information 449 * needed to perform the cipher operation 450 * 451 * Decrypt ciphertext data using the skcipher_request handle. That data 452 * structure and how it is filled with data is discussed with the 453 * skcipher_request_* functions. 454 * 455 * Return: 0 if the cipher operation was successful; < 0 if an error occurred 456 */ 457 static inline int crypto_skcipher_decrypt(struct skcipher_request *req) 458 { 459 struct crypto_skcipher *tfm = crypto_skcipher_reqtfm(req); 460 461 if (crypto_skcipher_get_flags(tfm) & CRYPTO_TFM_NEED_KEY) 462 return -ENOKEY; 463 464 return tfm->decrypt(req); 465 } 466 467 /** 468 * DOC: Symmetric Key Cipher Request Handle 469 * 470 * The skcipher_request data structure contains all pointers to data 471 * required for the symmetric key cipher operation. This includes the cipher 472 * handle (which can be used by multiple skcipher_request instances), pointer 473 * to plaintext and ciphertext, asynchronous callback function, etc. It acts 474 * as a handle to the skcipher_request_* API calls in a similar way as 475 * skcipher handle to the crypto_skcipher_* API calls. 476 */ 477 478 /** 479 * crypto_skcipher_reqsize() - obtain size of the request data structure 480 * @tfm: cipher handle 481 * 482 * Return: number of bytes 483 */ 484 static inline unsigned int crypto_skcipher_reqsize(struct crypto_skcipher *tfm) 485 { 486 return tfm->reqsize; 487 } 488 489 /** 490 * skcipher_request_set_tfm() - update cipher handle reference in request 491 * @req: request handle to be modified 492 * @tfm: cipher handle that shall be added to the request handle 493 * 494 * Allow the caller to replace the existing skcipher handle in the request 495 * data structure with a different one. 496 */ 497 static inline void skcipher_request_set_tfm(struct skcipher_request *req, 498 struct crypto_skcipher *tfm) 499 { 500 req->base.tfm = crypto_skcipher_tfm(tfm); 501 } 502 503 static inline struct skcipher_request *skcipher_request_cast( 504 struct crypto_async_request *req) 505 { 506 return container_of(req, struct skcipher_request, base); 507 } 508 509 /** 510 * skcipher_request_alloc() - allocate request data structure 511 * @tfm: cipher handle to be registered with the request 512 * @gfp: memory allocation flag that is handed to kmalloc by the API call. 513 * 514 * Allocate the request data structure that must be used with the skcipher 515 * encrypt and decrypt API calls. During the allocation, the provided skcipher 516 * handle is registered in the request data structure. 517 * 518 * Return: allocated request handle in case of success, or NULL if out of memory 519 */ 520 static inline struct skcipher_request *skcipher_request_alloc( 521 struct crypto_skcipher *tfm, gfp_t gfp) 522 { 523 struct skcipher_request *req; 524 525 req = kmalloc(sizeof(struct skcipher_request) + 526 crypto_skcipher_reqsize(tfm), gfp); 527 528 if (likely(req)) 529 skcipher_request_set_tfm(req, tfm); 530 531 return req; 532 } 533 534 /** 535 * skcipher_request_free() - zeroize and free request data structure 536 * @req: request data structure cipher handle to be freed 537 */ 538 static inline void skcipher_request_free(struct skcipher_request *req) 539 { 540 kzfree(req); 541 } 542 543 static inline void skcipher_request_zero(struct skcipher_request *req) 544 { 545 struct crypto_skcipher *tfm = crypto_skcipher_reqtfm(req); 546 547 memzero_explicit(req, sizeof(*req) + crypto_skcipher_reqsize(tfm)); 548 } 549 550 /** 551 * skcipher_request_set_callback() - set asynchronous callback function 552 * @req: request handle 553 * @flags: specify zero or an ORing of the flags 554 * CRYPTO_TFM_REQ_MAY_BACKLOG the request queue may back log and 555 * increase the wait queue beyond the initial maximum size; 556 * CRYPTO_TFM_REQ_MAY_SLEEP the request processing may sleep 557 * @compl: callback function pointer to be registered with the request handle 558 * @data: The data pointer refers to memory that is not used by the kernel 559 * crypto API, but provided to the callback function for it to use. Here, 560 * the caller can provide a reference to memory the callback function can 561 * operate on. As the callback function is invoked asynchronously to the 562 * related functionality, it may need to access data structures of the 563 * related functionality which can be referenced using this pointer. The 564 * callback function can access the memory via the "data" field in the 565 * crypto_async_request data structure provided to the callback function. 566 * 567 * This function allows setting the callback function that is triggered once the 568 * cipher operation completes. 569 * 570 * The callback function is registered with the skcipher_request handle and 571 * must comply with the following template:: 572 * 573 * void callback_function(struct crypto_async_request *req, int error) 574 */ 575 static inline void skcipher_request_set_callback(struct skcipher_request *req, 576 u32 flags, 577 crypto_completion_t compl, 578 void *data) 579 { 580 req->base.complete = compl; 581 req->base.data = data; 582 req->base.flags = flags; 583 } 584 585 /** 586 * skcipher_request_set_crypt() - set data buffers 587 * @req: request handle 588 * @src: source scatter / gather list 589 * @dst: destination scatter / gather list 590 * @cryptlen: number of bytes to process from @src 591 * @iv: IV for the cipher operation which must comply with the IV size defined 592 * by crypto_skcipher_ivsize 593 * 594 * This function allows setting of the source data and destination data 595 * scatter / gather lists. 596 * 597 * For encryption, the source is treated as the plaintext and the 598 * destination is the ciphertext. For a decryption operation, the use is 599 * reversed - the source is the ciphertext and the destination is the plaintext. 600 */ 601 static inline void skcipher_request_set_crypt( 602 struct skcipher_request *req, 603 struct scatterlist *src, struct scatterlist *dst, 604 unsigned int cryptlen, void *iv) 605 { 606 req->src = src; 607 req->dst = dst; 608 req->cryptlen = cryptlen; 609 req->iv = iv; 610 } 611 612 #endif /* _CRYPTO_SKCIPHER_H */ 613 614