711 lines
32 KiB
Plaintext
711 lines
32 KiB
Plaintext
.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
|
|
.\"
|
|
.\" 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
|
|
..
|
|
.\" Set up some character translations and predefined strings. \*(-- will
|
|
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
|
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
|
|
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
|
|
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
|
|
.\" nothing in troff, for use with C<>.
|
|
.tr \(*W-
|
|
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
|
.ie n \{\
|
|
. ds -- \(*W-
|
|
. ds PI pi
|
|
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
|
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
|
|
. ds L" ""
|
|
. ds R" ""
|
|
. ds C` ""
|
|
. ds C' ""
|
|
'br\}
|
|
.el\{\
|
|
. ds -- \|\(em\|
|
|
. ds PI \(*p
|
|
. ds L" ``
|
|
. ds R" ''
|
|
. 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 turned on, 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
|
|
.\"
|
|
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
|
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
|
. \" fudge factors for nroff and troff
|
|
.if n \{\
|
|
. ds #H 0
|
|
. ds #V .8m
|
|
. ds #F .3m
|
|
. ds #[ \f1
|
|
. ds #] \fP
|
|
.\}
|
|
.if t \{\
|
|
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
|
|
. ds #V .6m
|
|
. ds #F 0
|
|
. ds #[ \&
|
|
. ds #] \&
|
|
.\}
|
|
. \" simple accents for nroff and troff
|
|
.if n \{\
|
|
. ds ' \&
|
|
. ds ` \&
|
|
. ds ^ \&
|
|
. ds , \&
|
|
. ds ~ ~
|
|
. ds /
|
|
.\}
|
|
.if t \{\
|
|
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
|
|
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
|
|
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
|
|
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
|
|
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
|
|
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
|
|
.\}
|
|
. \" troff and (daisy-wheel) nroff accents
|
|
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
|
|
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
|
|
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
|
|
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
|
|
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
|
|
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
|
|
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
|
|
.ds ae a\h'-(\w'a'u*4/10)'e
|
|
.ds Ae A\h'-(\w'A'u*4/10)'E
|
|
. \" corrections for vroff
|
|
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
|
|
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
|
|
. \" for low resolution devices (crt and lpr)
|
|
.if \n(.H>23 .if \n(.V>19 \
|
|
\{\
|
|
. ds : e
|
|
. ds 8 ss
|
|
. ds o a
|
|
. ds d- d\h'-1'\(ga
|
|
. ds D- D\h'-1'\(hy
|
|
. ds th \o'bp'
|
|
. ds Th \o'LP'
|
|
. ds ae ae
|
|
. ds Ae AE
|
|
.\}
|
|
.rm #[ #] #H #V #F C
|
|
.\" ========================================================================
|
|
.\"
|
|
.IX Title "OPENSSL-VERIFICATION-OPTIONS 1ossl"
|
|
.TH OPENSSL-VERIFICATION-OPTIONS 1ossl "2024-01-30" "3.2.1" "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"
|
|
openssl\-verification\-options \- generic X.509 certificate verification options
|
|
.SH "SYNOPSIS"
|
|
.IX Header "SYNOPSIS"
|
|
\&\fBopenssl\fR
|
|
\&\fIcommand\fR
|
|
[ \fIoptions\fR ... ]
|
|
[ \fIparameters\fR ... ]
|
|
.SH "DESCRIPTION"
|
|
.IX Header "DESCRIPTION"
|
|
There are many situations where X.509 certificates are verified
|
|
within the OpenSSL libraries and in various OpenSSL commands.
|
|
.PP
|
|
Certificate verification is implemented by \fIX509_verify_cert\fR\|(3).
|
|
It is a complicated process consisting of a number of steps
|
|
and depending on numerous options.
|
|
The most important of them are detailed in the following sections.
|
|
.PP
|
|
In a nutshell, a valid chain of certificates needs to be built up and verified
|
|
starting from the \fItarget certificate\fR that is to be verified
|
|
and ending in a certificate that due to some policy is trusted.
|
|
Verification is done relative to the given \fIpurpose\fR, which is the intended use
|
|
of the target certificate, such as \s-1SSL\s0 server, or by default for any purpose.
|
|
.PP
|
|
The details of how each OpenSSL command handles errors
|
|
are documented on the specific command page.
|
|
.PP
|
|
\&\s-1DANE\s0 support is documented in \fIopenssl\-s_client\fR\|(1),
|
|
\&\fISSL_CTX_dane_enable\fR\|(3), \fISSL_set1_host\fR\|(3),
|
|
\&\fIX509_VERIFY_PARAM_set_flags\fR\|(3), and \fIX509_check_host\fR\|(3).
|
|
.SS "Trust Anchors"
|
|
.IX Subsection "Trust Anchors"
|
|
In general, according to \s-1RFC 4158\s0 and \s-1RFC 5280,\s0 a \fItrust anchor\fR is
|
|
any public key and related subject distinguished name (\s-1DN\s0) that
|
|
for some reason is considered trusted
|
|
and thus is acceptable as the root of a chain of certificates.
|
|
.PP
|
|
In practice, trust anchors are given in the form of certificates,
|
|
where their essential fields are the public key and the subject \s-1DN.\s0
|
|
In addition to the requirements in \s-1RFC 5280,\s0
|
|
OpenSSL checks the validity period of such certificates
|
|
and makes use of some further fields.
|
|
In particular, the subject key identifier extension, if present,
|
|
is used for matching trust anchors during chain building.
|
|
.PP
|
|
In the most simple and common case, trust anchors are by default
|
|
all self-signed \*(L"root\*(R" \s-1CA\s0 certificates that are placed in the \fItrust store\fR,
|
|
which is a collection of certificates that are trusted for certain uses.
|
|
This is akin to what is used in the trust stores of Mozilla Firefox,
|
|
or Apple's and Microsoft's certificate stores, ...
|
|
.PP
|
|
From the OpenSSL perspective, a trust anchor is a certificate
|
|
that should be augmented with an explicit designation for which
|
|
uses of a target certificate the certificate may serve as a trust anchor.
|
|
In \s-1PEM\s0 encoding, this is indicated by the \f(CW\*(C`TRUSTED CERTIFICATE\*(C'\fR string.
|
|
Such a designation provides a set of positive trust attributes
|
|
explicitly stating trust for the listed purposes
|
|
and/or a set of negative trust attributes
|
|
explicitly rejecting the use for the listed purposes.
|
|
The purposes are encoded using the values defined for the extended key usages
|
|
(EKUs) that may be given in X.509 extensions of end-entity certificates.
|
|
See also the \*(L"Extended Key Usage\*(R" section below.
|
|
.PP
|
|
The currently recognized uses are
|
|
\&\fBclientAuth\fR (\s-1SSL\s0 client use), \fBserverAuth\fR (\s-1SSL\s0 server use),
|
|
\&\fBemailProtection\fR (S/MIME email use), \fBcodeSigning\fR (object signer use),
|
|
\&\fBOCSPSigning\fR (\s-1OCSP\s0 responder use), \fB\s-1OCSP\s0\fR (\s-1OCSP\s0 request use),
|
|
\&\fBtimeStamping\fR (\s-1TSA\s0 server use), and \fBanyExtendedKeyUsage\fR.
|
|
As of OpenSSL 1.1.0, the last of these blocks all uses when rejected or
|
|
enables all uses when trusted.
|
|
.PP
|
|
A certificate, which may be \s-1CA\s0 certificate or an end-entity certificate,
|
|
is considered a trust anchor for the given use
|
|
if and only if all the following conditions hold:
|
|
.IP "\(bu" 4
|
|
It is an an element of the trust store.
|
|
.IP "\(bu" 4
|
|
It does not have a negative trust attribute rejecting the given use.
|
|
.IP "\(bu" 4
|
|
It has a positive trust attribute accepting the given use
|
|
or (by default) one of the following compatibility conditions apply:
|
|
It is self-signed or the \fB\-partial_chain\fR option is given
|
|
(which corresponds to the \fBX509_V_FLAG_PARTIAL_CHAIN\fR flag being set).
|
|
.SS "Certification Path Building"
|
|
.IX Subsection "Certification Path Building"
|
|
First, a certificate chain is built up starting from the target certificate
|
|
and ending in a trust anchor.
|
|
.PP
|
|
The chain is built up iteratively, looking up in turn
|
|
a certificate with suitable key usage that
|
|
matches as an issuer of the current \*(L"subject\*(R" certificate as described below.
|
|
If there is such a certificate, the first one found that is currently valid
|
|
is taken, otherwise the one that expired most recently of all such certificates.
|
|
For efficiency, no backtracking is performed, thus
|
|
any further candidate issuer certificates that would match equally are ignored.
|
|
.PP
|
|
When a self-signed certificate has been added, chain construction stops.
|
|
In this case it must fully match a trust anchor, otherwise chain building fails.
|
|
.PP
|
|
A candidate issuer certificate matches a subject certificate
|
|
if all of the following conditions hold:
|
|
.IP "\(bu" 4
|
|
Its subject name matches the issuer name of the subject certificate.
|
|
.IP "\(bu" 4
|
|
If the subject certificate has an authority key identifier extension,
|
|
each of its sub-fields equals the corresponding subject key identifier, serial
|
|
number, and issuer field of the candidate issuer certificate,
|
|
as far as the respective fields are present in both certificates.
|
|
.IP "\(bu" 4
|
|
The certificate signature algorithm used to sign the subject certificate
|
|
is supported and
|
|
equals the public key algorithm of the candidate issuer certificate.
|
|
.PP
|
|
The lookup first searches for issuer certificates in the trust store.
|
|
If it does not find a match there it consults
|
|
the list of untrusted (\*(L"intermediate\*(R" \s-1CA\s0) certificates, if provided.
|
|
.SS "Certification Path Validation"
|
|
.IX Subsection "Certification Path Validation"
|
|
When the certificate chain building process was successful
|
|
the chain components and their links are checked thoroughly.
|
|
.PP
|
|
The first step is to check that each certificate is well-formed.
|
|
Part of these checks are enabled only if the \fB\-x509_strict\fR option is given.
|
|
.PP
|
|
The second step is to check the extensions of every untrusted certificate
|
|
for consistency with the supplied purpose.
|
|
If the \fB\-purpose\fR option is not given then no such checks are done
|
|
except for \s-1SSL/TLS\s0 connection setup,
|
|
where by default \f(CW\*(C`sslserver\*(C'\fR or \f(CW\*(C`sslclient\*(C'\fR, are checked.
|
|
The target or \*(L"leaf\*(R" certificate, as well as any other untrusted certificates,
|
|
must have extensions compatible with the specified purpose.
|
|
All certificates except the target or \*(L"leaf\*(R" must also be valid \s-1CA\s0 certificates.
|
|
The precise extensions required are described in more detail in
|
|
\&\*(L"\s-1CERTIFICATE EXTENSIONS\*(R"\s0 in \fIopenssl\-x509\fR\|(1).
|
|
.PP
|
|
The third step is to check the trust settings on the last certificate
|
|
(which typically is a self-signed root \s-1CA\s0 certificate).
|
|
It must be trusted for the given use.
|
|
For compatibility with previous versions of OpenSSL, a self-signed certificate
|
|
with no trust attributes is considered to be valid for all uses.
|
|
.PP
|
|
The fourth, and final, step is to check the validity of the certificate chain.
|
|
For each element in the chain, including the root \s-1CA\s0 certificate,
|
|
the validity period as specified by the \f(CW\*(C`notBefore\*(C'\fR and \f(CW\*(C`notAfter\*(C'\fR fields
|
|
is checked against the current system time.
|
|
The \fB\-attime\fR flag may be used to use a reference time other than \*(L"now.\*(R"
|
|
The certificate signature is checked as well
|
|
(except for the signature of the typically self-signed root \s-1CA\s0 certificate,
|
|
which is verified only if the \fB\-check_ss_sig\fR option is given).
|
|
When verifying a certificate signature
|
|
the keyUsage extension (if present) of the candidate issuer certificate
|
|
is checked to permit digitalSignature for signing proxy certificates
|
|
or to permit keyCertSign for signing other certificates, respectively.
|
|
If all operations complete successfully then certificate is considered
|
|
valid. If any operation fails then the certificate is not valid.
|
|
.SH "OPTIONS"
|
|
.IX Header "OPTIONS"
|
|
.SS "Trusted Certificate Options"
|
|
.IX Subsection "Trusted Certificate Options"
|
|
The following options specify how to supply the certificates
|
|
that can be used as trust anchors for certain uses.
|
|
As mentioned, a collection of such certificates is called a \fItrust store\fR.
|
|
.PP
|
|
Note that OpenSSL does not provide a default set of trust anchors. Many
|
|
Linux distributions include a system default and configure OpenSSL to point
|
|
to that. Mozilla maintains an influential trust store that can be found at
|
|
<https://www.mozilla.org/en\-US/about/governance/policies/security\-group/certs/>.
|
|
.PP
|
|
The certificates to add to the trust store
|
|
can be specified using following options.
|
|
.IP "\fB\-CAfile\fR \fIfile\fR" 4
|
|
.IX Item "-CAfile file"
|
|
Load the specified file which contains a trusted certificate in \s-1DER\s0 format
|
|
or potentially several of them in case the input is in \s-1PEM\s0 format.
|
|
PEM-encoded certificates may also have trust attributes set.
|
|
.IP "\fB\-no\-CAfile\fR" 4
|
|
.IX Item "-no-CAfile"
|
|
Do not load the default file of trusted certificates.
|
|
.IP "\fB\-CApath\fR \fIdir\fR" 4
|
|
.IX Item "-CApath dir"
|
|
Use the specified directory as a collection of trusted certificates,
|
|
i.e., a trust store.
|
|
Files should be named with the hash value of the X.509 SubjectName of each
|
|
certificate. This is so that the library can extract the IssuerName,
|
|
hash it, and directly lookup the file to get the issuer certificate.
|
|
See \fIopenssl\-rehash\fR\|(1) for information on creating this type of directory.
|
|
.IP "\fB\-no\-CApath\fR" 4
|
|
.IX Item "-no-CApath"
|
|
Do not use the default directory of trusted certificates.
|
|
.IP "\fB\-CAstore\fR \fIuri\fR" 4
|
|
.IX Item "-CAstore uri"
|
|
Use \fIuri\fR as a store of \s-1CA\s0 certificates.
|
|
The \s-1URI\s0 may indicate a single certificate, as well as a collection of them.
|
|
With URIs in the \f(CW\*(C`file:\*(C'\fR scheme, this acts as \fB\-CAfile\fR or
|
|
\&\fB\-CApath\fR, depending on if the \s-1URI\s0 indicates a single file or
|
|
directory.
|
|
See \fIossl_store\-file\fR\|(7) for more information on the \f(CW\*(C`file:\*(C'\fR scheme.
|
|
.Sp
|
|
These certificates are also used when building the server certificate
|
|
chain (for example with \fIopenssl\-s_server\fR\|(1)) or client certificate
|
|
chain (for example with \fIopenssl\-s_time\fR\|(1)).
|
|
.IP "\fB\-no\-CAstore\fR" 4
|
|
.IX Item "-no-CAstore"
|
|
Do not use the default store of trusted \s-1CA\s0 certificates.
|
|
.SS "Verification Options"
|
|
.IX Subsection "Verification Options"
|
|
The certificate verification can be fine-tuned with the following flags.
|
|
.IP "\fB\-verbose\fR" 4
|
|
.IX Item "-verbose"
|
|
Print extra information about the operations being performed.
|
|
.IP "\fB\-attime\fR \fItimestamp\fR" 4
|
|
.IX Item "-attime timestamp"
|
|
Perform validation checks using time specified by \fItimestamp\fR and not
|
|
current system time. \fItimestamp\fR is the number of seconds since
|
|
January 1, 1970 (i.e., the Unix Epoch).
|
|
.IP "\fB\-no_check_time\fR" 4
|
|
.IX Item "-no_check_time"
|
|
This option suppresses checking the validity period of certificates and CRLs
|
|
against the current time. If option \fB\-attime\fR is used to specify
|
|
a verification time, the check is not suppressed.
|
|
.IP "\fB\-x509_strict\fR" 4
|
|
.IX Item "-x509_strict"
|
|
This disables non-compliant workarounds for broken certificates.
|
|
Thus errors are thrown on certificates not compliant with \s-1RFC 5280.\s0
|
|
.Sp
|
|
When this option is set,
|
|
among others, the following certificate well-formedness conditions are checked:
|
|
.RS 4
|
|
.IP "\(bu" 4
|
|
The basicConstraints of \s-1CA\s0 certificates must be marked critical.
|
|
.IP "\(bu" 4
|
|
\&\s-1CA\s0 certificates must explicitly include the keyUsage extension.
|
|
.IP "\(bu" 4
|
|
If a pathlenConstraint is given the key usage keyCertSign must be allowed.
|
|
.IP "\(bu" 4
|
|
The pathlenConstraint must not be given for non-CA certificates.
|
|
.IP "\(bu" 4
|
|
The issuer name of any certificate must not be empty.
|
|
.IP "\(bu" 4
|
|
The subject name of \s-1CA\s0 certs, certs with keyUsage crlSign, and certs
|
|
without subjectAlternativeName must not be empty.
|
|
.IP "\(bu" 4
|
|
If a subjectAlternativeName extension is given it must not be empty.
|
|
.IP "\(bu" 4
|
|
The signatureAlgorithm field and the cert signature must be consistent.
|
|
.IP "\(bu" 4
|
|
Any given authorityKeyIdentifier and any given subjectKeyIdentifier
|
|
must not be marked critical.
|
|
.IP "\(bu" 4
|
|
The authorityKeyIdentifier must be given for X.509v3 certs unless they
|
|
are self-signed.
|
|
.IP "\(bu" 4
|
|
The subjectKeyIdentifier must be given for all X.509v3 \s-1CA\s0 certs.
|
|
.RE
|
|
.RS 4
|
|
.RE
|
|
.IP "\fB\-ignore_critical\fR" 4
|
|
.IX Item "-ignore_critical"
|
|
Normally if an unhandled critical extension is present that is not
|
|
supported by OpenSSL the certificate is rejected (as required by \s-1RFC5280\s0).
|
|
If this option is set critical extensions are ignored.
|
|
.IP "\fB\-issuer_checks\fR" 4
|
|
.IX Item "-issuer_checks"
|
|
Ignored.
|
|
.IP "\fB\-crl_check\fR" 4
|
|
.IX Item "-crl_check"
|
|
Checks end entity certificate validity by attempting to look up a valid \s-1CRL.\s0
|
|
If a valid \s-1CRL\s0 cannot be found an error occurs.
|
|
.IP "\fB\-crl_check_all\fR" 4
|
|
.IX Item "-crl_check_all"
|
|
Checks the validity of \fBall\fR certificates in the chain by attempting
|
|
to look up valid CRLs.
|
|
.IP "\fB\-use_deltas\fR" 4
|
|
.IX Item "-use_deltas"
|
|
Enable support for delta CRLs.
|
|
.IP "\fB\-extended_crl\fR" 4
|
|
.IX Item "-extended_crl"
|
|
Enable extended \s-1CRL\s0 features such as indirect CRLs and alternate \s-1CRL\s0
|
|
signing keys.
|
|
.IP "\fB\-suiteB_128_only\fR, \fB\-suiteB_128\fR, \fB\-suiteB_192\fR" 4
|
|
.IX Item "-suiteB_128_only, -suiteB_128, -suiteB_192"
|
|
Enable the Suite B mode operation at 128 bit Level of Security, 128 bit or
|
|
192 bit, or only 192 bit Level of Security respectively.
|
|
See \s-1RFC6460\s0 for details. In particular the supported signature algorithms are
|
|
reduced to support only \s-1ECDSA\s0 and \s-1SHA256\s0 or \s-1SHA384\s0 and only the elliptic curves
|
|
P\-256 and P\-384.
|
|
.IP "\fB\-auth_level\fR \fIlevel\fR" 4
|
|
.IX Item "-auth_level level"
|
|
Set the certificate chain authentication security level to \fIlevel\fR.
|
|
The authentication security level determines the acceptable signature and
|
|
public key strength when verifying certificate chains. For a certificate
|
|
chain to validate, the public keys of all the certificates must meet the
|
|
specified security \fIlevel\fR. The signature algorithm security level is
|
|
enforced for all the certificates in the chain except for the chain's
|
|
\&\fItrust anchor\fR, which is either directly trusted or validated by means
|
|
other than its signature. See \fISSL_CTX_set_security_level\fR\|(3) for the
|
|
definitions of the available levels. The default security level is \-1,
|
|
or \*(L"not set\*(R". At security level 0 or lower all algorithms are acceptable.
|
|
Security level 1 requires at least 80\-bit\-equivalent security and is broadly
|
|
interoperable, though it will, for example, reject \s-1MD5\s0 signatures or \s-1RSA\s0
|
|
keys shorter than 1024 bits.
|
|
.IP "\fB\-partial_chain\fR" 4
|
|
.IX Item "-partial_chain"
|
|
Allow verification to succeed if an incomplete chain can be built.
|
|
That is, a chain ending in a certificate that normally would not be trusted
|
|
(because it has no matching positive trust attributes and is not self-signed)
|
|
but is an element of the trust store.
|
|
This certificate may be self-issued or belong to an intermediate \s-1CA.\s0
|
|
.IP "\fB\-check_ss_sig\fR" 4
|
|
.IX Item "-check_ss_sig"
|
|
Verify the signature of
|
|
the last certificate in a chain if the certificate is supposedly self-signed.
|
|
This is prohibited and will result in an error if it is a non-conforming \s-1CA\s0
|
|
certificate with key usage restrictions not including the keyCertSign bit.
|
|
This verification is disabled by default because it doesn't add any security.
|
|
.IP "\fB\-allow_proxy_certs\fR" 4
|
|
.IX Item "-allow_proxy_certs"
|
|
Allow the verification of proxy certificates.
|
|
.IP "\fB\-trusted_first\fR" 4
|
|
.IX Item "-trusted_first"
|
|
As of OpenSSL 1.1.0 this option is on by default and cannot be disabled.
|
|
.Sp
|
|
When constructing the certificate chain, the trusted certificates specified
|
|
via \fB\-CAfile\fR, \fB\-CApath\fR, \fB\-CAstore\fR or \fB\-trusted\fR are always used
|
|
before any certificates specified via \fB\-untrusted\fR.
|
|
.IP "\fB\-no_alt_chains\fR" 4
|
|
.IX Item "-no_alt_chains"
|
|
As of OpenSSL 1.1.0, since \fB\-trusted_first\fR always on, this option has no
|
|
effect.
|
|
.IP "\fB\-trusted\fR \fIfile\fR" 4
|
|
.IX Item "-trusted file"
|
|
Parse \fIfile\fR as a set of one or more certificates.
|
|
Each of them qualifies as trusted if has a suitable positive trust attribute
|
|
or it is self-signed or the \fB\-partial_chain\fR option is specified.
|
|
This option implies the \fB\-no\-CAfile\fR, \fB\-no\-CApath\fR, and \fB\-no\-CAstore\fR options
|
|
and it cannot be used with the \fB\-CAfile\fR, \fB\-CApath\fR or \fB\-CAstore\fR options, so
|
|
only certificates specified using the \fB\-trusted\fR option are trust anchors.
|
|
This option may be used multiple times.
|
|
.IP "\fB\-untrusted\fR \fIfile\fR" 4
|
|
.IX Item "-untrusted file"
|
|
Parse \fIfile\fR as a set of one or more certificates.
|
|
All certificates (typically of intermediate CAs) are considered untrusted
|
|
and may be used to
|
|
construct a certificate chain from the target certificate to a trust anchor.
|
|
This option may be used multiple times.
|
|
.IP "\fB\-policy\fR \fIarg\fR" 4
|
|
.IX Item "-policy arg"
|
|
Enable policy processing and add \fIarg\fR to the user-initial-policy-set (see
|
|
\&\s-1RFC5280\s0). The policy \fIarg\fR can be an object name an \s-1OID\s0 in numeric form.
|
|
This argument can appear more than once.
|
|
.IP "\fB\-explicit_policy\fR" 4
|
|
.IX Item "-explicit_policy"
|
|
Set policy variable require-explicit-policy (see \s-1RFC5280\s0).
|
|
.IP "\fB\-policy_check\fR" 4
|
|
.IX Item "-policy_check"
|
|
Enables certificate policy processing.
|
|
.IP "\fB\-policy_print\fR" 4
|
|
.IX Item "-policy_print"
|
|
Print out diagnostics related to policy processing.
|
|
.IP "\fB\-inhibit_any\fR" 4
|
|
.IX Item "-inhibit_any"
|
|
Set policy variable inhibit-any-policy (see \s-1RFC5280\s0).
|
|
.IP "\fB\-inhibit_map\fR" 4
|
|
.IX Item "-inhibit_map"
|
|
Set policy variable inhibit-policy-mapping (see \s-1RFC5280\s0).
|
|
.IP "\fB\-purpose\fR \fIpurpose\fR" 4
|
|
.IX Item "-purpose purpose"
|
|
The intended use for the certificate.
|
|
Currently defined purposes are \f(CW\*(C`sslclient\*(C'\fR, \f(CW\*(C`sslserver\*(C'\fR, \f(CW\*(C`nssslserver\*(C'\fR,
|
|
\&\f(CW\*(C`smimesign\*(C'\fR, \f(CW\*(C`smimeencrypt\*(C'\fR, \f(CW\*(C`crlsign\*(C'\fR, \f(CW\*(C`ocsphelper\*(C'\fR, \f(CW\*(C`timestampsign\*(C'\fR,
|
|
\&\f(CW\*(C`codesign\*(C'\fR and \f(CW\*(C`any\*(C'\fR.
|
|
If peer certificate verification is enabled, by default the \s-1TLS\s0 implementation
|
|
as well as the commands \fBs_client\fR and \fBs_server\fR check for consistency
|
|
with \s-1TLS\s0 server or \s-1TLS\s0 client use, respectively.
|
|
.Sp
|
|
While \s-1IETF RFC 5280\s0 says that \fBid-kp-serverAuth\fR and \fBid-kp-clientAuth\fR
|
|
are only for \s-1WWW\s0 use, in practice they are used for all kinds of \s-1TLS\s0 clients
|
|
and servers, and this is what OpenSSL assumes as well.
|
|
.IP "\fB\-verify_depth\fR \fInum\fR" 4
|
|
.IX Item "-verify_depth num"
|
|
Limit the certificate chain to \fInum\fR intermediate \s-1CA\s0 certificates.
|
|
A maximal depth chain can have up to \fInum\fR+2 certificates, since neither the
|
|
end-entity certificate nor the trust-anchor certificate count against the
|
|
\&\fB\-verify_depth\fR limit.
|
|
.IP "\fB\-verify_email\fR \fIemail\fR" 4
|
|
.IX Item "-verify_email email"
|
|
Verify if \fIemail\fR matches the email address in Subject Alternative Name or
|
|
the email in the subject Distinguished Name.
|
|
.IP "\fB\-verify_hostname\fR \fIhostname\fR" 4
|
|
.IX Item "-verify_hostname hostname"
|
|
Verify if \fIhostname\fR matches \s-1DNS\s0 name in Subject Alternative Name or
|
|
Common Name in the subject certificate.
|
|
.IP "\fB\-verify_ip\fR \fIip\fR" 4
|
|
.IX Item "-verify_ip ip"
|
|
Verify if \fIip\fR matches the \s-1IP\s0 address in Subject Alternative Name of
|
|
the subject certificate.
|
|
.IP "\fB\-verify_name\fR \fIname\fR" 4
|
|
.IX Item "-verify_name name"
|
|
Use default verification policies like trust model and required certificate
|
|
policies identified by \fIname\fR.
|
|
The trust model determines which auxiliary trust or reject OIDs are applicable
|
|
to verifying the given certificate chain.
|
|
They can be given using the \fB\-addtrust\fR and \fB\-addreject\fR options
|
|
for \fIopenssl\-x509\fR\|(1).
|
|
Supported policy names include: \fBdefault\fR, \fBpkcs7\fR, \fBsmime_sign\fR,
|
|
\&\fBssl_client\fR, \fBssl_server\fR.
|
|
These mimics the combinations of purpose and trust settings used in \s-1SSL, CMS\s0
|
|
and S/MIME.
|
|
As of OpenSSL 1.1.0, the trust model is inferred from the purpose when not
|
|
specified, so the \fB\-verify_name\fR options are functionally equivalent to the
|
|
corresponding \fB\-purpose\fR settings.
|
|
.SS "Extended Verification Options"
|
|
.IX Subsection "Extended Verification Options"
|
|
Sometimes there may be more than one certificate chain leading to an
|
|
end-entity certificate.
|
|
This usually happens when a root or intermediate \s-1CA\s0 signs a certificate
|
|
for another a \s-1CA\s0 in other organization.
|
|
Another reason is when a \s-1CA\s0 might have intermediates that use two different
|
|
signature formats, such as a \s-1SHA\-1\s0 and a \s-1SHA\-256\s0 digest.
|
|
.PP
|
|
The following options can be used to provide data that will allow the
|
|
OpenSSL command to generate an alternative chain.
|
|
.IP "\fB\-xkey\fR \fIinfile\fR, \fB\-xcert\fR \fIinfile\fR, \fB\-xchain\fR" 4
|
|
.IX Item "-xkey infile, -xcert infile, -xchain"
|
|
Specify an extra certificate, private key and certificate chain. These behave
|
|
in the same manner as the \fB\-cert\fR, \fB\-key\fR and \fB\-cert_chain\fR options. When
|
|
specified, the callback returning the first valid chain will be in use by the
|
|
client.
|
|
.IP "\fB\-xchain_build\fR" 4
|
|
.IX Item "-xchain_build"
|
|
Specify whether the application should build the certificate chain to be
|
|
provided to the server for the extra certificates via the \fB\-xkey\fR,
|
|
\&\fB\-xcert\fR, and \fB\-xchain\fR options.
|
|
.IP "\fB\-xcertform\fR \fB\s-1DER\s0\fR|\fB\s-1PEM\s0\fR|\fBP12\fR" 4
|
|
.IX Item "-xcertform DER|PEM|P12"
|
|
The input format for the extra certificate.
|
|
This option has no effect and is retained for backward compatibility only.
|
|
.IP "\fB\-xkeyform\fR \fB\s-1DER\s0\fR|\fB\s-1PEM\s0\fR|\fBP12\fR" 4
|
|
.IX Item "-xkeyform DER|PEM|P12"
|
|
The input format for the extra key.
|
|
This option has no effect and is retained for backward compatibility only.
|
|
.SS "Certificate Extensions"
|
|
.IX Subsection "Certificate Extensions"
|
|
Options like \fB\-purpose\fR lead to checking the certificate extensions,
|
|
which determine what the target certificate and intermediate \s-1CA\s0 certificates
|
|
can be used for.
|
|
.PP
|
|
\fIBasic Constraints\fR
|
|
.IX Subsection "Basic Constraints"
|
|
.PP
|
|
The basicConstraints extension \s-1CA\s0 flag is used to determine whether the
|
|
certificate can be used as a \s-1CA.\s0 If the \s-1CA\s0 flag is true then it is a \s-1CA,\s0
|
|
if the \s-1CA\s0 flag is false then it is not a \s-1CA. \s0\fBAll\fR CAs should have the
|
|
\&\s-1CA\s0 flag set to true.
|
|
.PP
|
|
If the basicConstraints extension is absent,
|
|
which includes the case that it is an X.509v1 certificate,
|
|
then the certificate is considered to be a \*(L"possible \s-1CA\*(R"\s0 and
|
|
other extensions are checked according to the intended use of the certificate.
|
|
The treatment of certificates without basicConstraints as a \s-1CA\s0
|
|
is presently supported, but this could change in the future.
|
|
.PP
|
|
\fIKey Usage\fR
|
|
.IX Subsection "Key Usage"
|
|
.PP
|
|
If the keyUsage extension is present then additional restraints are
|
|
made on the uses of the certificate. A \s-1CA\s0 certificate \fBmust\fR have the
|
|
keyCertSign bit set if the keyUsage extension is present.
|
|
.PP
|
|
\fIExtended Key Usage\fR
|
|
.IX Subsection "Extended Key Usage"
|
|
.PP
|
|
The extKeyUsage (\s-1EKU\s0) extension places additional restrictions on the
|
|
certificate uses. If this extension is present (whether critical or not)
|
|
the key can only be used for the purposes specified.
|
|
.PP
|
|
A complete description of each check is given below. The comments about
|
|
basicConstraints and keyUsage and X.509v1 certificates above apply to \fBall\fR
|
|
\&\s-1CA\s0 certificates.
|
|
.IP "\fB\s-1SSL\s0 Client\fR" 4
|
|
.IX Item "SSL Client"
|
|
The extended key usage extension must be absent or include the \*(L"web client
|
|
authentication\*(R" \s-1OID. \s0 The keyUsage extension must be absent or it must have the
|
|
digitalSignature bit set. The Netscape certificate type must be absent
|
|
or it must have the \s-1SSL\s0 client bit set.
|
|
.IP "\fB\s-1SSL\s0 Client \s-1CA\s0\fR" 4
|
|
.IX Item "SSL Client CA"
|
|
The extended key usage extension must be absent or include the \*(L"web client
|
|
authentication\*(R" \s-1OID.\s0
|
|
The Netscape certificate type must be absent or it must have the \s-1SSL CA\s0 bit set.
|
|
This is used as a work around if the basicConstraints extension is absent.
|
|
.IP "\fB\s-1SSL\s0 Server\fR" 4
|
|
.IX Item "SSL Server"
|
|
The extended key usage extension must be absent or include the \*(L"web server
|
|
authentication\*(R" and/or one of the \s-1SGC\s0 OIDs. The keyUsage extension must be
|
|
absent or it
|
|
must have the digitalSignature, the keyEncipherment set or both bits set.
|
|
The Netscape certificate type must be absent or have the \s-1SSL\s0 server bit set.
|
|
.IP "\fB\s-1SSL\s0 Server \s-1CA\s0\fR" 4
|
|
.IX Item "SSL Server CA"
|
|
The extended key usage extension must be absent or include the \*(L"web server
|
|
authentication\*(R" and/or one of the \s-1SGC\s0 OIDs. The Netscape certificate type must
|
|
be absent or the \s-1SSL CA\s0 bit must be set.
|
|
This is used as a work around if the basicConstraints extension is absent.
|
|
.IP "\fBNetscape \s-1SSL\s0 Server\fR" 4
|
|
.IX Item "Netscape SSL Server"
|
|
For Netscape \s-1SSL\s0 clients to connect to an \s-1SSL\s0 server it must have the
|
|
keyEncipherment bit set if the keyUsage extension is present. This isn't
|
|
always valid because some cipher suites use the key for digital signing.
|
|
Otherwise it is the same as a normal \s-1SSL\s0 server.
|
|
.IP "\fBCommon S/MIME Client Tests\fR" 4
|
|
.IX Item "Common S/MIME Client Tests"
|
|
The extended key usage extension must be absent or include the \*(L"email
|
|
protection\*(R" \s-1OID. \s0 The Netscape certificate type must be absent or should have the
|
|
S/MIME bit set. If the S/MIME bit is not set in the Netscape certificate type
|
|
then the \s-1SSL\s0 client bit is tolerated as an alternative but a warning is shown.
|
|
This is because some Verisign certificates don't set the S/MIME bit.
|
|
.IP "\fBS/MIME Signing\fR" 4
|
|
.IX Item "S/MIME Signing"
|
|
In addition to the common S/MIME client tests the digitalSignature bit or
|
|
the nonRepudiation bit must be set if the keyUsage extension is present.
|
|
.IP "\fBS/MIME Encryption\fR" 4
|
|
.IX Item "S/MIME Encryption"
|
|
In addition to the common S/MIME tests the keyEncipherment bit must be set
|
|
if the keyUsage extension is present.
|
|
.IP "\fBS/MIME \s-1CA\s0\fR" 4
|
|
.IX Item "S/MIME CA"
|
|
The extended key usage extension must be absent or include the \*(L"email
|
|
protection\*(R" \s-1OID. \s0 The Netscape certificate type must be absent or must have the
|
|
S/MIME \s-1CA\s0 bit set.
|
|
This is used as a work around if the basicConstraints extension is absent.
|
|
.IP "\fB\s-1CRL\s0 Signing\fR" 4
|
|
.IX Item "CRL Signing"
|
|
The keyUsage extension must be absent or it must have the \s-1CRL\s0 signing bit
|
|
set.
|
|
.IP "\fB\s-1CRL\s0 Signing \s-1CA\s0\fR" 4
|
|
.IX Item "CRL Signing CA"
|
|
The normal \s-1CA\s0 tests apply. Except in this case the basicConstraints extension
|
|
must be present.
|
|
.SH "BUGS"
|
|
.IX Header "BUGS"
|
|
The issuer checks still suffer from limitations in the underlying X509_LOOKUP
|
|
\&\s-1API. \s0 One consequence of this is that trusted certificates with matching
|
|
subject name must appear in a file (as specified by the \fB\-CAfile\fR option),
|
|
a directory (as specified by \fB\-CApath\fR),
|
|
or a store (as specified by \fB\-CAstore\fR).
|
|
If there are multiple such matches, possibly in multiple locations,
|
|
only the first one (in the mentioned order of locations) is recognised.
|
|
.SH "SEE ALSO"
|
|
.IX Header "SEE ALSO"
|
|
\&\fIX509_verify_cert\fR\|(3),
|
|
\&\fIopenssl\-verify\fR\|(1),
|
|
\&\fIopenssl\-ocsp\fR\|(1),
|
|
\&\fIopenssl\-ts\fR\|(1),
|
|
\&\fIopenssl\-s_client\fR\|(1),
|
|
\&\fIopenssl\-s_server\fR\|(1),
|
|
\&\fIopenssl\-smime\fR\|(1),
|
|
\&\fIopenssl\-cmp\fR\|(1),
|
|
\&\fIopenssl\-cms\fR\|(1)
|
|
.SH "HISTORY"
|
|
.IX Header "HISTORY"
|
|
The checks enabled by \fB\-x509_strict\fR have been extended in OpenSSL 3.0.
|
|
.SH "COPYRIGHT"
|
|
.IX Header "COPYRIGHT"
|
|
Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved.
|
|
.PP
|
|
Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file \s-1LICENSE\s0 in the source distribution or at
|
|
<https://www.openssl.org/source/license.html>.
|