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

#include <pubkey.h>

Public Member Functions

AlgorithmIdentifier algorithm_identifier () const
std::string hash_function () const
PK_Signer & operator= (const PK_Signer &)=delete
PK_Signer & operator= (PK_Signer &&) noexcept
 PK_Signer (const PK_Signer &)=delete
 PK_Signer (const Private_Key &key, RandomNumberGenerator &rng, const PK_Signature_Options &options=PK_Signature_Options())
 PK_Signer (const Private_Key &key, RandomNumberGenerator &rng, std::string_view padding, Signature_Format format=Signature_Format::Standard, std::string_view provider="")
 PK_Signer (PK_Signer &&) noexcept
void set_output_format (Signature_Format format)
std::vector< uint8_t > sign_message (const uint8_t in[], size_t length, RandomNumberGenerator &rng)
std::vector< uint8_t > sign_message (std::span< const uint8_t > in, RandomNumberGenerator &rng)
std::vector< uint8_t > signature (RandomNumberGenerator &rng)
size_t signature_length () const
void update (const uint8_t in[], size_t length)
void update (std::span< const uint8_t > in)
void update (std::string_view in)
void update (uint8_t in)
 ~PK_Signer ()

Detailed Description

Public Key Signer. Use the sign_message() functions for small messages. Use multiple calls update() to process large messages and generate the signature by finally calling signature().

Definition at line 176 of file pubkey.h.

Constructor & Destructor Documentation

◆ PK_Signer() [1/4]

Botan::PK_Signer::PK_Signer ( const Private_Key & key,
RandomNumberGenerator & rng,
const PK_Signature_Options & options = PK_Signature_Options() )

Construct a PK signer

Parameters
keythe key to use to generate signatures
Random Number Generatorsa RNG object which must outlive this operation object
optionscontrols the behavior of the signature generation, eg which hash function to use

Note that most common algorithms (eg RSA or ECDSA) require an options parameter to specify at least which hash function to use. Schemes without any parameters (eg Ed25519, ML-DSA, XMSS) can be used with the default.

Definition at line 322 of file pubkey.cpp.

322 {
323 const PK_Signature_Options_Reader reader(options, PK_Signature_Options_Reader::Usage::Signing);
324
325 m_op = key._create_signature_op(rng, reader);
326
327 if(!m_op) {
328 throw Invalid_Argument(fmt("Key type {} does not support signature generation", key.algo_name()));
329 }
330 m_sig_format = reader.using_der_encoded_signature() ? Signature_Format::DerSequence : Signature_Format::Standard;
331 m_sig_element_size = key._signature_element_size_for_DER_encoding();
332
333 if(m_sig_format == Signature_Format::DerSequence && !m_sig_element_size.has_value()) {
334 throw Invalid_Argument(fmt("Key type {} does not support DER encoded signatures", key.algo_name()));
335 }
336
337 reader.throw_if_unexamined(key.algo_name());
338}
std::string fmt(std::string_view format, const T &... args)
Definition fmt.h:53

References Botan::Private_Key::_create_signature_op(), Botan::Asymmetric_Key::_signature_element_size_for_DER_encoding(), Botan::Asymmetric_Key::algo_name(), Botan::DerSequence, Botan::fmt(), Botan::Standard, and Botan::PK_Signature_Options_Reader::using_der_encoded_signature().

Referenced by operator=(), operator=(), PK_Signer(), PK_Signer(), PK_Signer(), and update().

◆ PK_Signer() [2/4]

Botan::PK_Signer::PK_Signer ( const Private_Key & key,
RandomNumberGenerator & rng,
std::string_view padding,
Signature_Format format = Signature_Format::Standard,
std::string_view provider = "" )

Construct a PK Signer.

Parameters
keythe key to use inside this signer
Random Number Generatorsa RNG object which must outlive this operation object
paddingthe padding/hash to use, eg "SHA-512" or "PSS(SHA-256)"
formatthe signature format to use
providerthe provider to use

Definition at line 311 of file pubkey.cpp.

315 :
316 PK_Signer(key,
317 rng,
318 parse_legacy_sig_options(key, padding)
319 .with_der_encoded_signature(format == Signature_Format::DerSequence)
320 .with_provider(provider)) {}
PK_Signer(const Private_Key &key, RandomNumberGenerator &rng, const PK_Signature_Options &options=PK_Signature_Options())
Definition pubkey.cpp:322
PK_Signature_Options parse_legacy_sig_options(const Public_Key &key, std::string_view params)

References Botan::parse_legacy_sig_options(), and PK_Signer().

◆ ~PK_Signer()

Botan::PK_Signer::~PK_Signer ( )
default

◆ PK_Signer() [3/4]

Botan::PK_Signer::PK_Signer ( const PK_Signer & )
delete

References PK_Signer().

◆ PK_Signer() [4/4]

Botan::PK_Signer::PK_Signer ( PK_Signer && )
defaultnoexcept

References PK_Signer().

Member Function Documentation

◆ algorithm_identifier()

AlgorithmIdentifier Botan::PK_Signer::algorithm_identifier ( ) const

Return an AlgorithmIdentifier appropriate for identifying the signature method being generated by this PK_Signer. Throws an exception if this is not available for the current signature scheme.

Definition at line 340 of file pubkey.cpp.

340 {
341 return m_op->algorithm_identifier();
342}

◆ hash_function()

std::string Botan::PK_Signer::hash_function ( ) const

Return the hash function which is being used to create signatures. This should never return an empty string however it may return a string which does not map directly to a hash function, in particular if "Raw" (unhashed) encoding is being used.

Definition at line 344 of file pubkey.cpp.

344 {
345 return m_op->hash_function();
346}

◆ operator=() [1/2]

PK_Signer & Botan::PK_Signer::operator= ( const PK_Signer & )
delete

References PK_Signer().

◆ operator=() [2/2]

PK_Signer & Botan::PK_Signer::operator= ( PK_Signer && )
defaultnoexcept

References PK_Signer().

◆ set_output_format()

void Botan::PK_Signer::set_output_format ( Signature_Format format)

Set the output format of the signature.

Parameters
formatthe signature format to use

Definition at line 426 of file pubkey.cpp.

426 {
427 if(format == Signature_Format::DerSequence) {
428 BOTAN_ARG_CHECK(m_sig_element_size.has_value(), "This key does not support DER signatures");
429 }
430 m_sig_format = format;
431}
#define BOTAN_ARG_CHECK(expr, msg)
Definition assert.h:33

References BOTAN_ARG_CHECK, and Botan::DerSequence.

◆ sign_message() [1/2]

std::vector< uint8_t > Botan::PK_Signer::sign_message ( const uint8_t in[],
size_t length,
RandomNumberGenerator & rng )
inline

Sign a message all in one go

Parameters
inthe message to sign as a byte array
lengththe length of the above byte array
Random Number Generatorsthe rng to use
Returns
signature

Definition at line 222 of file pubkey.h.

222 {
223 this->update(in, length);
224 return this->signature(rng);
225 }
void update(uint8_t in)
Definition pubkey.h:241
std::vector< uint8_t > signature(RandomNumberGenerator &rng)
Definition pubkey.cpp:433

References sign_message(), signature(), and update().

Referenced by Botan::X509_Object::make_signed(), sign_message(), sign_message(), Botan::KeyPair::signature_consistency_check(), and Botan::TLS::Callbacks::tls_sign_message().

◆ sign_message() [2/2]

std::vector< uint8_t > Botan::PK_Signer::sign_message ( std::span< const uint8_t > in,
RandomNumberGenerator & rng )
inline

Sign a message.

Parameters
inthe message to sign
Random Number Generatorsthe rng to use
Returns
signature

Definition at line 233 of file pubkey.h.

233 {
234 return sign_message(in.data(), in.size(), rng);
235 }
std::vector< uint8_t > sign_message(const uint8_t in[], size_t length, RandomNumberGenerator &rng)
Definition pubkey.h:222

References sign_message().

◆ signature()

std::vector< uint8_t > Botan::PK_Signer::signature ( RandomNumberGenerator & rng)

Get the signature of the so far processed message (provided by the calls to update()).

Parameters
Random Number Generatorsthe rng to use
Returns
signature of the total message

Definition at line 433 of file pubkey.cpp.

433 {
434 // The format is checked before signing, since signing may consume a stateful key index
435 if(m_sig_format == Signature_Format::Standard) {
436 return m_op->sign(rng);
437 } else if(m_sig_format == Signature_Format::DerSequence) {
438 BOTAN_ASSERT_NOMSG(m_sig_element_size.has_value());
439 return der_encode_signature(m_op->sign(rng), 2, m_sig_element_size.value());
440 } else {
441 throw Internal_Error("PK_Signer: Invalid signature format enum");
442 }
443}
#define BOTAN_ASSERT_NOMSG(expr)
Definition assert.h:82

References BOTAN_ASSERT_NOMSG, Botan::DerSequence, and Botan::Standard.

Referenced by Botan::ed25519_sign(), and sign_message().

◆ signature_length()

size_t Botan::PK_Signer::signature_length ( ) const

Return an upper bound on the length of the signatures this PK_Signer will produce

Definition at line 382 of file pubkey.cpp.

382 {
383 if(m_sig_format == Signature_Format::Standard) {
384 return m_op->signature_length();
385 } else if(m_sig_format == Signature_Format::DerSequence) {
386 const size_t sig_len = m_op->signature_length();
387
388 const size_t der_overhead = [sig_len]() {
389 /*
390 This was computed by DER encoding of some maximal value signatures
391 (since DER is variable length)
392
393 The first two cases covers all EC schemes since groups are at most 521
394 bits.
395
396 The other cases are only for finite field DSA which practically is only
397 used up to 3072 bit groups but the calculation is correct up to a
398 262096 (!) bit group so allow it. There are some intermediate sizes but
399 this function is allowed to (and indeed must) return an over-estimate
400 rather than an exact value since the actual length will change based on
401 the computed signature.
402 */
403
404 if(sig_len <= 120) {
405 // EC signatures <= 480 bits
406 return 8;
407 } else if(sig_len <= 248) {
408 // EC signatures > 480 bits (or very small DSA groups...)
409 return 9;
410 } else {
411 // Everything else. This is an over-estimate for groups under
412 // 2040 bits but exact otherwise
413
414 // This requires 15 bytes DER overhead and should never happen
415 BOTAN_ASSERT_NOMSG(sig_len < 65524);
416 return 14;
417 }
418 }();
419
420 return sig_len + der_overhead;
421 } else {
422 throw Internal_Error("PK_Signer: Invalid signature format enum");
423 }
424}

References BOTAN_ASSERT_NOMSG, Botan::DerSequence, and Botan::Standard.

◆ update() [1/4]

void Botan::PK_Signer::update ( const uint8_t in[],
size_t length )

Add a message part.

Parameters
inthe message part to add as a byte array
lengththe length of the above byte array

Definition at line 357 of file pubkey.cpp.

357 {
358 m_op->update({in, length});
359}

◆ update() [2/4]

void Botan::PK_Signer::update ( std::span< const uint8_t > in)
inline

Add a message part.

Parameters
inthe message part to add

Definition at line 254 of file pubkey.h.

254{ update(in.data(), in.size()); }

References update().

Referenced by update().

◆ update() [3/4]

void Botan::PK_Signer::update ( std::string_view in)

Add a message part.

Parameters
inthe message part to add

Definition at line 353 of file pubkey.cpp.

353 {
354 this->update(as_span_of_bytes(in));
355}
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(), PK_Signer(), and update().

◆ update() [4/4]

void Botan::PK_Signer::update ( uint8_t in)
inline

Add a message part (single byte).

Parameters
inthe byte to add

Definition at line 241 of file pubkey.h.

241{ update(&in, 1); }

References update().

Referenced by Botan::ed25519_sign(), sign_message(), update(), and update().


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