include/crypto/akcipher.h

   1 /* SPDX-License-Identifier: GPL-2.0-or-later */
   2 /*
   3  * Public Key Encryption
   4  *
   5  * Copyright (c) 2015, Intel Corporation
   6  * Authors: Tadeusz Struk <tadeusz.struk@intel.com>
   7  */
   8 #ifndef _CRYPTO_AKCIPHER_H
   9 #define _CRYPTO_AKCIPHER_H
  10 #include <linux/crypto.h>
  11
  12 /**
  13  * struct akcipher_request - public key request
  14  *
  15  * @base:       Common attributes for async crypto requests
  16  * @src:        Source data
  17  *              For verify op this is signature + digest, in that case
  18  *              total size of @src is @src_len + @dst_len.
  19  * @dst:        Destination data (Should be NULL for verify op)
  20  * @src_len:    Size of the input buffer
  21  *              For verify op it's size of signature part of @src, this part
  22  *              is supposed to be operated by cipher.
  23  * @dst_len:    Size of @dst buffer (for all ops except verify).
  24  *              It needs to be at least as big as the expected result
  25  *              depending on the operation.
  26  *              After operation it will be updated with the actual size of the
  27  *              result.
  28  *              In case of error where the dst sgl size was insufficient,
  29  *              it will be updated to the size required for the operation.
  30  *              For verify op this is size of digest part in @src.
  31  * @__ctx:      Start of private context data
  32  */
  33 struct akcipher_request {
  34         struct crypto_async_request base;
  35         struct scatterlist *src;
  36         struct scatterlist *dst;
  37         unsigned int src_len;
  38         unsigned int dst_len;
  39         void *__ctx[] CRYPTO_MINALIGN_ATTR;
  40 };
  41
  42 /**
  43  * struct crypto_akcipher - user-instantiated objects which encapsulate
  44  * algorithms and core processing logic
  45  *
  46  * @base:       Common crypto API algorithm data structure
  47  */
  48 struct crypto_akcipher {
  49         struct crypto_tfm base;
  50 };
  51
  52 /**
  53  * struct akcipher_alg - generic public key algorithm
  54  *
  55  * @sign:       Function performs a sign operation as defined by public key
  56  *              algorithm. In case of error, where the dst_len was insufficient,
  57  *              the req->dst_len will be updated to the size required for the
  58  *              operation
  59  * @verify:     Function performs a complete verify operation as defined by
  60  *              public key algorithm, returning verification status. Requires
  61  *              digest value as input parameter.
  62  * @encrypt:    Function performs an encrypt operation as defined by public key
  63  *              algorithm. In case of error, where the dst_len was insufficient,
  64  *              the req->dst_len will be updated to the size required for the
  65  *              operation
  66  * @decrypt:    Function performs a decrypt operation as defined by public key
  67  *              algorithm. In case of error, where the dst_len was insufficient,
  68  *              the req->dst_len will be updated to the size required for the
  69  *              operation
  70  * @set_pub_key: Function invokes the algorithm specific set public key
  71  *              function, which knows how to decode and interpret
  72  *              the BER encoded public key and parameters
  73  * @set_priv_key: Function invokes the algorithm specific set private key
  74  *              function, which knows how to decode and interpret
  75  *              the BER encoded private key and parameters
  76  * @max_size:   Function returns dest buffer size required for a given key.
  77  * @init:       Initialize the cryptographic transformation object.
  78  *              This function is used to initialize the cryptographic
  79  *              transformation object. This function is called only once at
  80  *              the instantiation time, right after the transformation context
  81  *              was allocated. In case the cryptographic hardware has some
  82  *              special requirements which need to be handled by software, this
  83  *              function shall check for the precise requirement of the
  84  *              transformation and put any software fallbacks in place.
  85  * @exit:       Deinitialize the cryptographic transformation object. This is a
  86  *              counterpart to @init, used to remove various changes set in
  87  *              @init.
  88  *
  89  * @reqsize:    Request context size required by algorithm implementation
  90  * @base:       Common crypto API algorithm data structure
  91  */
  92 struct akcipher_alg {
  93         int (*sign)(struct akcipher_request *req);
  94         int (*verify)(struct akcipher_request *req);
  95         int (*encrypt)(struct akcipher_request *req);
  96         int (*decrypt)(struct akcipher_request *req);
  97         int (*set_pub_key)(struct crypto_akcipher *tfm, const void *key,
  98                            unsigned int keylen);
  99         int (*set_priv_key)(struct crypto_akcipher *tfm, const void *key,
 100                             unsigned int keylen);
 101         unsigned int (*max_size)(struct crypto_akcipher *tfm);
 102         int (*init)(struct crypto_akcipher *tfm);
 103         void (*exit)(struct crypto_akcipher *tfm);
 104
 105         unsigned int reqsize;
 106         struct crypto_alg base;
 107 };
 108
 109 /**
 110  * DOC: Generic Public Key API
 111  *
 112  * The Public Key API is used with the algorithms of type
 113  * CRYPTO_ALG_TYPE_AKCIPHER (listed as type "akcipher" in /proc/crypto)
 114  */
 115
 116 /**
 117  * crypto_alloc_akcipher() - allocate AKCIPHER tfm handle
 118  * @alg_name: is the cra_name / name or cra_driver_name / driver name of the
 119  *            public key algorithm e.g. "rsa"
 120  * @type: specifies the type of the algorithm
 121  * @mask: specifies the mask for the algorithm
 122  *
 123  * Allocate a handle for public key algorithm. The returned struct
 124  * crypto_akcipher is the handle that is required for any subsequent
 125  * API invocation for the public key operations.
 126  *
 127  * Return: allocated handle in case of success; IS_ERR() is true in case
 128  *         of an error, PTR_ERR() returns the error code.
 129  */
 130 struct crypto_akcipher *crypto_alloc_akcipher(const char *alg_name, u32 type,
 131                                               u32 mask);
 132
 133 static inline struct crypto_tfm *crypto_akcipher_tfm(
 134         struct crypto_akcipher *tfm)
 135 {
 136         return &tfm->base;
 137 }
 138
 139 static inline struct akcipher_alg *__crypto_akcipher_alg(struct crypto_alg *alg)
 140 {
 141         return container_of(alg, struct akcipher_alg, base);
 142 }
 143
 144 static inline struct crypto_akcipher *__crypto_akcipher_tfm(
 145         struct crypto_tfm *tfm)
 146 {
 147         return container_of(tfm, struct crypto_akcipher, base);
 148 }
 149
 150 static inline struct akcipher_alg *crypto_akcipher_alg(
 151         struct crypto_akcipher *tfm)
 152 {
 153         return __crypto_akcipher_alg(crypto_akcipher_tfm(tfm)->__crt_alg);
 154 }
 155
 156 static inline unsigned int crypto_akcipher_reqsize(struct crypto_akcipher *tfm)
 157 {
 158         return crypto_akcipher_alg(tfm)->reqsize;
 159 }
 160
 161 static inline void akcipher_request_set_tfm(struct akcipher_request *req,
 162                                             struct crypto_akcipher *tfm)
 163 {
 164         req->base.tfm = crypto_akcipher_tfm(tfm);
 165 }
 166
 167 static inline struct crypto_akcipher *crypto_akcipher_reqtfm(
 168         struct akcipher_request *req)
 169 {
 170         return __crypto_akcipher_tfm(req->base.tfm);
 171 }
 172
 173 /**
 174  * crypto_free_akcipher() - free AKCIPHER tfm handle
 175  *
 176  * @tfm: AKCIPHER tfm handle allocated with crypto_alloc_akcipher()
 177  */
 178 static inline void crypto_free_akcipher(struct crypto_akcipher *tfm)
 179 {
 180         crypto_destroy_tfm(tfm, crypto_akcipher_tfm(tfm));
 181 }
 182
 183 /**
 184  * akcipher_request_alloc() - allocates public key request
 185  *
 186  * @tfm:        AKCIPHER tfm handle allocated with crypto_alloc_akcipher()
 187  * @gfp:        allocation flags
 188  *
 189  * Return: allocated handle in case of success or NULL in case of an error.
 190  */
 191 static inline struct akcipher_request *akcipher_request_alloc(
 192         struct crypto_akcipher *tfm, gfp_t gfp)
 193 {
 194         struct akcipher_request *req;
 195
 196         req = kmalloc(sizeof(*req) + crypto_akcipher_reqsize(tfm), gfp);
 197         if (likely(req))
 198                 akcipher_request_set_tfm(req, tfm);
 199
 200         return req;
 201 }
 202
 203 /**
 204  * akcipher_request_free() - zeroize and free public key request
 205  *
 206  * @req:        request to free
 207  */
 208 static inline void akcipher_request_free(struct akcipher_request *req)
 209 {
 210         kzfree(req);
 211 }
 212
 213 /**
 214  * akcipher_request_set_callback() - Sets an asynchronous callback.
 215  *
 216  * Callback will be called when an asynchronous operation on a given
 217  * request is finished.
 218  *
 219  * @req:        request that the callback will be set for
 220  * @flgs:       specify for instance if the operation may backlog
 221  * @cmpl:       callback which will be called
 222  * @data:       private data used by the caller
 223  */
 224 static inline void akcipher_request_set_callback(struct akcipher_request *req,
 225                                                  u32 flgs,
 226                                                  crypto_completion_t cmpl,
 227                                                  void *data)
 228 {
 229         req->base.complete = cmpl;
 230         req->base.data = data;
 231         req->base.flags = flgs;
 232 }
 233
 234 /**
 235  * akcipher_request_set_crypt() - Sets request parameters
 236  *
 237  * Sets parameters required by crypto operation
 238  *
 239  * @req:        public key request
 240  * @src:        ptr to input scatter list
 241  * @dst:        ptr to output scatter list or NULL for verify op
 242  * @src_len:    size of the src input scatter list to be processed
 243  * @dst_len:    size of the dst output scatter list or size of signature
 244  *              portion in @src for verify op
 245  */
 246 static inline void akcipher_request_set_crypt(struct akcipher_request *req,
 247                                               struct scatterlist *src,
 248                                               struct scatterlist *dst,
 249                                               unsigned int src_len,
 250                                               unsigned int dst_len)
 251 {
 252         req->src = src;
 253         req->dst = dst;
 254         req->src_len = src_len;
 255         req->dst_len = dst_len;
 256 }
 257
 258 /**
 259  * crypto_akcipher_maxsize() - Get len for output buffer
 260  *
 261  * Function returns the dest buffer size required for a given key.
 262  * Function assumes that the key is already set in the transformation. If this
 263  * function is called without a setkey or with a failed setkey, you will end up
 264  * in a NULL dereference.
 265  *
 266  * @tfm:        AKCIPHER tfm handle allocated with crypto_alloc_akcipher()
 267  */
 268 static inline unsigned int crypto_akcipher_maxsize(struct crypto_akcipher *tfm)
 269 {
 270         struct akcipher_alg *alg = crypto_akcipher_alg(tfm);
 271
 272         return alg->max_size(tfm);
 273 }
 274
 275 /**
 276  * crypto_akcipher_encrypt() - Invoke public key encrypt operation
 277  *
 278  * Function invokes the specific public key encrypt operation for a given
 279  * public key algorithm
 280  *
 281  * @req:        asymmetric key request
 282  *
 283  * Return: zero on success; error code in case of error
 284  */
 285 static inline int crypto_akcipher_encrypt(struct akcipher_request *req)
 286 {
 287         struct crypto_akcipher *tfm = crypto_akcipher_reqtfm(req);
 288         struct akcipher_alg *alg = crypto_akcipher_alg(tfm);
 289         struct crypto_alg *calg = tfm->base.__crt_alg;
 290         unsigned int src_len = req->src_len;
 291         int ret;
 292
 293         crypto_stats_get(calg);
 294         ret = alg->encrypt(req);
 295         crypto_stats_akcipher_encrypt(src_len, ret, calg);
 296         return ret;
 297 }
 298
 299 /**
 300  * crypto_akcipher_decrypt() - Invoke public key decrypt operation
 301  *
 302  * Function invokes the specific public key decrypt operation for a given
 303  * public key algorithm
 304  *
 305  * @req:        asymmetric key request
 306  *
 307  * Return: zero on success; error code in case of error
 308  */
 309 static inline int crypto_akcipher_decrypt(struct akcipher_request *req)
 310 {
 311         struct crypto_akcipher *tfm = crypto_akcipher_reqtfm(req);
 312         struct akcipher_alg *alg = crypto_akcipher_alg(tfm);
 313         struct crypto_alg *calg = tfm->base.__crt_alg;
 314         unsigned int src_len = req->src_len;
 315         int ret;
 316
 317         crypto_stats_get(calg);
 318         ret = alg->decrypt(req);
 319         crypto_stats_akcipher_decrypt(src_len, ret, calg);
 320         return ret;
 321 }
 322
 323 /**
 324  * crypto_akcipher_sign() - Invoke public key sign operation
 325  *
 326  * Function invokes the specific public key sign operation for a given
 327  * public key algorithm
 328  *
 329  * @req:        asymmetric key request
 330  *
 331  * Return: zero on success; error code in case of error
 332  */
 333 static inline int crypto_akcipher_sign(struct akcipher_request *req)
 334 {
 335         struct crypto_akcipher *tfm = crypto_akcipher_reqtfm(req);
 336         struct akcipher_alg *alg = crypto_akcipher_alg(tfm);
 337         struct crypto_alg *calg = tfm->base.__crt_alg;
 338         int ret;
 339
 340         crypto_stats_get(calg);
 341         ret = alg->sign(req);
 342         crypto_stats_akcipher_sign(ret, calg);
 343         return ret;
 344 }
 345
 346 /**
 347  * crypto_akcipher_verify() - Invoke public key signature verification
 348  *
 349  * Function invokes the specific public key signature verification operation
 350  * for a given public key algorithm.
 351  *
 352  * @req:        asymmetric key request
 353  *
 354  * Note: req->dst should be NULL, req->src should point to SG of size
 355  * (req->src_size + req->dst_size), containing signature (of req->src_size
 356  * length) with appended digest (of req->dst_size length).
 357  *
 358  * Return: zero on verification success; error code in case of error.
 359  */
 360 static inline int crypto_akcipher_verify(struct akcipher_request *req)
 361 {
 362         struct crypto_akcipher *tfm = crypto_akcipher_reqtfm(req);
 363         struct akcipher_alg *alg = crypto_akcipher_alg(tfm);
 364         struct crypto_alg *calg = tfm->base.__crt_alg;
 365         int ret;
 366
 367         crypto_stats_get(calg);
 368         ret = alg->verify(req);
 369         crypto_stats_akcipher_verify(ret, calg);
 370         return ret;
 371 }
 372
 373 /**
 374  * crypto_akcipher_set_pub_key() - Invoke set public key operation
 375  *
 376  * Function invokes the algorithm specific set key function, which knows
 377  * how to decode and interpret the encoded key and parameters
 378  *
 379  * @tfm:        tfm handle
 380  * @key:        BER encoded public key, algo OID, paramlen, BER encoded
 381  *              parameters
 382  * @keylen:     length of the key (not including other data)
 383  *
 384  * Return: zero on success; error code in case of error
 385  */
 386 static inline int crypto_akcipher_set_pub_key(struct crypto_akcipher *tfm,
 387                                               const void *key,
 388                                               unsigned int keylen)
 389 {
 390         struct akcipher_alg *alg = crypto_akcipher_alg(tfm);
 391
 392         return alg->set_pub_key(tfm, key, keylen);
 393 }
 394
 395 /**
 396  * crypto_akcipher_set_priv_key() - Invoke set private key operation
 397  *
 398  * Function invokes the algorithm specific set key function, which knows
 399  * how to decode and interpret the encoded key and parameters
 400  *
 401  * @tfm:        tfm handle
 402  * @key:        BER encoded private key, algo OID, paramlen, BER encoded
 403  *              parameters
 404  * @keylen:     length of the key (not including other data)
 405  *
 406  * Return: zero on success; error code in case of error
 407  */
 408 static inline int crypto_akcipher_set_priv_key(struct crypto_akcipher *tfm,
 409                                                const void *key,
 410                                                unsigned int keylen)
 411 {
 412         struct akcipher_alg *alg = crypto_akcipher_alg(tfm);
 413
 414         return alg->set_priv_key(tfm, key, keylen);
 415 }
 416 #endif