Botan 3.14.1
Crypto and TLS for C&
pk_options.h
Go to the documentation of this file.
1/*
2* (C) 2024,2025 Jack Lloyd
3*
4* Botan is released under the Simplified BSD License (see license.txt)
5*/
6
7#ifndef BOTAN_PK_OPTIONS_H_
8#define BOTAN_PK_OPTIONS_H_
9
10#include <botan/pk_keys.h>
11#include <optional>
12#include <span>
13#include <string>
14#include <string_view>
15#include <vector>
16
17namespace Botan {
18
19class PK_Signer;
20class PK_Verifier;
27
28// Defined in pk_options_readers.h; only implementations of key types use them
33
34/**
35* Signature generation/verification options
36*
37* The normal usage of this is in a builder style, eg
38*
39* PK_Signature_Options()
40* .with_hash("SHA-256")
41* .with_der_encoded_signature()
42* .with_context("Foo")
43*
44* Every option that is set must be understood by the signature scheme in use.
45* If a scheme does not support an option (for example a context for RSA, or a
46* salt for Ed25519) then constructing the PK_Signer or PK_Verifier throws an
47* exception; an option is never silently ignored.
48*/
50 public:
51 /// Create an empty PK_Signature_Options
52 ///
53 /// This can be further parameterized by calling with_xxx functions
55
58
62
63 /// Format this PK_Signature_Options as a string
64 ///
65 /// This is primarily intended for debugging and error messages;
66 /// the format is not fixed
67 std::string to_string() const;
68
69 /// Specify the hash function to use for signing/verification
70 ///
71 /// Most, but not all, schemes require specifying a hash function.
72 PK_Signature_Options with_hash(std::string_view hash);
73
74 /// Specify a padding scheme
75 ///
76 /// This is mostly/only used for RSA
77 ///
78 /// If the scheme does not support a padding option, it will throw an
79 /// exception when presented with such an option.
80 PK_Signature_Options with_padding(std::string_view padding);
81
82 /// Request that the library prehash the message
83 ///
84 /// Some signature schemes, such as Ed25519, normally sign the
85 /// entire message along with some context data. However such
86 /// schemes also sometimes offer a prehashing variant where the
87 /// message is hashed on its own, then the hash is signed.
88 ///
89 /// With this option the library computes the prehash itself; the
90 /// caller still provides the full message. If given this specifies
91 /// what hash function to use for prehashing. If prehash is nullopt,
92 /// this requests prehashing using an algorithm specific default
93 /// function.
94 ///
95 /// If the scheme does not support prehashing, it will throw an
96 /// exception when presented with such an option.
97 ///
98 /// This cannot be combined with with_externally_computed_prehash
99 PK_Signature_Options with_prehash(std::optional<std::string> prehash = std::nullopt);
100
101 /// Specify that the caller has already hashed the message
102 ///
103 /// With this option the data passed to the signature operation is
104 /// not the message but a hash of it, which the caller computed. The
105 /// library signs (or verifies) the provided digest directly, without
106 /// hashing it again.
107 ///
108 /// The hash function that was used can be named either here or via
109 /// with_hash (if both are given they must agree). Naming it allows
110 /// the scheme to check the digest length and to identify the hash in
111 /// the signature where the format requires it (for example the
112 /// PKCS #1 v1.5 DigestInfo). If no hash is named the input is signed
113 /// as an opaque byte string.
114 ///
115 /// @warning Signing externally computed hashes is easy to get wrong
116 /// and many ways of doing it are insecure. Don't use this unless you
117 /// know what you are doing.
118 ///
119 /// If the scheme does not support signing an externally computed hash,
120 /// it will throw an exception when presented with such an option.
121 ///
122 /// This cannot be combined with with_prehash
123 PK_Signature_Options with_externally_computed_prehash(std::optional<std::string> hash = std::nullopt);
124
125 /// Specify a context
126 ///
127 /// Some signature schemes allow specifying a context with the signature.
128 /// This is typically a fixed string that identifies a protocol or peer.
129 ///
130 /// For SM2 this context is the user identifier
131 ///
132 /// If the scheme does not support contextual identifiers, then an exception
133 /// will be thrown.
134 PK_Signature_Options with_context(std::span<const uint8_t> context);
135
136 /// Specify a context as a string
137 ///
138 /// Equivalent to the version taking a span above; just uses the bytes
139 /// of the string instead.
140 PK_Signature_Options with_context(std::string_view context);
141
142 /// Specify the size of salt to be used
143 ///
144 /// A small number of padding schemes (most importantly RSA-PSS) use a randomized
145 /// salt. This allows controlling the size of the salt that is used.
146 PK_Signature_Options with_salt_size(size_t salt_size);
147
148 /// Request producing a deterministic signature
149 ///
150 /// Some signature schemes are always deterministic, or always randomized.
151 /// Others support both randomized or deterministic options. This allows
152 /// requesting this. For signatures which are always deterministic this
153 /// option has no effect. Schemes which can only produce randomized
154 /// signatures reject this option.
155 ///
156 /// This option is ignored for verification
157 PK_Signature_Options with_deterministic_signature(bool deterministic = true);
158
159 /// Specify producing or expecting a DER encoded signature
160 ///
161 /// This is mostly used with ECDSA
162 ///
163 /// For schemes that do not support such formatting (such as RSA
164 /// or post-quantum schemes), an exception will be thrown when the
165 /// PK_Signer or PK_Verifier is created.
167
168 /// Specify producing or expecting an explicit trailer field
169 ///
170 /// Certain RSA padding schemes, such as PSS and ISO-9796, support two
171 /// different trailer fields. One is an "implicit" trailer, which does not
172 /// directly identify the hash. The other is an "explicit" trailer, which
173 /// does.
174 ///
175 /// Note that currently this option is only supported by ISO-9796. While
176 /// some standards allow PSS to use a trailer field, others (such as RFC
177 /// 4055) prohibit using explicit trailers for PSS, and it is not
178 /// currently supported.
179 ///
181
182 /// Specify a provider that should be used
183 ///
184 /// This is rarely relevant
185 PK_Signature_Options with_provider(std::string_view provider);
186
187 private:
189
190 std::optional<std::string> m_hash_fn;
191 std::optional<std::string> m_prehash;
192 std::optional<std::string> m_external_prehash;
193 std::optional<std::string> m_padding;
194 std::optional<std::vector<uint8_t>> m_context;
195 std::optional<std::string> m_provider;
196 std::optional<size_t> m_salt_size;
197 bool m_using_prehash = false;
198 bool m_using_external_prehash = false;
199 bool m_use_der = false;
200 bool m_deterministic_sig = false;
201 bool m_explicit_trailer_field = false;
202};
203
204/**
205* Public key encryption/decryption options
206*
207* The normal usage of this is in a builder style, eg
208*
209* PK_Encryption_Options()
210* .with_padding("OAEP")
211* .with_hash("SHA-256")
212* .with_context(label)
213*
214* As with PK_Signature_Options, every option that is set must be understood by
215* the encryption scheme in use; constructing the PK_Encryptor_EME or
216* PK_Decryptor_EME throws an exception otherwise. An option is never silently
217* ignored.
218*/
220 public:
222
225
229
230 /// Format this PK_Encryption_Options as a string
231 ///
232 /// This is primarily intended for debugging and error messages;
233 /// the format is not fixed
234 std::string to_string() const;
235
236 /// Specify the padding scheme
237 ///
238 /// For RSA (and ElGamal) this is required, and is one of "OAEP", "PKCS1v15"
239 /// or "Raw". Other schemes do not use padding.
240 PK_Encryption_Options with_padding(std::string_view padding);
241
242 /// Specify the hash function
243 ///
244 /// For OAEP this selects the hash used for the label and (unless
245 /// with_mgf1_hash is also used) for the mask generation function.
246 /// For SM2 it selects the KDF hash, and defaults to SM3.
247 PK_Encryption_Options with_hash(std::string_view hash);
248
249 /// Specify a different hash function for OAEP's MGF1
250 ///
251 /// Only OAEP supports this; by default MGF1 uses the same hash as OAEP
252 PK_Encryption_Options with_mgf1_hash(std::string_view hash);
253
254 /// Specify a context
255 ///
256 /// For OAEP this is the label ("L" in RFC 8017). Schemes without such
257 /// a parameter reject this option.
258 PK_Encryption_Options with_context(std::span<const uint8_t> context);
259
260 /// Specify a context as a string
261 ///
262 /// Equivalent to the version taking a span above; just uses the bytes
263 /// of the string instead.
264 PK_Encryption_Options with_context(std::string_view context);
265
266 /// Specify a provider that should be used
267 ///
268 /// This is rarely relevant
269 PK_Encryption_Options with_provider(std::string_view provider);
270
271 private:
273
274 std::optional<std::string> m_padding;
275 std::optional<std::string> m_hash_fn;
276 std::optional<std::string> m_mgf1_hash_fn;
277 std::optional<std::vector<uint8_t>> m_context;
278 std::optional<std::string> m_provider;
279};
280
281/**
282* Key encapsulation options
283*
284* The normal usage of this is in a builder style, eg
285*
286* PK_KEM_Options().with_kdf("HKDF(SHA-256)")
287*
288* As with PK_Signature_Options, every option that is set must be understood by
289* the KEM in use; constructing the PK_KEM_Encryptor or PK_KEM_Decryptor throws
290* an exception otherwise.
291*/
293 public:
294 PK_KEM_Options() = default;
295
296 PK_KEM_Options(PK_KEM_Options&& other) = default;
298
300 PK_KEM_Options& operator=(const PK_KEM_Options& other) = default;
302
303 /// Format this PK_KEM_Options as a string
304 ///
305 /// This is primarily intended for debugging and error messages;
306 /// the format is not fixed
307 std::string to_string() const;
308
309 /// Specify a KDF used to derive the shared key from the KEM output
310 ///
311 /// The salt and desired length passed to the encrypt/decrypt operations
312 /// are inputs to this KDF.
313 ///
314 /// The name must not be empty; this cannot be combined with with_raw_shared_key
315 PK_KEM_Options with_kdf(std::string_view kdf);
316
317 /// Request the raw output of the KEM as the shared key
318 ///
319 /// If neither this nor with_kdf is used, KEMs whose output is already a
320 /// uniformly random key (for example ML-KEM) return that output directly,
321 /// while KEMs whose output is not (for example RSA-KEM or a key
322 /// agreement used as a KEM) reject the request.
323 ///
324 /// This cannot be combined with with_kdf
326
327 /// Specify a provider that should be used
328 ///
329 /// This is rarely relevant
330 PK_KEM_Options with_provider(std::string_view provider);
331
332 private:
334
335 std::optional<std::string> m_kdf;
336 bool m_raw_shared_key = false;
337 std::optional<std::string> m_provider;
338};
339
340/**
341* Key agreement options
342*
343* The normal usage of this is in a builder style, eg
344*
345* PK_Key_Agreement_Options().with_kdf("HKDF(SHA-256)")
346*
347* As with PK_Signature_Options, every option that is set must be understood by
348* the scheme in use; constructing the PK_Key_Agreement throws an exception
349* otherwise.
350*/
352 public:
354
357
361
362 /// Format this PK_Key_Agreement_Options as a string
363 ///
364 /// This is primarily intended for debugging and error messages;
365 /// the format is not fixed
366 std::string to_string() const;
367
368 /// Specify a KDF used to derive the shared key from the agreed value
369 ///
370 /// The salt and desired length passed to derive_key are inputs to
371 /// this KDF.
372 ///
373 /// The name must not be empty; this cannot be combined with with_raw_shared_key
374 PK_Key_Agreement_Options with_kdf(std::string_view kdf);
375
376 /// Request the raw agreed value as the shared key
377 ///
378 /// The agreed value (for example the x coordinate of an elliptic curve
379 /// point) is not a uniformly random key, so key agreement requires either
380 /// a KDF or this explicit request; the default options are rejected.
381 ///
382 /// This cannot be combined with with_kdf
384
385 /// Specify a provider that should be used
386 ///
387 /// This is rarely relevant
388 PK_Key_Agreement_Options with_provider(std::string_view provider);
389
390 private:
392
393 std::optional<std::string> m_kdf;
394 bool m_raw_shared_key = false;
395 std::optional<std::string> m_provider;
396};
397
398} // namespace Botan
399
400#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
PK_Encryption_Options with_padding(std::string_view padding)
PK_Encryption_Options & operator=(const PK_Encryption_Options &other)=default
PK_Encryption_Options & operator=(PK_Encryption_Options &&other)=default
PK_Encryption_Options with_hash(std::string_view hash)
PK_Encryption_Options with_mgf1_hash(std::string_view hash)
PK_Encryption_Options with_context(std::span< const uint8_t > context)
std::string to_string() const
PK_Encryption_Options(const PK_Encryption_Options &)=default
friend class PK_Encryption_Options_Reader
Definition pk_options.h:272
PK_Encryption_Options with_provider(std::string_view provider)
PK_Encryption_Options(PK_Encryption_Options &&other)=default
PK_KEM_Options(PK_KEM_Options &&other)=default
PK_KEM_Options(const PK_KEM_Options &)=default
PK_KEM_Options with_provider(std::string_view provider)
PK_KEM_Options with_kdf(std::string_view kdf)
friend class PK_KEM_Options_Reader
Definition pk_options.h:333
PK_KEM_Options & operator=(const PK_KEM_Options &other)=default
std::string to_string() const
PK_KEM_Options & operator=(PK_KEM_Options &&other)=default
PK_KEM_Options with_raw_shared_key()
PK_Key_Agreement_Options(PK_Key_Agreement_Options &&other)=default
std::string to_string() const
PK_Key_Agreement_Options(const PK_Key_Agreement_Options &)=default
PK_Key_Agreement_Options with_provider(std::string_view provider)
PK_Key_Agreement_Options & operator=(const PK_Key_Agreement_Options &other)=default
PK_Key_Agreement_Options with_kdf(std::string_view kdf)
friend class PK_Key_Agreement_Options_Reader
Definition pk_options.h:391
PK_Key_Agreement_Options & operator=(PK_Key_Agreement_Options &&other)=default
PK_Key_Agreement_Options with_raw_shared_key()
PK_Signature_Options with_explicit_trailer_field(bool trailer=true)
PK_Signature_Options & operator=(PK_Signature_Options &&other)=default
PK_Signature_Options with_deterministic_signature(bool deterministic=true)
friend class PK_Signature_Options_Reader
Definition pk_options.h:188
PK_Signature_Options with_padding(std::string_view padding)
PK_Signature_Options with_hash(std::string_view hash)
PK_Signature_Options with_der_encoded_signature(bool der=true)
PK_Signature_Options with_salt_size(size_t salt_size)
PK_Signature_Options with_prehash(std::optional< std::string > prehash=std::nullopt)
PK_Signature_Options(PK_Signature_Options &&other)=default
std::string to_string() const
PK_Signature_Options & operator=(const PK_Signature_Options &other)=default
PK_Signature_Options with_provider(std::string_view provider)
PK_Signature_Options(const PK_Signature_Options &)=default
PK_Signature_Options with_context(std::span< const uint8_t > context)
PK_Signature_Options with_externally_computed_prehash(std::optional< std::string > hash=std::nullopt)