Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help

       openssl-verification-options - generic X.509 certificate	verification

       openssl command [ options ... ] [ parameters ...	]

       Many OpenSSL commands and various other uses of the crypto library
       function	X509_verify_cert(3) verify X.509 certificates. The details of
       how each	command	handles	errors are documented on the specific command

       Certificate verification	is a complicated process, consisting of	a
       number of separate steps	that are detailed in the following paragraphs.

       First, a	certificate chain is built up starting from the	target
       certificate and typically ending	in a self-signed "root"	CA
       certificate.  It	is an error if the whole chain cannot be built up
       unless the -partial_chain option	is given.  The chain is	built up
       iteratively, looking up in turn the certificate of the signer
       ("issuer") of the current certificate.  If a certificate	is found that
       appears to be its own issuer it is assumed to be	the self-signed	root,
       which must be trusted.

       The process of looking up the issuer's certificate itself involves a
       number of steps.	 All available certificates with a subject name	that
       matches the issuer name of the current certificate are subject to
       further tests.  The relevant authority key identifier components	of the
       current certificate (if present)	must match the subject key identifier
       (if present) and	issuer and serial number of the	candidate issuer
       certificate.  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.

       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
       "intermediate" CA certificates (if provided).  The last certificate
       (which typically	is of a	root CA) is always looked up in	the trusted
       certificate list; an exact match	must be	found there.

       The second step is to check the extensions of every untrusted
       certificate for consistency with	the supplied purpose.  If the -purpose
       option is not included then no checks are done.	The target or "leaf"
       certificate must	have extensions	compatible with	the supplied purpose
       and all other certificates must also be valid CA	certificates.  The
       precise extensions required are described in more detail	in
       "CERTIFICATE EXTENSIONS"	in openssl-x509(1).

       The third step is to check the trust settings on	the last certficate,
       typically of a root CA.	It should be trusted for the supplied purpose.
       For compatibility with previous versions	of OpenSSL, a certificate with
       no trust	settings is considered to be valid for all purposes.

       The fourth, and final, step is to check the validity of the certificate
       chain.  For each	element	in the chain, including	the root CA
       certificate, the	validity period	as specified by	the "notBefore"	and
       "notAfter" fields is checked against the	current	system time.  The
       -attime flag may	be used	to use a reference time	other than "now."  The
       certificate signature is	checked	as well	(except	for the	signature of
       the typically self-signed root CA certificate, which is verified	only
       if the -check_ss_sig 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

   Trusted Certificate Options
       The following options specify how to select the trusted root
       certificates, also known	as trust anchors.  A collection	of trusted
       roots is	called a trust store.

       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

       The certificates	to trust can be	specified using	following options.

       -CAfile file
	   Load	the specified file which contains one or more PEM-format
	   certificates	of CA's	that are trusted.

	   Do not load the default file	of trusted certificates.

       -CApath dir
	   Use the specified directory as a list of trust certificates.	That
	   is, files should be named with the hash 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 openssl-rehash(1) for information on creating
	   this	type of	directory.

	   Do not use the default directory of trusted certificates.

       -CAstore	uri
	   Use uri as a	store of trusted CA certificates.  The URI may
	   indicate a single certificate, as well as a collection of them.
	   With	URIs in	the "file:" scheme, this acts as -CAfile or -CApath,
	   depending on	if the URI indicates a single file or directory.  See
	   ossl_store-file(7) for more information on the "file:" scheme.

	   These certificates are also used when building the server
	   certificate chain (for example with openssl-s_server(1)) or client
	   certificate chain (for example with openssl-s_time(1)).

	   Do not use the default store.

   Verification	Options
       The certificate verification can	be fine-tuned with the following

	   Print extra information about the operations	being performed.

       -attime timestamp
	   Perform validation checks using time	specified by timestamp and not
	   current system time.	timestamp is the number	of seconds since
	   January 1, 1970 (i.e., the Unix Epoch).

	   This	option suppresses checking the validity	period of certificates
	   and CRLs against the	current	time. If option	-attime	is used	to
	   specify a verification time,	the check is not suppressed.

	   This	disables non-compliant workarounds for broken certificates.
	   Thus	errors are thrown on certificates not compliant	with RFC 5280.

	   When	this option is set, among others, the following	certificate
	   well-formedness conditions are checked:

	   -   The basicConstraints of CA certificates must be marked

	   -   CA certificates must explicitly include the keyUsage extension.

	   -   If a pathlenConstraint is given the key usage keyCertSign must
	       be allowed.

	   -   The pathlenConstraint must not be given for non-CA

	   -   The issuer name of any certificate must not be empty.

	   -   The subject name	of CA certs, certs with	keyUsage crlSign, and
	       certs without subjectAlternativeName must not be	empty.

	   -   If a subjectAlternativeName extension is	given it must not be

	   -   The signatureAlgorithm field and	the cert signature must	be

	   -   Any given authorityKeyIdentifier	and any	given
	       subjectKeyIdentifier must not be	marked critical.

	   -   The authorityKeyIdentifier must be given	for X.509v3 certs
	       unless they are self-signed.

	   -   The subjectKeyIdentifier	must be	given for all X.509v3 CA

	   Normally if an unhandled critical extension is present that is not
	   supported by	OpenSSL	the certificate	is rejected (as	required by
	   RFC5280).  If this option is	set critical extensions	are ignored.


	   Checks end entity certificate validity by attempting	to look	up a
	   valid CRL.  If a valid CRL cannot be	found an error occurs.

	   Checks the validity of all certificates in the chain	by attempting
	   to look up valid CRLs.

	   Enable support for delta CRLs.

	   Enable extended CRL features	such as	indirect CRLs and alternate
	   CRL signing keys.

       -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 RFC6460 for details. In particular the supported	signature
	   algorithms are reduced to support only ECDSA	and SHA256 or SHA384
	   and only the	elliptic curves	P-256 and P-384.

       -auth_level level
	   Set the certificate chain authentication security level to level.
	   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 level.	 The
	   signature algorithm security	level is enforced for all the
	   certificates	in the chain except for	the chain's trust anchor,
	   which is either directly trusted or validated by means other	than
	   its signature.  See SSL_CTX_set_security_level(3) for the
	   definitions of the available	levels.	 The default security level is
	   -1, or "not set".  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 MD5 signatures or RSA	keys shorter than 1024 bits.

	   Allow verification to succeed even if a complete chain cannot be
	   built to a self-signed trust-anchor,	provided it is possible	to
	   construct a chain to	a trusted certificate that might not be	self-
	   signed.  This certificate may be self-issued	or belong to an
	   intermediate	CA.

	   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	CA certificate with
	   key usage restrictions not including	the keyCertSign	bit.  This
	   verification	is disabled by default because it doesn't add any

	   Allow the verification of proxy certificates.

	   As of OpenSSL 1.1.0 this option is on by default and	cannot be

	   When	constructing the certificate chain, the	trusted	certificates
	   specified via -CAfile, -CApath, -CAstore or -trusted	are always
	   used	before any certificates	specified via -untrusted.

	   As of OpenSSL 1.1.0,	since -trusted_first always on,	this option
	   has no effect.

       -trusted	file
	   Parse file as a set of one or more certificates in PEM format.  All
	   certificates	must be	self-signed, unless the	-partial_chain option
	   is specified.  This option implies the -no-CAfile, -no-CApath, and
	   -no-CAstore options and it cannot be	used with the -CAfile, -CApath
	   or -CAstore options,	so only	certificates in	the file are trust
	   anchors.  This option may be	used multiple times.

       -untrusted file
	   Parse file as a set of one or more certificates in PEM format.  All
	   certificates	are untrusted certificates (typically of intermedate
	   CAs)	that may be used to construct a	certificate chain from the
	   subject certificate to a trust anchor.  This	option may be used
	   multiple times.

       -policy arg
	   Enable policy processing and	add arg	to the user-initial-policy-set
	   (see	RFC5280). The policy arg can be	an object name an OID in
	   numeric form.  This argument	can appear more	than once.

	   Set policy variable require-explicit-policy (see RFC5280).

	   Enables certificate policy processing.

	   Print out diagnostics related to policy processing.

	   Set policy variable inhibit-any-policy (see RFC5280).

	   Set policy variable inhibit-policy-mapping (see RFC5280).

       -purpose	purpose
	   The intended	use for	the certificate. If this option	is not
	   specified, this command will	not consider certificate purpose
	   during chain	verification.  Currently accepted uses are sslclient,
	   sslserver, nssslserver, smimesign, smimeencrypt.

       -verify_depth num
	   Limit the certificate chain to num intermediate CA certificates.  A
	   maximal depth chain can have	up to num+2 certificates, since
	   neither the end-entity certificate nor the trust-anchor certificate
	   count against the -verify_depth limit.

       -verify_email email
	   Verify if email matches the email address in	Subject	Alternative
	   Name	or the email in	the subject Distinguished Name.

       -verify_hostname	hostname
	   Verify if hostname matches DNS name in Subject Alternative Name or
	   Common Name in the subject certificate.

       -verify_ip ip
	   Verify if ip	matches	the IP address in Subject Alternative Name of
	   the subject certificate.

       -verify_name name
	   Use default verification policies like trust	model and required
	   certificate policies	identified by name.  The trust model
	   determines which auxiliary trust or reject OIDs are applicable to
	   verifying the given certificate chain.  See the -addtrust and
	   -addreject options for openssl-x509(1).  Supported policy names
	   include: default, pkcs7, smime_sign,	ssl_client, ssl_server.	 These
	   mimics the combinations of purpose and trust	settings used in SSL,
	   CMS and S/MIME.  As of OpenSSL 1.1.0, the trust model is inferred
	   from	the purpose when not specified,	so the -verify_name options
	   are functionally equivalent to the corresponding -purpose settings.

   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 CA signs a certificate for another a CA in other
       organization.  Another reason is	when a CA might	have intermediates
       that use	two different signature	formats, such as a SHA-1 and a SHA-256

       The following options can be used to provide data that will allow the
       OpenSSL command to generate an alternative chain.

       -xkey infile, -xcert infile, -xchain
	   Specify an extra certificate, private key and certificate chain.
	   These behave	in the same manner as the -cert, -key and -cert_chain
	   options.  When specified, the callback returning the	first valid
	   chain will be in use	by the client.

	   Specify whether the application should build	the certificate	chain
	   to be provided to the server	for the	extra certificates via the
	   -xkey, -xcert, and -xchain options.

       -xcertform DER|PEM|P12
	   The input format for	the extra certificate.	This option has	no
	   effect and is retained for backward compatibility only.

       -xkeyform DER|PEM|P12
	   The input format for	the extra key.	This option has	no effect and
	   is retained for backward compatibility only.

       X509_verify_cert(3), openssl-verify(1), openssl-ocsp(1),	openssl-ts(1),
       openssl-s_client(1), openssl-s_server(1), openssl-smime(1),
       openssl-cmp(1), openssl-cms(1)

       The checks enabled by -x509_strict have been extended in	OpenSSL	3.0.

       Copyright 2000-2021 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

3.0.0-alpha12			  2021-02-18   OPENSSL-VERIFICATION-OPTIONS(1)


Want to link to this manual page? Use this URL:

home | help