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         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