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 * struct sig_alg - generic public key signature algorithm 24 * 25 * @sign: Function performs a sign operation as defined by public key 26 * algorithm. Optional. 27 * @verify: Function performs a complete verify operation as defined by 28 * public key algorithm, returning verification status. Optional. 29 * @set_pub_key: Function invokes the algorithm specific set public key 30 * function, which knows how to decode and interpret 31 * the BER encoded public key and parameters. Mandatory. 32 * @set_priv_key: Function invokes the algorithm specific set private key 33 * function, which knows how to decode and interpret 34 * the BER encoded private key and parameters. Optional. 35 * @max_size: Function returns key size. Mandatory. 36 * @init: Initialize the cryptographic transformation object. 37 * This function is used to initialize the cryptographic 38 * transformation object. This function is called only once at 39 * the instantiation time, right after the transformation context 40 * was allocated. In case the cryptographic hardware has some 41 * special requirements which need to be handled by software, this 42 * function shall check for the precise requirement of the 43 * transformation and put any software fallbacks in place. 44 * @exit: Deinitialize the cryptographic transformation object. This is a 45 * counterpart to @init, used to remove various changes set in 46 * @init. 47 * 48 * @base: Common crypto API algorithm data structure 49 */ 50 struct sig_alg { 51 int (*sign)(struct crypto_sig *tfm, 52 const void *src, unsigned int slen, 53 void *dst, unsigned int dlen); 54 int (*verify)(struct crypto_sig *tfm, 55 const void *src, unsigned int slen, 56 const void *digest, unsigned int dlen); 57 int (*set_pub_key)(struct crypto_sig *tfm, 58 const void *key, unsigned int keylen); 59 int (*set_priv_key)(struct crypto_sig *tfm, 60 const void *key, unsigned int keylen); 61 unsigned int (*max_size)(struct crypto_sig *tfm); 62 int (*init)(struct crypto_sig *tfm); 63 void (*exit)(struct crypto_sig *tfm); 64 65 struct crypto_alg base; 66 }; 67 68 /** 69 * DOC: Generic Public Key Signature API 70 * 71 * The Public Key Signature API is used with the algorithms of type 72 * CRYPTO_ALG_TYPE_SIG (listed as type "sig" in /proc/crypto) 73 */ 74 75 /** 76 * crypto_alloc_sig() - allocate signature tfm handle 77 * @alg_name: is the cra_name / name or cra_driver_name / driver name of the 78 * signing algorithm e.g. "ecdsa" 79 * @type: specifies the type of the algorithm 80 * @mask: specifies the mask for the algorithm 81 * 82 * Allocate a handle for public key signature algorithm. The returned struct 83 * crypto_sig is the handle that is required for any subsequent 84 * API invocation for signature operations. 85 * 86 * Return: allocated handle in case of success; IS_ERR() is true in case 87 * of an error, PTR_ERR() returns the error code. 88 */ 89 struct crypto_sig *crypto_alloc_sig(const char *alg_name, u32 type, u32 mask); 90 91 static inline struct crypto_tfm *crypto_sig_tfm(struct crypto_sig *tfm) 92 { 93 return &tfm->base; 94 } 95 96 static inline struct crypto_sig *__crypto_sig_tfm(struct crypto_tfm *tfm) 97 { 98 return container_of(tfm, struct crypto_sig, base); 99 } 100 101 static inline struct sig_alg *__crypto_sig_alg(struct crypto_alg *alg) 102 { 103 return container_of(alg, struct sig_alg, base); 104 } 105 106 static inline struct sig_alg *crypto_sig_alg(struct crypto_sig *tfm) 107 { 108 return __crypto_sig_alg(crypto_sig_tfm(tfm)->__crt_alg); 109 } 110 111 /** 112 * crypto_free_sig() - free signature tfm handle 113 * 114 * @tfm: signature tfm handle allocated with crypto_alloc_sig() 115 * 116 * If @tfm is a NULL or error pointer, this function does nothing. 117 */ 118 static inline void crypto_free_sig(struct crypto_sig *tfm) 119 { 120 crypto_destroy_tfm(tfm, crypto_sig_tfm(tfm)); 121 } 122 123 /** 124 * crypto_sig_maxsize() - Get len for output buffer 125 * 126 * Function returns the dest buffer size required for a given key. 127 * Function assumes that the key is already set in the transformation. If this 128 * function is called without a setkey or with a failed setkey, you will end up 129 * in a NULL dereference. 130 * 131 * @tfm: signature tfm handle allocated with crypto_alloc_sig() 132 */ 133 int crypto_sig_maxsize(struct crypto_sig *tfm); 134 135 /** 136 * crypto_sig_sign() - Invoke signing operation 137 * 138 * Function invokes the specific signing operation for a given algorithm 139 * 140 * @tfm: signature tfm handle allocated with crypto_alloc_sig() 141 * @src: source buffer 142 * @slen: source length 143 * @dst: destination obuffer 144 * @dlen: destination length 145 * 146 * Return: zero on success; error code in case of error 147 */ 148 int crypto_sig_sign(struct crypto_sig *tfm, 149 const void *src, unsigned int slen, 150 void *dst, unsigned int dlen); 151 152 /** 153 * crypto_sig_verify() - Invoke signature verification 154 * 155 * Function invokes the specific signature verification operation 156 * for a given algorithm. 157 * 158 * @tfm: signature tfm handle allocated with crypto_alloc_sig() 159 * @src: source buffer 160 * @slen: source length 161 * @digest: digest 162 * @dlen: digest length 163 * 164 * Return: zero on verification success; error code in case of error. 165 */ 166 int crypto_sig_verify(struct crypto_sig *tfm, 167 const void *src, unsigned int slen, 168 const void *digest, unsigned int dlen); 169 170 /** 171 * crypto_sig_set_pubkey() - Invoke set public key operation 172 * 173 * Function invokes the algorithm specific set key function, which knows 174 * how to decode and interpret the encoded key and parameters 175 * 176 * @tfm: tfm handle 177 * @key: BER encoded public key, algo OID, paramlen, BER encoded 178 * parameters 179 * @keylen: length of the key (not including other data) 180 * 181 * Return: zero on success; error code in case of error 182 */ 183 int crypto_sig_set_pubkey(struct crypto_sig *tfm, 184 const void *key, unsigned int keylen); 185 186 /** 187 * crypto_sig_set_privkey() - Invoke set private key operation 188 * 189 * Function invokes the algorithm specific set key function, which knows 190 * how to decode and interpret the encoded key and parameters 191 * 192 * @tfm: tfm handle 193 * @key: BER encoded private key, algo OID, paramlen, BER encoded 194 * parameters 195 * @keylen: length of the key (not including other data) 196 * 197 * Return: zero on success; error code in case of error 198 */ 199 int crypto_sig_set_privkey(struct crypto_sig *tfm, 200 const void *key, unsigned int keylen); 201 #endif 202