.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Required to disable full justification in groff 1.23.0. .if n .ds AD l .\" ======================================================================== .\" .IX Title "NAME_CONSTRAINTS_CHECK 3ssl" .TH NAME_CONSTRAINTS_CHECK 3ssl 2026-08-25 3.6.4 OpenSSL .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME NAME_CONSTRAINTS_check, NAME_CONSTRAINTS_check_CN \- check a certificate\*(Aqs names against a name constraints extension .SH SYNOPSIS .IX Header "SYNOPSIS" .Vb 1 \& #include \& \& int NAME_CONSTRAINTS_check(const X509 *x, NAME_CONSTRAINTS *nc); \& int NAME_CONSTRAINTS_check_CN(const X509 *x, NAME_CONSTRAINTS *nc); .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" \&\fBNAME_CONSTRAINTS_check()\fR tests whether the names asserted by certificate \&\fIx\fR satisfy the name constraints \fInc\fR. It implements the matching primitive of RFC 5280 section 4.2.1.10: given a constraint set (a \&\fBNAME_CONSTRAINTS\fR structure containing zero or more \fBpermittedSubtrees\fR and \fBexcludedSubtrees\fR) and a candidate certificate, decide whether the certificate\*(Aqs names fall within the permitted subtrees and outside the excluded subtrees. .PP The names considered by \fBNAME_CONSTRAINTS_check()\fR are: .IP \(bu 4 The certificate\*(Aqs subject distinguished name, matched as a \fBdirectoryName\fR general\-name type. The subject is considered only when it is nonempty. .IP \(bu 4 Each \fBemailAddress\fR attribute appearing within the subject distinguished name, matched as an \fBrfc822Name\fR general\-name type. These attributes are the historical, pre\-SAN way of expressing an email address in a certificate\*(Aqs subject, and RFC 5280 requires that they be subjected to name\-constraint checking. .IP \(bu 4 Each entry in the certificate\*(Aqs subject alternative name extension, matched according to its declared general\-name type. .PP \&\fBNAME_CONSTRAINTS_check()\fR implements matching for the following general\-name types: \fBdirectoryName\fR, \fBdNSName\fR, \fBrfc822Name\fR, \&\fBuniformResourceIdentifier\fR, and \fBiPAddress\fR. The \fBotherName\fR form \&\fBid\-on\-SmtpUTF8Mailbox\fR (RFC 8398) is additionally matched against \&\fBrfc822Name\fR subtrees. Any other general\-name type, including \&\fBx400Address\fR, \fBediPartyName\fR, \fBregisteredID\fR, and other \fBotherName\fR forms, yields \fBX509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE\fR. .PP For each name considered, the function evaluates two conditions: .IP \(bu 4 If \fInc\fR contains at least one \fBpermittedSubtree\fR of the same general\-name type as the name, the name must match at least one of those permitted subtrees. If \fInc\fR contains no permitted subtrees of that type, no permitted\-subtrees test is imposed on names of that type. .IP \(bu 4 The name must not match any \fBexcludedSubtree\fR of the same general\-name type in \fInc\fR. .PP The function returns at the first violation encountered; it does not collect or report multiple failures. .PP For \fBdNSName\fR entries, matching follows the byte/label algorithm of RFC 5280 section 4.2.1.10, which RFC 5280 mandates when no protocol\-specific matching rules apply. Because this match is performed without awareness of any specific higher\-level protocol, additional matching rules defined by later or more specific protocols must be applied independently of this function to the certificate chain. .PP \&\fBNAME_CONSTRAINTS_check()\fR performs only the constraint match for a single certificate against a single constraint set. It does \fBnot\fR perform the chain\-wide enforcement of RFC 5280 section 6.1.4(g)\-(j): callers wishing to enforce name constraints across an entire certification path must walk the chain themselves and apply each ancestor\*(Aqs constraint set to certificates lower in the chain, observing the usual exceptions (for example, self\-issued intermediate certificates are exempt from constraints imposed by certificates above them, except when they are the leaf of the chain). For full RFC 5280 name\-constraint enforcement integrated with chain validation, applications should use \fBX509_verify_cert\fR\|(3), which performs this internally. .PP \&\fBNAME_CONSTRAINTS_check()\fR enforces an implementation limit on the product of the certificate\*(Aqs name count and the constraint set\*(Aqs subtree count, to prevent computationally expensive matching on pathological input. If that limit is exceeded the function returns \fBX509_V_ERR_UNSPECIFIED\fR without performing any matching. The current limit is 2**20 (1,048,576) on the product of the name count (subject DN entries plus \fBsubjectAltName\fR entries) and the subtree count (\fBpermittedSubtrees\fR plus \&\fBexcludedSubtrees\fR). .SH "RETURN VALUES" .IX Header "RETURN VALUES" \&\fBNAME_CONSTRAINTS_check()\fR returns \fBX509_V_OK\fR if every name considered satisfies the constraints. Otherwise it returns one of the following \&\fBX509_V_ERR_*\fR codes: .IP \fBX509_V_ERR_PERMITTED_VIOLATION\fR 4 .IX Item "X509_V_ERR_PERMITTED_VIOLATION" A name of a type for which \fInc\fR contains at least one permitted subtree failed to match any of those subtrees. .IP \fBX509_V_ERR_EXCLUDED_VIOLATION\fR 4 .IX Item "X509_V_ERR_EXCLUDED_VIOLATION" A name matched an excluded subtree. .IP \fBX509_V_ERR_SUBTREE_MINMAX\fR 4 .IX Item "X509_V_ERR_SUBTREE_MINMAX" A subtree in \fInc\fR specified a \fBminimum\fR other than 0 or a \fBmaximum\fR at all. RFC 5280 requires that these \fBGeneralSubtree\fR fields not be used, and a constraint set that uses them cannot be processed. .IP \fBX509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE\fR 4 .IX Item "X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE" A general\-name type for which matching is not implemented was encountered. The list of supported types is given in the DESCRIPTION above. .IP \fBX509_V_ERR_UNSUPPORTED_NAME_SYNTAX\fR 4 .IX Item "X509_V_ERR_UNSUPPORTED_NAME_SYNTAX" A name in the certificate is encoded in a way that cannot be matched (for example, an \fBemailAddress\fR attribute in the subject that is not encoded as an \fBIA5String\fR). .IP \fBX509_V_ERR_UNSPECIFIED\fR 4 .IX Item "X509_V_ERR_UNSPECIFIED" The product of the certificate\*(Aqs name count and the constraint set\*(Aqs subtree count exceeded the implementation limit; no matching was performed. .PP Other \fBX509_V_ERR_*\fR codes may be returned by deeper name\-matching helpers (for example, codes arising from individual general\-name type comparisons). Callers should treat the return value as the authoritative success/failure signal and treat any value other than \fBX509_V_OK\fR as a failure, rather than enumerating the specific codes above. .SH NOTES .IX Header "NOTES" \&\fBNAME_CONSTRAINTS_check()\fR does not match the certificate\*(Aqs commonName against \fBdNSName\fR name constraints; that check is provided by a separate function, \fBNAME_CONSTRAINTS_check_CN\fR(). The commonName\-as\-DNS\-identity practice is a legacy concern: modern certificates assert DNS identities through \fBdNSName\fR entries in the subject alternative name extension, which \fBNAME_CONSTRAINTS_check()\fR already covers. \fBNAME_CONSTRAINTS_check_CN()\fR is required only for older certificates that express a DNS identity through their commonName instead of, or in addition to, the SAN; for certificates conforming to modern profiles a call to \fBNAME_CONSTRAINTS_check()\fR alone is generally sufficient. .SH BUGS .IX Header "BUGS" RFC 9525\*(Aqs wildcard semantics apply only to presented\-identifier matching for TLS service identity, and explicitly call out they are not valid for any other purpose; they do not define wildcard handling for name\-constraint matching. \fBNAME_CONSTRAINTS_check()\fR therefore follows RFC 5280\*(Aqs requirements for when this is undefined, and treats the \fB*\fR character in a \fBdNSName\fR as a literal label component, per the RFC 5280 algorithm, which is often contrary to caller expectation. .PP Even if specified in the future, due to the "fallback implementation" nature of matching wildcards in SAN \fBdNSName\fR entries specified by RFC 5280, name constraint behaviour in the presence of wildcards should not be strictly relied upon across implementations and protocols. This matters most for the use of \fBexcluded names\fR constraints, which should not be relied upon to reliably constrain signing certificates for a PKI in a security dependent manner unless the consumers of these certificates are themselves known to be constrained by other means to only use implementations that provide different semantics, or the PKI can be constrained by other means to ensure that wildcards are never issued from such signing certificates. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBX509_verify_cert\fR\|(3), \&\fBX509_VERIFY_PARAM_set_flags\fR\|(3) .SH HISTORY .IX Header "HISTORY" \&\fBNAME_CONSTRAINTS_check()\fR was added in OpenSSL 1.0.0. .PP \&\fBNAME_CONSTRAINTS_check_CN()\fR was added in OpenSSL 1.1.0. .SH COPYRIGHT .IX Header "COPYRIGHT" Copyright 2026 The OpenSSL Project Authors. All Rights Reserved. .PP Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at .