1=pod 2 3=head1 NAME 4 5NAME_CONSTRAINTS_check, 6NAME_CONSTRAINTS_check_CN - check a certificate's names against a name 7constraints extension 8 9=head1 SYNOPSIS 10 11 #include <openssl/x509v3.h> 12 13 int NAME_CONSTRAINTS_check(const X509 *x, NAME_CONSTRAINTS *nc); 14 int NAME_CONSTRAINTS_check_CN(const X509 *x, NAME_CONSTRAINTS *nc); 15 16=head1 DESCRIPTION 17 18NAME_CONSTRAINTS_check() tests whether the names asserted by certificate 19I<x> satisfy the name constraints I<nc>. It implements the matching 20primitive of RFC 5280 section 4.2.1.10: given a constraint set (a 21B<NAME_CONSTRAINTS> structure containing zero or more B<permittedSubtrees> 22and B<excludedSubtrees>) and a candidate certificate, decide whether the 23certificate's names fall within the permitted subtrees and outside the 24excluded subtrees. 25 26The names considered by NAME_CONSTRAINTS_check() are: 27 28=over 4 29 30=item * 31 32The certificate's subject distinguished name, matched as a B<directoryName> 33general-name type. The subject is considered only when it is nonempty. 34 35=item * 36 37Each B<emailAddress> attribute appearing within the subject distinguished 38name, matched as an B<rfc822Name> general-name type. These attributes are 39the historical, pre-SAN way of expressing an email address in a 40certificate's subject, and RFC 5280 requires that they be subjected to 41name-constraint checking. 42 43=item * 44 45Each entry in the certificate's subject alternative name extension, matched 46according to its declared general-name type. 47 48=back 49 50NAME_CONSTRAINTS_check() implements matching for the following 51general-name types: B<directoryName>, B<dNSName>, B<rfc822Name>, 52B<uniformResourceIdentifier>, and B<iPAddress>. The B<otherName> form 53B<id-on-SmtpUTF8Mailbox> (RFC 8398) is additionally matched against 54B<rfc822Name> subtrees. Any other general-name type, including 55B<x400Address>, B<ediPartyName>, B<registeredID>, and other B<otherName> 56forms, yields B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE>. 57 58For each name considered, the function evaluates two conditions: 59 60=over 4 61 62=item * 63 64If I<nc> contains at least one B<permittedSubtree> of the same general-name 65type as the name, the name must match at least one of those permitted 66subtrees. If I<nc> contains no permitted subtrees of that type, no 67permitted-subtrees test is imposed on names of that type. 68 69=item * 70 71The name must not match any B<excludedSubtree> of the same general-name 72type in I<nc>. 73 74=back 75 76The function returns at the first violation encountered; it does not 77collect or report multiple failures. 78 79For B<dNSName> entries, matching follows the byte/label algorithm of 80RFC 5280 section 4.2.1.10, which RFC 5280 mandates when no 81protocol-specific matching rules apply. Because this match is performed 82without awareness of any specific higher-level protocol, additional 83matching rules defined by later or more specific protocols must be 84applied independently of this function to the certificate chain. 85 86NAME_CONSTRAINTS_check() performs only the constraint match for a single 87certificate against a single constraint set. It does B<not> perform the 88chain-wide enforcement of RFC 5280 section 6.1.4(g)-(j): callers wishing to 89enforce name constraints across an entire certification path must walk the 90chain themselves and apply each ancestor's constraint set to certificates 91lower in the chain, observing the usual exceptions (for example, 92self-issued intermediate certificates are exempt from constraints imposed 93by certificates above them, except when they are the leaf of the chain). 94For full RFC 5280 name-constraint enforcement integrated with chain 95validation, applications should use L<X509_verify_cert(3)>, which performs 96this internally. 97 98NAME_CONSTRAINTS_check() enforces an implementation limit on the product 99of the certificate's name count and the constraint set's subtree count, to 100prevent computationally expensive matching on pathological input. If that 101limit is exceeded the function returns B<X509_V_ERR_UNSPECIFIED> without 102performing any matching. The current limit is 2**20 (1,048,576) on the 103product of the name count (subject DN entries plus B<subjectAltName> 104entries) and the subtree count (B<permittedSubtrees> plus 105B<excludedSubtrees>). 106 107=head1 RETURN VALUES 108 109NAME_CONSTRAINTS_check() returns B<X509_V_OK> if every name considered 110satisfies the constraints. Otherwise it returns one of the following 111B<X509_V_ERR_*> codes: 112 113=over 4 114 115=item B<X509_V_ERR_PERMITTED_VIOLATION> 116 117A name of a type for which I<nc> contains at least one permitted subtree 118failed to match any of those subtrees. 119 120=item B<X509_V_ERR_EXCLUDED_VIOLATION> 121 122A name matched an excluded subtree. 123 124=item B<X509_V_ERR_SUBTREE_MINMAX> 125 126A subtree in I<nc> specified a B<minimum> other than 0 or a B<maximum> at 127all. RFC 5280 requires that these B<GeneralSubtree> fields not be used, 128and a constraint set that uses them cannot be processed. 129 130=item B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE> 131 132A general-name type for which matching is not implemented was encountered. 133The list of supported types is given in the DESCRIPTION above. 134 135=item B<X509_V_ERR_UNSUPPORTED_NAME_SYNTAX> 136 137A name in the certificate is encoded in a way that cannot be matched (for 138example, an B<emailAddress> attribute in the subject that is not encoded 139as an B<IA5String>). 140 141=item B<X509_V_ERR_UNSPECIFIED> 142 143The product of the certificate's name count and the constraint set's 144subtree count exceeded the implementation limit; no matching was 145performed. 146 147=back 148 149Other B<X509_V_ERR_*> codes may be returned by deeper name-matching 150helpers (for example, codes arising from individual general-name type 151comparisons). Callers should treat the return value as the authoritative 152success/failure signal and treat any value other than B<X509_V_OK> as a 153failure, rather than enumerating the specific codes above. 154 155=head1 NOTES 156 157NAME_CONSTRAINTS_check() does not match the certificate's commonName 158against B<dNSName> name constraints; that check is provided by a separate 159function, B<NAME_CONSTRAINTS_check_CN>(). The commonName-as-DNS-identity 160practice is a legacy concern: modern certificates assert DNS identities 161through B<dNSName> entries in the subject alternative name extension, 162which NAME_CONSTRAINTS_check() already covers. NAME_CONSTRAINTS_check_CN() 163is required only for older certificates that express a DNS identity 164through their commonName instead of, or in addition to, the SAN; for 165certificates conforming to modern profiles a call to NAME_CONSTRAINTS_check() 166alone is generally sufficient. 167 168=head1 BUGS 169 170RFC 9525's wildcard semantics apply only to presented-identifier 171matching for TLS service identity, and explicitly call out they are not 172valid for any other purpose; they do not define wildcard handling 173for name-constraint matching. NAME_CONSTRAINTS_check() therefore 174follows RFC 5280's requirements for when this is undefined, and treats 175the B<*> character in a B<dNSName> as a literal label component, per 176the RFC 5280 algorithm, which is often contrary to caller expectation. 177 178Even if specified in the future, due to the "fallback implementation" 179nature of matching wildcards in SAN B<dNSName> entries specified by 180RFC 5280, name constraint behaviour in the presence of wildcards 181should not be strictly relied upon across implementations and 182protocols. This matters most for the use of B<excluded names> 183constraints, which should not be relied upon to reliably constrain 184signing certificates for a PKI in a security dependent manner unless 185the consumers of these certificates are themselves known to be 186constrained by other means to only use implementations that provide 187different semantics, or the PKI can be constrained by other means to 188ensure that wildcards are never issued from such signing 189certificates. 190 191=head1 SEE ALSO 192 193L<X509_verify_cert(3)>, 194L<X509_VERIFY_PARAM_set_flags(3)> 195 196=head1 HISTORY 197 198NAME_CONSTRAINTS_check() was added in OpenSSL 1.0.0. 199 200NAME_CONSTRAINTS_check_CN() was added in OpenSSL 1.1.0. 201 202=head1 COPYRIGHT 203 204Copyright 2026 The OpenSSL Project Authors. All Rights Reserved. 205 206Licensed under the Apache License 2.0 (the "License"). You may not use 207this file except in compliance with the License. You can obtain a copy 208in the file LICENSE in the source distribution or at 209L<https://www.openssl.org/source/license.html>. 210 211=cut 212