secure/lib/libcrypto/man/SSL_CTX_set_tlsext_status_cb.3

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