Botan 3.14.1
Crypto and TLS for C&
pk_options.cpp
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#include <botan/pk_options_readers.h>
8
9#include <botan/assert.h>
10#include <botan/hex.h>
11#include <botan/internal/fmt.h>
12#include <botan/internal/mem_utils.h>
13#include <initializer_list>
14#include <sstream>
15#include <utility>
16
17namespace Botan {
18
20
22 BOTAN_STATE_CHECK_MSG(!m_hash_fn.has_value(), "PK_Signature_Options::with_hash cannot specify hash twice");
23 auto next = (*this);
24 if(!hash.empty()) {
25 next.m_hash_fn = hash;
26 }
27 return next;
28}
29
31 BOTAN_STATE_CHECK_MSG(!m_padding.has_value(), "PK_Signature_Options::with_padding cannot specify padding twice");
32 auto next = (*this);
33 if(!padding.empty()) {
34 next.m_padding = padding;
35 }
36 return next;
37}
38
39PK_Signature_Options PK_Signature_Options::with_prehash(std::optional<std::string> prehash_function) {
40 BOTAN_STATE_CHECK_MSG(!m_using_prehash, "PK_Signature_Options::with_prehash cannot specify prehash twice");
41 BOTAN_STATE_CHECK_MSG(!m_using_external_prehash,
42 "PK_Signature_Options::with_prehash cannot be combined with an externally computed prehash");
43 auto next = (*this);
44
45 // Calling this with a std::nullopt enables prehashing with an algorithm-
46 // specific hash function that is not user-defined. Hence the bool flag.
47 next.m_using_prehash = true;
48 next.m_prehash = std::move(prehash_function);
49 return next;
50}
51
54 !m_using_external_prehash,
55 "PK_Signature_Options::with_externally_computed_prehash cannot specify external prehash twice");
56 BOTAN_STATE_CHECK_MSG(!m_using_prehash,
57 "PK_Signature_Options::with_externally_computed_prehash cannot be combined with a prehash");
58 auto next = (*this);
59
60 // As with with_prehash, a nullopt hash is meaningful (the input is an
61 // unidentified digest) so a flag tracks that the option was requested
62 next.m_using_external_prehash = true;
63 next.m_external_prehash = std::move(hash);
64 return next;
65}
66
68 BOTAN_STATE_CHECK_MSG(provider.empty() || !m_provider.has_value(),
69 "PK_Signature_Options::with_provider cannot specify provider twice");
70 auto next = (*this);
71 if(!provider.empty()) {
72 next.m_provider = provider;
73 }
74 return next;
75}
76
78 BOTAN_STATE_CHECK_MSG(!m_context.has_value(), "PK_Signature_Options::with_context cannot specify context twice");
79 auto next = (*this);
80 next.m_context = std::vector<uint8_t>(context.begin(), context.end());
81 return next;
82}
83
85 BOTAN_STATE_CHECK_MSG(!m_context.has_value(), "PK_Signature_Options::with_context cannot specify context twice");
86 auto next = (*this);
87 const auto contextb = as_span_of_bytes(context);
88 next.m_context = std::vector<uint8_t>(contextb.begin(), contextb.end());
89 return next;
90}
91
93 BOTAN_STATE_CHECK_MSG(!m_salt_size.has_value(),
94 "PK_Signature_Options::with_salt_size cannot specify salt size twice");
95 BOTAN_ARG_CHECK(salt_size <= 1024, "Unreasonable salt size");
96 auto next = (*this);
97 next.m_salt_size = salt_size;
98 return next;
99}
100
103 !m_deterministic_sig,
104 "PK_Signature_Options::with_deterministic_signature cannot specify deterministic signature twice");
105 auto next = (*this);
106 next.m_deterministic_sig = deterministic;
107 return next;
108}
109
111 BOTAN_STATE_CHECK_MSG(!m_use_der,
112 "PK_Signature_Options::with_der_encoded_signature cannot specify DER encoding twice");
113 auto next = (*this);
114 next.m_use_der = der;
115 return next;
116}
117
120 !m_explicit_trailer_field,
121 "PK_Signature_Options::with_explicit_trailer_field cannot specify explicit trailer field twice");
122 auto next = (*this);
123 next.m_explicit_trailer_field = trailer;
124 return next;
125}
126
127namespace {
128
129bool provider_is_in_use(const std::optional<std::string>& provider) {
130 return provider.has_value() && !provider->empty() && *provider != "base";
131}
132
133} // namespace
134
136 note_examined(Option::Provider);
137 return provider_is_in_use(m_options.m_provider);
138}
139
141 note_examined(Option::Hash);
142
143 if(m_options.m_hash_fn.has_value()) {
144 return m_options.m_hash_fn.value();
145 }
146
147 throw Invalid_State("This signature scheme requires specifying a hash function");
148}
149
150uint32_t PK_Signature_Options_Reader::options_in_use() const {
151 uint32_t in_use = 0;
152
153 const auto set_if = [&](bool cond, Option option) {
154 if(cond) {
155 in_use |= static_cast<uint32_t>(option);
156 }
157 };
158
159 const auto& o = m_options;
160
161 set_if(o.m_hash_fn.has_value(), Option::Hash);
162 set_if(o.m_using_prehash, Option::Prehash);
163 set_if(o.m_using_external_prehash, Option::ExternalPrehash);
164 set_if(o.m_padding.has_value(), Option::Padding);
165 set_if(o.m_context.has_value(), Option::Context);
166 set_if(provider_is_in_use(o.m_provider), Option::Provider);
167 set_if(o.m_salt_size.has_value(), Option::SaltSize);
168 set_if(o.m_use_der, Option::DerEncoded);
169 set_if(o.m_deterministic_sig && m_usage == Usage::Signing, Option::Deterministic);
170 set_if(o.m_explicit_trailer_field, Option::ExplicitTrailer);
171
172 return in_use;
173}
174
175namespace {
176
177/*
178* Shared by all of the option types: throw naming each option in the
179* unexamined bitmask, using the provided (bit, name) table.
180*/
181template <typename OptionEnum>
182void throw_for_unexamined_options(std::string_view algo_name,
183 std::string_view option_kind,
184 uint32_t unexamined,
185 std::initializer_list<std::pair<OptionEnum, std::string_view>> option_names) {
186 if(unexamined == 0) {
187 return;
188 }
189
190 std::string names;
191 for(const auto& [option, name] : option_names) {
192 if((unexamined & static_cast<uint32_t>(option)) != 0) {
193 if(!names.empty()) {
194 names += ", ";
195 }
196 names += name;
197 }
198 }
199
200 throw Invalid_Argument(fmt("{} does not support the {} option(s): {}", algo_name, option_kind, names));
201}
202
203} // namespace
204
205void PK_Signature_Options_Reader::throw_if_unexamined(std::string_view algo_name) const {
206 const uint32_t unexamined = options_in_use() & ~m_examined;
207
208 if(unexamined != 0) {
209 throw_for_unexamined_options<Option>(algo_name,
210 "signature",
211 unexamined,
212 {
213 {Option::Hash, "hash"},
214 {Option::Prehash, "prehash"},
215 {Option::Padding, "padding"},
216 {Option::Context, "context"},
217 {Option::Provider, "provider"},
218 {Option::SaltSize, "salt size"},
219 {Option::DerEncoded, "DER encoding"},
220 {Option::Deterministic, "deterministic"},
221 {Option::ExplicitTrailer, "explicit trailer field"},
222 {Option::ExternalPrehash, "externally computed prehash"},
223 });
224 }
225}
226
228 std::ostringstream out;
229
230 const auto print_str = [&](std::string_view name, std::optional<std::string> val) {
231 if(val.has_value()) {
232 out << name << "='" << val.value() << "' ";
233 }
234 };
235
236 print_str("Hash", m_hash_fn);
237 print_str("Padding", m_padding);
238 print_str("Provider", m_provider);
239
240 if(m_using_prehash) {
241 out << "Prehash=" << m_prehash.value_or("default") << " ";
242 }
243 if(m_using_external_prehash) {
244 out << "ExternalPrehash=" << m_external_prehash.value_or("unspecified") << " ";
245 }
246
247 if(m_context) {
248 out << "Context=" << hex_encode(*m_context) << " ";
249 }
250
251 if(m_salt_size) {
252 out << "SaltLen=" << *m_salt_size << " ";
253 }
254 if(m_use_der) {
255 out << "DerSignature ";
256 }
257 if(m_deterministic_sig) {
258 out << "Deterministic ";
259 }
260 if(m_explicit_trailer_field) {
261 out << "ExplicitTrailer ";
262 }
263
264 return out.str();
265}
266
267// PK_Encryption_Options
268
270
272 BOTAN_STATE_CHECK_MSG(!m_padding.has_value(), "PK_Encryption_Options::with_padding cannot specify padding twice");
273 auto next = (*this);
274 if(!padding.empty()) {
275 next.m_padding = padding;
276 }
277 return next;
278}
279
281 BOTAN_STATE_CHECK_MSG(!m_hash_fn.has_value(), "PK_Encryption_Options::with_hash cannot specify hash twice");
282 auto next = (*this);
283 if(!hash.empty()) {
284 next.m_hash_fn = hash;
285 }
286 return next;
287}
288
290 BOTAN_STATE_CHECK_MSG(!m_mgf1_hash_fn.has_value(),
291 "PK_Encryption_Options::with_mgf1_hash cannot specify MGF1 hash twice");
292 auto next = (*this);
293 if(!hash.empty()) {
294 next.m_mgf1_hash_fn = hash;
295 }
296 return next;
297}
298
300 BOTAN_STATE_CHECK_MSG(!m_context.has_value(), "PK_Encryption_Options::with_context cannot specify context twice");
301 auto next = (*this);
302 next.m_context = std::vector<uint8_t>(context.begin(), context.end());
303 return next;
304}
305
307 return this->with_context(as_span_of_bytes(context));
308}
309
311 BOTAN_STATE_CHECK_MSG(provider.empty() || !m_provider.has_value(),
312 "PK_Encryption_Options::with_provider cannot specify provider twice");
313 auto next = (*this);
314 if(!provider.empty()) {
315 next.m_provider = provider;
316 }
317 return next;
318}
319
321 note_examined(Option::Provider);
322 return provider_is_in_use(m_options.m_provider);
323}
324
326 note_examined(Option::Hash);
327
328 if(m_options.m_hash_fn.has_value()) {
329 return m_options.m_hash_fn.value();
330 }
331
332 throw Invalid_State("This encryption scheme requires specifying a hash function");
333}
334
335uint32_t PK_Encryption_Options_Reader::options_in_use() const {
336 uint32_t in_use = 0;
337
338 const auto set_if = [&](bool cond, Option option) {
339 if(cond) {
340 in_use |= static_cast<uint32_t>(option);
341 }
342 };
343
344 const auto& o = m_options;
345
346 set_if(o.m_padding.has_value(), Option::Padding);
347 set_if(o.m_hash_fn.has_value(), Option::Hash);
348 set_if(o.m_mgf1_hash_fn.has_value(), Option::Mgf1Hash);
349 set_if(o.m_context.has_value(), Option::Context);
350 set_if(provider_is_in_use(o.m_provider), Option::Provider);
351
352 return in_use;
353}
354
355void PK_Encryption_Options_Reader::throw_if_unexamined(std::string_view algo_name) const {
356 const uint32_t unexamined = options_in_use() & ~m_examined;
357
358 if(unexamined != 0) {
359 throw_for_unexamined_options<Option>(algo_name,
360 "encryption",
361 unexamined,
362 {
363 {Option::Padding, "padding"},
364 {Option::Hash, "hash"},
365 {Option::Mgf1Hash, "MGF1 hash"},
366 {Option::Context, "context"},
367 {Option::Provider, "provider"},
368 });
369 }
370}
371
373 std::ostringstream out;
374
375 const auto print_str = [&](std::string_view name, const std::optional<std::string>& val) {
376 if(val.has_value()) {
377 out << name << "='" << val.value() << "' ";
378 }
379 };
380
381 print_str("Padding", m_padding);
382 print_str("Hash", m_hash_fn);
383 print_str("MGF1Hash", m_mgf1_hash_fn);
384 print_str("Provider", m_provider);
385
386 if(m_context) {
387 out << "Context=" << hex_encode(*m_context) << " ";
388 }
389
390 return out.str();
391}
392
393// PK_KEM_Options
394
396
398 BOTAN_STATE_CHECK_MSG(!m_kdf.has_value(), "PK_KEM_Options::with_kdf cannot specify KDF twice");
399 BOTAN_STATE_CHECK_MSG(!m_raw_shared_key, "PK_KEM_Options::with_kdf cannot be combined with with_raw_shared_key");
400 // Silently accepting an empty name would turn a request for a KDF into the raw shared key
401 BOTAN_ARG_CHECK(!kdf.empty(), "PK_KEM_Options::with_kdf requires a KDF name");
402 auto next = (*this);
403 next.m_kdf = kdf;
404 return next;
405}
406
408 BOTAN_STATE_CHECK_MSG(!m_raw_shared_key, "PK_KEM_Options::with_raw_shared_key cannot be specified twice");
409 BOTAN_STATE_CHECK_MSG(!m_kdf.has_value(), "PK_KEM_Options::with_raw_shared_key cannot be combined with with_kdf");
410 auto next = (*this);
411 next.m_raw_shared_key = true;
412 return next;
413}
414
416 BOTAN_STATE_CHECK_MSG(provider.empty() || !m_provider.has_value(),
417 "PK_KEM_Options::with_provider cannot specify provider twice");
418 auto next = (*this);
419 if(!provider.empty()) {
420 next.m_provider = provider;
421 }
422 return next;
423}
424
426 note_examined(Option::Provider);
427 return provider_is_in_use(m_options.m_provider);
428}
429
430uint32_t PK_KEM_Options_Reader::options_in_use() const {
431 uint32_t in_use = 0;
432
433 const auto set_if = [&](bool cond, Option option) {
434 if(cond) {
435 in_use |= static_cast<uint32_t>(option);
436 }
437 };
438
439 set_if(m_options.m_kdf.has_value(), Option::Kdf);
440 set_if(m_options.m_raw_shared_key, Option::RawSharedKey);
441 set_if(provider_is_in_use(m_options.m_provider), Option::Provider);
442
443 return in_use;
444}
445
446void PK_KEM_Options_Reader::throw_if_unexamined(std::string_view algo_name) const {
447 const uint32_t unexamined = options_in_use() & ~m_examined;
448
449 if(unexamined != 0) {
450 throw_for_unexamined_options<Option>(algo_name,
451 "KEM",
452 unexamined,
453 {
454 {Option::Kdf, "KDF"},
455 {Option::RawSharedKey, "raw shared key"},
456 {Option::Provider, "provider"},
457 });
458 }
459}
460
461std::string PK_KEM_Options::to_string() const {
462 std::ostringstream out;
463
464 if(m_kdf) {
465 out << "KDF='" << *m_kdf << "' ";
466 }
467 if(m_raw_shared_key) {
468 out << "RawSharedKey ";
469 }
470 if(m_provider) {
471 out << "Provider='" << *m_provider << "' ";
472 }
473
474 return out.str();
475}
476
477// PK_Key_Agreement_Options
478
480
482 BOTAN_STATE_CHECK_MSG(!m_kdf.has_value(), "PK_Key_Agreement_Options::with_kdf cannot specify KDF twice");
483 BOTAN_STATE_CHECK_MSG(!m_raw_shared_key,
484 "PK_Key_Agreement_Options::with_kdf cannot be combined with with_raw_shared_key");
485 // Silently accepting an empty name would turn a request for a KDF into the raw agreed value
486 BOTAN_ARG_CHECK(!kdf.empty(), "PK_Key_Agreement_Options::with_kdf requires a KDF name");
487 auto next = (*this);
488 next.m_kdf = kdf;
489 return next;
490}
491
493 BOTAN_STATE_CHECK_MSG(!m_raw_shared_key, "PK_Key_Agreement_Options::with_raw_shared_key cannot be specified twice");
494 BOTAN_STATE_CHECK_MSG(!m_kdf.has_value(),
495 "PK_Key_Agreement_Options::with_raw_shared_key cannot be combined with with_kdf");
496 auto next = (*this);
497 next.m_raw_shared_key = true;
498 return next;
499}
500
502 BOTAN_STATE_CHECK_MSG(provider.empty() || !m_provider.has_value(),
503 "PK_Key_Agreement_Options::with_provider cannot specify provider twice");
504 auto next = (*this);
505 if(!provider.empty()) {
506 next.m_provider = provider;
507 }
508 return next;
509}
510
512 note_examined(Option::Provider);
513 return provider_is_in_use(m_options.m_provider);
514}
515
516uint32_t PK_Key_Agreement_Options_Reader::options_in_use() const {
517 uint32_t in_use = 0;
518
519 const auto set_if = [&](bool cond, Option option) {
520 if(cond) {
521 in_use |= static_cast<uint32_t>(option);
522 }
523 };
524
525 set_if(m_options.m_kdf.has_value(), Option::Kdf);
526 set_if(m_options.m_raw_shared_key, Option::RawSharedKey);
527 set_if(provider_is_in_use(m_options.m_provider), Option::Provider);
528
529 return in_use;
530}
531
532void PK_Key_Agreement_Options_Reader::throw_if_unexamined(std::string_view algo_name) const {
533 const uint32_t unexamined = options_in_use() & ~m_examined;
534
535 if(unexamined != 0) {
536 throw_for_unexamined_options<Option>(algo_name,
537 "key agreement",
538 unexamined,
539 {
540 {Option::Kdf, "KDF"},
541 {Option::RawSharedKey, "raw shared key"},
542 {Option::Provider, "provider"},
543 });
544 }
545}
546
548 std::ostringstream out;
549
550 if(m_kdf) {
551 out << "KDF='" << *m_kdf << "' ";
552 }
553 if(m_raw_shared_key) {
554 out << "RawSharedKey ";
555 }
556 if(m_provider) {
557 out << "Provider='" << *m_provider << "' ";
558 }
559
560 return out.str();
561}
562
563} // namespace Botan
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33
#define BOTAN_STATE_CHECK_MSG(expr, msg)
Definition assert.h:59
const std::string & hash_function_name() const
PK_Encryption_Options with_padding(std::string_view padding)
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 with_provider(std::string_view provider)
PK_KEM_Options with_provider(std::string_view provider)
PK_KEM_Options with_kdf(std::string_view kdf)
std::string to_string() const
PK_KEM_Options with_raw_shared_key()
std::string to_string() const
PK_Key_Agreement_Options with_provider(std::string_view provider)
PK_Key_Agreement_Options with_kdf(std::string_view kdf)
PK_Key_Agreement_Options with_raw_shared_key()
const std::string & hash_function_name() const
PK_Signature_Options with_explicit_trailer_field(bool trailer=true)
PK_Signature_Options with_deterministic_signature(bool deterministic=true)
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)
std::string to_string() const
PK_Signature_Options with_provider(std::string_view provider)
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)
const char * name
Definition ffi_tls.h:59
std::span< const uint8_t > as_span_of_bytes(const char *s, size_t len)
Definition mem_utils.h:59
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53
void hex_encode(char output[], const uint8_t input[], size_t input_length, bool uppercase)
Definition hex.cpp:34