kernel/include/crypto/skcipher.h

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