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(mem: 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 | |