xref: /freebsd/crypto/openssl/doc/man3/NAME_CONSTRAINTS_check.pod (revision 78e936b2d0b5e6554425009199be31e76bc67c10)

=pod

=head1 NAME

NAME_CONSTRAINTS_check,
NAME_CONSTRAINTS_check_CN - check a certificate's names against a name
constraints extension

=head1 SYNOPSIS

 #include <openssl/x509v3.h>

 int NAME_CONSTRAINTS_check(const X509 *x, NAME_CONSTRAINTS *nc);
 int NAME_CONSTRAINTS_check_CN(const X509 *x, NAME_CONSTRAINTS *nc);

=head1 DESCRIPTION

NAME_CONSTRAINTS_check() tests whether the names asserted by certificate
I<x> satisfy the name constraints I<nc>. It implements the matching
primitive of RFC 5280 section 4.2.1.10: given a constraint set (a
B<NAME_CONSTRAINTS> structure containing zero or more B<permittedSubtrees>
and B<excludedSubtrees>) and a candidate certificate, decide whether the
certificate's names fall within the permitted subtrees and outside the
excluded subtrees.

The names considered by NAME_CONSTRAINTS_check() are:

=over 4

=item *

The certificate's subject distinguished name, matched as a B<directoryName>
general-name type. The subject is considered only when it is nonempty.

=item *

Each B<emailAddress> attribute appearing within the subject distinguished
name, matched as an B<rfc822Name> general-name type. These attributes are
the historical, pre-SAN way of expressing an email address in a
certificate's subject, and RFC 5280 requires that they be subjected to
name-constraint checking.

=item *

Each entry in the certificate's subject alternative name extension, matched
according to its declared general-name type.

=back

NAME_CONSTRAINTS_check() implements matching for the following
general-name types: B<directoryName>, B<dNSName>, B<rfc822Name>,
B<uniformResourceIdentifier>, and B<iPAddress>. The B<otherName> form
B<id-on-SmtpUTF8Mailbox> (RFC 8398) is additionally matched against
B<rfc822Name> subtrees. Any other general-name type, including
B<x400Address>, B<ediPartyName>, B<registeredID>, and other B<otherName>
forms, yields B<X509_V_ERR_UNSUPPORTED_CONSTRAINT_TYPE>.

For each name considered, the function evaluates two conditions:

=over 4

=item *

If I<nc> contains at least one B<permittedSubtree> of the same general-name
type as the name, the name must match at least one of those permitted
subtrees. If I<nc> contains no permitted subtrees of that type, no
permitted-subtrees test is imposed on names of that type.

=item *

The name must not match any B<excludedSubtree> of the same general-name
type in I<nc>.

=back

The function returns at the first violation encountered; it does not
collect or report multiple failures.

For B<dNSName> 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.

NAME_CONSTRAINTS_check() performs only the constraint match for a single
certificate against a single constraint set. It does B<not> 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's 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 L<X509_verify_cert(3)>, which performs
this internally.

NAME_CONSTRAINTS_check() enforces an implementation limit on the product
of the certificate's name count and the constraint set's subtree count, to
prevent computationally expensive matching on pathological input. If that
limit is exceeded the function returns B<X509_V_ERR_UNSPECIFIED> without
performing any matching. The current limit is 2**20 (1,048,576) on the
product of the name count (subject DN entries plus B<subjectAltName>
entries) and the subtree count (B<permittedSubtrees> plus
B<excludedSubtrees>).

=head1 RETURN VALUES

NAME_CONSTRAINTS_check() returns B<X509_V_OK> if every name considered
satisfies the constraints. Otherwise it returns one of the following
B<X509_V_ERR_*> codes:

=over 4

=item B<X509_V_ERR_PERMITTED_VIOLATION>

A name of a type for which I<nc> contains at least one permitted subtree
failed to match any of those subtrees.

=item B<X509_V_ERR_EXCLUDED_VIOLATION>

A name matched an excluded subtree.

=item B<X509_V_ERR_SUBTREE_MINMAX>

A subtree in I<nc> specified a B<minimum> other than 0 or a B<maximum> at
all. RFC 5280 requires that these B<GeneralSubtree> fields not be used,
and a constraint set that uses them cannot be processed.

=item B<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.

=item B<X509_V_ERR_UNSUPPORTED_NAME_SYNTAX>

A name in the certificate is encoded in a way that cannot be matched (for
example, an B<emailAddress> attribute in the subject that is not encoded
as an B<IA5String>).

=item B<X509_V_ERR_UNSPECIFIED>

The product of the certificate's name count and the constraint set's
subtree count exceeded the implementation limit; no matching was
performed.

=back

Other B<X509_V_ERR_*> 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 B<X509_V_OK> as a
failure, rather than enumerating the specific codes above.

=head1 NOTES

NAME_CONSTRAINTS_check() does not match the certificate's commonName
against B<dNSName> name constraints; that check is provided by a separate
function, B<NAME_CONSTRAINTS_check_CN>(). The commonName-as-DNS-identity
practice is a legacy concern: modern certificates assert DNS identities
through B<dNSName> entries in the subject alternative name extension,
which NAME_CONSTRAINTS_check() already covers. NAME_CONSTRAINTS_check_CN()
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 NAME_CONSTRAINTS_check()
alone is generally sufficient.

=head1 BUGS

RFC 9525's 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. NAME_CONSTRAINTS_check() therefore
follows RFC 5280's requirements for when this is undefined, and treats
the B<*> character in a B<dNSName> as a literal label component, per
the RFC 5280 algorithm, which is often contrary to caller expectation.

Even if specified in the future, due to the "fallback implementation"
nature of matching wildcards in SAN B<dNSName> 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 B<excluded names>
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.

=head1 SEE ALSO

L<X509_verify_cert(3)>,
L<X509_VERIFY_PARAM_set_flags(3)>

=head1 HISTORY

NAME_CONSTRAINTS_check() was added in OpenSSL 1.0.0.

NAME_CONSTRAINTS_check_CN() was added in OpenSSL 1.1.0.

=head1 COPYRIGHT

Copyright 2026 The OpenSSL Project Authors. All Rights Reserved.

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
L<https://www.openssl.org/source/license.html>.

=cut