Botan 3.14.1
Crypto and TLS for C&
pk_options_readers.h
Go to the documentation of this file.
1/*
2* (C) 2024,2025,2026 Jack Lloyd
3*
4* Botan is released under the Simplified BSD License (see license.txt)
5*/
6
7#ifndef BOTAN_PK_OPTIONS_READERS_H_
8#define BOTAN_PK_OPTIONS_READERS_H_
9
10#include <botan/pk_options.h>
11
12/**
13* Read access to the public key operation options
14*
15* Applications never interact with the types in this header; they build a
16* PK_Signature_Options (or the encryption, KEM, or key agreement equivalent)
17* and hand it to the wrapper in pubkey.h. The library then creates a reader
18* object and passes it to the key's _create_xxx_op, so these types are only
19* relevant for out-of-tree implementations of public key schemes.
20*
21* These types are unstable API and may change between releases.
22*/
23
24namespace Botan {
25
26/**
27* Read access to a PK_Signature_Options
28*
29* The library creates one of these when a PK_Signer or PK_Verifier is
30* constructed and passes it to the key's _create_signature_op or
31* _create_verification_op; applications never create or hold one.
32*
33* Each getter records that the scheme examined the option. Any option the
34* caller set which the scheme never examined is then rejected, since it would
35* otherwise be silently ignored. A scheme should therefore only read an option
36* that it will actually act on.
37*/
39 public:
45
46 /// Format the options as a string, for error messages
47 std::string to_string() const { return m_options.to_string(); }
48
49 /// Return the name of the hash function to use
50 ///
51 /// This will throw an exception if no hash function was configured
52 const std::string& hash_function_name() const;
53
54 const std::optional<std::string>& hash_function() const {
55 note_examined(Option::Hash);
56 return m_options.m_hash_fn;
57 }
58
59 const std::optional<std::string>& prehash_function() const {
60 note_examined(Option::Prehash);
61 return m_options.m_prehash;
62 }
63
64 const std::optional<std::string>& externally_computed_prehash_function() const {
65 note_examined(Option::ExternalPrehash);
66 return m_options.m_external_prehash;
67 }
68
69 const std::optional<std::string>& padding() const {
70 note_examined(Option::Padding);
71 return m_options.m_padding;
72 }
73
74 const std::optional<std::vector<uint8_t>>& context() const {
75 note_examined(Option::Context);
76 return m_options.m_context;
77 }
78
79 const std::optional<std::string>& provider() const {
80 note_examined(Option::Provider);
81 return m_options.m_provider;
82 }
83
84 const std::optional<size_t>& salt_size() const {
85 note_examined(Option::SaltSize);
86 return m_options.m_salt_size;
87 }
88
90 note_examined(Option::DerEncoded);
91 return m_options.m_use_der;
92 }
93
95 note_examined(Option::Deterministic);
96 return m_options.m_deterministic_sig && m_usage == Usage::Signing;
97 }
98
100 note_examined(Option::ExplicitTrailer);
101 return m_options.m_explicit_trailer_field;
102 }
103
104 bool using_hash() const { return hash_function().has_value(); }
105
106 bool using_context() const { return context().has_value(); }
107
108 bool using_prehash() const {
109 note_examined(Option::Prehash);
110 return m_options.m_using_prehash;
111 }
112
114 note_examined(Option::ExternalPrehash);
115 return m_options.m_using_external_prehash;
116 }
117
118 bool using_padding() const { return padding().has_value(); }
119
120 bool using_salt_size() const { return salt_size().has_value(); }
121
122 bool using_provider() const;
123
124 private:
125 friend class PK_Signer;
126 friend class PK_Verifier;
128
129 /*
130 * The deterministic option only affects signature generation, so a reader
131 * for verification hides it rather than have every verification operation
132 * know to ignore it
133 */
134 enum class Usage : uint8_t {
135 Signing,
136 Verification,
137 };
138
139 PK_Signature_Options_Reader(const PK_Signature_Options& options, Usage usage) :
140 m_options(options), m_usage(usage) {}
141
142 enum class Option : uint32_t /* NOLINT(*-enum-size) */ {
143 Hash = (1 << 0),
144 Prehash = (1 << 1),
145 Padding = (1 << 2),
146 Context = (1 << 3),
147 Provider = (1 << 4),
148 SaltSize = (1 << 5),
149 DerEncoded = (1 << 6),
150 Deterministic = (1 << 7),
151 ExplicitTrailer = (1 << 8),
152 ExternalPrehash = (1 << 9),
153 };
154
155 void note_examined(Option option) const { m_examined |= static_cast<uint32_t>(option); }
156
157 /// Return the bitmask of options which were set to a non-default value
158 uint32_t options_in_use() const;
159
160 /// Throw Invalid_Argument if any option in use has not been examined
161 void throw_if_unexamined(std::string_view algo_name) const;
162
163 const PK_Signature_Options& m_options;
164 Usage m_usage;
165 mutable uint32_t m_examined = 0;
166};
167
168/**
169* Read access to a PK_Encryption_Options
170*
171* The library creates one of these when a PK_Encryptor_EME or PK_Decryptor_EME
172* is constructed and passes it to the key's _create_encryption_op or
173* _create_decryption_op; applications never create or hold one.
174*
175* As with PK_Signature_Options_Reader, each getter records that the scheme
176* examined the option, and any option set but never examined is rejected.
177*/
179 public:
185
186 /// Format the options as a string, for error messages
187 std::string to_string() const { return m_options.to_string(); }
188
189 /// Return the name of the hash function to use
190 ///
191 /// This will throw an exception if no hash function was configured
192 const std::string& hash_function_name() const;
193
194 const std::optional<std::string>& padding() const {
195 note_examined(Option::Padding);
196 return m_options.m_padding;
197 }
198
199 const std::optional<std::string>& hash_function() const {
200 note_examined(Option::Hash);
201 return m_options.m_hash_fn;
202 }
203
204 const std::optional<std::string>& mgf1_hash_function() const {
205 note_examined(Option::Mgf1Hash);
206 return m_options.m_mgf1_hash_fn;
207 }
208
209 const std::optional<std::vector<uint8_t>>& context() const {
210 note_examined(Option::Context);
211 return m_options.m_context;
212 }
213
214 const std::optional<std::string>& provider() const {
215 note_examined(Option::Provider);
216 return m_options.m_provider;
217 }
218
219 bool using_padding() const { return padding().has_value(); }
220
221 bool using_hash() const { return hash_function().has_value(); }
222
223 bool using_mgf1_hash() const { return mgf1_hash_function().has_value(); }
224
225 bool using_context() const { return context().has_value(); }
226
227 bool using_provider() const;
228
229 private:
230 friend class PK_Encryptor_EME;
231 friend class PK_Decryptor_EME;
233
234 explicit PK_Encryption_Options_Reader(const PK_Encryption_Options& options) : m_options(options) {}
235
236 enum class Option : uint32_t /* NOLINT(*-enum-size) */ {
237 Padding = (1 << 0),
238 Hash = (1 << 1),
239 Mgf1Hash = (1 << 2),
240 Context = (1 << 3),
241 Provider = (1 << 4),
242 };
243
244 void note_examined(Option option) const { m_examined |= static_cast<uint32_t>(option); }
245
246 uint32_t options_in_use() const;
247
248 void throw_if_unexamined(std::string_view algo_name) const;
249
250 const PK_Encryption_Options& m_options;
251 mutable uint32_t m_examined = 0;
252};
253
254/**
255* Read access to a PK_KEM_Options
256*
257* The library creates one of these when a PK_KEM_Encryptor or PK_KEM_Decryptor
258* is constructed and passes it to the key's _create_kem_encryption_op or
259* _create_kem_decryption_op; applications never create or hold one.
260*
261* As with PK_Signature_Options_Reader, each getter records that the scheme
262* examined the option, and any option set but never examined is rejected.
263*/
265 public:
271
272 /// Format the options as a string, for error messages
273 std::string to_string() const { return m_options.to_string(); }
274
275 const std::optional<std::string>& kdf() const {
276 note_examined(Option::Kdf);
277 return m_options.m_kdf;
278 }
279
280 bool using_kdf() const { return kdf().has_value(); }
281
282 bool using_raw_shared_key() const {
283 note_examined(Option::RawSharedKey);
284 return m_options.m_raw_shared_key;
285 }
286
287 const std::optional<std::string>& provider() const {
288 note_examined(Option::Provider);
289 return m_options.m_provider;
290 }
291
292 bool using_provider() const;
293
294 private:
295 friend class PK_KEM_Encryptor;
296 friend class PK_KEM_Decryptor;
298
299 explicit PK_KEM_Options_Reader(const PK_KEM_Options& options) : m_options(options) {}
300
301 enum class Option : uint32_t /* NOLINT(*-enum-size) */ {
302 Kdf = (1 << 0),
303 RawSharedKey = (1 << 1),
304 Provider = (1 << 2),
305 };
306
307 void note_examined(Option option) const { m_examined |= static_cast<uint32_t>(option); }
308
309 uint32_t options_in_use() const;
310
311 void throw_if_unexamined(std::string_view algo_name) const;
312
313 const PK_KEM_Options& m_options;
314 mutable uint32_t m_examined = 0;
315};
316
317/**
318* Read access to a PK_Key_Agreement_Options
319*
320* The library creates one of these when a PK_Key_Agreement is constructed and
321* passes it to the key's _create_key_agreement_op; applications never create
322* or hold one.
323*
324* As with PK_Signature_Options_Reader, each getter records that the scheme
325* examined the option, and any option set but never examined is rejected.
326*/
328 public:
334
335 /// Format the options as a string, for error messages
336 std::string to_string() const { return m_options.to_string(); }
337
338 const std::optional<std::string>& kdf() const {
339 note_examined(Option::Kdf);
340 return m_options.m_kdf;
341 }
342
343 bool using_kdf() const { return kdf().has_value(); }
344
345 bool using_raw_shared_key() const {
346 note_examined(Option::RawSharedKey);
347 return m_options.m_raw_shared_key;
348 }
349
350 const std::optional<std::string>& provider() const {
351 note_examined(Option::Provider);
352 return m_options.m_provider;
353 }
354
355 bool using_provider() const;
356
357 private:
358 friend class PK_Key_Agreement;
360
361 explicit PK_Key_Agreement_Options_Reader(const PK_Key_Agreement_Options& options) : m_options(options) {}
362
363 enum class Option : uint32_t /* NOLINT(*-enum-size) */ {
364 Kdf = (1 << 0),
365 RawSharedKey = (1 << 1),
366 Provider = (1 << 2),
367 };
368
369 void note_examined(Option option) const { m_examined |= static_cast<uint32_t>(option); }
370
371 uint32_t options_in_use() const;
372
373 void throw_if_unexamined(std::string_view algo_name) const;
374
375 const PK_Key_Agreement_Options& m_options;
376 mutable uint32_t m_examined = 0;
377};
378
379} // namespace Botan
380
381#endif
#define BOTAN_UNSTABLE_API
Definition api.h:34
PK_Encryption_Options_Reader(PK_Encryption_Options_Reader &&)=delete
std::string to_string() const
Format the options as a string, for error messages.
PK_Encryption_Options_Reader(const PK_Encryption_Options_Reader &)=delete
const std::optional< std::string > & hash_function() const
const std::optional< std::vector< uint8_t > > & context() const
const std::optional< std::string > & provider() const
const std::optional< std::string > & padding() const
const std::optional< std::string > & mgf1_hash_function() const
PK_Encryption_Options_Reader & operator=(PK_Encryption_Options_Reader &&)=delete
PK_Encryption_Options_Reader & operator=(const PK_Encryption_Options_Reader &)=delete
PK_KEM_Options_Reader(PK_KEM_Options_Reader &&)=delete
PK_KEM_Options_Reader & operator=(const PK_KEM_Options_Reader &)=delete
std::string to_string() const
Format the options as a string, for error messages.
const std::optional< std::string > & kdf() const
const std::optional< std::string > & provider() const
PK_KEM_Options_Reader & operator=(PK_KEM_Options_Reader &&)=delete
PK_KEM_Options_Reader(const PK_KEM_Options_Reader &)=delete
PK_Key_Agreement_Options_Reader(const PK_Key_Agreement_Options_Reader &)=delete
const std::optional< std::string > & provider() const
PK_Key_Agreement_Options_Reader(PK_Key_Agreement_Options_Reader &&)=delete
std::string to_string() const
Format the options as a string, for error messages.
PK_Key_Agreement_Options_Reader & operator=(const PK_Key_Agreement_Options_Reader &)=delete
const std::optional< std::string > & kdf() const
PK_Key_Agreement_Options_Reader & operator=(PK_Key_Agreement_Options_Reader &&)=delete
const std::optional< std::string > & hash_function() const
const std::optional< std::string > & provider() const
PK_Signature_Options_Reader(PK_Signature_Options_Reader &&)=delete
const std::optional< std::string > & padding() const
const std::optional< std::vector< uint8_t > > & context() const
const std::optional< std::string > & externally_computed_prehash_function() const
PK_Signature_Options_Reader(const PK_Signature_Options_Reader &)=delete
PK_Signature_Options_Reader & operator=(const PK_Signature_Options_Reader &)=delete
PK_Signature_Options_Reader & operator=(PK_Signature_Options_Reader &&)=delete
const std::optional< std::string > & prehash_function() const
std::string to_string() const
Format the options as a string, for error messages.
const std::optional< size_t > & salt_size() const