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