=head1 NAME
-X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, X509_VERIFY_PARAM_get_flags, X509_VERIFY_PARAM_set_purpose, X509_VERIFY_PARAM_set_trust, X509_VERIFY_PARAM_set_depth, X509_VERIFY_PARAM_get_depth, X509_VERIFY_PARAM_set_time, X509_VERIFY_PARAM_add0_policy, X509_VERIFY_PARAM_set1_policies - X509 verification parameters
+X509_VERIFY_PARAM_set_flags, X509_VERIFY_PARAM_clear_flags, X509_VERIFY_PARAM_get_flags, X509_VERIFY_PARAM_set_purpose, X509_VERIFY_PARAM_set_trust, X509_VERIFY_PARAM_set_depth, X509_VERIFY_PARAM_get_depth, X509_VERIFY_PARAM_set_time, X509_VERIFY_PARAM_add0_policy, X509_VERIFY_PARAM_set1_policies, X509_VERIFY_PARAM_set1_host, X509_VERIFY_PARAM_add1_host, X509_VERIFY_PARAM_set_hostflags, X509_VERIFY_PARAM_get0_peername, X509_VERIFY_PARAM_set1_email, X509_VERIFY_PARAM_set1_ip, X509_VERIFY_PARAM_set1_ip_asc - X509 verification parameters
=head1 SYNOPSIS
int X509_VERIFY_PARAM_get_depth(const X509_VERIFY_PARAM *param);
int X509_VERIFY_PARAM_set1_host(X509_VERIFY_PARAM *param,
- const unsigned char *name, size_t namelen);
+ const char *name, size_t namelen);
+ int X509_VERIFY_PARAM_add1_host(X509_VERIFY_PARAM *param,
+ const char *name, size_t namelen);
void X509_VERIFY_PARAM_set_hostflags(X509_VERIFY_PARAM *param,
unsigned int flags);
+ char *X509_VERIFY_PARAM_get0_peername(X509_VERIFY_PARAM *param);
int X509_VERIFY_PARAM_set1_email(X509_VERIFY_PARAM *param,
- const unsigned char *email, size_t emaillen);
+ const char *email, size_t emaillen);
int X509_VERIFY_PARAM_set1_ip(X509_VERIFY_PARAM *param,
const unsigned char *ip, size_t iplen);
- int X509_VERIFY_PARAM_set1_ip_asc(X509_VERIFY_PARAM *param,
- const char *ipasc);
+ int X509_VERIFY_PARAM_set1_ip_asc(X509_VERIFY_PARAM *param, const char *ipasc);
=head1 DESCRIPTION
That is the maximum number of untrusted CA certificates that can appear in a
chain.
-X509_VERIFY_PARAM_set1_host() sets the expected DNS hostname to B<name>. If
-B<name> is NUL-terminated, B<namelen> may be zero, otherwise B<namelen> must
-be set to the length of B<name>. When a hostname is specified, certificate
-verification automatically invokes L<X509_check_host(3)> with flags equal to
-the B<flags> argument given to B<X509_VERIFY_PARAM_set_hostflags()> (default
-zero). Applications are strongly advised to use this interface in preference
-to explicitly calling L<X509_check_host(3)>, hostname checks are
-out of scope with the DANE-EE(3) certificate usage, and the internal
-check will be suppressed as appropriate when DANE support is added
-to OpenSSL.
+X509_VERIFY_PARAM_set1_host() sets the expected DNS hostname to
+B<name> clearing any previously specified host name or names. If
+B<name> is NULL, or empty the list of hostnames is cleared, and
+name checks are not performed on the peer certificate. If B<name>
+is NUL-terminated, B<namelen> may be zero, otherwise B<namelen>
+must be set to the length of B<name>. When a hostname is specified,
+certificate verification automatically invokes L<X509_check_host(3)>
+with flags equal to the B<flags> argument given to
+X509_VERIFY_PARAM_set_hostflags() (default zero). Applications
+are strongly advised to use this interface in preference to explicitly
+calling L<X509_check_host(3)>, hostname checks are out of scope
+with the DANE-EE(3) certificate usage, and the internal check will
+be suppressed as appropriate when DANE support is added to OpenSSL.
+
+X509_VERIFY_PARAM_add1_host() adds B<name> as an additional reference
+identifier that can match the peer's certificate. Any previous names
+set via X509_VERIFY_PARAM_set1_host() or X509_VERIFY_PARAM_add1_host()
+are retained, no change is made if B<name> is NULL or empty. When
+multiple names are configured, the peer is considered verified when
+any name matches.
+
+X509_VERIFY_PARAM_get0_peername() returns the DNS hostname or subject
+CommonName from the peer certificate that matched one of the reference
+identifiers. When wildcard matching is not disabled, or when a
+reference identifier specifies a parent domain (starts with ".")
+rather than a hostname, the peer name may be a wildcard name or a
+sub-domain of the reference identifier respectively. The return
+string is allocated by the library and is no longer valid once the
+associated B<param> argument is freed. Applications must not free
+the return value.
X509_VERIFY_PARAM_set1_email() sets the expected RFC822 email address to
-B<email>. If B<email is NUL-terminated, B<emaillen> may be zero, otherwise
+B<email>. If B<email> is NUL-terminated, B<emaillen> may be zero, otherwise
B<emaillen> must be set to the length of B<email>. When an email address
is specified, certificate verification automatically invokes
L<X509_check_email(3)>.
X509_VERIFY_PARAM_set_flags(), X509_VERIFY_PARAM_clear_flags(),
X509_VERIFY_PARAM_set_purpose(), X509_VERIFY_PARAM_set_trust(),
X509_VERIFY_PARAM_add0_policy() X509_VERIFY_PARAM_set1_policies(),
-X509_VERIFY_PARAM_set1_host(), X509_VERIFY_PARAM_set_hostflags(),
+X509_VERIFY_PARAM_set1_host(), X509_VERIFY_PARAM_add1_host(),
X509_VERIFY_PARAM_set1_email(), X509_VERIFY_PARAM_set1_ip() and
X509_VERIFY_PARAM_set1_ip_asc() return 1 for success and 0 for
failure.
purposes can be a security risk. Finer control over which extensions are
supported can be performed in the verification callback.
-THe B<X509_V_FLAG_X509_STRICT> flag disables workarounds for some broken
+The B<X509_V_FLAG_X509_STRICT> flag disables workarounds for some broken
certificates and makes the verification strictly apply B<X509> rules.
B<X509_V_FLAG_ALLOW_PROXY_CERTS> enables proxy certificate verification.
B<X509_V_FLAG_POLICY_CHECK> enables certificate policy checking, by default
-no policy checking is peformed. Additional information is sent to the
+no policy checking is performed. Additional information is sent to the
verification callback relating to policy checking.
B<X509_V_FLAG_EXPLICIT_POLICY>, B<X509_V_FLAG_INHIBIT_ANY> and
different keys are disabled. If B<X509_V_FLAG_EXTENDED_CRL_SUPPORT> is set
they are enabled.
-If B<X509_V_FLAG_USE_DELTAS> ise set delta CRLs (if present) are used to
+If B<X509_V_FLAG_USE_DELTAS> is set delta CRLs (if present) are used to
determine certificate status. If not set deltas are ignored.
B<X509_V_FLAG_CHECK_SS_SIGNATURE> enables checking of the root CA self signed
-cerificate signature. By default this check is disabled because it doesn't
+certificate signature. By default this check is disabled because it doesn't
add any additional security but in some cases applications might want to
check the signature anyway. A side effect of not checking the root CA
signature is that disabled or unsupported message digests on the root CA
to the verification callback and it B<must> be prepared to handle such cases
without assuming they are hard errors.
+If B<X509_V_FLAG_TRUSTED_FIRST> is set, when constructing the certificate chain,
+L<X509_verify_cert(3)> will search the trust store for issuer certificates before
+searching the provided untrusted certificates.
+As of OpenSSL 1.1.0 this option is on by default and cannot be disabled.
+
+The B<X509_V_FLAG_NO_ALT_CHAINS> flag suppresses checking for alternative
+chains.
+By default, unless B<X509_V_FLAG_TRUSTED_FIRST> is set, when building a
+certificate chain, if the first certificate chain found is not trusted, then
+OpenSSL will attempt to replace untrusted certificates supplied by the peer
+with certificates from the trust store to see if an alternative chain can be
+found that is trusted.
+As of OpenSSL 1.1.0, with B<X509_V_FLAG_TRUSTED_FIRST> always set, this option
+has no effect.
+
+The B<X509_V_FLAG_NO_CHECK_TIME> flag suppresses checking the validity period
+of certificates and CRLs against the current time. If X509_VERIFY_PARAM_set_time()
+is used to specify a verification time, the check is not suppressed.
+
=head1 NOTES
The above functions should be used to manipulate verification parameters
=head1 SEE ALSO
-L<X509_verify_cert(3)|X509_verify_cert(3)>
+L<X509_verify_cert(3)>,
+L<X509_check_host(3)>,
+L<X509_check_email(3)>,
+L<X509_check_ip(3)>
=head1 HISTORY
-TBA
+The B<X509_V_FLAG_NO_ALT_CHAINS> flag was added in OpenSSL 1.1.0
=cut
projects / openssl.git / blobdiff