Botan::X509_Serial_Number Class Reference

#include <pkix_types.h>

Inheritance diagram for Botan::X509_Serial_Number:

Public Member Functions
std::vector< uint8_t >	BER_encode () const
bool	conforms_to_rfc5280 () const
void	decode_from (BER_Decoder &from) override
std::span< const uint8_t >	der_contents () const
void	encode_into (DER_Encoder &to) const override
bool	is_negative () const
bool	is_zero () const
std::vector< uint8_t >	magnitude () const
size_t	octet_length () const
std::strong_ordering	operator<=> (const X509_Serial_Number &other) const
bool	operator== (const X509_Serial_Number &other) const
BigInt	to_bigint () const
std::string	to_string () const
	X509_Serial_Number ()
	X509_Serial_Number (const BigInt &value)

Static Public Member Functions
static X509_Serial_Number	from_bytes (std::span< const uint8_t > bytes)
static X509_Serial_Number	from_der_contents (std::span< const uint8_t > contents)
static X509_Serial_Number	random (RandomNumberGenerator &rng)

Detailed Description

X.509 certificate serial number (RFC 5280 CertificateSerialNumber)

Stores the value as the contents octets of the DER INTEGER encoding (two's complement, minimal length), so the sign is preserved and equality on the stored bytes is value equality.

RFC 5280 4.1.2.2: The serial number MUST be a positive integer assigned by the CA to each certificate. and Note: Non-conforming CAs may issue certificates with serial numbers that are negative or zero. Certificate users SHOULD be prepared to gracefully handle such certificates.

so non-conforming values are representable, and can be detected with is_negative, is_zero and octet_length.

Definition at line 65 of file pkix_types.h.

Constructor & Destructor Documentation

X509_Serial_Number() [1/2]

Botan::X509_Serial_Number::X509_Serial_Number ( )

inline

Serial number zero

Definition at line 70 of file pkix_types.h.

: m_contents{0x00} {}

Referenced by decode_from(), from_bytes(), from_der_contents(), operator<=>(), operator==(), and random().

X509_Serial_Number() [2/2]

Botan::X509_Serial_Number::X509_Serial_Number ( const BigInt & value )

explicit

Create from an integer value

Definition at line 20 of file x509_serial.cpp.

: m_contents(ASN1::integer_contents(value)) {}

Member Function Documentation

BER_encode()

std::vector< uint8_t > Botan::ASN1_Object::BER_encode ( ) const

inherited

Return the encoding of this object. This is a convenience method when just one object needs to be serialized. Use DER_Encoder for complicated encodings.

Definition at line 21 of file asn1_obj.cpp.

                                                 {
   std::vector<uint8_t> output;
   DER_Encoder der(output);
   this->encode_into(der);
   return output;
}

References encode_into().

Referenced by decode_from(), Botan::PKCS12::export_to(), Botan::Certificate_Store_In_SQL::find_all_certs(), Botan::Certificate_Store_In_SQL::find_cert(), Botan::X509_Certificate::fingerprint(), Botan::Certificate_Store_In_SQL::insert_cert(), Botan::X509_Object::PEM_encode(), and Botan::PSS_Params::PSS_Params().

conforms_to_rfc5280()

bool Botan::X509_Serial_Number::conforms_to_rfc5280 ( ) const

inline

True if this serial number satisfies the RFC 5280 4.1.2.2 rules for conforming CAs: a positive integer of at most 20 octets

Definition at line 118 of file pkix_types.h.

{ return !is_negative() && !is_zero() && octet_length() <= 20; }

References is_negative(), is_zero(), and octet_length().

decode_from()

void Botan::X509_Serial_Number::decode_from ( BER_Decoder & from )

overridevirtual

Decode whatever this object is from from

Parameters

from	the BER_Decoder that will be read from

Implements Botan::ASN1_Object.

Definition at line 108 of file x509_serial.cpp.

                                                      {
   // Decode via BigInt so the decoder's limits apply, in particular the
   // rejection of non-minimal INTEGER encodings in DER mode
   BigInt value;
   from.decode(value);
   *this = X509_Serial_Number(value);
}

References Botan::BER_Decoder::decode(), and X509_Serial_Number().

der_contents()

std::span< const uint8_t > Botan::X509_Serial_Number::der_contents ( ) const

inline

The contents octets of the DER INTEGER encoding (big-endian two's complement, minimal length)

Definition at line 124 of file pkix_types.h.

{ return m_contents; }

encode_into()

void Botan::X509_Serial_Number::encode_into ( DER_Encoder & to ) const

overridevirtual

Encode whatever this object is into to

Parameters

to	the DER_Encoder that will be written to

Implements Botan::ASN1_Object.

Definition at line 103 of file x509_serial.cpp.

                                                          {
   BOTAN_STATE_CHECK(!m_contents.empty());
   to.add_object(ASN1_Type::Integer, ASN1_Class::Universal, m_contents);
}

References Botan::DER_Encoder::add_object(), BOTAN_STATE_CHECK, Botan::Integer, and Botan::Universal.

from_bytes()

X509_Serial_Number Botan::X509_Serial_Number::from_bytes ( std::span< const uint8_t > bytes )

static

Create from an unsigned big-endian encoded integer

Definition at line 22 of file x509_serial.cpp.

                                                                              {
   while(!bytes.empty() && bytes.front() == 0x00) {
      bytes = bytes.subspan(1);
   }
 
   if(bytes.empty()) {
      return X509_Serial_Number();  // zero
   }
 
   X509_Serial_Number sn;
   sn.m_contents.clear();
   if((bytes.front() & 0x80) == 0x80) {
      sn.m_contents.push_back(0x00);
   }
   sn.m_contents.insert(sn.m_contents.end(), bytes.begin(), bytes.end());
   return sn;
}

References X509_Serial_Number().

Referenced by random().

from_der_contents()

X509_Serial_Number Botan::X509_Serial_Number::from_der_contents ( std::span< const uint8_t > contents )

static

Create from the contents octets of a BER INTEGER (big-endian two's complement). Redundant leading octets are normalized away; an empty input is rejected.

Definition at line 40 of file x509_serial.cpp.

                                                                                        {
   if(contents.empty()) {
      throw Decoding_Error("Serial number INTEGER encoding has no contents octets");
   }
 
   // Normalize away redundant leading octets a BER encoding may carry
   size_t offset = 0;
   while(offset + 1 < contents.size() && ((contents[offset] == 0x00 && (contents[offset + 1] & 0x80) == 0x00) ||
                                          (contents[offset] == 0xFF && (contents[offset + 1] & 0x80) == 0x80))) {
      offset += 1;
   }
 
   X509_Serial_Number sn;
   sn.m_contents.assign(contents.begin() + offset, contents.end());
   return sn;
}

References X509_Serial_Number().

is_negative()

bool Botan::X509_Serial_Number::is_negative

(

)

const

Return true if the serial number is negative

TODO(Botan4) remove this once negative serial numbers are prohibited

Definition at line 65 of file x509_serial.cpp.

                                           {
   BOTAN_STATE_CHECK(!m_contents.empty());
   return (m_contents[0] & 0x80) == 0x80;
}

References BOTAN_STATE_CHECK.

Referenced by Botan::PKIX::check_chain(), conforms_to_rfc5280(), Botan::X509_Certificate::is_serial_negative(), magnitude(), operator<=>(), and to_string().

is_zero()

bool Botan::X509_Serial_Number::is_zero

(

)

const

Return true if the serial number is the integer zero

Definition at line 70 of file x509_serial.cpp.

                                       {
   return m_contents.size() == 1 && m_contents[0] == 0x00;
}

Referenced by conforms_to_rfc5280(), magnitude(), and to_string().

magnitude()

std::vector< uint8_t > Botan::X509_Serial_Number::magnitude

(

)

const

The absolute value as unsigned big-endian bytes without leading zeros. Note this loses the sign, and is empty for a zero serial; it matches X509_Certificate::serial_number.

Definition at line 74 of file x509_serial.cpp.

                                                       {
   BOTAN_STATE_CHECK(!m_contents.empty());
 
   if(is_zero()) {
      return {};
   } else if(is_negative()) {
      return to_bigint().serialize();
   } else if(m_contents[0] == 0x00) {
      // Positive value whose leading magnitude bit is set; skip the sign octet
      return {m_contents.begin() + 1, m_contents.end()};
   } else {
      return m_contents;
   }
}

References BOTAN_STATE_CHECK, is_negative(), is_zero(), Botan::BigInt::serialize(), and to_bigint().

Referenced by to_string().

octet_length()

size_t Botan::X509_Serial_Number::octet_length ( ) const

inline

Number of contents octets in the DER encoding of this value

Definition at line 112 of file pkix_types.h.

{ return m_contents.size(); }

Referenced by conforms_to_rfc5280().

operator<=>()

std::strong_ordering Botan::X509_Serial_Number::operator<=>

(

const X509_Serial_Number &

other

)

const

Numeric ordering

Definition at line 116 of file x509_serial.cpp.

                                              =>(const X509_Serial_Number& other) const {
   BOTAN_STATE_CHECK(!m_contents.empty());
 
   const bool neg = is_negative();
 
   if(neg != other.is_negative()) {
      return neg ? std::strong_ordering::less : std::strong_ordering::greater;
   }
 
   // Same sign: for positive values the longer encoding is the larger value,
   // for negative values the longer encoding is the smaller (more negative)
   if(m_contents.size() != other.m_contents.size()) {
      const bool shorter = m_contents.size() < other.m_contents.size();
      return (shorter != neg) ? std::strong_ordering::less : std::strong_ordering::greater;
   }
 
   /*
   * When comparing two values of the same sign in two's complement
   * encoding, the lexicographic ordering is correct for both signs,
   * for instance -2 (0xFE) is less than -1 (0xFF)
   */
   const int cmp = std::memcmp(m_contents.data(), other.m_contents.data(), m_contents.size());
   if(cmp < 0) {
      return std::strong_ordering::less;
   } else if(cmp > 0) {
      return std::strong_ordering::greater;
   } else {
      return std::strong_ordering::equal;
   }
}

References BOTAN_STATE_CHECK, is_negative(), and X509_Serial_Number().

operator==()

bool Botan::X509_Serial_Number::operator== ( const X509_Serial_Number & other ) const

inline

Definition at line 143 of file pkix_types.h.

{ return m_contents == other.m_contents; }

References X509_Serial_Number().

random()

X509_Serial_Number Botan::X509_Serial_Number::random ( RandomNumberGenerator & rng )

static

Generate a serial number suitable for issuing a certificate.

The result is positive, never zero, and contains 126 bits of output from the RNG. The topmost bit is cleared, and the 127th bit is set.

Definition at line 57 of file x509_serial.cpp.

                                                                        {
   std::array<uint8_t, 16> bytes{};
   rng.randomize(bytes);
   bytes[0] &= 0x7F;  // clear bit 128
   bytes[0] |= 0x40;  // set bit 127
   return X509_Serial_Number::from_bytes(bytes);
}

References from_bytes(), Botan::RandomNumberGenerator::randomize(), and X509_Serial_Number().

Referenced by Botan::X509_CA::make_cert().

to_bigint()

BigInt Botan::X509_Serial_Number::to_bigint

(

)

const

Definition at line 89 of file x509_serial.cpp.

                                           {
   BOTAN_STATE_CHECK(!m_contents.empty());
   return ASN1::integer_from_contents(m_contents);
}

References BOTAN_STATE_CHECK, and Botan::ASN1::integer_from_contents().

Referenced by botan_x509_cert_serial_number(), botan_x509_crl_entry_serial_number(), and magnitude().

to_string()

std::string Botan::X509_Serial_Number::to_string

(

)

const

The value in hex, prefixed with '-' if negative

Definition at line 94 of file x509_serial.cpp.

                                              {
   BOTAN_STATE_CHECK(!m_contents.empty());
   if(is_zero()) {
      return "00";
   }
   const std::string hex = hex_encode(magnitude());
   return is_negative() ? "-" + hex : hex;
}

References BOTAN_STATE_CHECK, Botan::hex_encode(), is_negative(), is_zero(), and magnitude().

Referenced by Botan::X509_Certificate::to_string().

---

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

• src/lib/x509/pkix_types.h
• src/lib/x509/x509_serial.cpp