secure/lib/libssl/man/SSL_CTX_add1_chain_cert.3

   1 .\" Automatically generated by Pod::Man 4.07 (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 "2017-11-02" "1.0.2m" "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,
 139 SSL_CTX_add1_chain_cert, SSL_CTX_get0_chain_certs, SSL_CTX_clear_chain_certs,
 140 SSL_set0_chain, SSL_set1_chain, SSL_add0_chain_cert, SSL_add1_chain_cert,
 141 SSL_get0_chain_certs, SSL_clear_chain_certs, SSL_CTX_build_cert_chain,
 142 SSL_build_cert_chain, SSL_CTX_select_current_cert,
 143 SSL_select_current_cert, SSL_CTX_set_current_cert, SSL_set_current_cert \- extra
 144 chain certificate processing
 145 .SH "SYNOPSIS"
 146 .IX Header "SYNOPSIS"
 147 .Vb 1
 148 \& #include <openssl/ssl.h>
 149 \&
 150 \& int SSL_CTX_set0_chain(SSL_CTX *ctx, STACK_OF(X509) *sk);
 151 \& int SSL_CTX_set1_chain(SSL_CTX *ctx, STACK_OF(X509) *sk);
 152 \& int SSL_CTX_add0_chain_cert(SSL_CTX *ctx, X509 *x509);
 153 \& int SSL_CTX_add1_chain_cert(SSL_CTX *ctx, X509 *x509);
 154 \& int SSL_CTX_get0_chain_certs(SSL_CTX *ctx, STACK_OF(X509) **sk);
 155 \& int SSL_CTX_clear_chain_certs(SSL_CTX *ctx);
 156 \&
 157 \& int SSL_set0_chain(SSL *ssl, STACK_OF(X509) *sk);
 158 \& int SSL_set1_chain(SSL *ssl, STACK_OF(X509) *sk);
 159 \& int SSL_add0_chain_cert(SSL *ssl, X509 *x509);
 160 \& int SSL_add1_chain_cert(SSL *ssl, X509 *x509);
 161 \& int SSL_get0_chain_certs(SSL *ssl, STACK_OF(X509) **sk);
 162 \& int SSL_clear_chain_certs(SSL *ssl);
 163 \&
 164 \& int SSL_CTX_build_cert_chain(SSL_CTX *ctx, flags);
 165 \& int SSL_build_cert_chain(SSL *ssl, flags);
 166 \&
 167 \& int SSL_CTX_select_current_cert(SSL_CTX *ctx, X509 *x509);
 168 \& int SSL_select_current_cert(SSL *ssl, X509 *x509);
 169 \& int SSL_CTX_set_current_cert(SSL_CTX *ctx, long op);
 170 \& int SSL_set_current_cert(SSL *ssl, long op);
 171 .Ve
 172 .SH "DESCRIPTION"
 173 .IX Header "DESCRIPTION"
 174 \&\fISSL_CTX_set0_chain()\fR and \fISSL_CTX_set1_chain()\fR set the certificate chain
 175 associated with the current certificate of \fBctx\fR to \fBsk\fR.
 176 .PP
 177 \&\fISSL_CTX_add0_chain_cert()\fR and \fISSL_CTX_add1_chain_cert()\fR append the single
 178 certificate \fBx509\fR to the chain associated with the current certificate of
 179 \&\fBctx\fR.
 180 .PP
 181 \&\fISSL_CTX_get0_chain_certs()\fR retrieves the chain associated with the current
 182 certificate of \fBctx\fR.
 183 .PP
 184 \&\fISSL_CTX_clear_chain_certs()\fR clears any existing chain associated with the
 185 current certificate of \fBctx\fR.  (This is implemented by calling
 186 \&\fISSL_CTX_set0_chain()\fR with \fBsk\fR set to \fB\s-1NULL\s0\fR).
 187 .PP
 188 \&\fISSL_CTX_build_cert_chain()\fR builds the certificate chain for \fBctx\fR normally
 189 this uses the chain store or the verify store if the chain store is not set.
 190 If the function is successful the built chain will replace any existing chain.
 191 The \fBflags\fR parameter can be set to \fB\s-1SSL_BUILD_CHAIN_FLAG_UNTRUSTED\s0\fR to use
 192 existing chain certificates as untrusted CAs, \fB\s-1SSL_BUILD_CHAIN_FLAG_NO_ROOT\s0\fR
 193 to omit the root \s-1CA\s0 from the built chain, \fB\s-1SSL_BUILD_CHAIN_FLAG_CHECK\s0\fR to
 194 use all existing chain certificates only to build the chain (effectively
 195 sanity checking and rearranging them if necessary), the flag
 196 \&\fB\s-1SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR\s0\fR ignores any errors during verification:
 197 if flag \fB\s-1SSL_BUILD_CHAIN_FLAG_CLEAR_ERROR\s0\fR is also set verification errors
 198 are cleared from the error queue.
 199 .PP
 200 Each of these functions operates on the \fIcurrent\fR end entity
 201 (i.e. server or client) certificate. This is the last certificate loaded or
 202 selected on the corresponding \fBctx\fR structure.
 203 .PP
 204 \&\fISSL_CTX_select_current_cert()\fR selects \fBx509\fR as the current end entity
 205 certificate, but only if \fBx509\fR has already been loaded into \fBctx\fR using a
 206 function such as \fISSL_CTX_use_certificate()\fR.
 207 .PP
 208 \&\fISSL_set0_chain()\fR, \fISSL_set1_chain()\fR, \fISSL_add0_chain_cert()\fR,
 209 \&\fISSL_add1_chain_cert()\fR, \fISSL_get0_chain_certs()\fR, \fISSL_clear_chain_certs()\fR,
 210 \&\fISSL_build_cert_chain()\fR, \fISSL_select_current_cert()\fR and \fISSL_set_current_cert()\fR
 211 are similar except they apply to \s-1SSL\s0 structure \fBssl\fR.
 212 .PP
 213 \&\fISSL_CTX_set_current_cert()\fR changes the current certificate to a value based
 214 on the \fBop\fR argument. Currently \fBop\fR can be \fB\s-1SSL_CERT_SET_FIRST\s0\fR to use
 215 the first valid certificate or \fB\s-1SSL_CERT_SET_NEXT\s0\fR to set the next valid
 216 certificate after the current certificate. These two operations can be
 217 used to iterate over all certificates in an \fB\s-1SSL_CTX\s0\fR structure.
 218 .PP
 219 \&\fISSL_set_current_cert()\fR also supports the option \fB\s-1SSL_CERT_SET_SERVER\s0\fR.
 220 If \fBssl\fR is a server and has sent a certificate to a connected client
 221 this option sets that certificate to the current certificate and returns 1.
 222 If the negotiated ciphersuite is anonymous (and thus no certificate will
 223 be sent) 2 is returned and the current certificate is unchanged. If \fBssl\fR
 224 is not a server or a certificate has not been sent 0 is returned and
 225 the current certificate is unchanged.
 226 .PP
 227 All these functions are implemented as macros. Those containing a \fB1\fR
 228 increment the reference count of the supplied certificate or chain so it must
 229 be freed at some point after the operation. Those containing a \fB0\fR do
 230 not increment reference counts and the supplied certificate or chain
 231 \&\fB\s-1MUST NOT\s0\fR be freed after the operation.
 232 .SH "NOTES"
 233 .IX Header "NOTES"
 234 The chains associate with an \s-1SSL_CTX\s0 structure are copied to any \s-1SSL\s0
 235 structures when \fISSL_new()\fR is called. \s-1SSL\s0 structures will not be affected
 236 by any chains subsequently changed in the parent \s-1SSL_CTX.\s0
 237 .PP
 238 One chain can be set for each key type supported by a server. So, for example,
 239 an \s-1RSA\s0 and a \s-1DSA\s0 certificate can (and often will) have different chains.
 240 .PP
 241 The functions \fISSL_CTX_build_cert_chain()\fR and \fISSL_build_cert_chain()\fR can
 242 be used to check application configuration and to ensure any necessary
 243 subordinate CAs are sent in the correct order. Misconfigured applications
 244 sending incorrect certificate chains often cause problems with peers.
 245 .PP
 246 For example an application can add any set of certificates using
 247 \&\fISSL_CTX_use_certificate_chain_file()\fR then call \fISSL_CTX_build_cert_chain()\fR
 248 with the option \fB\s-1SSL_BUILD_CHAIN_FLAG_CHECK\s0\fR to check and reorder them.
 249 .PP
 250 Applications can issue non fatal warnings when checking chains by setting
 251 the flag \fB\s-1SSL_BUILD_CHAIN_FLAG_IGNORE_ERRORS\s0\fR and checking the return
 252 value.
 253 .PP
 254 Calling \fISSL_CTX_build_cert_chain()\fR or \fISSL_build_cert_chain()\fR is more
 255 efficient than the automatic chain building as it is only performed once.
 256 Automatic chain building is performed on each new session.
 257 .PP
 258 If any certificates are added using these functions no certificates added
 259 using \fISSL_CTX_add_extra_chain_cert()\fR will be used.
 260 .SH "RETURN VALUES"
 261 .IX Header "RETURN VALUES"
 262 \&\fISSL_set_current_cert()\fR with \fB\s-1SSL_CERT_SET_SERVER\s0\fR return 1 for success, 2 if
 263 no server certificate is used because the ciphersuites is anonymous and 0
 264 for failure.
 265 .PP
 266 \&\fISSL_CTX_build_cert_chain()\fR and \fISSL_build_cert_chain()\fR return 1 for success
 267 and 0 for failure. If the flag \fB\s-1SSL_BUILD_CHAIN_FLAG_IGNORE_ERROR\s0\fR and
 268 a verification error occurs then 2 is returned.
 269 .PP
 270 All other functions return 1 for success and 0 for failure.
 271 .SH "SEE ALSO"
 272 .IX Header "SEE ALSO"
 273 \&\fISSL_CTX_add_extra_chain_cert\fR\|(3)
 274 .SH "HISTORY"
 275 .IX Header "HISTORY"
 276 These functions were first added to OpenSSL 1.0.2.