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

#include <pkix_types.h>

Inheritance diagram for Botan::X509_DN:
Botan::ASN1_Object

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.

161 {
162 for(const auto& i : args) {
163 add_attribute(i.first, i.second);
164 }
165 }
void add_attribute(std::string_view key, std::string_view val)
Definition x509_dn.cpp:184

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.

172 {
173 for(const auto& i : args) {
174 add_attribute(i.first, i.second);
175 }
176 }

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.

183 {
184 for(const auto& i : args) {
185 add_attribute(i.first, i.second);
186 }
187 }

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 191 of file x509_dn.cpp.

191 {
192 if(str.empty()) {
193 return;
194 }
195
196 // Each programmatic add appends a new single-AVA RDN.
197 add_rdn({std::make_pair(oid, str)});
198}
void add_rdn(std::vector< std::pair< OID, ASN1_String > > rdn)
Definition x509_dn.cpp:200

References add_rdn(), and 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 184 of file x509_dn.cpp.

184 {
186}
static OID from_string(std::string_view str)
Definition asn1_oid.cpp:80

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 200 of file x509_dn.cpp.

200 {
201 if(rdn.empty()) {
202 return;
203 }
204 append_canonical_rdn(m_canonical_dn_bits, rdn);
205 m_rdn.push_back(std::move(rdn));
206 m_dn_bits.clear();
207}

Referenced by add_attribute(), 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.

21 {
22 std::vector<uint8_t> output;
23 DER_Encoder der(output);
24 this->encode_into(der);
25 return output;
26}
virtual void encode_into(DER_Encoder &to) const =0

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 236 of file x509_dn.cpp.

236 {
237 std::multimap<std::string, std::string> retval;
238
239 for(const auto& rdn : m_rdn) {
240 for(const auto& ava : rdn) {
241 retval.emplace(ava.first.to_formatted_string(), ava.second.value());
242 }
243 }
244 return retval;
245}

◆ 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
fromthe BER_Decoder that will be read from

Implements Botan::ASN1_Object.

Definition at line 405 of file x509_dn.cpp.

405 {
406 std::vector<uint8_t> bits;
407
408 source.start_sequence().raw_bytes(bits).end_cons();
409
410 BER_Decoder sequence(bits, source.limits());
411
412 std::vector<std::vector<std::pair<OID, ASN1_String>>> rdns;
413
414 // Cap AVAs per RDN to bound work for downstream set-based matching.
415 // No legitimate cert has anywhere near this many AVAs in a single RDN.
416 constexpr size_t MAX_AVAS_PER_RDN = 32;
417
418 while(sequence.more_items()) {
419 BER_Decoder rdn_decoder = sequence.start_set();
420
421 std::vector<std::pair<OID, ASN1_String>> rdn;
422 while(rdn_decoder.more_items()) {
423 OID oid;
424 ASN1_String str;
425
426 rdn_decoder.start_sequence()
427 .decode(oid)
428 .decode(str) // TODO support Any
429 .end_cons();
430
431 rdn.emplace_back(std::move(oid), std::move(str));
432
433 if(rdn.size() > MAX_AVAS_PER_RDN) {
434 throw Decoding_Error("X.500 RDN has too many attribute-value assertions");
435 }
436 }
437
438 /*
439 RFC 5280 4.1.2.4:
440 RelativeDistinguishedName ::=
441 SET SIZE (1..MAX) OF AttributeTypeAndValue
442 */
443 if(rdn.empty()) {
444 throw Decoding_Error("X.500 RDN must contain at least one attribute-value assertion");
445 }
446 rdns.push_back(std::move(rdn));
447 }
448
449 auto canonical_bits = canonicalize_dn(rdns);
450
451 m_rdn = std::move(rdns);
452 m_dn_bits = std::move(bits);
453 m_canonical_dn_bits = std::move(canonical_bits);
454}
const std::vector< std::vector< std::pair< OID, ASN1_String > > > & rdns() const
Definition pkix_types.h:229

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 370 of file x509_dn.cpp.

370 {
371 std::vector<uint8_t> result;
372 DER_Encoder der(result);
373 this->encode_into(der);
374 return result;
375}
void encode_into(DER_Encoder &to) const override
Definition x509_dn.cpp:380

References encode_into().

◆ deref_info_field()

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

Definition at line 309 of file x509_dn.cpp.

309 {
310 if(info == "Name" || info == "CommonName" || info == "CN") {
311 return "X520.CommonName";
312 }
313 if(info == "SerialNumber" || info == "SN") {
314 return "X520.SerialNumber";
315 }
316 if(info == "Country" || info == "C") {
317 return "X520.Country";
318 }
319 if(info == "Organization" || info == "O") {
320 return "X520.Organization";
321 }
322 if(info == "Organizational Unit" || info == "OrgUnit" || info == "OU") {
323 return "X520.OrganizationalUnit";
324 }
325 if(info == "Locality" || info == "L") {
326 return "X520.Locality";
327 }
328 if(info == "State" || info == "Province" || info == "ST") {
329 return "X520.State";
330 }
331 if(info == "Email") {
332 return "RFC822";
333 }
334 return std::string(info);
335}

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 209 of file x509_dn.cpp.

209 {
210 std::vector<std::pair<OID, ASN1_String>> flat;
211 for(const auto& rdn : m_rdn) {
212 for(const auto& ava : rdn) {
213 flat.push_back(ava);
214 }
215 }
216 return flat;
217}

◆ 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
tothe DER_Encoder that will be written to

Implements Botan::ASN1_Object.

Definition at line 380 of file x509_dn.cpp.

380 {
381 der.start_sequence();
382
383 if(!m_dn_bits.empty()) {
384 /*
385 If we decoded this from somewhere, encode it back exactly as
386 we received it
387 */
388 der.raw_bytes(m_dn_bits);
389 } else {
390 for(const auto& rdn : m_rdn) {
391 der.start_set();
392 for(const auto& ava : rdn) {
393 der.start_sequence().encode(ava.first).encode(ava.second).end_cons();
394 }
395 der.end_cons();
396 }
397 }
398
399 der.end_cons();
400}

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 290 of file x509_dn.cpp.

290 {
291 const OID oid = OID::from_string(deref_info_field(attr));
292
293 std::vector<std::string> values;
294
295 for(const auto& rdn : m_rdn) {
296 for(const auto& ava : rdn) {
297 if(ava.first == oid) {
298 values.push_back(ava.second.value());
299 }
300 }
301 }
302
303 return values;
304}
static std::string deref_info_field(std::string_view key)
Definition x509_dn.cpp:309

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 222 of file x509_dn.cpp.

222 {
223 std::multimap<OID, std::string> retval;
224
225 for(const auto& rdn : m_rdn) {
226 for(const auto& ava : rdn) {
227 retval.emplace(ava.first, ava.second.value());
228 }
229 }
230 return retval;
231}

◆ 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; }

◆ get_first_attribute() [1/2]

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

Definition at line 275 of file x509_dn.cpp.

275 {
276 for(const auto& rdn : m_rdn) {
277 for(const auto& ava : rdn) {
278 if(ava.first == oid) {
279 return ava.second;
280 }
281 }
282 }
283
284 return ASN1_String();
285}

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 270 of file x509_dn.cpp.

270 {
271 const OID oid = OID::from_string(deref_info_field(attr));
272 return get_first_attribute(oid).value();
273}
const std::string & value() const
Definition asn1_obj.h:590
ASN1_String get_first_attribute(const OID &oid) const
Definition x509_dn.cpp:275

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 258 of file x509_dn.cpp.

258 {
259 for(const auto& rdn : m_rdn) {
260 for(const auto& ava : rdn) {
261 if(ava.first == oid) {
262 return true;
263 }
264 }
265 }
266
267 return false;
268}

Referenced by has_field().

◆ has_field() [2/2]

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

Definition at line 247 of file x509_dn.cpp.

247 {
248 try {
249 const OID o = OID::from_string(deref_info_field(attr));
250 if(o.has_value()) {
251 return has_field(o);
252 }
253 } catch(Lookup_Error&) {}
254
255 return false;
256}
bool has_field(const OID &oid) const
Definition x509_dn.cpp:258

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
oidthe 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.

16 {
17 /*
18 * See RFC 5280 Appendix A.1 starting with comment "-- Upper Bounds"
19 */
20
21 // NOLINTBEGIN(*-branch-clone)
22 if(auto iso_dn = is_sub_element_of(oid, {2, 5, 4})) {
23 switch(*iso_dn) {
24 case 3:
25 // X520.CommonName
26 return 64;
27 case 4:
28 // X520.Surname
29 return 40;
30 case 5:
31 // X520.SerialNumber
32 return 64;
33 case 6:
34 // X520.Country
35 return 3;
36 case 7:
37 // X520.Locality
38 return 128;
39 case 8:
40 // X520.State
41 return 128;
42 case 9:
43 // X520.StreetAddress
44 return 128;
45 case 10:
46 // X520.Organization
47 return 64;
48 case 11:
49 // X520.OrganizationalUnit
50 return 64;
51 case 12:
52 // X520.Title
53 return 64;
54 case 42:
55 // X520.GivenName
56 return 16;
57 case 43:
58 // X520.Initials
59 return 5;
60 case 44:
61 // X520.GenerationalQualifier
62 return 3;
63 case 46:
64 // X520.DNQualifier
65 return 64;
66 case 65:
67 // X520.Pseudonym
68 return 128;
69 default:
70 return 0;
71 }
72 }
73
74 // NOLINTEND(*-branch-clone)
75
76 return 0;
77}
std::optional< uint32_t > is_sub_element_of(const OID &oid, std::initializer_list< uint32_t > prefix)
Definition x509_utils.h:22

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
strthe string to parse
Returns
the parsed DN, or nullopt if str is not a well-formed DN

Definition at line 551 of file x509_dn.cpp.

551 {
552 X509_DN dn;
553
554 // AVAs accumulate here; a trailing '+' keeps the next AVA in the same
555 // RDN, while a ',' (or end of input) flushes them as a single RDN.
556 std::vector<std::pair<OID, ASN1_String>> pending_rdn;
557
558 // Separator that ended the previous AVA. A ',' or '+' still pending after the
559 // loop means the input ended with a separator and no AVA to follow it.
560 char terminator = '\0';
561
562 size_t pos = 0;
563 while(pos < str.size()) {
564 // Whitespace separating an attributeType from the preceding ',' or '+'
565 // is tolerated even though RFC 4514 does not produce it.
566 while(pos < str.size() && is_space(str[pos])) {
567 ++pos;
568 }
569 if(pos == str.size()) {
570 break;
571 }
572
573 // attributeType, terminated by '='
574 const size_t type_start = pos;
575 while(pos < str.size() && str[pos] != '=' && !is_space(str[pos])) {
576 ++pos;
577 }
578 const std::string_view type = str.substr(type_start, pos - type_start);
579 if(type.empty() || pos == str.size() || str[pos] != '=') {
580 return std::nullopt;
581 }
582 ++pos; // consume '='
583
584 /*
585 attributeValue, in RFC 4514 <string> form plus the legacy quoted form.
586 value_len tracks the length up to the last significant octet: leading and
587 trailing unescaped whitespace is not significant unless it was escaped or
588 quoted, so trailing whitespace is dropped by the final resize.
589 */
590 std::string value;
591 size_t value_len = 0;
592
593 // The legacy quoted form wraps the whole value: a quote is only an opening
594 // quote at the start of the value, and nothing but trailing whitespace or a
595 // separator may follow the closing quote.
596 enum class Quote : uint8_t { None, Open, Closed };
597 Quote quote = Quote::None;
598
599 terminator = '\0';
600
601 while(pos < str.size()) {
602 const char c = str[pos];
603
604 if(c == '"') {
605 if(quote == Quote::Open) {
606 quote = Quote::Closed;
607 } else if(quote == Quote::None && value.empty()) {
608 quote = Quote::Open;
609 } else {
610 return std::nullopt; // quote in mid-value or after the closing quote
611 }
612 ++pos;
613 } else if(c == '\\') {
614 if(quote == Quote::Closed) {
615 return std::nullopt; // escape after the closing quote
616 }
617 // pair = ESC ( ESC / special / hexpair )
618 ++pos;
619 if(pos == str.size()) {
620 return std::nullopt;
621 }
622 if(const auto hi = hex_digit_value(str[pos])) {
623 const auto lo = (pos + 1 < str.size()) ? hex_digit_value(str[pos + 1]) : std::nullopt;
624 if(!lo) {
625 return std::nullopt;
626 }
627 value.push_back(static_cast<char>((*hi << 4) | *lo));
628 pos += 2;
629 } else if(is_escapable_char(str[pos])) {
630 value.push_back(str[pos]);
631 ++pos;
632 } else {
633 return std::nullopt; // not ESC / special / hexpair
634 }
635 value_len = value.size(); // an escaped octet is always significant
636 } else if((c == ',' || c == '+') && quote != Quote::Open) {
637 terminator = c;
638 ++pos;
639 break;
640 } else if(quote == Quote::Closed) {
641 if(!is_space(c)) {
642 return std::nullopt; // content after the closing quote
643 }
644 ++pos; // trailing whitespace after the closing quote is insignificant
645 } else if(quote != Quote::Open && is_unescaped_special_value_char(c)) {
646 return std::nullopt;
647 } else {
648 ++pos;
649 if(is_space(c) && quote != Quote::Open) {
650 // Keep interior whitespace only if more content follows; skip it
651 // entirely while leading (value is still empty)
652 if(!value.empty()) {
653 value.push_back(c);
654 }
655 } else {
656 value.push_back(c);
657 value_len = value.size();
658 }
659 }
660 }
661
662 if(quote == Quote::Open) {
663 return std::nullopt; // unterminated quoted value
664 }
665 value.resize(value_len); // strip trailing unescaped whitespace
666
667 try {
668 OID oid = OID::from_string(deref_info_field(type));
669 // ASN1_String rejects values (e.g. a \FF hexpair) that are not valid
670 // for any supported string encoding.
671 pending_rdn.emplace_back(std::move(oid), ASN1_String(value));
672 } catch(const Exception&) {
673 return std::nullopt; // unknown attributeType or invalid attributeValue
674 }
675
676 if(terminator != '+') {
677 dn.add_rdn(std::move(pending_rdn));
678 pending_rdn.clear();
679 }
680 }
681
682 // A trailing ',' or '+' leaves an RDN/AVA with nothing to follow it
683 if(terminator == ',' || terminator == '+') {
684 return std::nullopt;
685 }
686 return dn;
687}
X509_DN()=default

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 482 of file x509_dn.cpp.

482 {
483 std::ostringstream out;
484 out << *this;
485 return out.str();
486}

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


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