Botan 3.14.1
Crypto and TLS for C&
Botan::PK_Signature_Options Class Referencefinal

#include <pk_options.h>

Public Member Functions

PK_Signature_Options & operator= (const PK_Signature_Options &other)=default
PK_Signature_Options & operator= (PK_Signature_Options &&other)=default
 PK_Signature_Options ()=default
 PK_Signature_Options (const PK_Signature_Options &)=default
 PK_Signature_Options (PK_Signature_Options &&other)=default
std::string to_string () const
PK_Signature_Options with_context (std::span< const uint8_t > context)
PK_Signature_Options with_context (std::string_view context)
PK_Signature_Options with_der_encoded_signature (bool der=true)
PK_Signature_Options with_deterministic_signature (bool deterministic=true)
PK_Signature_Options with_explicit_trailer_field (bool trailer=true)
PK_Signature_Options with_externally_computed_prehash (std::optional< std::string > hash=std::nullopt)
PK_Signature_Options with_hash (std::string_view hash)
PK_Signature_Options with_padding (std::string_view padding)
PK_Signature_Options with_prehash (std::optional< std::string > prehash=std::nullopt)
PK_Signature_Options with_provider (std::string_view provider)
PK_Signature_Options with_salt_size (size_t salt_size)
 ~PK_Signature_Options ()

Friends

class PK_Signature_Options_Reader

Detailed Description

Signature generation/verification options

The normal usage of this is in a builder style, eg

PK_Signature_Options() .with_hash("SHA-256") .with_der_encoded_signature() .with_context("Foo")

Every option that is set must be understood by the signature scheme in use. If a scheme does not support an option (for example a context for RSA, or a salt for Ed25519) then constructing the PK_Signer or PK_Verifier throws an exception; an option is never silently ignored.

Definition at line 49 of file pk_options.h.

Constructor & Destructor Documentation

◆ PK_Signature_Options() [1/3]

◆ PK_Signature_Options() [2/3]

Botan::PK_Signature_Options::PK_Signature_Options ( PK_Signature_Options && other)
default

◆ PK_Signature_Options() [3/3]

Botan::PK_Signature_Options::PK_Signature_Options ( const PK_Signature_Options & )
default

◆ ~PK_Signature_Options()

Member Function Documentation

◆ operator=() [1/2]

PK_Signature_Options & Botan::PK_Signature_Options::operator= ( const PK_Signature_Options & other)
default

◆ operator=() [2/2]

PK_Signature_Options & Botan::PK_Signature_Options::operator= ( PK_Signature_Options && other)
default

◆ to_string()

std::string Botan::PK_Signature_Options::to_string ( ) const

Format this PK_Signature_Options as a string

This is primarily intended for debugging and error messages; the format is not fixed

Definition at line 227 of file pk_options.cpp.

227 {
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}
const char * name
Definition ffi_tls.h:59
void hex_encode(char output[], const uint8_t input[], size_t input_length, bool uppercase)
Definition hex.cpp:34

References Botan::hex_encode(), and name.

Referenced by ~PK_Signature_Options().

◆ with_context() [1/2]

PK_Signature_Options Botan::PK_Signature_Options::with_context ( std::span< const uint8_t > context)

Specify a context

Some signature schemes allow specifying a context with the signature. This is typically a fixed string that identifies a protocol or peer.

For SM2 this context is the user identifier

If the scheme does not support contextual identifiers, then an exception will be thrown.

Definition at line 77 of file pk_options.cpp.

77 {
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}
#define BOTAN_STATE_CHECK_MSG(expr, msg)
Definition assert.h:59

References BOTAN_STATE_CHECK_MSG, and PK_Signature_Options().

Referenced by Botan::parse_legacy_sig_options(), and ~PK_Signature_Options().

◆ with_context() [2/2]

PK_Signature_Options Botan::PK_Signature_Options::with_context ( std::string_view context)

Specify a context as a string

Equivalent to the version taking a span above; just uses the bytes of the string instead.

Definition at line 84 of file pk_options.cpp.

84 {
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}
std::span< const uint8_t > as_span_of_bytes(const char *s, size_t len)
Definition mem_utils.h:59

References Botan::as_span_of_bytes(), BOTAN_STATE_CHECK_MSG, and PK_Signature_Options().

◆ with_der_encoded_signature()

PK_Signature_Options Botan::PK_Signature_Options::with_der_encoded_signature ( bool der = true)

Specify producing or expecting a DER encoded signature

This is mostly used with ECDSA

For schemes that do not support such formatting (such as RSA or post-quantum schemes), an exception will be thrown when the PK_Signer or PK_Verifier is created.

Definition at line 110 of file pk_options.cpp.

110 {
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}

References BOTAN_STATE_CHECK_MSG, and PK_Signature_Options().

Referenced by ~PK_Signature_Options().

◆ with_deterministic_signature()

PK_Signature_Options Botan::PK_Signature_Options::with_deterministic_signature ( bool deterministic = true)

Request producing a deterministic signature

Some signature schemes are always deterministic, or always randomized. Others support both randomized or deterministic options. This allows requesting this. For signatures which are always deterministic this option has no effect. Schemes which can only produce randomized signatures reject this option.

This option is ignored for verification

Definition at line 101 of file pk_options.cpp.

101 {
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}

References BOTAN_STATE_CHECK_MSG, and PK_Signature_Options().

Referenced by Botan::parse_legacy_sig_options(), and ~PK_Signature_Options().

◆ with_explicit_trailer_field()

PK_Signature_Options Botan::PK_Signature_Options::with_explicit_trailer_field ( bool trailer = true)

Specify producing or expecting an explicit trailer field

Certain RSA padding schemes, such as PSS and ISO-9796, support two different trailer fields. One is an "implicit" trailer, which does not directly identify the hash. The other is an "explicit" trailer, which does.

Note that currently this option is only supported by ISO-9796. While some standards allow PSS to use a trailer field, others (such as RFC 4055) prohibit using explicit trailers for PSS, and it is not currently supported.

Definition at line 118 of file pk_options.cpp.

118 {
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}

References BOTAN_STATE_CHECK_MSG, and PK_Signature_Options().

Referenced by Botan::parse_legacy_sig_options(), and ~PK_Signature_Options().

◆ with_externally_computed_prehash()

PK_Signature_Options Botan::PK_Signature_Options::with_externally_computed_prehash ( std::optional< std::string > hash = std::nullopt)

Specify that the caller has already hashed the message

With this option the data passed to the signature operation is not the message but a hash of it, which the caller computed. The library signs (or verifies) the provided digest directly, without hashing it again.

The hash function that was used can be named either here or via with_hash (if both are given they must agree). Naming it allows the scheme to check the digest length and to identify the hash in the signature where the format requires it (for example the PKCS #1 v1.5 DigestInfo). If no hash is named the input is signed as an opaque byte string.

Warning
Signing externally computed hashes is easy to get wrong and many ways of doing it are insecure. Don't use this unless you know what you are doing.

If the scheme does not support signing an externally computed hash, it will throw an exception when presented with such an option.

This cannot be combined with with_prehash

Definition at line 52 of file pk_options.cpp.

52 {
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}

References BOTAN_STATE_CHECK_MSG, and PK_Signature_Options().

Referenced by Botan::parse_legacy_sig_options(), and ~PK_Signature_Options().

◆ with_hash()

PK_Signature_Options Botan::PK_Signature_Options::with_hash ( std::string_view hash)

Specify the hash function to use for signing/verification

Most, but not all, schemes require specifying a hash function.

Definition at line 21 of file pk_options.cpp.

21 {
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}

References BOTAN_STATE_CHECK_MSG, and PK_Signature_Options().

Referenced by Botan::parse_legacy_sig_options(), and ~PK_Signature_Options().

◆ with_padding()

PK_Signature_Options Botan::PK_Signature_Options::with_padding ( std::string_view padding)

Specify a padding scheme

This is mostly/only used for RSA

If the scheme does not support a padding option, it will throw an exception when presented with such an option.

Definition at line 30 of file pk_options.cpp.

30 {
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}

References BOTAN_STATE_CHECK_MSG, and PK_Signature_Options().

Referenced by Botan::parse_legacy_sig_options(), and ~PK_Signature_Options().

◆ with_prehash()

PK_Signature_Options Botan::PK_Signature_Options::with_prehash ( std::optional< std::string > prehash = std::nullopt)

Request that the library prehash the message

Some signature schemes, such as Ed25519, normally sign the entire message along with some context data. However such schemes also sometimes offer a prehashing variant where the message is hashed on its own, then the hash is signed.

With this option the library computes the prehash itself; the caller still provides the full message. If given this specifies what hash function to use for prehashing. If prehash is nullopt, this requests prehashing using an algorithm specific default function.

If the scheme does not support prehashing, it will throw an exception when presented with such an option.

This cannot be combined with with_externally_computed_prehash

Definition at line 39 of file pk_options.cpp.

39 {
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}

References BOTAN_STATE_CHECK_MSG, and PK_Signature_Options().

Referenced by Botan::parse_legacy_sig_options(), and ~PK_Signature_Options().

◆ with_provider()

PK_Signature_Options Botan::PK_Signature_Options::with_provider ( std::string_view provider)

Specify a provider that should be used

This is rarely relevant

Definition at line 67 of file pk_options.cpp.

67 {
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}

References BOTAN_STATE_CHECK_MSG, and PK_Signature_Options().

Referenced by Botan::Private_Key::create_signature_op(), Botan::Public_Key::create_verification_op(), and ~PK_Signature_Options().

◆ with_salt_size()

PK_Signature_Options Botan::PK_Signature_Options::with_salt_size ( size_t salt_size)

Specify the size of salt to be used

A small number of padding schemes (most importantly RSA-PSS) use a randomized salt. This allows controlling the size of the salt that is used.

Definition at line 92 of file pk_options.cpp.

92 {
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}
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33

References BOTAN_ARG_CHECK, BOTAN_STATE_CHECK_MSG, and PK_Signature_Options().

Referenced by ~PK_Signature_Options().

◆ PK_Signature_Options_Reader

friend class PK_Signature_Options_Reader
friend

Definition at line 188 of file pk_options.h.

References PK_Signature_Options_Reader.

Referenced by PK_Signature_Options_Reader.


The documentation for this class was generated from the following files: