secure/lib/libcrypto/man/SSL_CTX_add1_chain_cert.3

   1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "SSL_CTX_ADD1_CHAIN_CERT 3"
 132 .TH SSL_CTX_ADD1_CHAIN_CERT 3 "2018-11-20" "1.1.1a" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 SSL_CTX_set0_chain, SSL_CTX_set1_chain, SSL_CTX_add0_chain_cert, SSL_CTX_add1_chain_cert, SSL_CTX_get0_chain_certs, SSL_CTX_clear_chain_certs, SSL_set0_chain, SSL_set1_chain, SSL_add0_chain_cert, SSL_add1_chain_cert, SSL_get0_chain_certs, SSL_clear_chain_certs, SSL_CTX_build_cert_chain, SSL_build_cert_chain, SSL_CTX_select_current_cert, SSL_select_current_cert, SSL_CTX_set_current_cert, SSL_set_current_cert \- extra chain certificate processing
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/ssl.h>
 143 \&
 144 \& int SSL_CTX_set0_chain(SSL_CTX *ctx, STACK_OF(X509) *sk);
 145 \& int SSL_CTX_set1_chain(SSL_CTX *ctx, STACK_OF(X509) *sk);
 146 \& int SSL_CTX_add0_chain_cert(SSL_CTX *ctx, X509 *x509);
 147 \& int SSL_CTX_add1_chain_cert(SSL_CTX *ctx, X509 *x509);
 148 \& int SSL_CTX_get0_chain_certs(SSL_CTX *ctx, STACK_OF(X509) **sk);
 149 \& int SSL_CTX_clear_chain_certs(SSL_CTX *ctx);
 150 \&
 151 \& int SSL_set0_chain(SSL *ssl, STACK_OF(X509) *sk);
 152 \& int SSL_set1_chain(SSL *ssl, STACK_OF(X509) *sk);
 153 \& int SSL_add0_chain_cert(SSL *ssl, X509 *x509);
 154 \& int SSL_add1_chain_cert(SSL *ssl, X509 *x509);
 155 \& int SSL_get0_chain_certs(SSL *ssl, STACK_OF(X509) **sk);
 156 \& int SSL_clear_chain_certs(SSL *ssl);
 157 \&
 158 \& int SSL_CTX_build_cert_chain(SSL_CTX *ctx, flags);
 159 \& int SSL_build_cert_chain(SSL *ssl, flags);
 160 \&
 161 \& int SSL_CTX_select_current_cert(SSL_CTX *ctx, X509 *x509);
 162 \& int SSL_select_current_cert(SSL *ssl, X509 *x509);
 163 \& int SSL_CTX_set_current_cert(SSL_CTX *ctx, long op);
 164 \& int SSL_set_current_cert(SSL *ssl, long op);
 165 .Ve
 166 .SH "DESCRIPTION"
 167 .IX Header "DESCRIPTION"
 168 \&\fISSL_CTX_set0_chain()\fR and \fISSL_CTX_set1_chain()\fR set the certificate chain
 169 associated with the current certificate of \fBctx\fR to \fBsk\fR.
 170 .PP
 171 \&\fISSL_CTX_add0_chain_cert()\fR and \fISSL_CTX_add1_chain_cert()\fR append the single
 172 certificate \fBx509\fR to the chain associated with the current certificate of
 173 \&\fBctx\fR.
 174 .PP
 175 \&\fISSL_CTX_get0_chain_certs()\fR retrieves the chain associated with the current
 176 certificate of \fBctx\fR.
 177 .PP
 178 \&\fISSL_CTX_clear_chain_certs()\fR clears any existing chain associated with the
 179 current certificate of \fBctx\fR.  (This is implemented by calling
 180 \&\fISSL_CTX_set0_chain()\fR with \fBsk\fR set to \fB\s-1NULL\s0\fR).
 181 .PP
 182 \&\fISSL_CTX_build_cert_chain()\fR builds the certificate chain for \fBctx\fR normally
 183 this uses the chain store or the verify store if the chain store is not set.
 184 If the function is successful the built chain will replace any existing chain.
 185 The \fBflags\fR parameter can be set to \fB\s-1SSL_BUILD_CHAIN_FLAG_UNTRUSTED\s0\fR to use
 186 existing chain certificates as untrusted CAs, \fB\s-1SSL_BUILD_CHAIN_FLAG_NO_ROOT\s0\fR
 187 to omit the root \s-1CA\s0 from the built chain, \fB\s-1SSL_BUILD_CHAIN_FLAG_CHECK\s0\fR to
 188 use all existing chain certificates only to build the chain (effectively
 189 sanity checking and rearranging them if necessary), the flag
 190 \&\fB\s-1SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR\s0\fR ignores any errors during verification:
 191 if flag \fB\s-1SSL_BUILD_CHAIN_FLAG_CLEAR_ERROR\s0\fR is also set verification errors
 192 are cleared from the error queue.
 193 .PP
 194 Each of these functions operates on the \fIcurrent\fR end entity
 195 (i.e. server or client) certificate. This is the last certificate loaded or
 196 selected on the corresponding \fBctx\fR structure.
 197 .PP
 198 \&\fISSL_CTX_select_current_cert()\fR selects \fBx509\fR as the current end entity
 199 certificate, but only if \fBx509\fR has already been loaded into \fBctx\fR using a
 200 function such as \fISSL_CTX_use_certificate()\fR.
 201 .PP
 202 \&\fISSL_set0_chain()\fR, \fISSL_set1_chain()\fR, \fISSL_add0_chain_cert()\fR,
 203 \&\fISSL_add1_chain_cert()\fR, \fISSL_get0_chain_certs()\fR, \fISSL_clear_chain_certs()\fR,
 204 \&\fISSL_build_cert_chain()\fR, \fISSL_select_current_cert()\fR and \fISSL_set_current_cert()\fR
 205 are similar except they apply to \s-1SSL\s0 structure \fBssl\fR.
 206 .PP
 207 \&\fISSL_CTX_set_current_cert()\fR changes the current certificate to a value based
 208 on the \fBop\fR argument. Currently \fBop\fR can be \fB\s-1SSL_CERT_SET_FIRST\s0\fR to use
 209 the first valid certificate or \fB\s-1SSL_CERT_SET_NEXT\s0\fR to set the next valid
 210 certificate after the current certificate. These two operations can be
 211 used to iterate over all certificates in an \fB\s-1SSL_CTX\s0\fR structure.
 212 .PP
 213 \&\fISSL_set_current_cert()\fR also supports the option \fB\s-1SSL_CERT_SET_SERVER\s0\fR.
 214 If \fBssl\fR is a server and has sent a certificate to a connected client
 215 this option sets that certificate to the current certificate and returns 1.
 216 If the negotiated cipher suite is anonymous (and thus no certificate will
 217 be sent) 2 is returned and the current certificate is unchanged. If \fBssl\fR
 218 is not a server or a certificate has not been sent 0 is returned and
 219 the current certificate is unchanged.
 220 .PP
 221 All these functions are implemented as macros. Those containing a \fB1\fR
 222 increment the reference count of the supplied certificate or chain so it must
 223 be freed at some point after the operation. Those containing a \fB0\fR do
 224 not increment reference counts and the supplied certificate or chain
 225 \&\fB\s-1MUST NOT\s0\fR be freed after the operation.
 226 .SH "NOTES"
 227 .IX Header "NOTES"
 228 The chains associate with an \s-1SSL_CTX\s0 structure are copied to any \s-1SSL\s0
 229 structures when \fISSL_new()\fR is called. \s-1SSL\s0 structures will not be affected
 230 by any chains subsequently changed in the parent \s-1SSL_CTX.\s0
 231 .PP
 232 One chain can be set for each key type supported by a server. So, for example,
 233 an \s-1RSA\s0 and a \s-1DSA\s0 certificate can (and often will) have different chains.
 234 .PP
 235 The functions \fISSL_CTX_build_cert_chain()\fR and \fISSL_build_cert_chain()\fR can
 236 be used to check application configuration and to ensure any necessary
 237 subordinate CAs are sent in the correct order. Misconfigured applications
 238 sending incorrect certificate chains often cause problems with peers.
 239 .PP
 240 For example an application can add any set of certificates using
 241 \&\fISSL_CTX_use_certificate_chain_file()\fR then call \fISSL_CTX_build_cert_chain()\fR
 242 with the option \fB\s-1SSL_BUILD_CHAIN_FLAG_CHECK\s0\fR to check and reorder them.
 243 .PP
 244 Applications can issue non fatal warnings when checking chains by setting
 245 the flag \fB\s-1SSL_BUILD_CHAIN_FLAG_IGNORE_ERRORS\s0\fR and checking the return
 246 value.
 247 .PP
 248 Calling \fISSL_CTX_build_cert_chain()\fR or \fISSL_build_cert_chain()\fR is more
 249 efficient than the automatic chain building as it is only performed once.
 250 Automatic chain building is performed on each new session.
 251 .PP
 252 If any certificates are added using these functions no certificates added
 253 using \fISSL_CTX_add_extra_chain_cert()\fR will be used.
 254 .SH "RETURN VALUES"
 255 .IX Header "RETURN VALUES"
 256 \&\fISSL_set_current_cert()\fR with \fB\s-1SSL_CERT_SET_SERVER\s0\fR return 1 for success, 2 if
 257 no server certificate is used because the cipher suites is anonymous and 0
 258 for failure.
 259 .PP
 260 \&\fISSL_CTX_build_cert_chain()\fR and \fISSL_build_cert_chain()\fR return 1 for success
 261 and 0 for failure. If the flag \fB\s-1SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR\s0\fR and
 262 a verification error occurs then 2 is returned.
 263 .PP
 264 All other functions return 1 for success and 0 for failure.
 265 .SH "SEE ALSO"
 266 .IX Header "SEE ALSO"
 267 \&\fISSL_CTX_add_extra_chain_cert\fR\|(3)
 268 .SH "HISTORY"
 269 .IX Header "HISTORY"
 270 These functions were first added to OpenSSL 1.0.2.
 271 .SH "COPYRIGHT"
 272 .IX Header "COPYRIGHT"
 273 Copyright 2013\-2016 The OpenSSL Project Authors. All Rights Reserved.
 274 .PP
 275 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 276 this file except in compliance with the License.  You can obtain a copy
 277 in the file \s-1LICENSE\s0 in the source distribution or at
 278 <https://www.openssl.org/source/license.html>.