1 /* SPDX-License-Identifier: GPL-2.0-or-later */ 2 /* 3 * Public Key Signature Algorithm 4 * 5 * Copyright (c) 2023 Herbert Xu <herbert@gondor.apana.org.au> 6 */ 7 #ifndef _CRYPTO_SIG_H 8 #define _CRYPTO_SIG_H 9 10 #include <linux/crypto.h> 11 12 /** 13 * struct crypto_sig - user-instantiated objects which encapsulate 14 * algorithms and core processing logic 15 * 16 * @base: Common crypto API algorithm data structure 17 */ 18 struct crypto_sig { 19 struct crypto_tfm base; 20 }; 21 22 /** 23 * DOC: Generic Public Key Signature API 24 * 25 * The Public Key Signature API is used with the algorithms of type 26 * CRYPTO_ALG_TYPE_SIG (listed as type "sig" in /proc/crypto) 27 */ 28 29 /** 30 * crypto_alloc_sig() - allocate signature tfm handle 31 * @alg_name: is the cra_name / name or cra_driver_name / driver name of the 32 * signing algorithm e.g. "ecdsa" 33 * @type: specifies the type of the algorithm 34 * @mask: specifies the mask for the algorithm 35 * 36 * Allocate a handle for public key signature algorithm. The returned struct 37 * crypto_sig is the handle that is required for any subsequent 38 * API invocation for signature operations. 39 * 40 * Return: allocated handle in case of success; IS_ERR() is true in case 41 * of an error, PTR_ERR() returns the error code. 42 */ 43 struct crypto_sig *crypto_alloc_sig(const char *alg_name, u32 type, u32 mask); 44 45 static inline struct crypto_tfm *crypto_sig_tfm(struct crypto_sig *tfm) 46 { 47 return &tfm->base; 48 } 49 50 /** 51 * crypto_free_sig() - free signature tfm handle 52 * 53 * @tfm: signature tfm handle allocated with crypto_alloc_sig() 54 * 55 * If @tfm is a NULL or error pointer, this function does nothing. 56 */ 57 static inline void crypto_free_sig(struct crypto_sig *tfm) 58 { 59 crypto_destroy_tfm(tfm, crypto_sig_tfm(tfm)); 60 } 61 62 /** 63 * crypto_sig_maxsize() - Get len for output buffer 64 * 65 * Function returns the dest buffer size required for a given key. 66 * Function assumes that the key is already set in the transformation. If this 67 * function is called without a setkey or with a failed setkey, you will end up 68 * in a NULL dereference. 69 * 70 * @tfm: signature tfm handle allocated with crypto_alloc_sig() 71 */ 72 int crypto_sig_maxsize(struct crypto_sig *tfm); 73 74 /** 75 * crypto_sig_sign() - Invoke signing operation 76 * 77 * Function invokes the specific signing operation for a given algorithm 78 * 79 * @tfm: signature tfm handle allocated with crypto_alloc_sig() 80 * @src: source buffer 81 * @slen: source length 82 * @dst: destination obuffer 83 * @dlen: destination length 84 * 85 * Return: zero on success; error code in case of error 86 */ 87 int crypto_sig_sign(struct crypto_sig *tfm, 88 const void *src, unsigned int slen, 89 void *dst, unsigned int dlen); 90 91 /** 92 * crypto_sig_verify() - Invoke signature verification 93 * 94 * Function invokes the specific signature verification operation 95 * for a given algorithm. 96 * 97 * @tfm: signature tfm handle allocated with crypto_alloc_sig() 98 * @src: source buffer 99 * @slen: source length 100 * @digest: digest 101 * @dlen: digest length 102 * 103 * Return: zero on verification success; error code in case of error. 104 */ 105 int crypto_sig_verify(struct crypto_sig *tfm, 106 const void *src, unsigned int slen, 107 const void *digest, unsigned int dlen); 108 109 /** 110 * crypto_sig_set_pubkey() - Invoke set public key operation 111 * 112 * Function invokes the algorithm specific set key function, which knows 113 * how to decode and interpret the encoded key and parameters 114 * 115 * @tfm: tfm handle 116 * @key: BER encoded public key, algo OID, paramlen, BER encoded 117 * parameters 118 * @keylen: length of the key (not including other data) 119 * 120 * Return: zero on success; error code in case of error 121 */ 122 int crypto_sig_set_pubkey(struct crypto_sig *tfm, 123 const void *key, unsigned int keylen); 124 125 /** 126 * crypto_sig_set_privkey() - Invoke set private key operation 127 * 128 * Function invokes the algorithm specific set key function, which knows 129 * how to decode and interpret the encoded key and parameters 130 * 131 * @tfm: tfm handle 132 * @key: BER encoded private key, algo OID, paramlen, BER encoded 133 * parameters 134 * @keylen: length of the key (not including other data) 135 * 136 * Return: zero on success; error code in case of error 137 */ 138 int crypto_sig_set_privkey(struct crypto_sig *tfm, 139 const void *key, unsigned int keylen); 140 #endif 141