#include <pkix_types.h>

Inheritance diagram for Botan::X509_DN:

Public Member Functions
const std::vector< uint8_t > &	_canonical_bytes () const
void	add_attribute (const OID &oid, const ASN1_String &val)
void	add_attribute (const OID &oid, std::string_view val)
void	add_attribute (std::string_view key, std::string_view val)
void	add_rdn (std::vector< std::pair< OID, ASN1_String > > rdn)
std::vector< uint8_t >	BER_encode () const
std::multimap< std::string, std::string >	contents () const
size_t	count () const
void	decode_from (BER_Decoder &from) override
std::vector< uint8_t >	DER_encode () const
std::vector< std::pair< OID, ASN1_String > >	dn_info () const
bool	empty () const
void	encode_into (DER_Encoder &to) const override
std::vector< std::string >	get_attribute (std::string_view attr) const
std::multimap< OID, std::string >	get_attributes () const
const std::vector< uint8_t > &	get_bits () const
ASN1_String	get_first_attribute (const OID &oid) const
std::string	get_first_attribute (std::string_view attr) const
bool	has_field (const OID &oid) const
bool	has_field (std::string_view attr) const
const std::vector< std::vector< std::pair< OID, ASN1_String > > > &	rdns () const
std::string	to_string () const
	X509_DN ()=default
	X509_DN (const std::multimap< OID, std::string > &args)
	X509_DN (const std::multimap< std::string, std::string > &args)
	X509_DN (std::initializer_list< std::pair< std::string_view, std::string_view > > args)

Static Public Member Functions
static std::string	deref_info_field (std::string_view key)
static size_t	lookup_ub (const OID &oid)
static std::optional< X509_DN >	parse (std::string_view str)

Detailed Description

Distinguished Name

Definition at line 157 of file pkix_types.h.

Constructor & Destructor Documentation

◆ X509_DN() [1/4]

Botan::X509_DN::X509_DN ( )

default

Referenced by parse(), X509_DN(), and X509_DN().

◆ X509_DN() [2/4]

Botan::X509_DN::X509_DN ( std::initializer_list< std::pair< std::string_view, std::string_view > > args )

inline

Definition at line 161 of file pkix_types.h.

                                                                                 {
         for(const auto& i : args) {
            add_attribute(i.first, i.second);
         }
      }

References add_attribute().

◆ X509_DN() [3/4]

Botan::X509_DN::X509_DN ( const std::multimap< OID, std::string > & args )

inlineexplicit

Since DN matching for Name Constraints requires preserving order and multimaps have sorted keys, this constructor is deprecated.

Definition at line 172 of file pkix_types.h.

                                                                {
         for(const auto& i : args) {
            add_attribute(i.first, i.second);
         }
      }

References add_attribute(), and X509_DN().

◆ X509_DN() [4/4]

Botan::X509_DN::X509_DN ( const std::multimap< std::string, std::string > & args )

inlineexplicit

Since DN matching for Name Constraints requires preserving order and multimaps have sorted keys, this constructor is deprecated.

Definition at line 183 of file pkix_types.h.

                                                                      {
         for(const auto& i : args) {
            add_attribute(i.first, i.second);
         }
      }

References add_attribute(), and X509_DN().

Member Function Documentation

◆ _canonical_bytes()

const std::vector< uint8_t > & Botan::X509_DN::_canonical_bytes ( ) const

inline

Return a canonical byte encoding

Internal interface, not covered by SemVer

Definition at line 274 of file pkix_types.h.

274{ return m_canonical_dn_bits; }

Referenced by Botan::operator<(), Botan::operator==(), and Botan::x509_dn_subtree_match().

◆ add_attribute() [1/3]

void Botan::X509_DN::add_attribute	(	const OID &	oid,
		const ASN1_String &	val )

Definition at line 144 of file x509_dn.cpp.

                                                                  {
   if(str.empty()) {
      return;
   }
 
   // Each programmatic add appends a new single-AVA RDN.
   m_rdn.push_back({std::make_pair(oid, str)});
   m_dn_bits.clear();
   update_canonical_bits();
}

References Botan::ASN1_String::empty().

◆ add_attribute() [2/3]

void Botan::X509_DN::add_attribute	(	const OID &	oid,
		std::string_view	val )

inline

Definition at line 247 of file pkix_types.h.

247{ add_attribute(oid, ASN1_String(val)); }

References add_attribute(), and add_attribute().

Referenced by add_attribute().

◆ add_attribute() [3/3]

void Botan::X509_DN::add_attribute	(	std::string_view	key,
		std::string_view	val )

Definition at line 137 of file x509_dn.cpp.

                                                                   {
   add_attribute(OID::from_string(type), str);
}

References add_attribute(), and Botan::OID::from_string().

Referenced by add_attribute(), add_attribute(), X509_DN(), X509_DN(), and X509_DN().

◆ add_rdn()

void Botan::X509_DN::add_rdn ( std::vector< std::pair< OID, ASN1_String > > rdn )

Append a complete RDN. The provided AVAs become one RelativeDistinguishedName (X.501 SET OF AttributeTypeAndValue). An empty input is ignored.

Definition at line 155 of file x509_dn.cpp.

                                                              {
   if(rdn.empty()) {
      return;
   }
   m_rdn.push_back(std::move(rdn));
   m_dn_bits.clear();
   update_canonical_bits();
}

Referenced by Botan::AlternativeName::dn(), and parse().

◆ 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().

◆ contents()

std::multimap< std::string, std::string > Botan::X509_DN::contents ( ) const

Definition at line 191 of file x509_dn.cpp.

                                                          {
   std::multimap<std::string, std::string> retval;
 
   for(const auto& rdn : m_rdn) {
      for(const auto& ava : rdn) {
         retval.emplace(ava.first.to_formatted_string(), ava.second.value());
      }
   }
   return retval;
}

◆ count()

size_t Botan::X509_DN::count ( ) const

inline

Number of relative distinguished names (RDNs) in the DN. Note: prior to multi-AVA RDN support this returned the total number of AVAs; the two differ only when the DN contains a multi-valued RDN.

Definition at line 209 of file pkix_types.h.

209{ return m_rdn.size(); }

Referenced by Botan::NameConstraints::is_excluded(), and Botan::NameConstraints::is_permitted().

◆ decode_from()

void Botan::X509_DN::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 408 of file x509_dn.cpp.

                                             {
   std::vector<uint8_t> bits;
 
   source.start_sequence().raw_bytes(bits).end_cons();
 
   BER_Decoder sequence(bits, source.limits());
 
   std::vector<std::vector<std::pair<OID, ASN1_String>>> rdns;
 
   // Cap AVAs per RDN to bound work for downstream set-based matching.
   // No legitimate cert has anywhere near this many AVAs in a single RDN.
   constexpr size_t MAX_AVAS_PER_RDN = 32;
 
   while(sequence.more_items()) {
      BER_Decoder rdn_decoder = sequence.start_set();
 
      std::vector<std::pair<OID, ASN1_String>> rdn;
      while(rdn_decoder.more_items()) {
         OID oid;
         ASN1_String str;
 
         rdn_decoder.start_sequence()
            .decode(oid)
            .decode(str)  // TODO support Any
            .end_cons();
 
         rdn.emplace_back(std::move(oid), std::move(str));
 
         if(rdn.size() > MAX_AVAS_PER_RDN) {
            throw Decoding_Error("X.500 RDN has too many attribute-value assertions");
         }
      }
 
      /*
      RFC 5280 4.1.2.4:
         RelativeDistinguishedName ::=
           SET SIZE (1..MAX) OF AttributeTypeAndValue
      */
      if(rdn.empty()) {
         throw Decoding_Error("X.500 RDN must contain at least one attribute-value assertion");
      }
      rdns.push_back(std::move(rdn));
   }
 
   auto canonical_bits = canonicalize_dn(rdns);
 
   m_rdn = std::move(rdns);
   m_dn_bits = std::move(bits);
   m_canonical_dn_bits = std::move(canonical_bits);
}

References Botan::BER_Decoder::decode(), Botan::BER_Decoder::end_cons(), Botan::BER_Decoder::limits(), Botan::BER_Decoder::more_items(), Botan::BER_Decoder::raw_bytes(), rdns(), Botan::BER_Decoder::start_sequence(), and Botan::BER_Decoder::start_set().

Referenced by Botan::Certificate_Store_In_SQL::all_subjects(), and Botan::GeneralName::decode_from().

◆ DER_encode()

std::vector< uint8_t > Botan::X509_DN::DER_encode ( ) const

Definition at line 373 of file x509_dn.cpp.

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

References encode_into().

◆ deref_info_field()

std::string Botan::X509_DN::deref_info_field ( std::string_view key )

static

Definition at line 264 of file x509_dn.cpp.

                                                       {
   if(info == "Name" || info == "CommonName" || info == "CN") {
      return "X520.CommonName";
   }
   if(info == "SerialNumber" || info == "SN") {
      return "X520.SerialNumber";
   }
   if(info == "Country" || info == "C") {
      return "X520.Country";
   }
   if(info == "Organization" || info == "O") {
      return "X520.Organization";
   }
   if(info == "Organizational Unit" || info == "OrgUnit" || info == "OU") {
      return "X520.OrganizationalUnit";
   }
   if(info == "Locality" || info == "L") {
      return "X520.Locality";
   }
   if(info == "State" || info == "Province" || info == "ST") {
      return "X520.State";
   }
   if(info == "Email") {
      return "RFC822";
   }
   return std::string(info);
}

Referenced by get_attribute(), get_first_attribute(), has_field(), and parse().

◆ dn_info()

std::vector< std::pair< OID, ASN1_String > > Botan::X509_DN::dn_info ( ) const

Return the DN attributes as a flat sequence of AVAs in decoded order. RDN structure is not preserved in this view; prefer rdns() to retain it.

Definition at line 164 of file x509_dn.cpp.

                                                            {
   std::vector<std::pair<OID, ASN1_String>> flat;
   for(const auto& rdn : m_rdn) {
      for(const auto& ava : rdn) {
         flat.push_back(ava);
      }
   }
   return flat;
}

◆ empty()

bool Botan::X509_DN::empty ( ) const

inline

Definition at line 202 of file pkix_types.h.

202{ return m_rdn.empty(); }

Referenced by Botan::NameConstraints::is_permitted().

◆ encode_into()

void Botan::X509_DN::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 383 of file x509_dn.cpp.

                                                {
   der.start_sequence();
 
   if(!m_dn_bits.empty()) {
      /*
      If we decoded this from somewhere, encode it back exactly as
      we received it
      */
      der.raw_bytes(m_dn_bits);
   } else {
      for(const auto& rdn : m_rdn) {
         der.start_set();
         for(const auto& ava : rdn) {
            der.start_sequence().encode(ava.first).encode(ava.second).end_cons();
         }
         der.end_cons();
      }
   }
 
   der.end_cons();
}

References Botan::DER_Encoder::encode(), Botan::DER_Encoder::end_cons(), Botan::DER_Encoder::raw_bytes(), Botan::DER_Encoder::start_sequence(), and Botan::DER_Encoder::start_set().

Referenced by DER_encode().

◆ get_attribute()

std::vector< std::string > Botan::X509_DN::get_attribute ( std::string_view attr ) const

Definition at line 245 of file x509_dn.cpp.

                                                                     {
   const OID oid = OID::from_string(deref_info_field(attr));
 
   std::vector<std::string> values;
 
   for(const auto& rdn : m_rdn) {
      for(const auto& ava : rdn) {
         if(ava.first == oid) {
            values.push_back(ava.second.value());
         }
      }
   }
 
   return values;
}

References deref_info_field(), and Botan::OID::from_string().

Referenced by Botan::NameConstraints::is_excluded(), Botan::NameConstraints::is_permitted(), and Botan::GeneralName::matches().

◆ get_attributes()

std::multimap< OID, std::string > Botan::X509_DN::get_attributes ( ) const

Definition at line 177 of file x509_dn.cpp.

                                                          {
   std::multimap<OID, std::string> retval;
 
   for(const auto& rdn : m_rdn) {
      for(const auto& ava : rdn) {
         retval.emplace(ava.first, ava.second.value());
      }
   }
   return retval;
}

◆ get_bits()

const std::vector< uint8_t > & Botan::X509_DN::get_bits ( ) const

inline

Definition at line 198 of file pkix_types.h.

198{ return m_dn_bits; }

Referenced by botan_x509_crl_view_binary_values().

◆ get_first_attribute() [1/2]

ASN1_String Botan::X509_DN::get_first_attribute ( const OID & oid ) const

Definition at line 230 of file x509_dn.cpp.

                                                             {
   for(const auto& rdn : m_rdn) {
      for(const auto& ava : rdn) {
         if(ava.first == oid) {
            return ava.second;
         }
      }
   }
 
   return ASN1_String();
}

Referenced by get_first_attribute().

◆ get_first_attribute() [2/2]

std::string Botan::X509_DN::get_first_attribute ( std::string_view attr ) const

Definition at line 225 of file x509_dn.cpp.

                                                                {
   const OID oid = OID::from_string(deref_info_field(attr));
   return get_first_attribute(oid).value();
}

References deref_info_field(), Botan::OID::from_string(), get_first_attribute(), and Botan::ASN1_String::value().

◆ has_field() [1/2]

bool Botan::X509_DN::has_field ( const OID & oid ) const

Definition at line 213 of file x509_dn.cpp.

                                            {
   for(const auto& rdn : m_rdn) {
      for(const auto& ava : rdn) {
         if(ava.first == oid) {
            return true;
         }
      }
   }
 
   return false;
}

Referenced by has_field().

◆ has_field() [2/2]

bool Botan::X509_DN::has_field ( std::string_view attr ) const

Definition at line 202 of file x509_dn.cpp.

                                                 {
   try {
      const OID o = OID::from_string(deref_info_field(attr));
      if(o.has_value()) {
         return has_field(o);
      }
   } catch(Lookup_Error&) {}
 
   return false;
}

References deref_info_field(), Botan::OID::from_string(), has_field(), and Botan::OID::has_value().

◆ lookup_ub()

size_t Botan::X509_DN::lookup_ub ( const OID & oid )

static

Lookup upper bounds in characters for the length of distinguished name fields as given in RFC 5280, Appendix A.

Parameters

oid	the oid of the DN to lookup

Returns: the upper bound, or zero if no ub is known to Botan

Definition at line 16 of file x509_dn_ub.cpp.

                                        {
   /*
   * See RFC 5280 Appendix A.1 starting with comment "-- Upper Bounds"
   */
 
   // NOLINTBEGIN(*-branch-clone)
   if(auto iso_dn = is_sub_element_of(oid, {2, 5, 4})) {
      switch(*iso_dn) {
         case 3:
            // X520.CommonName
            return 64;
         case 4:
            // X520.Surname
            return 40;
         case 5:
            // X520.SerialNumber
            return 64;
         case 6:
            // X520.Country
            return 3;
         case 7:
            // X520.Locality
            return 128;
         case 8:
            // X520.State
            return 128;
         case 9:
            // X520.StreetAddress
            return 128;
         case 10:
            // X520.Organization
            return 64;
         case 11:
            // X520.OrganizationalUnit
            return 64;
         case 12:
            // X520.Title
            return 64;
         case 42:
            // X520.GivenName
            return 16;
         case 43:
            // X520.Initials
            return 5;
         case 44:
            // X520.GenerationalQualifier
            return 3;
         case 46:
            // X520.DNQualifier
            return 64;
         case 65:
            // X520.Pseudonym
            return 128;
         default:
            return 0;
      }
   }
 
   // NOLINTEND(*-branch-clone)
 
   return 0;
}

References Botan::is_sub_element_of().

Referenced by Botan::PKIX::check_chain().

◆ parse()

std::optional< X509_DN > Botan::X509_DN::parse ( std::string_view str )

static

Parse the string representation of a distinguished name.

The grammar accepted is a subset of RFC 4514 Section 3, but also accepts quoted-value forms ala RFC 2253. The entire input must be consumed.

Parameters

str	the string to parse

Returns: the parsed DN, or nullopt if str is not a well-formed DN

Definition at line 554 of file x509_dn.cpp.

                                                      {
   X509_DN dn;
 
   // AVAs accumulate here; a trailing '+' keeps the next AVA in the same
   // RDN, while a ',' (or end of input) flushes them as a single RDN.
   std::vector<std::pair<OID, ASN1_String>> pending_rdn;
 
   // Separator that ended the previous AVA. A ',' or '+' still pending after the
   // loop means the input ended with a separator and no AVA to follow it.
   char terminator = '\0';
 
   size_t pos = 0;
   while(pos < str.size()) {
      // Whitespace separating an attributeType from the preceding ',' or '+'
      // is tolerated even though RFC 4514 does not produce it.
      while(pos < str.size() && is_space(str[pos])) {
         ++pos;
      }
      if(pos == str.size()) {
         break;
      }
 
      // attributeType, terminated by '='
      const size_t type_start = pos;
      while(pos < str.size() && str[pos] != '=' && !is_space(str[pos])) {
         ++pos;
      }
      const std::string_view type = str.substr(type_start, pos - type_start);
      if(type.empty() || pos == str.size() || str[pos] != '=') {
         return std::nullopt;
      }
      ++pos;  // consume '='
 
      /*
      attributeValue, in RFC 4514 <string> form plus the legacy quoted form.
      value_len tracks the length up to the last significant octet: leading and
      trailing unescaped whitespace is not significant unless it was escaped or
      quoted, so trailing whitespace is dropped by the final resize.
      */
      std::string value;
      size_t value_len = 0;
 
      // The legacy quoted form wraps the whole value: a quote is only an opening
      // quote at the start of the value, and nothing but trailing whitespace or a
      // separator may follow the closing quote.
      enum class Quote : uint8_t { None, Open, Closed };
      Quote quote = Quote::None;
 
      terminator = '\0';
 
      while(pos < str.size()) {
         const char c = str[pos];
 
         if(c == '"') {
            if(quote == Quote::Open) {
               quote = Quote::Closed;
            } else if(quote == Quote::None && value.empty()) {
               quote = Quote::Open;
            } else {
               return std::nullopt;  // quote in mid-value or after the closing quote
            }
            ++pos;
         } else if(c == '\\') {
            if(quote == Quote::Closed) {
               return std::nullopt;  // escape after the closing quote
            }
            // pair = ESC ( ESC / special / hexpair )
            ++pos;
            if(pos == str.size()) {
               return std::nullopt;
            }
            if(const auto hi = hex_digit_value(str[pos])) {
               const auto lo = (pos + 1 < str.size()) ? hex_digit_value(str[pos + 1]) : std::nullopt;
               if(!lo) {
                  return std::nullopt;
               }
               value.push_back(static_cast<char>((*hi << 4) | *lo));
               pos += 2;
            } else if(is_escapable_char(str[pos])) {
               value.push_back(str[pos]);
               ++pos;
            } else {
               return std::nullopt;  // not ESC / special / hexpair
            }
            value_len = value.size();  // an escaped octet is always significant
         } else if((c == ',' || c == '+') && quote != Quote::Open) {
            terminator = c;
            ++pos;
            break;
         } else if(quote == Quote::Closed) {
            if(!is_space(c)) {
               return std::nullopt;  // content after the closing quote
            }
            ++pos;  // trailing whitespace after the closing quote is insignificant
         } else if(quote != Quote::Open && is_unescaped_special_value_char(c)) {
            return std::nullopt;
         } else {
            ++pos;
            if(is_space(c) && quote != Quote::Open) {
               // Keep interior whitespace only if more content follows; skip it
               // entirely while leading (value is still empty)
               if(!value.empty()) {
                  value.push_back(c);
               }
            } else {
               value.push_back(c);
               value_len = value.size();
            }
         }
      }
 
      if(quote == Quote::Open) {
         return std::nullopt;  // unterminated quoted value
      }
      value.resize(value_len);  // strip trailing unescaped whitespace
 
      try {
         OID oid = OID::from_string(deref_info_field(type));
         // ASN1_String rejects values (e.g. a \FF hexpair) that are not valid
         // for any supported string encoding.
         pending_rdn.emplace_back(std::move(oid), ASN1_String(value));
      } catch(const Exception&) {
         return std::nullopt;  // unknown attributeType or invalid attributeValue
      }
 
      if(terminator != '+') {
         dn.add_rdn(std::move(pending_rdn));
         pending_rdn.clear();
      }
   }
 
   // A trailing ',' or '+' leaves an RDN/AVA with nothing to follow it
   if(terminator == ',' || terminator == '+') {
      return std::nullopt;
   }
   return dn;
}

References add_rdn(), deref_info_field(), Botan::OID::from_string(), Botan::None, and X509_DN().

Referenced by Botan::AlternativeName::add_attribute(), and Botan::operator>>().

◆ rdns()

const std::vector< std::vector< std::pair< OID, ASN1_String > > > & Botan::X509_DN::rdns ( ) const

inline

Return the DN as a sequence of RDNs. Each RDN is an X.501 SET OF AttributeTypeAndValue; the inner vector preserves the decoded order but RDN equality is set-based per RFC 5280 7.1.

Definition at line 229 of file pkix_types.h.

229{ return m_rdn; }

Referenced by Botan::PKIX::check_chain(), decode_from(), and Botan::operator<<().

◆ to_string()

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

Definition at line 485 of file x509_dn.cpp.

                                   {
   std::ostringstream out;
   out << *this;
   return out.str();
}

Referenced by Botan::Flatfile_Certificate_Store::Flatfile_Certificate_Store().

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

src/lib/x509/pkix_types.h
src/lib/x509/x509_dn.cpp
src/lib/x509/x509_dn_ub.cpp

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ X509_DN() [1/4]

◆ X509_DN() [2/4]

◆ X509_DN() [3/4]

◆ X509_DN() [4/4]

Member Function Documentation

◆ _canonical_bytes()

◆ add_attribute() [1/3]

◆ add_attribute() [2/3]

◆ add_attribute() [3/3]

◆ add_rdn()

◆ BER_encode()

◆ contents()

◆ count()

◆ decode_from()

◆ DER_encode()

◆ deref_info_field()

◆ dn_info()

◆ empty()

◆ encode_into()

◆ get_attribute()

◆ get_attributes()

◆ get_bits()

◆ get_first_attribute() [1/2]

◆ get_first_attribute() [2/2]

◆ has_field() [1/2]

◆ has_field() [2/2]

◆ lookup_ub()

◆ parse()

◆ rdns()

◆ to_string()