Name Constraints. More...

#include <pkix_types.h>

Public Member Functions
const std::vector< GeneralSubtree > &	excluded () const
bool	is_excluded (const X509_Certificate &cert, bool reject_unknown) const
bool	is_permitted (const X509_Certificate &cert, bool reject_unknown) const
	NameConstraints ()=default
	NameConstraints (std::vector< GeneralSubtree > &&permitted_subtrees, std::vector< GeneralSubtree > &&excluded_subtrees)
const std::vector< GeneralSubtree > &	permitted () const

Detailed Description

Name Constraints.

Wraps the Name Constraints associated with a certificate.

Definition at line 750 of file pkix_types.h.

Constructor & Destructor Documentation

◆ NameConstraints() [1/2]

Botan::NameConstraints::NameConstraints ( )

default

Creates an empty name NameConstraints.

References NameConstraints().

Referenced by NameConstraints().

◆ NameConstraints() [2/2]

Botan::NameConstraints::NameConstraints	(	std::vector< GeneralSubtree > &&	permitted_subtrees,
		std::vector< GeneralSubtree > &&	excluded_subtrees )

Creates NameConstraints from a list of permitted and excluded subtrees.

Parameters

permitted_subtrees	names for which the certificate is permitted
excluded_subtrees	names for which the certificate is not permitted

Definition at line 832 of file name_constraint.cpp.

                                                                                :
      m_permitted_subtrees(std::move(permitted_subtrees)), m_excluded_subtrees(std::move(excluded_subtrees)) {
   for(const auto& c : m_permitted_subtrees) {
      m_permitted_name_types.insert(c.base().type_code());
   }
   for(const auto& c : m_excluded_subtrees) {
      m_excluded_name_types.insert(c.base().type_code());
   }
}

Member Function Documentation

◆ excluded()

const std::vector< GeneralSubtree > & Botan::NameConstraints::excluded ( ) const

inline

Returns: excluded names

Definition at line 775 of file pkix_types.h.

                                                                                                      {
         return m_excluded_subtrees;
      }

References excluded().

Referenced by botan_x509_cert_excluded_name_constraints(), excluded(), and is_excluded().

◆ is_excluded()

bool Botan::NameConstraints::is_excluded	(	const X509_Certificate &	cert,
		bool	reject_unknown ) const

Return true if any of the names in the certificate are excluded

Definition at line 1135 of file name_constraint.cpp.

                                                                                         {
   if(excluded().empty()) {
      return false;
   }
 
   const auto& alt_name = cert.subject_alt_name();
 
   if(exceeds_limit(cert.subject_dn().count(), alt_name.count(), excluded().size())) {
      return true;
   }
 
   if(reject_unknown) {
      // This is one is overly broad: we should just reject if there is a name constraint
      // with the same OID as one of the other names
      if(m_excluded_name_types.contains(GeneralName::NameType::Other) && !alt_name.other_name_values().empty()) {
         return true;
      }
      // As in is_permitted: a critical NC restricting an unrecognized
      // GeneralName form cannot be evaluated; reject conservatively.
      if(m_excluded_name_types.contains(GeneralName::NameType::Unknown)) {
         return true;
      }
   }
 
   auto is_excluded_dn = [&](const X509_DN& dn) {
      // If no restrictions, then immediate accept
      if(!m_excluded_name_types.contains(GeneralName::NameType::DN)) {
         return false;
      }
 
      for(const auto& c : m_excluded_subtrees) {
         if(c.base().matches_dn(dn)) {
            return true;
         }
      }
 
      // There is at least one excluded name and we didn't match
      return false;
   };
 
   auto is_excluded_dns_name = [&](const DNSName& name) {
      // If no restrictions, then immediate accept
      if(!m_excluded_name_types.contains(GeneralName::NameType::DNS)) {
         return false;
      }
 
      for(const auto& c : m_excluded_subtrees) {
         if(c.base().matches_dns(name)) {
            return true;
         }
 
         /*
         RFC 5280 4.2.1.10:
            Any name matching a restriction in the excludedSubtrees
            field is invalid regardless of information appearing in
            the permittedSubtrees.
 
         If the cert has a wildcard SAN (*.example.com), and that wildcard
         could be matched against an excluded name, it must be rejected.
         */
         if(c.base().m_type == GeneralName::NameType::DNS && name.is_wildcard()) {
            const auto& constraint = std::get<GeneralName::DNSConstraint>(c.base().m_name).value();
            if(wildcard_intersects_excluded_dns_subtree(name.to_string(), constraint)) {
               return true;
            }
         }
      }
 
      // There is at least one excluded name and we didn't match
      return false;
   };
 
   auto is_excluded_ipv4 = [&](const IPv4Address& ipv4) {
      if(m_excluded_name_types.contains(GeneralName::NameType::IPv4)) {
         for(const auto& c : m_excluded_subtrees) {
            if(c.base().matches_ipv4(ipv4)) {
               return true;
            }
         }
      }
 
      // This name did not match any of the excluded names
      return false;
   };
 
   auto is_excluded_ipv6 = [&](const IPv6Address& ipv6) {
      if(m_excluded_name_types.contains(GeneralName::NameType::IPv6)) {
         for(const auto& c : m_excluded_subtrees) {
            if(c.base().matches_ipv6(ipv6)) {
               return true;
            }
         }
      }
 
      // An IPv4-mapped IPv6 address names an IPv4 address so verify that
      // address is not restricted by an IPv4 excludes rule
      if(m_excluded_name_types.contains(GeneralName::NameType::IPv4)) {
         if(auto embedded_v4 = ipv6.as_ipv4()) {
            for(const auto& c : m_excluded_subtrees) {
               if(c.base().matches_ipv4(*embedded_v4)) {
                  return true;
               }
            }
         }
      }
 
      // This name did not match any of the excluded names
      return false;
   };
 
   auto is_excluded_uri = [&](const URI& uri) {
      if(!m_excluded_name_types.contains(GeneralName::NameType::URI)) {
         return false;
      }
      /*
      RFC 5280 4.2.1.10:
         If a constraint is applied to the uniformResourceIdentifier
         name form and a subsequent certificate includes a
         subjectAltName extension with a uniformResourceIdentifier that
         does not include an authority component with a host name
         specified as a fully qualified domain name (e.g., if the URI
         either does not include an authority component or includes an
         authority component in which the host name is specified as an
         IP address), then the application MUST reject the certificate.
      */
      const auto host = uri.host();
      if(!host.has_value() || !std::holds_alternative<DNSName>(host->get())) {
         return true;
      }
      if(std::get<DNSName>(host->get()).to_string().find('.') == std::string::npos) {
         return true;
      }
      for(const auto& c : m_excluded_subtrees) {
         if(c.base().matches_uri(uri)) {
            return true;
         }
      }
      return false;
   };
 
   /*
   * The email matching logic on the exclude side is intentionally stricter
   * (more expansive) than the permit side logic.
   *
   * RFC 9549 updates RFC 5280 and among other things completely removes mailbox
   * form constraints (ones with a '@', rather than just a domain constraint)
   * claiming "This capability was not used".
   *
   * This prohibition is reiterated in RFC 9598 Section 6 with "rfc822Name
   * constraints with a Local-part SHOULD NOT be used."
   *
   * Here we lean very conservative in our interpretation: if there is a
   * mailbox-form exclude constraint, we reject any mailbox at that domain. That
   * is, if excludedSubtrees includes "user@example.com", we treat that
   * constraint identically to an exclusion of "example.com".
   *
   * This might be overly cautious, but generally a rejects-valid bug gets you a
   * prompt bug report with testcase, while an accepts-invalid eventually gets
   * you a surprise CVE.
   */
   auto mailbox_form_constraint_covers_domain = [](const GeneralName& gn, const DNSName& san_domain) {
      if(gn.type_code() != GeneralName::NameType::RFC822) {
         return false;
      }
      const auto& constraint = std::get<GeneralName::EmailConstraint>(gn.m_name).value();
      const auto at = constraint.find('@');
      return at != std::string::npos && san_domain.to_string() == constraint.substr(at + 1);
   };
 
   auto is_excluded_email = [&](const EmailAddress& addr) {
      if(m_excluded_name_types.contains(GeneralName::NameType::RFC822)) {
         for(const auto& c : m_excluded_subtrees) {
            if(c.base().matches_email(addr)) {
               return true;
            }
            /*
            If we were strictly following RFC 9549 we would here want to call
            mailbox_form_constraint_covers_domain, but this breaks chains which
            are in conformance to the specifications prior to 9549.
            */
         }
      }
      return false;
   };
 
   // RFC 9598 Section 6: rfc822Name name constraints also apply to
   // SmtpUTF8Mailbox SAN entries. See is_permitted_smtp_utf8.
   auto is_excluded_smtp_utf8 = [&](const SmtpUtf8Mailbox& mailbox) {
      if(m_excluded_name_types.contains(GeneralName::NameType::RFC822)) {
         for(const auto& c : m_excluded_subtrees) {
            if(c.base().matches_email(mailbox)) {
               return true;
            }
            if(mailbox_form_constraint_covers_domain(c.base(), mailbox.domain())) {
               return true;
            }
         }
      }
      return false;
   };
 
   if(is_excluded_dn(cert.subject_dn())) {
      return true;
   }
 
   for(const auto& alt_dn : alt_name.directory_names()) {
      if(is_excluded_dn(alt_dn)) {
         return true;
      }
   }
 
   for(const auto& alt_dns : alt_name.dns_names()) {
      if(is_excluded_dns_name(alt_dns)) {
         return true;
      }
   }
 
   for(const auto& alt_ipv4 : alt_name.ipv4_addresses()) {
      if(is_excluded_ipv4(alt_ipv4)) {
         return true;
      }
   }
 
   for(const auto& alt_ipv6 : alt_name.ipv6_addresses()) {
      if(is_excluded_ipv6(alt_ipv6)) {
         return true;
      }
   }
 
   for(const auto& uri : alt_name.uri_names()) {
      if(is_excluded_uri(uri)) {
         return true;
      }
   }
 
   for(const auto& addr : alt_name.email_addresses()) {
      if(is_excluded_email(addr)) {
         return true;
      }
   }
 
   for(const auto& mailbox : alt_name.smtp_utf8_mailboxes()) {
      if(is_excluded_smtp_utf8(mailbox)) {
         return true;
      }
   }
 
   // TODO(Botan4): CN fallback is deprecated for removal in Botan4.
   if(alt_name.is_empty()) {
      for(const auto& cn : cert.subject_info("Name")) {
         if(auto ipv4 = IPv4Address::from_string(cn)) {
            if(is_excluded_ipv4(*ipv4)) {
               return true;
            }
         } else if(cn.find('.') != std::string::npos) {
            if(auto dns_form = DNSName::from_san_string(cn)) {
               if(is_excluded_dns_name(*dns_form)) {
                  return true;
               }
            }
         }
      }
 
      // RFC 5280 4.2.1.10 fallback to subject DN emailAddress when the cert has no SAN
      for(const auto& email_str : cert.subject_dn().get_attribute("PKCS9.EmailAddress")) {
         if(auto addr = EmailAddress::from_string(email_str)) {
            if(is_excluded_email(*addr)) {
               return true;
            }
         } else if(m_excluded_name_types.contains(GeneralName::NameType::RFC822)) {
            return true;
         }
      }
   }
 
   // We didn't encounter a name that matched any prohibited name
   return false;
}

◆ is_permitted()

bool Botan::NameConstraints::is_permitted	(	const X509_Certificate &	cert,
		bool	reject_unknown ) const

Return true if all of the names in the certificate are permitted

Definition at line 864 of file name_constraint.cpp.

                                                                                          {
   if(permitted().empty()) {
      return true;
   }
 
   const auto& alt_name = cert.subject_alt_name();
 
   if(exceeds_limit(cert.subject_dn().count(), alt_name.count(), permitted().size())) {
      return false;
   }
 
   if(reject_unknown) {
      /* A critical NC restricting an unrecognized GeneralName form (e.g. x400Address)
      * causes immediate rejection.
      *
      * RFC 5280 4.2.1.10 leaves this both unspecified
      *   The syntax and semantics for name constraints for otherName, ediPartyName, and
      *   registeredID are not defined by this specification
      * and discouraged
      *    Conforming CAs [...] SHOULD NOT impose name constraints on the x400Address,
      *    ediPartyName, or registeredID name forms.
      *
      * In principle we should only reject when the constrained form appears in the
      * certificate. But this situation in general seems to be a minefield, with no help
      * from specs, test suites, etc. Lacking any obvious use case, just fail closed.
      *
      * If you happen to hit this with a real chain, open an issue.
      */
      if(m_permitted_name_types.contains(GeneralName::NameType::Unknown)) {
         return false;
      }
      if(m_permitted_name_types.contains(GeneralName::NameType::Other) && !alt_name.other_name_values().empty()) {
         return false;
      }
   }
 
   auto is_permitted_dn = [&](const X509_DN& dn) {
      // If no restrictions, then immediate accept
      if(!m_permitted_name_types.contains(GeneralName::NameType::DN)) {
         return true;
      }
 
      for(const auto& c : m_permitted_subtrees) {
         if(c.base().matches_dn(dn)) {
            return true;
         }
      }
 
      // There is at least one permitted name and we didn't match
      return false;
   };
 
   auto is_permitted_dns_name = [&](const DNSName& name) {
      // If no restrictions, then immediate accept
      if(!m_permitted_name_types.contains(GeneralName::NameType::DNS)) {
         return true;
      }
 
      for(const auto& c : m_permitted_subtrees) {
         if(c.base().matches_dns(name)) {
            return true;
         }
      }
 
      // There is at least one permitted name and we didn't match
      return false;
   };
 
   /*
   RFC 5280 4.2.1.10: iPAddress is a single GeneralName element where
   IPv4 and IPv6 are distinguished only by the length.
 
   An iPAddress subtree of either version therefore restricts the iPAddress name
   form for both versions.
   */
   const bool ip_form_restricted = m_permitted_name_types.contains(GeneralName::NameType::IPv4) ||
                                   m_permitted_name_types.contains(GeneralName::NameType::IPv6);
 
   auto is_permitted_ipv4 = [&](const IPv4Address& ipv4) {
      if(!ip_form_restricted) {
         return true;
      }
 
      for(const auto& c : m_permitted_subtrees) {
         if(c.base().matches_ipv4(ipv4)) {
            return true;
         }
      }
 
      // We might here check if there are any IPv6 permitted names which are
      // mapped IPv4 addresses, and if so check if any of those apply. It's not
      // clear if this is desirable, and RFC 5280 is completely silent on the issue.
 
      // There is at least one permitted iPAddress name and we didn't match
      return false;
   };
 
   auto is_permitted_ipv6 = [&](const IPv6Address& ipv6) {
      if(!ip_form_restricted) {
         return true;
      }
 
      for(const auto& c : m_permitted_subtrees) {
         if(c.base().matches_ipv6(ipv6)) {
            return true;
         }
      }
 
      // There is at least one permitted iPAddress name and we didn't match
      return false;
   };
 
   auto is_permitted_uri = [&](const URI& uri) {
      // If no URI restrictions, accept.
      if(!m_permitted_name_types.contains(GeneralName::NameType::URI)) {
         return true;
      }
      /*
      RFC 5280 4.2.1.10:
         If a constraint is applied to the uniformResourceIdentifier
         name form and a subsequent certificate includes a
         subjectAltName extension with a uniformResourceIdentifier that
         does not include an authority component with a host name
         specified as a fully qualified domain name (e.g., if the URI
         either does not include an authority component or includes an
         authority component in which the host name is specified as an
         IP address), then the application MUST reject the certificate.
      */
      const auto host = uri.host();
      if(!host.has_value() || !std::holds_alternative<DNSName>(host->get())) {
         return false;
      }
      if(std::get<DNSName>(host->get()).to_string().find('.') == std::string::npos) {
         return false;
      }
      for(const auto& c : m_permitted_subtrees) {
         if(c.base().matches_uri(uri)) {
            return true;
         }
      }
      return false;
   };
 
   auto is_permitted_email = [&](const EmailAddress& addr) {
      // If no email restrictions, accept.
      if(!m_permitted_name_types.contains(GeneralName::NameType::RFC822)) {
         return true;
      }
      for(const auto& c : m_permitted_subtrees) {
         if(c.base().matches_email(addr)) {
            return true;
         }
      }
      return false;
   };
 
   // RFC 9598 Section 6 extends rfc822Name name constraints to SmtpUTF8Mailbox
   // SAN entries (id-on-SmtpUTF8Mailbox otherNames). When rfc822Name
   // constraints are in effect, every SmtpUTF8Mailbox SAN must match
   // at least one permitted entry.
   auto is_permitted_smtp_utf8 = [&](const SmtpUtf8Mailbox& mailbox) {
      if(!m_permitted_name_types.contains(GeneralName::NameType::RFC822)) {
         return true;
      }
      for(const auto& c : m_permitted_subtrees) {
         if(c.base().matches_email(mailbox)) {
            return true;
         }
      }
      return false;
   };
 
   /*
   RFC 5280 4.1.2.6:
      If subject naming information is present only in the
      subjectAltName extension (e.g., a key bound only to an email
      address or URI), then the subject name MUST be an empty
      sequence and the subjectAltName extension MUST be critical.
 
   RFC 5280 4.2.1.10:
      Restrictions of the form directoryName MUST be applied to the subject
      field in the certificate (when the certificate includes a non-empty
      subject field) and to any names of type directoryName in the
      subjectAltName extension.
   */
   if(!cert.subject_dn().empty() && !is_permitted_dn(cert.subject_dn())) {
      return false;
   }
 
   for(const auto& alt_dn : alt_name.directory_names()) {
      if(!is_permitted_dn(alt_dn)) {
         return false;
      }
   }
 
   for(const auto& alt_dns : alt_name.dns_names()) {
      if(!is_permitted_dns_name(alt_dns)) {
         return false;
      }
   }
 
   for(const auto& alt_ipv4 : alt_name.ipv4_addresses()) {
      if(!is_permitted_ipv4(alt_ipv4)) {
         return false;
      }
   }
 
   for(const auto& alt_ipv6 : alt_name.ipv6_addresses()) {
      if(!is_permitted_ipv6(alt_ipv6)) {
         return false;
      }
   }
 
   for(const auto& uri : alt_name.uri_names()) {
      if(!is_permitted_uri(uri)) {
         return false;
      }
   }
 
   for(const auto& addr : alt_name.email_addresses()) {
      if(!is_permitted_email(addr)) {
         return false;
      }
   }
 
   for(const auto& mailbox : alt_name.smtp_utf8_mailboxes()) {
      if(!is_permitted_smtp_utf8(mailbox)) {
         return false;
      }
   }
 
   // TODO(Botan4): CN fallback is deprecated for removal in Botan4.
   if(alt_name.is_empty()) {
      for(const auto& cn : cert.subject_info("CN")) {
         if(auto ipv4 = IPv4Address::from_string(cn)) {
            if(!is_permitted_ipv4(*ipv4)) {
               return false;
            }
         } else if(cn.find('.') != std::string::npos) {
            if(auto dns_form = DNSName::from_san_string(cn)) {
               if(!is_permitted_dns_name(*dns_form)) {
                  return false;
               }
            }
         }
      }
 
      /*
      RFC 5280 4.2.1.10:
         When constraints are imposed on the rfc822Name name form, but the
         certificate does not include a subject alternative name, the
         rfc822Name constraint MUST be applied to the attribute of type
         emailAddress in the subject distinguished name.
      */
      for(const auto& email_str : cert.subject_dn().get_attribute("PKCS9.EmailAddress")) {
         if(auto addr = EmailAddress::from_string(email_str)) {
            if(!is_permitted_email(*addr)) {
               return false;
            }
         } else if(m_permitted_name_types.contains(GeneralName::NameType::RFC822)) {
            // emailAddress is present but unparsable and an rfc822Name
            // constraint is in effect; treat as not permitted.
            return false;
         }
      }
   }
 
   // We didn't encounter a name that doesn't have a matching constraint
   return true;
}

◆ permitted()

const std::vector< GeneralSubtree > & Botan::NameConstraints::permitted ( ) const

inline

Returns: permitted names

Definition at line 768 of file pkix_types.h.

                                                                                                       {
         return m_permitted_subtrees;
      }

References permitted().

Referenced by botan_x509_cert_permitted_name_constraints(), is_permitted(), permitted(), and 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/name_constraint.cpp

Public Member Functions