secure/lib/libssl/man/SSL_CTX_add1_chain_cert.3

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