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