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  * If @tfm is a NULL or error pointer, this function does nothing.
 179  */
 180 static inline void crypto_free_akcipher(struct crypto_akcipher *tfm)
 181 {
 182         crypto_destroy_tfm(tfm, crypto_akcipher_tfm(tfm));
 183 }
 184
 185 /**
 186  * akcipher_request_alloc() - allocates public key request
 187  *
 188  * @tfm:        AKCIPHER tfm handle allocated with crypto_alloc_akcipher()
 189  * @gfp:        allocation flags
 190  *
 191  * Return: allocated handle in case of success or NULL in case of an error.
 192  */
 193 static inline struct akcipher_request *akcipher_request_alloc(
 194         struct crypto_akcipher *tfm, gfp_t gfp)
 195 {
 196         struct akcipher_request *req;
 197
 198         req = kmalloc(sizeof(*req) + crypto_akcipher_reqsize(tfm), gfp);
 199         if (likely(req))
 200                 akcipher_request_set_tfm(req, tfm);
 201
 202         return req;
 203 }
 204
 205 /**
 206  * akcipher_request_free() - zeroize and free public key request
 207  *
 208  * @req:        request to free
 209  */
 210 static inline void akcipher_request_free(struct akcipher_request *req)
 211 {
 212         kfree_sensitive(req);
 213 }
 214
 215 /**
 216  * akcipher_request_set_callback() - Sets an asynchronous callback.
 217  *
 218  * Callback will be called when an asynchronous operation on a given
 219  * request is finished.
 220  *
 221  * @req:        request that the callback will be set for
 222  * @flgs:       specify for instance if the operation may backlog
 223  * @cmpl:       callback which will be called
 224  * @data:       private data used by the caller
 225  */
 226 static inline void akcipher_request_set_callback(struct akcipher_request *req,
 227                                                  u32 flgs,
 228                                                  crypto_completion_t cmpl,
 229                                                  void *data)
 230 {
 231         req->base.complete = cmpl;
 232         req->base.data = data;
 233         req->base.flags = flgs;
 234 }
 235
 236 /**
 237  * akcipher_request_set_crypt() - Sets request parameters
 238  *
 239  * Sets parameters required by crypto operation
 240  *
 241  * @req:        public key request
 242  * @src:        ptr to input scatter list
 243  * @dst:        ptr to output scatter list or NULL for verify op
 244  * @src_len:    size of the src input scatter list to be processed
 245  * @dst_len:    size of the dst output scatter list or size of signature
 246  *              portion in @src for verify op
 247  */
 248 static inline void akcipher_request_set_crypt(struct akcipher_request *req,
 249                                               struct scatterlist *src,
 250                                               struct scatterlist *dst,
 251                                               unsigned int src_len,
 252                                               unsigned int dst_len)
 253 {
 254         req->src = src;
 255         req->dst = dst;
 256         req->src_len = src_len;
 257         req->dst_len = dst_len;
 258 }
 259
 260 /**
 261  * crypto_akcipher_maxsize() - Get len for output buffer
 262  *
 263  * Function returns the dest buffer size required for a given key.
 264  * Function assumes that the key is already set in the transformation. If this
 265  * function is called without a setkey or with a failed setkey, you will end up
 266  * in a NULL dereference.
 267  *
 268  * @tfm:        AKCIPHER tfm handle allocated with crypto_alloc_akcipher()
 269  */
 270 static inline unsigned int crypto_akcipher_maxsize(struct crypto_akcipher *tfm)
 271 {
 272         struct akcipher_alg *alg = crypto_akcipher_alg(tfm);
 273
 274         return alg->max_size(tfm);
 275 }
 276
 277 /**
 278  * crypto_akcipher_encrypt() - Invoke public key encrypt operation
 279  *
 280  * Function invokes the specific public key encrypt operation for a given
 281  * public key algorithm
 282  *
 283  * @req:        asymmetric key request
 284  *
 285  * Return: zero on success; error code in case of error
 286  */
 287 static inline int crypto_akcipher_encrypt(struct akcipher_request *req)
 288 {
 289         struct crypto_akcipher *tfm = crypto_akcipher_reqtfm(req);
 290         struct akcipher_alg *alg = crypto_akcipher_alg(tfm);
 291         struct crypto_alg *calg = tfm->base.__crt_alg;
 292         unsigned int src_len = req->src_len;
 293         int ret;
 294
 295         crypto_stats_get(calg);
 296         ret = alg->encrypt(req);
 297         crypto_stats_akcipher_encrypt(src_len, ret, calg);
 298         return ret;
 299 }
 300
 301 /**
 302  * crypto_akcipher_decrypt() - Invoke public key decrypt operation
 303  *
 304  * Function invokes the specific public key decrypt operation for a given
 305  * public key algorithm
 306  *
 307  * @req:        asymmetric key request
 308  *
 309  * Return: zero on success; error code in case of error
 310  */
 311 static inline int crypto_akcipher_decrypt(struct akcipher_request *req)
 312 {
 313         struct crypto_akcipher *tfm = crypto_akcipher_reqtfm(req);
 314         struct akcipher_alg *alg = crypto_akcipher_alg(tfm);
 315         struct crypto_alg *calg = tfm->base.__crt_alg;
 316         unsigned int src_len = req->src_len;
 317         int ret;
 318
 319         crypto_stats_get(calg);
 320         ret = alg->decrypt(req);
 321         crypto_stats_akcipher_decrypt(src_len, ret, calg);
 322         return ret;
 323 }
 324
 325 /**
 326  * crypto_akcipher_sign() - Invoke public key sign operation
 327  *
 328  * Function invokes the specific public key sign operation for a given
 329  * public key algorithm
 330  *
 331  * @req:        asymmetric key request
 332  *
 333  * Return: zero on success; error code in case of error
 334  */
 335 static inline int crypto_akcipher_sign(struct akcipher_request *req)
 336 {
 337         struct crypto_akcipher *tfm = crypto_akcipher_reqtfm(req);
 338         struct akcipher_alg *alg = crypto_akcipher_alg(tfm);
 339         struct crypto_alg *calg = tfm->base.__crt_alg;
 340         int ret;
 341
 342         crypto_stats_get(calg);
 343         ret = alg->sign(req);
 344         crypto_stats_akcipher_sign(ret, calg);
 345         return ret;
 346 }
 347
 348 /**
 349  * crypto_akcipher_verify() - Invoke public key signature verification
 350  *
 351  * Function invokes the specific public key signature verification operation
 352  * for a given public key algorithm.
 353  *
 354  * @req:        asymmetric key request
 355  *
 356  * Note: req->dst should be NULL, req->src should point to SG of size
 357  * (req->src_size + req->dst_size), containing signature (of req->src_size
 358  * length) with appended digest (of req->dst_size length).
 359  *
 360  * Return: zero on verification success; error code in case of error.
 361  */
 362 static inline int crypto_akcipher_verify(struct akcipher_request *req)
 363 {
 364         struct crypto_akcipher *tfm = crypto_akcipher_reqtfm(req);
 365         struct akcipher_alg *alg = crypto_akcipher_alg(tfm);
 366         struct crypto_alg *calg = tfm->base.__crt_alg;
 367         int ret;
 368
 369         crypto_stats_get(calg);
 370         ret = alg->verify(req);
 371         crypto_stats_akcipher_verify(ret, calg);
 372         return ret;
 373 }
 374
 375 /**
 376  * crypto_akcipher_set_pub_key() - Invoke set public key operation
 377  *
 378  * Function invokes the algorithm specific set key function, which knows
 379  * how to decode and interpret the encoded key and parameters
 380  *
 381  * @tfm:        tfm handle
 382  * @key:        BER encoded public key, algo OID, paramlen, BER encoded
 383  *              parameters
 384  * @keylen:     length of the key (not including other data)
 385  *
 386  * Return: zero on success; error code in case of error
 387  */
 388 static inline int crypto_akcipher_set_pub_key(struct crypto_akcipher *tfm,
 389                                               const void *key,
 390                                               unsigned int keylen)
 391 {
 392         struct akcipher_alg *alg = crypto_akcipher_alg(tfm);
 393
 394         return alg->set_pub_key(tfm, key, keylen);
 395 }
 396
 397 /**
 398  * crypto_akcipher_set_priv_key() - Invoke set private key operation
 399  *
 400  * Function invokes the algorithm specific set key function, which knows
 401  * how to decode and interpret the encoded key and parameters
 402  *
 403  * @tfm:        tfm handle
 404  * @key:        BER encoded private key, algo OID, paramlen, BER encoded
 405  *              parameters
 406  * @keylen:     length of the key (not including other data)
 407  *
 408  * Return: zero on success; error code in case of error
 409  */
 410 static inline int crypto_akcipher_set_priv_key(struct crypto_akcipher *tfm,
 411                                                const void *key,
 412                                                unsigned int keylen)
 413 {
 414         struct akcipher_alg *alg = crypto_akcipher_alg(tfm);
 415
 416         return alg->set_priv_key(tfm, key, keylen);
 417 }
 418 #endif