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 */
18struct 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 */
43struct crypto_sig *crypto_alloc_sig(const char *alg_name, u32 type, u32 mask);
44
45static 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 */
57static 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 */
72int 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 */
87int 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 */
105int 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 */
122int 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 */
138int crypto_sig_set_privkey(struct crypto_sig *tfm,
139			   const void *key, unsigned int keylen);
140#endif
141