secure/lib/libcrypto/man/man3/SSL_CTX_set_cert_cb.3

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
   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_SET_CERT_CB 3"
 136 .TH SSL_CTX_SET_CERT_CB 3 "2022-05-03" "1.1.1o" "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_set_cert_cb, SSL_set_cert_cb \- handle certificate callback function
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/ssl.h>
 147 \&
 148 \& void SSL_CTX_set_cert_cb(SSL_CTX *c, int (*cert_cb)(SSL *ssl, void *arg),
 149 \&                          void *arg);
 150 \& void SSL_set_cert_cb(SSL *s, int (*cert_cb)(SSL *ssl, void *arg), void *arg);
 151 \&
 152 \& int (*cert_cb)(SSL *ssl, void *arg);
 153 .Ve
 154 .SH "DESCRIPTION"
 155 .IX Header "DESCRIPTION"
 156 \&\fBSSL_CTX_set_cert_cb()\fR and \fBSSL_set_cert_cb()\fR sets the \fBcert_cb()\fR callback,
 157 \&\fBarg\fR value is pointer which is passed to the application callback.
 158 .PP
 159 When \fBcert_cb()\fR is \s-1NULL,\s0 no callback function is used.
 160 .PP
 161 \&\fBcert_cb()\fR is the application defined callback. It is called before a
 162 certificate will be used by a client or server. The callback can then inspect
 163 the passed \fBssl\fR structure and set or clear any appropriate certificates. If
 164 the callback is successful it \fB\s-1MUST\s0\fR return 1 even if no certificates have
 165 been set. A zero is returned on error which will abort the handshake with a
 166 fatal internal error alert. A negative return value will suspend the handshake
 167 and the handshake function will return immediately.
 168 \&\fBSSL_get_error\fR\|(3) will return \s-1SSL_ERROR_WANT_X509_LOOKUP\s0 to
 169 indicate, that the handshake was suspended. The next call to the handshake
 170 function will again lead to the call of \fBcert_cb()\fR. It is the job of the
 171 \&\fBcert_cb()\fR to store information about the state of the last call,
 172 if required to continue.
 173 .SH "NOTES"
 174 .IX Header "NOTES"
 175 An application will typically call \fBSSL_use_certificate()\fR and
 176 \&\fBSSL_use_PrivateKey()\fR to set the end entity certificate and private key.
 177 It can add intermediate and optionally the root \s-1CA\s0 certificates using
 178 \&\fBSSL_add1_chain_cert()\fR.
 179 .PP
 180 It might also call \fBSSL_certs_clear()\fR to delete any certificates associated
 181 with the \fB\s-1SSL\s0\fR object.
 182 .PP
 183 The certificate callback functionality supersedes the (largely broken)
 184 functionality provided by the old client certificate callback interface.
 185 It is \fBalways\fR called even is a certificate is already set so the callback
 186 can modify or delete the existing certificate.
 187 .PP
 188 A more advanced callback might examine the handshake parameters and set
 189 whatever chain is appropriate. For example a legacy client supporting only
 190 TLSv1.0 might receive a certificate chain signed using \s-1SHA1\s0 whereas a
 191 TLSv1.2 or later client which advertises support for \s-1SHA256\s0 could receive a
 192 chain using \s-1SHA256.\s0
 193 .PP
 194 Normal server sanity checks are performed on any certificates set
 195 by the callback. So if an \s-1EC\s0 chain is set for a curve the client does not
 196 support it will \fBnot\fR be used.
 197 .SH "RETURN VALUES"
 198 .IX Header "RETURN VALUES"
 199 \&\fBSSL_CTX_set_cert_cb()\fR and \fBSSL_set_cert_cb()\fR do not return values.
 200 .SH "SEE ALSO"
 201 .IX Header "SEE ALSO"
 202 \&\fBssl\fR\|(7), \fBSSL_use_certificate\fR\|(3),
 203 \&\fBSSL_add1_chain_cert\fR\|(3),
 204 \&\fBSSL_get_client_CA_list\fR\|(3),
 205 \&\fBSSL_clear\fR\|(3), \fBSSL_free\fR\|(3)
 206 .SH "COPYRIGHT"
 207 .IX Header "COPYRIGHT"
 208 Copyright 2014\-2018 The OpenSSL Project Authors. All Rights Reserved.
 209 .PP
 210 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 211 this file except in compliance with the License.  You can obtain a copy
 212 in the file \s-1LICENSE\s0 in the source distribution or at
 213 <https://www.openssl.org/source/license.html>.