secure/lib/libcrypto/man/SSL_CTX_set_tlsext_status_cb.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_SET_TLSEXT_STATUS_CB 3"
 136 .TH SSL_CTX_SET_TLSEXT_STATUS_CB 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_set_tlsext_status_cb, SSL_CTX_get_tlsext_status_cb, SSL_CTX_set_tlsext_status_arg, SSL_CTX_get_tlsext_status_arg, SSL_CTX_set_tlsext_status_type, SSL_CTX_get_tlsext_status_type, SSL_set_tlsext_status_type, SSL_get_tlsext_status_type, SSL_get_tlsext_status_ocsp_resp, SSL_set_tlsext_status_ocsp_resp \&\- OCSP Certificate Status Request functions
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/tls1.h>
 147 \&
 148 \& long SSL_CTX_set_tlsext_status_cb(SSL_CTX *ctx, int (*callback)(SSL *, void *));
 149 \& long SSL_CTX_get_tlsext_status_cb(SSL_CTX *ctx, int (**callback)(SSL *, void *));
 150 \&
 151 \& long SSL_CTX_set_tlsext_status_arg(SSL_CTX *ctx, void *arg);
 152 \& long SSL_CTX_get_tlsext_status_arg(SSL_CTX *ctx, void **arg);
 153 \&
 154 \& long SSL_CTX_set_tlsext_status_type(SSL_CTX *ctx, int type);
 155 \& long SSL_CTX_get_tlsext_status_type(SSL_CTX *ctx);
 156 \&
 157 \& long SSL_set_tlsext_status_type(SSL *s, int type);
 158 \& long SSL_get_tlsext_status_type(SSL *s);
 159 \&
 160 \& long SSL_get_tlsext_status_ocsp_resp(ssl, unsigned char **resp);
 161 \& long SSL_set_tlsext_status_ocsp_resp(ssl, unsigned char *resp, int len);
 162 .Ve
 163 .SH "DESCRIPTION"
 164 .IX Header "DESCRIPTION"
 165 A client application may request that a server send back an \s-1OCSP\s0 status response
 166 (also known as \s-1OCSP\s0 stapling). To do so the client should call the
 167 \&\fBSSL_CTX_set_tlsext_status_type()\fR function prior to the creation of any \s-1SSL\s0
 168 objects. Alternatively an application can call the \fBSSL_set_tlsext_status_type()\fR
 169 function on an individual \s-1SSL\s0 object prior to the start of the handshake.
 170 Currently the only supported type is \fBTLSEXT_STATUSTYPE_ocsp\fR. This value
 171 should be passed in the \fBtype\fR argument. Calling
 172 \&\fBSSL_CTX_get_tlsext_status_type()\fR will return the type \fBTLSEXT_STATUSTYPE_ocsp\fR
 173 previously set via \fBSSL_CTX_set_tlsext_status_type()\fR or \-1 if not set.
 174 .PP
 175 The client should additionally provide a callback function to decide what to do
 176 with the returned \s-1OCSP\s0 response by calling \fBSSL_CTX_set_tlsext_status_cb()\fR. The
 177 callback function should determine whether the returned \s-1OCSP\s0 response is
 178 acceptable or not. The callback will be passed as an argument the value
 179 previously set via a call to \fBSSL_CTX_set_tlsext_status_arg()\fR. Note that the
 180 callback will not be called in the event of a handshake where session resumption
 181 occurs (because there are no Certificates exchanged in such a handshake).
 182 The callback previously set via \fBSSL_CTX_set_tlsext_status_cb()\fR can be retrieved
 183 by calling \fBSSL_CTX_get_tlsext_status_cb()\fR, and the argument by calling
 184 \&\fBSSL_CTX_get_tlsext_status_arg()\fR.
 185 .PP
 186 On the client side \fBSSL_get_tlsext_status_type()\fR can be used to determine whether
 187 the client has previously called \fBSSL_set_tlsext_status_type()\fR. It will return
 188 \&\fBTLSEXT_STATUSTYPE_ocsp\fR if it has been called or \-1 otherwise. On the server
 189 side \fBSSL_get_tlsext_status_type()\fR can be used to determine whether the client
 190 requested \s-1OCSP\s0 stapling. If the client requested it then this function will
 191 return \fBTLSEXT_STATUSTYPE_ocsp\fR, or \-1 otherwise.
 192 .PP
 193 The response returned by the server can be obtained via a call to
 194 \&\fBSSL_get_tlsext_status_ocsp_resp()\fR. The value \fB*resp\fR will be updated to point
 195 to the \s-1OCSP\s0 response data and the return value will be the length of that data.
 196 Typically a callback would obtain an \s-1OCSP_RESPONSE\s0 object from this data via a
 197 call to the \fBd2i_OCSP_RESPONSE()\fR function. If the server has not provided any
 198 response data then \fB*resp\fR will be \s-1NULL\s0 and the return value from
 199 \&\fBSSL_get_tlsext_status_ocsp_resp()\fR will be \-1.
 200 .PP
 201 A server application must also call the \fBSSL_CTX_set_tlsext_status_cb()\fR function
 202 if it wants to be able to provide clients with \s-1OCSP\s0 Certificate Status
 203 responses. Typically the server callback would obtain the server certificate
 204 that is being sent back to the client via a call to \fBSSL_get_certificate()\fR;
 205 obtain the \s-1OCSP\s0 response to be sent back; and then set that response data by
 206 calling \fBSSL_set_tlsext_status_ocsp_resp()\fR. A pointer to the response data should
 207 be provided in the \fBresp\fR argument, and the length of that data should be in
 208 the \fBlen\fR argument.
 209 .SH "RETURN VALUES"
 210 .IX Header "RETURN VALUES"
 211 The callback when used on the client side should return a negative value on
 212 error; 0 if the response is not acceptable (in which case the handshake will
 213 fail) or a positive value if it is acceptable.
 214 .PP
 215 The callback when used on the server side should return with either
 216 \&\s-1SSL_TLSEXT_ERR_OK\s0 (meaning that the \s-1OCSP\s0 response that has been set should be
 217 returned), \s-1SSL_TLSEXT_ERR_NOACK\s0 (meaning that an \s-1OCSP\s0 response should not be
 218 returned) or \s-1SSL_TLSEXT_ERR_ALERT_FATAL\s0 (meaning that a fatal error has
 219 occurred).
 220 .PP
 221 \&\fBSSL_CTX_set_tlsext_status_cb()\fR, \fBSSL_CTX_set_tlsext_status_arg()\fR,
 222 \&\fBSSL_CTX_set_tlsext_status_type()\fR, \fBSSL_set_tlsext_status_type()\fR and
 223 \&\fBSSL_set_tlsext_status_ocsp_resp()\fR return 0 on error or 1 on success.
 224 .PP
 225 \&\fBSSL_CTX_get_tlsext_status_type()\fR returns the value previously set by
 226 \&\fBSSL_CTX_set_tlsext_status_type()\fR, or \-1 if not set.
 227 .PP
 228 \&\fBSSL_get_tlsext_status_ocsp_resp()\fR returns the length of the \s-1OCSP\s0 response data
 229 or \-1 if there is no \s-1OCSP\s0 response data.
 230 .PP
 231 \&\fBSSL_get_tlsext_status_type()\fR returns \fBTLSEXT_STATUSTYPE_ocsp\fR on the client
 232 side if \fBSSL_set_tlsext_status_type()\fR was previously called, or on the server
 233 side if the client requested \s-1OCSP\s0 stapling. Otherwise \-1 is returned.
 234 .SH "HISTORY"
 235 .IX Header "HISTORY"
 236 The \fBSSL_get_tlsext_status_type()\fR, \fBSSL_CTX_get_tlsext_status_type()\fR
 237 and \fBSSL_CTX_set_tlsext_status_type()\fR functions were added in OpenSSL 1.1.0.
 238 .SH "COPYRIGHT"
 239 .IX Header "COPYRIGHT"
 240 Copyright 2015\-2016 The OpenSSL Project Authors. All Rights Reserved.
 241 .PP
 242 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 243 this file except in compliance with the License.  You can obtain a copy
 244 in the file \s-1LICENSE\s0 in the source distribution or at
 245 <https://www.openssl.org/source/license.html>.