secure/lib/libcrypto/man/SSL_CTX_add1_chain_cert.3

   1 .\" Automatically generated by Pod::Man 4.10 (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 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "SSL_CTX_ADD1_CHAIN_CERT 3"
 136 .TH SSL_CTX_ADD1_CHAIN_CERT 3 "2019-02-26" "1.1.1b" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 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
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/ssl.h>
 147 \&
 148 \& int SSL_CTX_set0_chain(SSL_CTX *ctx, STACK_OF(X509) *sk);
 149 \& int SSL_CTX_set1_chain(SSL_CTX *ctx, STACK_OF(X509) *sk);
 150 \& int SSL_CTX_add0_chain_cert(SSL_CTX *ctx, X509 *x509);
 151 \& int SSL_CTX_add1_chain_cert(SSL_CTX *ctx, X509 *x509);
 152 \& int SSL_CTX_get0_chain_certs(SSL_CTX *ctx, STACK_OF(X509) **sk);
 153 \& int SSL_CTX_clear_chain_certs(SSL_CTX *ctx);
 154 \&
 155 \& int SSL_set0_chain(SSL *ssl, STACK_OF(X509) *sk);
 156 \& int SSL_set1_chain(SSL *ssl, STACK_OF(X509) *sk);
 157 \& int SSL_add0_chain_cert(SSL *ssl, X509 *x509);
 158 \& int SSL_add1_chain_cert(SSL *ssl, X509 *x509);
 159 \& int SSL_get0_chain_certs(SSL *ssl, STACK_OF(X509) **sk);
 160 \& int SSL_clear_chain_certs(SSL *ssl);
 161 \&
 162 \& int SSL_CTX_build_cert_chain(SSL_CTX *ctx, flags);
 163 \& int SSL_build_cert_chain(SSL *ssl, flags);
 164 \&
 165 \& int SSL_CTX_select_current_cert(SSL_CTX *ctx, X509 *x509);
 166 \& int SSL_select_current_cert(SSL *ssl, X509 *x509);
 167 \& int SSL_CTX_set_current_cert(SSL_CTX *ctx, long op);
 168 \& int SSL_set_current_cert(SSL *ssl, long op);
 169 .Ve
 170 .SH "DESCRIPTION"
 171 .IX Header "DESCRIPTION"
 172 \&\fBSSL_CTX_set0_chain()\fR and \fBSSL_CTX_set1_chain()\fR set the certificate chain
 173 associated with the current certificate of \fBctx\fR to \fBsk\fR.
 174 .PP
 175 \&\fBSSL_CTX_add0_chain_cert()\fR and \fBSSL_CTX_add1_chain_cert()\fR append the single
 176 certificate \fBx509\fR to the chain associated with the current certificate of
 177 \&\fBctx\fR.
 178 .PP
 179 \&\fBSSL_CTX_get0_chain_certs()\fR retrieves the chain associated with the current
 180 certificate of \fBctx\fR.
 181 .PP
 182 \&\fBSSL_CTX_clear_chain_certs()\fR clears any existing chain associated with the
 183 current certificate of \fBctx\fR.  (This is implemented by calling
 184 \&\fBSSL_CTX_set0_chain()\fR with \fBsk\fR set to \fB\s-1NULL\s0\fR).
 185 .PP
 186 \&\fBSSL_CTX_build_cert_chain()\fR builds the certificate chain for \fBctx\fR normally
 187 this uses the chain store or the verify store if the chain store is not set.
 188 If the function is successful the built chain will replace any existing chain.
 189 The \fBflags\fR parameter can be set to \fB\s-1SSL_BUILD_CHAIN_FLAG_UNTRUSTED\s0\fR to use
 190 existing chain certificates as untrusted CAs, \fB\s-1SSL_BUILD_CHAIN_FLAG_NO_ROOT\s0\fR
 191 to omit the root \s-1CA\s0 from the built chain, \fB\s-1SSL_BUILD_CHAIN_FLAG_CHECK\s0\fR to
 192 use all existing chain certificates only to build the chain (effectively
 193 sanity checking and rearranging them if necessary), the flag
 194 \&\fB\s-1SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR\s0\fR ignores any errors during verification:
 195 if flag \fB\s-1SSL_BUILD_CHAIN_FLAG_CLEAR_ERROR\s0\fR is also set verification errors
 196 are cleared from the error queue.
 197 .PP
 198 Each of these functions operates on the \fIcurrent\fR end entity
 199 (i.e. server or client) certificate. This is the last certificate loaded or
 200 selected on the corresponding \fBctx\fR structure.
 201 .PP
 202 \&\fBSSL_CTX_select_current_cert()\fR selects \fBx509\fR as the current end entity
 203 certificate, but only if \fBx509\fR has already been loaded into \fBctx\fR using a
 204 function such as \fBSSL_CTX_use_certificate()\fR.
 205 .PP
 206 \&\fBSSL_set0_chain()\fR, \fBSSL_set1_chain()\fR, \fBSSL_add0_chain_cert()\fR,
 207 \&\fBSSL_add1_chain_cert()\fR, \fBSSL_get0_chain_certs()\fR, \fBSSL_clear_chain_certs()\fR,
 208 \&\fBSSL_build_cert_chain()\fR, \fBSSL_select_current_cert()\fR and \fBSSL_set_current_cert()\fR
 209 are similar except they apply to \s-1SSL\s0 structure \fBssl\fR.
 210 .PP
 211 \&\fBSSL_CTX_set_current_cert()\fR changes the current certificate to a value based
 212 on the \fBop\fR argument. Currently \fBop\fR can be \fB\s-1SSL_CERT_SET_FIRST\s0\fR to use
 213 the first valid certificate or \fB\s-1SSL_CERT_SET_NEXT\s0\fR to set the next valid
 214 certificate after the current certificate. These two operations can be
 215 used to iterate over all certificates in an \fB\s-1SSL_CTX\s0\fR structure.
 216 .PP
 217 \&\fBSSL_set_current_cert()\fR also supports the option \fB\s-1SSL_CERT_SET_SERVER\s0\fR.
 218 If \fBssl\fR is a server and has sent a certificate to a connected client
 219 this option sets that certificate to the current certificate and returns 1.
 220 If the negotiated cipher suite is anonymous (and thus no certificate will
 221 be sent) 2 is returned and the current certificate is unchanged. If \fBssl\fR
 222 is not a server or a certificate has not been sent 0 is returned and
 223 the current certificate is unchanged.
 224 .PP
 225 All these functions are implemented as macros. Those containing a \fB1\fR
 226 increment the reference count of the supplied certificate or chain so it must
 227 be freed at some point after the operation. Those containing a \fB0\fR do
 228 not increment reference counts and the supplied certificate or chain
 229 \&\fB\s-1MUST NOT\s0\fR be freed after the operation.
 230 .SH "NOTES"
 231 .IX Header "NOTES"
 232 The chains associate with an \s-1SSL_CTX\s0 structure are copied to any \s-1SSL\s0
 233 structures when \fBSSL_new()\fR is called. \s-1SSL\s0 structures will not be affected
 234 by any chains subsequently changed in the parent \s-1SSL_CTX.\s0
 235 .PP
 236 One chain can be set for each key type supported by a server. So, for example,
 237 an \s-1RSA\s0 and a \s-1DSA\s0 certificate can (and often will) have different chains.
 238 .PP
 239 The functions \fBSSL_CTX_build_cert_chain()\fR and \fBSSL_build_cert_chain()\fR can
 240 be used to check application configuration and to ensure any necessary
 241 subordinate CAs are sent in the correct order. Misconfigured applications
 242 sending incorrect certificate chains often cause problems with peers.
 243 .PP
 244 For example an application can add any set of certificates using
 245 \&\fBSSL_CTX_use_certificate_chain_file()\fR then call \fBSSL_CTX_build_cert_chain()\fR
 246 with the option \fB\s-1SSL_BUILD_CHAIN_FLAG_CHECK\s0\fR to check and reorder them.
 247 .PP
 248 Applications can issue non fatal warnings when checking chains by setting
 249 the flag \fB\s-1SSL_BUILD_CHAIN_FLAG_IGNORE_ERRORS\s0\fR and checking the return
 250 value.
 251 .PP
 252 Calling \fBSSL_CTX_build_cert_chain()\fR or \fBSSL_build_cert_chain()\fR is more
 253 efficient than the automatic chain building as it is only performed once.
 254 Automatic chain building is performed on each new session.
 255 .PP
 256 If any certificates are added using these functions no certificates added
 257 using \fBSSL_CTX_add_extra_chain_cert()\fR will be used.
 258 .SH "RETURN VALUES"
 259 .IX Header "RETURN VALUES"
 260 \&\fBSSL_set_current_cert()\fR with \fB\s-1SSL_CERT_SET_SERVER\s0\fR return 1 for success, 2 if
 261 no server certificate is used because the cipher suites is anonymous and 0
 262 for failure.
 263 .PP
 264 \&\fBSSL_CTX_build_cert_chain()\fR and \fBSSL_build_cert_chain()\fR return 1 for success
 265 and 0 for failure. If the flag \fB\s-1SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR\s0\fR and
 266 a verification error occurs then 2 is returned.
 267 .PP
 268 All other functions return 1 for success and 0 for failure.
 269 .SH "SEE ALSO"
 270 .IX Header "SEE ALSO"
 271 \&\fBSSL_CTX_add_extra_chain_cert\fR\|(3)
 272 .SH "HISTORY"
 273 .IX Header "HISTORY"
 274 These functions were added in OpenSSL 1.0.2.
 275 .SH "COPYRIGHT"
 276 .IX Header "COPYRIGHT"
 277 Copyright 2013\-2016 The OpenSSL Project Authors. All Rights Reserved.
 278 .PP
 279 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 280 this file except in compliance with the License.  You can obtain a copy
 281 in the file \s-1LICENSE\s0 in the source distribution or at
 282 <https://www.openssl.org/source/license.html>.