secure/lib/libssl/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-11-20" "1.0.2q" "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_set_tlsext_status_arg,
 139 SSL_set_tlsext_status_type, SSL_get_tlsext_status_ocsp_resp,
 140 SSL_set_tlsext_status_ocsp_resp \- OCSP Certificate Status Request functions
 141 .SH "SYNOPSIS"
 142 .IX Header "SYNOPSIS"
 143 .Vb 1
 144 \& #include <openssl/tls1.h>
 145 \&
 146 \& long SSL_CTX_set_tlsext_status_cb(SSL_CTX *ctx,
 147 \&                                   int (*callback)(SSL *, void *));
 148 \& long SSL_CTX_set_tlsext_status_arg(SSL_CTX *ctx, void *arg);
 149 \&
 150 \& long SSL_set_tlsext_status_type(SSL *s, int type);
 151 \&
 152 \& long SSL_get_tlsext_status_ocsp_resp(ssl, unsigned char **resp);
 153 \& long SSL_set_tlsext_status_ocsp_resp(ssl, unsigned char *resp, int len);
 154 .Ve
 155 .SH "DESCRIPTION"
 156 .IX Header "DESCRIPTION"
 157 A client application may request that a server send back an \s-1OCSP\s0 status response
 158 (also known as \s-1OCSP\s0 stapling). To do so the client should call the
 159 \&\fISSL_set_tlsext_status_type()\fR function prior to the start of the handshake.
 160 Currently the only supported type is \fBTLSEXT_STATUSTYPE_ocsp\fR. This value
 161 should be passed in the \fBtype\fR argument. The client should additionally provide
 162 a callback function to decide what to do with the returned \s-1OCSP\s0 response by
 163 calling \fISSL_CTX_set_tlsext_status_cb()\fR. The callback function should determine
 164 whether the returned \s-1OCSP\s0 response is acceptable or not. The callback will be
 165 passed as an argument the value previously set via a call to
 166 \&\fISSL_CTX_set_tlsext_status_arg()\fR. Note that the callback will not be called in
 167 the event of a handshake where session resumption occurs (because there are no
 168 Certificates exchanged in such a handshake).
 169 .PP
 170 The response returned by the server can be obtained via a call to
 171 \&\fISSL_get_tlsext_status_ocsp_resp()\fR. The value \fB*resp\fR will be updated to point
 172 to the \s-1OCSP\s0 response data and the return value will be the length of that data.
 173 Typically a callback would obtain an \s-1OCSP_RESPONSE\s0 object from this data via a
 174 call to the \fId2i_OCSP_RESPONSE()\fR function. If the server has not provided any
 175 response data then \fB*resp\fR will be \s-1NULL\s0 and the return value from
 176 \&\fISSL_get_tlsext_status_ocsp_resp()\fR will be \-1.
 177 .PP
 178 A server application must also call the \fISSL_CTX_set_tlsext_status_cb()\fR function
 179 if it wants to be able to provide clients with \s-1OCSP\s0 Certificate Status
 180 responses. Typically the server callback would obtain the server certificate
 181 that is being sent back to the client via a call to \fISSL_get_certificate()\fR;
 182 obtain the \s-1OCSP\s0 response to be sent back; and then set that response data by
 183 calling \fISSL_set_tlsext_status_ocsp_resp()\fR. A pointer to the response data should
 184 be provided in the \fBresp\fR argument, and the length of that data should be in
 185 the \fBlen\fR argument.
 186 .SH "RETURN VALUES"
 187 .IX Header "RETURN VALUES"
 188 The callback when used on the client side should return a negative value on
 189 error; 0 if the response is not acceptable (in which case the handshake will
 190 fail) or a positive value if it is acceptable.
 191 .PP
 192 The callback when used on the server side should return with either
 193 \&\s-1SSL_TLSEXT_ERR_OK\s0 (meaning that the \s-1OCSP\s0 response that has been set should be
 194 returned), \s-1SSL_TLSEXT_ERR_NOACK\s0 (meaning that an \s-1OCSP\s0 response should not be
 195 returned) or \s-1SSL_TLSEXT_ERR_ALERT_FATAL\s0 (meaning that a fatal error has
 196 occurred).
 197 .PP
 198 \&\fISSL_CTX_set_tlsext_status_cb()\fR, \fISSL_CTX_set_tlsext_status_arg()\fR,
 199 \&\fISSL_set_tlsext_status_type()\fR and \fISSL_set_tlsext_status_ocsp_resp()\fR return 0 on
 200 error or 1 on success.
 201 .PP
 202 \&\fISSL_get_tlsext_status_ocsp_resp()\fR returns the length of the \s-1OCSP\s0 response data
 203 or \-1 if there is no \s-1OCSP\s0 response data.