← Back
Editing: X509_VERIFY_PARAM_set_purpose.3
.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35) .\" .\" 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 >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 .\" .\" 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 "X509_VERIFY_PARAM_set_flags 3" .TH X509_VERIFY_PARAM_set_flags 3 "2019-12-20" "1.0.2u" "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" 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 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include <openssl/x509_vfy.h> \& \& int X509_VERIFY_PARAM_set_flags(X509_VERIFY_PARAM *param, unsigned long flags); \& int X509_VERIFY_PARAM_clear_flags(X509_VERIFY_PARAM *param, \& unsigned long flags); \& unsigned long X509_VERIFY_PARAM_get_flags(X509_VERIFY_PARAM *param); \& \& int X509_VERIFY_PARAM_set_purpose(X509_VERIFY_PARAM *param, int purpose); \& int X509_VERIFY_PARAM_set_trust(X509_VERIFY_PARAM *param, int trust); \& \& void X509_VERIFY_PARAM_set_time(X509_VERIFY_PARAM *param, time_t t); \& \& int X509_VERIFY_PARAM_add0_policy(X509_VERIFY_PARAM *param, \& ASN1_OBJECT *policy); \& int X509_VERIFY_PARAM_set1_policies(X509_VERIFY_PARAM *param, \& STACK_OF(ASN1_OBJECT) *policies); \& \& void X509_VERIFY_PARAM_set_depth(X509_VERIFY_PARAM *param, int depth); \& int X509_VERIFY_PARAM_get_depth(const X509_VERIFY_PARAM *param); \& \& int X509_VERIFY_PARAM_set1_host(X509_VERIFY_PARAM *param, \& 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 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); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" These functions manipulate the \fBX509_VERIFY_PARAM\fR structure associated with a certificate verification operation. .PP The \fBX509_VERIFY_PARAM_set_flags()\fR function sets the flags in \fBparam\fR by oring it with \fBflags\fR. See the \fB\s-1VERIFICATION FLAGS\s0\fR section for a complete description of values the \fBflags\fR parameter can take. .PP \&\fBX509_VERIFY_PARAM_get_flags()\fR returns the flags in \fBparam\fR. .PP \&\fBX509_VERIFY_PARAM_clear_flags()\fR clears the flags \fBflags\fR in \fBparam\fR. .PP \&\fBX509_VERIFY_PARAM_set_purpose()\fR sets the verification purpose in \fBparam\fR to \fBpurpose\fR. This determines the acceptable purpose of the certificate chain, for example \s-1SSL\s0 client or \s-1SSL\s0 server. .PP \&\fBX509_VERIFY_PARAM_set_trust()\fR sets the trust setting in \fBparam\fR to \&\fBtrust\fR. .PP \&\fBX509_VERIFY_PARAM_set_time()\fR sets the verification time in \fBparam\fR to \&\fBt\fR. Normally the current time is used. .PP \&\fBX509_VERIFY_PARAM_add0_policy()\fR enables policy checking (it is disabled by default) and adds \fBpolicy\fR to the acceptable policy set. .PP \&\fBX509_VERIFY_PARAM_set1_policies()\fR enables policy checking (it is disabled by default) and sets the acceptable policy set to \fBpolicies\fR. Any existing policy set is cleared. The \fBpolicies\fR parameter can be \fB\s-1NULL\s0\fR to clear an existing policy set. .PP \&\fBX509_VERIFY_PARAM_set_depth()\fR sets the maximum verification depth to \fBdepth\fR. That is the maximum number of untrusted \s-1CA\s0 certificates that can appear in a chain. .PP \&\fBX509_VERIFY_PARAM_set1_host()\fR sets the expected \s-1DNS\s0 hostname to \&\fBname\fR clearing any previously specified host name or names. If \&\fBname\fR is \s-1NULL,\s0 or empty the list of hostnames is cleared, and name checks are not performed on the peer certificate. If \fBname\fR is NUL-terminated, \fBnamelen\fR may be zero, otherwise \fBnamelen\fR must be set to the length of \fBname\fR. When a hostname is specified, certificate verification automatically invokes \fBX509_check_host\fR\|(3) with flags equal to the \fBflags\fR argument given to \&\fB\fBX509_VERIFY_PARAM_set_hostflags()\fB\fR (default zero). Applications are strongly advised to use this interface in preference to explicitly calling \fBX509_check_host\fR\|(3), hostname checks are out of scope with the \s-1\fBDANE\-EE\s0\fR\|(3) certificate usage, and the internal check will be suppressed as appropriate when \s-1DANE\s0 support is added to OpenSSL. .PP \&\fBX509_VERIFY_PARAM_add1_host()\fR adds \fBname\fR as an additional reference identifer that can match the peer's certificate. Any previous names set via \fBX509_VERIFY_PARAM_set1_host()\fR or \fBX509_VERIFY_PARAM_add1_host()\fR are retained, no change is made if \fBname\fR is \s-1NULL\s0 or empty. When multiple names are configured, the peer is considered verified when any name matches. .PP \&\fBX509_VERIFY_PARAM_get0_peername()\fR returns the \s-1DNS\s0 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 \*(L".\*(R") 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 \fBparam\fR argument is freed. Applications must not free the return value. .PP \&\fBX509_VERIFY_PARAM_set1_email()\fR sets the expected \s-1RFC822\s0 email address to \&\fBemail\fR. If \fBemail\fR is NUL-terminated, \fBemaillen\fR may be zero, otherwise \&\fBemaillen\fR must be set to the length of \fBemail\fR. When an email address is specified, certificate verification automatically invokes \&\fBX509_check_email\fR\|(3). .PP \&\fBX509_VERIFY_PARAM_set1_ip()\fR sets the expected \s-1IP\s0 address to \fBip\fR. The \fBip\fR argument is in binary format, in network byte-order and \&\fBiplen\fR must be set to 4 for IPv4 and 16 for IPv6. When an \s-1IP\s0 address is specified, certificate verification automatically invokes \&\fBX509_check_ip\fR\|(3). .PP \&\fBX509_VERIFY_PARAM_set1_ip_asc()\fR sets the expected \s-1IP\s0 address to \&\fBipasc\fR. The \fBipasc\fR argument is a NUL-terminal \s-1ASCII\s0 string: dotted decimal quad for IPv4 and colon-separated hexadecimal for IPv6. The condensed \*(L"::\*(R" notation is supported for IPv6 addresses. .SH "RETURN VALUES" .IX Header "RETURN VALUES" \&\fBX509_VERIFY_PARAM_set_flags()\fR, \fBX509_VERIFY_PARAM_clear_flags()\fR, \&\fBX509_VERIFY_PARAM_set_purpose()\fR, \fBX509_VERIFY_PARAM_set_trust()\fR, \&\fBX509_VERIFY_PARAM_add0_policy()\fR \fBX509_VERIFY_PARAM_set1_policies()\fR, \&\fBX509_VERIFY_PARAM_set1_host()\fR, \fBX509_VERIFY_PARAM_set_hostflags()\fR, \&\fBX509_VERIFY_PARAM_set1_email()\fR, \fBX509_VERIFY_PARAM_set1_ip()\fR and \&\fBX509_VERIFY_PARAM_set1_ip_asc()\fR return 1 for success and 0 for failure. .PP \&\fBX509_VERIFY_PARAM_get_flags()\fR returns the current verification flags. .PP \&\fBX509_VERIFY_PARAM_set_time()\fR and \fBX509_VERIFY_PARAM_set_depth()\fR do not return values. .PP \&\fBX509_VERIFY_PARAM_get_depth()\fR returns the current verification depth. .SH "VERIFICATION FLAGS" .IX Header "VERIFICATION FLAGS" The verification flags consists of zero or more of the following flags ored together. .PP \&\fBX509_V_FLAG_CRL_CHECK\fR enables \s-1CRL\s0 checking for the certificate chain leaf certificate. An error occurs if a suitable \s-1CRL\s0 cannot be found. .PP \&\fBX509_V_FLAG_CRL_CHECK_ALL\fR enables \s-1CRL\s0 checking for the entire certificate chain. .PP \&\fBX509_V_FLAG_IGNORE_CRITICAL\fR disabled critical extension checking. By default any unhandled critical extensions in certificates or (if checked) CRLs results in a fatal error. If this flag is set unhandled critical extensions are ignored. \fB\s-1WARNING\s0\fR setting this option for anything other than debugging purposes can be a security risk. Finer control over which extensions are supported can be performed in the verification callback. .PP THe \fBX509_V_FLAG_X509_STRICT\fR flag disables workarounds for some broken certificates and makes the verification strictly apply \fBX509\fR rules. .PP \&\fBX509_V_FLAG_ALLOW_PROXY_CERTS\fR enables proxy certificate verification. .PP \&\fBX509_V_FLAG_POLICY_CHECK\fR enables certificate policy checking, by default no policy checking is peformed. Additional information is sent to the verification callback relating to policy checking. .PP \&\fBX509_V_FLAG_EXPLICIT_POLICY\fR, \fBX509_V_FLAG_INHIBIT_ANY\fR and \&\fBX509_V_FLAG_INHIBIT_MAP\fR set the \fBrequire explicit policy\fR, \fBinhibit any policy\fR and \fBinhibit policy mapping\fR flags respectively as defined in \&\fB\s-1RFC3280\s0\fR. Policy checking is automatically enabled if any of these flags are set. .PP If \fBX509_V_FLAG_NOTIFY_POLICY\fR is set and the policy checking is successful a special status code is set to the verification callback. This permits it to examine the valid policy tree and perform additional checks or simply log it for debugging purposes. .PP By default some additional features such as indirect CRLs and CRLs signed by different keys are disabled. If \fBX509_V_FLAG_EXTENDED_CRL_SUPPORT\fR is set they are enabled. .PP If \fBX509_V_FLAG_USE_DELTAS\fR ise set delta CRLs (if present) are used to determine certificate status. If not set deltas are ignored. .PP \&\fBX509_V_FLAG_CHECK_SS_SIGNATURE\fR enables checking of the root \s-1CA\s0 self signed cerificate 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 \s-1CA\s0 signature is that disabled or unsupported message digests on the root \s-1CA\s0 are not treated as fatal errors. .PP The \fBX509_V_FLAG_CB_ISSUER_CHECK\fR flag enables debugging of certificate issuer checks. It is \fBnot\fR needed unless you are logging certificate verification. If this flag is set then additional status codes will be sent to the verification callback and it \fBmust\fR be prepared to handle such cases without assuming they are hard errors. .PP The \fBX509_V_FLAG_NO_ALT_CHAINS\fR flag suppresses checking for alternative chains. By default, when building a certificate chain, if the first certificate chain found is not trusted, then OpenSSL will continue to check to see if an alternative chain can be found that is trusted. With this flag set the behaviour will match that of OpenSSL versions prior to 1.0.2b. .PP The \fBX509_V_FLAG_TRUSTED_FIRST\fR flag causes chain construction to look for issuers in the trust store before looking at the untrusted certificates provided as part of the the peer chain. Though it is not on by default in OpenSSL 1.0.2, applications should generally set this flag. Local issuer certificates are often more likely to satisfy local security requirements and lead to a locally trusted root. This is especially important When some certificates in the trust store have explicit trust settings (see \*(L"\s-1TRUST SETTINGS\*(R"\s0 in \fBx509\fR\|(1)). .PP The \fBX509_V_FLAG_PARTIAL_CHAIN\fR flag causes intermediate certificates in the trust store to be treated as trust-anchors, in the same way as the self-signed root \s-1CA\s0 certificates. This makes it possible to trust certificates issued by an intermediate \s-1CA\s0 without having to trust its ancestor root \s-1CA.\s0 With OpenSSL 1.0.2, chain construction continues as long as there are additional trusted issuers in the trust store, and the last trusted issuer becomes the trust-anchor. Thus, even when an intermediate certificate is found in the trust store, the verified chain passed to callbacks may still be anchored by a root \s-1CA.\s0 .SH "NOTES" .IX Header "NOTES" The above functions should be used to manipulate verification parameters instead of legacy functions which work in specific structures such as \&\fBX509_STORE_CTX_set_flags()\fR. .SH "BUGS" .IX Header "BUGS" Delta \s-1CRL\s0 checking is currently primitive. Only a single delta can be used and (partly due to limitations of \fBX509_STORE\fR) constructed CRLs are not maintained. .PP If CRLs checking is enable CRLs are expected to be available in the corresponding \fBX509_STORE\fR structure. No attempt is made to download CRLs from the \s-1CRL\s0 distribution points extension. .SH "EXAMPLE" .IX Header "EXAMPLE" Enable \s-1CRL\s0 checking when performing certificate verification during \s-1SSL\s0 connections associated with an \fB\s-1SSL_CTX\s0\fR structure \fBctx\fR: .PP .Vb 5 \& X509_VERIFY_PARAM *param; \& param = X509_VERIFY_PARAM_new(); \& X509_VERIFY_PARAM_set_flags(param, X509_V_FLAG_CRL_CHECK); \& SSL_CTX_set1_param(ctx, param); \& X509_VERIFY_PARAM_free(param); .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBX509_verify_cert\fR\|(3), \&\fBX509_check_host\fR\|(3), \&\fBX509_check_email\fR\|(3), \&\fBX509_check_ip\fR\|(3), \&\fBx509\fR\|(1) .SH "HISTORY" .IX Header "HISTORY" The \fBX509_V_FLAG_NO_ALT_CHAINS\fR flag was added in OpenSSL 1.0.2b
Save File
Cancel