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
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.