Botan 3.14.1
Crypto and TLS for C&
pk_ops.h
Go to the documentation of this file.
1/*
2* (C) 2010,2015 Jack Lloyd
3*
4* Botan is released under the Simplified BSD License (see license.txt)
5*/
6
7#ifndef BOTAN_PK_OPERATIONS_H_
8#define BOTAN_PK_OPERATIONS_H_
9
10/**
11* Ordinary applications should never need to include or use this
12* header. It is exposed only for specialized applications which want
13* to implement new versions of public key crypto without merging them
14* as changes to the library. One actual example of such usage is an
15* application which creates RSA signatures using a custom TPM library.
16* Unless you're doing something like that, you don't need anything
17* here. Instead use pubkey.h which wraps these types safely and
18* provides a stable application-oriented API.
19*
20* Note: This header was accidentally pulled from the public API between
21* Botan 3.0.0 and 3.2.0, and then restored in 3.3.0. If you are
22* maintaining an application which used this header in Botan 2.x,
23* you should make sure to use Botan 3.3.0 or later when migrating.
24*/
25
26#include <botan/pk_keys.h>
27#include <botan/secmem.h>
28#include <span>
29
30namespace Botan {
31
33
34} // namespace Botan
35
36namespace Botan::PK_Ops {
37
38/**
39* Public key encryption interface
40*/
41class BOTAN_UNSTABLE_API Encryption /* NOLINT(*special-member-functions) */ {
42 public:
43 /**
44 * Encrypt a message returning the ciphertext
45 */
46 virtual std::vector<uint8_t> encrypt(std::span<const uint8_t> msg, RandomNumberGenerator& rng) = 0;
47
48 /**
49 * Return the maximum input size for this key
50 */
51 virtual size_t max_input_bits() const = 0;
52
53 /**
54 * Given the plaintext length, return an upper bound of the ciphertext
55 * length for this key and padding.
56 */
57 virtual size_t ciphertext_length(size_t ptext_len) const = 0;
58
59 virtual ~Encryption() = default;
60};
61
62/**
63* Public key decryption interface
64*/
65class BOTAN_UNSTABLE_API Decryption /* NOLINT(*special-member-functions) */ {
66 public:
67 /**
68 * Decrypt a ciphertext, writing the plaintext to the start of ptext
69 *
70 * @param valid_mask set to 0xFF if the ciphertext was valid, otherwise 0
71 * @param ptext the output, which must be at least
72 * plaintext_length(ctext.size()) bytes long
73 * @param ctext the ciphertext
74 * @return the length of the plaintext, which is meaningless if the
75 * ciphertext was invalid
76 *
77 * For some schemes (eg PKCS #1 v1.5) whether the ciphertext was valid, and
78 * the length of the plaintext, must be kept secret, so neither should be
79 * declassified here.
80 */
81 virtual size_t decrypt(uint8_t& valid_mask, std::span<uint8_t> ptext, std::span<const uint8_t> ctext) = 0;
82
83 virtual size_t plaintext_length(size_t ctext_len) const = 0;
84
85 /**
86 * Given the plaintext length, return an upper bound on the ciphertext
87 * length that decrypt() expects for this key and padding.
88 */
89 virtual size_t ciphertext_length(size_t ptext_len) const = 0;
90
91 virtual ~Decryption() = default;
92};
93
94/**
95* Public key signature verification interface
96*/
97class BOTAN_UNSTABLE_API Verification /* NOLINT(*special-member-functions) */ {
98 public:
99 /**
100 * Add more data to the message currently being signed
101 * @param input the input to be hashed/verified
102 */
103 virtual void update(std::span<const uint8_t> input) = 0;
104
105 /**
106 * Perform a verification operation
107 * @param sig the signature to be checked with respect to the input
108 */
109 virtual bool is_valid_signature(std::span<const uint8_t> sig) = 0;
110
111 /**
112 * Return the hash function being used by this signer
113 */
114 virtual std::string hash_function() const = 0;
115
116 virtual ~Verification() = default;
117};
118
119/**
120* Public key signature creation interface
121*/
122class BOTAN_UNSTABLE_API Signature /* NOLINT(*special-member-functions) */ {
123 public:
124 /**
125 * Add more data to the message currently being signed
126 * @param input the input to be hashed/signed
127 */
128 virtual void update(std::span<const uint8_t> input) = 0;
129
130 /**
131 * Perform a signature operation
132 * @param rng a random number generator
133 */
134 virtual std::vector<uint8_t> sign(RandomNumberGenerator& rng) = 0;
135
136 /**
137 * Return an upper bound on the length of the output signature
138 */
139 virtual size_t signature_length() const = 0;
140
141 /**
142 * Return an algorithm identifier associated with this signature scheme.
143 *
144 * Default implementation throws an exception
145 */
147
148 /**
149 * Return the hash function being used by this signer
150 */
151 virtual std::string hash_function() const = 0;
152
153 virtual ~Signature() = default;
154};
155
156/**
157* A generic key agreement operation (eg DH or ECDH)
158*/
159class BOTAN_UNSTABLE_API Key_Agreement /* NOLINT(*special-member-functions) */ {
160 public:
161 virtual secure_vector<uint8_t> agree(size_t key_len,
162 std::span<const uint8_t> other_key,
163 std::span<const uint8_t> salt) = 0;
164
165 virtual size_t agreed_value_size() const = 0;
166
167 virtual ~Key_Agreement() = default;
168};
169
170/**
171* KEM (key encapsulation)
172*/
173class BOTAN_UNSTABLE_API KEM_Encryption /* NOLINT(*special-member-functions) */ {
174 public:
175 virtual void kem_encrypt(std::span<uint8_t> out_encapsulated_key,
176 std::span<uint8_t> out_shared_key,
178 size_t desired_shared_key_len,
179 std::span<const uint8_t> salt) = 0;
180
181 virtual size_t shared_key_length(size_t desired_shared_key_len) const = 0;
182
183 virtual size_t encapsulated_key_length() const = 0;
184
185 virtual ~KEM_Encryption() = default;
186};
187
188class BOTAN_UNSTABLE_API KEM_Decryption /* NOLINT(*special-member-functions) */ {
189 public:
190 virtual void kem_decrypt(std::span<uint8_t> out_shared_key,
191 std::span<const uint8_t> encapsulated_key,
192 size_t desired_shared_key_len,
193 std::span<const uint8_t> salt) = 0;
194
195 virtual size_t shared_key_length(size_t desired_shared_key_len) const = 0;
196
197 virtual size_t encapsulated_key_length() const = 0;
198
199 virtual ~KEM_Decryption() = default;
200};
201
202} // namespace Botan::PK_Ops
203
204#endif
#define BOTAN_UNSTABLE_API
Definition api.h:34
virtual size_t ciphertext_length(size_t ptext_len) const =0
virtual size_t decrypt(uint8_t &valid_mask, std::span< uint8_t > ptext, std::span< const uint8_t > ctext)=0
virtual ~Decryption()=default
virtual size_t plaintext_length(size_t ctext_len) const =0
virtual size_t ciphertext_length(size_t ptext_len) const =0
virtual std::vector< uint8_t > encrypt(std::span< const uint8_t > msg, RandomNumberGenerator &rng)=0
virtual ~Encryption()=default
virtual size_t max_input_bits() const =0
virtual void kem_decrypt(std::span< uint8_t > out_shared_key, std::span< const uint8_t > encapsulated_key, size_t desired_shared_key_len, std::span< const uint8_t > salt)=0
virtual ~KEM_Decryption()=default
virtual size_t encapsulated_key_length() const =0
virtual size_t shared_key_length(size_t desired_shared_key_len) const =0
virtual size_t encapsulated_key_length() const =0
virtual ~KEM_Encryption()=default
virtual void kem_encrypt(std::span< uint8_t > out_encapsulated_key, std::span< uint8_t > out_shared_key, RandomNumberGenerator &rng, size_t desired_shared_key_len, std::span< const uint8_t > salt)=0
virtual size_t shared_key_length(size_t desired_shared_key_len) const =0
virtual size_t agreed_value_size() const =0
virtual secure_vector< uint8_t > agree(size_t key_len, std::span< const uint8_t > other_key, std::span< const uint8_t > salt)=0
virtual ~Key_Agreement()=default
virtual AlgorithmIdentifier algorithm_identifier() const
Definition pk_ops.cpp:30
virtual size_t signature_length() const =0
virtual ~Signature()=default
virtual std::string hash_function() const =0
virtual void update(std::span< const uint8_t > input)=0
virtual std::vector< uint8_t > sign(RandomNumberGenerator &rng)=0
virtual std::string hash_function() const =0
virtual void update(std::span< const uint8_t > input)=0
virtual ~Verification()=default
virtual bool is_valid_signature(std::span< const uint8_t > sig)=0
std::vector< T, secure_allocator< T > > secure_vector
Definition secmem.h:128