secure/lib/libcrypto/man/SSL_extension_supported.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_EXTENSION_SUPPORTED 3"
 132 .TH SSL_EXTENSION_SUPPORTED 3 "2018-11-20" "1.1.1a" "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_extension_supported, SSL_CTX_add_custom_ext, SSL_CTX_add_client_custom_ext, SSL_CTX_add_server_custom_ext, custom_ext_add_cb, custom_ext_free_cb, custom_ext_parse_cb \&\- custom TLS extension handling
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/ssl.h>
 143 \&
 144 \& typedef int (*SSL_custom_ext_add_cb_ex) (SSL *s, unsigned int ext_type,
 145 \&                                          unsigned int context,
 146 \&                                          const unsigned char **out,
 147 \&                                          size_t *outlen, X509 *x,
 148 \&                                          size_t chainidx, int *al,
 149 \&                                          void *add_arg);
 150 \&
 151 \& typedef void (*SSL_custom_ext_free_cb_ex) (SSL *s, unsigned int ext_type,
 152 \&                                            unsigned int context,
 153 \&                                            const unsigned char *out,
 154 \&                                            void *add_arg);
 155 \&
 156 \& typedef int (*SSL_custom_ext_parse_cb_ex) (SSL *s, unsigned int ext_type,
 157 \&                                            unsigned int context,
 158 \&                                            const unsigned char *in,
 159 \&                                            size_t inlen, X509 *x,
 160 \&                                            size_t chainidx, int *al,
 161 \&                                            void *parse_arg);
 162 \&
 163 \& int SSL_CTX_add_custom_ext(SSL_CTX *ctx, unsigned int ext_type,
 164 \&                            unsigned int context,
 165 \&                            SSL_custom_ext_add_cb_ex add_cb,
 166 \&                            SSL_custom_ext_free_cb_ex free_cb,
 167 \&                            void *add_arg,
 168 \&                            SSL_custom_ext_parse_cb_ex parse_cb,
 169 \&                            void *parse_arg);
 170 \&
 171 \& typedef int (*custom_ext_add_cb)(SSL *s, unsigned int ext_type,
 172 \&                                  const unsigned char **out,
 173 \&                                  size_t *outlen, int *al,
 174 \&                                  void *add_arg);
 175 \&
 176 \& typedef void (*custom_ext_free_cb)(SSL *s, unsigned int ext_type,
 177 \&                                    const unsigned char *out,
 178 \&                                    void *add_arg);
 179 \&
 180 \& typedef int (*custom_ext_parse_cb)(SSL *s, unsigned int ext_type,
 181 \&                                    const unsigned char *in,
 182 \&                                    size_t inlen, int *al,
 183 \&                                    void *parse_arg);
 184 \&
 185 \& int SSL_CTX_add_client_custom_ext(SSL_CTX *ctx, unsigned int ext_type,
 186 \&                                   custom_ext_add_cb add_cb,
 187 \&                                   custom_ext_free_cb free_cb, void *add_arg,
 188 \&                                   custom_ext_parse_cb parse_cb,
 189 \&                                   void *parse_arg);
 190 \&
 191 \& int SSL_CTX_add_server_custom_ext(SSL_CTX *ctx, unsigned int ext_type,
 192 \&                                   custom_ext_add_cb add_cb,
 193 \&                                   custom_ext_free_cb free_cb, void *add_arg,
 194 \&                                   custom_ext_parse_cb parse_cb,
 195 \&                                   void *parse_arg);
 196 \&
 197 \& int SSL_extension_supported(unsigned int ext_type);
 198 .Ve
 199 .SH "DESCRIPTION"
 200 .IX Header "DESCRIPTION"
 201 \&\fISSL_CTX_add_custom_ext()\fR adds a custom extension for a \s-1TLS/DTLS\s0 client or server
 202 for all supported protocol versions with extension type \fBext_type\fR and
 203 callbacks \fBadd_cb\fR, \fBfree_cb\fR and \fBparse_cb\fR (see the
 204 \&\*(L"\s-1EXTENSION CALLBACKS\*(R"\s0 section below). The \fBcontext\fR value determines
 205 which messages and under what conditions the extension will be added/parsed (see
 206 the \*(L"\s-1EXTENSION CONTEXTS\*(R"\s0 section below).
 207 .PP
 208 \&\fISSL_CTX_add_client_custom_ext()\fR adds a custom extension for a \s-1TLS/DTLS\s0 client
 209 with extension type \fBext_type\fR and callbacks \fBadd_cb\fR, \fBfree_cb\fR and
 210 \&\fBparse_cb\fR. This function is similar to \fISSL_CTX_add_custom_ext()\fR except it only
 211 applies to clients, uses the older style of callbacks, and implicitly sets the
 212 \&\fBcontext\fR value to:
 213 .PP
 214 .Vb 2
 215 \& SSL_EXT_TLS1_2_AND_BELOW_ONLY | SSL_EXT_CLIENT_HELLO
 216 \& | SSL_EXT_TLS1_2_SERVER_HELLO | SSL_EXT_IGNORE_ON_RESUMPTION
 217 .Ve
 218 .PP
 219 \&\fISSL_CTX_add_server_custom_ext()\fR adds a custom extension for a \s-1TLS/DTLS\s0 server
 220 with extension type \fBext_type\fR and callbacks \fBadd_cb\fR, \fBfree_cb\fR and
 221 \&\fBparse_cb\fR. This function is similar to \fISSL_CTX_add_custom_ext()\fR except it
 222 only applies to servers, uses the older style of callbacks, and implicitly sets
 223 the \fBcontext\fR value to the same as for \fISSL_CTX_add_client_custom_ext()\fR above.
 224 .PP
 225 The \fBext_type\fR parameter corresponds to the \fBextension_type\fR field of
 226 \&\s-1RFC5246\s0 et al. It is \fBnot\fR a \s-1NID.\s0 In all cases the extension type must not be
 227 handled by OpenSSL internally or an error occurs.
 228 .PP
 229 \&\fISSL_extension_supported()\fR returns 1 if the extension \fBext_type\fR is handled
 230 internally by OpenSSL and 0 otherwise.
 231 .SH "EXTENSION CALLBACKS"
 232 .IX Header "EXTENSION CALLBACKS"
 233 The callback \fBadd_cb\fR is called to send custom extension data to be
 234 included in various \s-1TLS\s0 messages. The \fBext_type\fR parameter is set to the
 235 extension type which will be added and \fBadd_arg\fR to the value set when the
 236 extension handler was added. When using the new style callbacks the \fBcontext\fR
 237 parameter will indicate which message is currently being constructed e.g. for
 238 the ClientHello it will be set to \fB\s-1SSL_EXT_CLIENT_HELLO\s0\fR.
 239 .PP
 240 If the application wishes to include the extension \fBext_type\fR it should
 241 set \fB*out\fR to the extension data, set \fB*outlen\fR to the length of the
 242 extension data and return 1.
 243 .PP
 244 If the \fBadd_cb\fR does not wish to include the extension it must return 0.
 245 .PP
 246 If \fBadd_cb\fR returns \-1 a fatal handshake error occurs using the \s-1TLS\s0
 247 alert value specified in \fB*al\fR.
 248 .PP
 249 When constructing the ClientHello, if \fBadd_cb\fR is set to \s-1NULL\s0 a zero length
 250 extension is added for \fBext_type\fR. For all other messages if \fBadd_cb\fR is set
 251 to \s-1NULL\s0 then no extension is added.
 252 .PP
 253 When constructing a Certificate message the callback will be called for each
 254 certificate in the message. The \fBx\fR parameter will indicate the
 255 current certificate and the \fBchainidx\fR parameter will indicate the position
 256 of the certificate in the message. The first certificate is always the end
 257 entity certificate and has a \fBchainidx\fR value of 0. The certificates are in the
 258 order that they were received in the Certificate message.
 259 .PP
 260 For all messages except the ServerHello and EncryptedExtensions every
 261 registered \fBadd_cb\fR is always called to see if the application wishes to add an
 262 extension (as long as all requirements of the specified \fBcontext\fR are met).
 263 .PP
 264 For the ServerHello and EncryptedExtension messages every registered \fBadd_cb\fR
 265 is called once if and only if the requirements of the specified \fBcontext\fR are
 266 met and the corresponding extension was received in the ClientHello. That is, if
 267 no corresponding extension was received in the ClientHello then \fBadd_cb\fR will
 268 not be called.
 269 .PP
 270 If an extension is added (that is \fBadd_cb\fR returns 1) \fBfree_cb\fR is called
 271 (if it is set) with the value of \fBout\fR set by the add callback. It can be
 272 used to free up any dynamic extension data set by \fBadd_cb\fR. Since \fBout\fR is
 273 constant (to permit use of constant data in \fBadd_cb\fR) applications may need to
 274 cast away const to free the data.
 275 .PP
 276 The callback \fBparse_cb\fR receives data for \s-1TLS\s0 extensions. The callback is only
 277 called if the extension is present and relevant for the context (see
 278 \&\*(L"\s-1EXTENSION CONTEXTS\*(R"\s0 below).
 279 .PP
 280 The extension data consists of \fBinlen\fR bytes in the buffer \fBin\fR for the
 281 extension \fBext_type\fR.
 282 .PP
 283 If the message being parsed is a TLSv1.3 compatible Certificate message then
 284 \&\fBparse_cb\fR will be called for each certificate contained within the message.
 285 The \fBx\fR parameter will indicate the current certificate and the \fBchainidx\fR
 286 parameter will indicate the position of the certificate in the message. The
 287 first certificate is always the end entity certificate and has a \fBchainidx\fR
 288 value of 0.
 289 .PP
 290 If the \fBparse_cb\fR considers the extension data acceptable it must return
 291 1. If it returns 0 or a negative value a fatal handshake error occurs
 292 using the \s-1TLS\s0 alert value specified in \fB*al\fR.
 293 .PP
 294 The buffer \fBin\fR is a temporary internal buffer which will not be valid after
 295 the callback returns.
 296 .SH "EXTENSION CONTEXTS"
 297 .IX Header "EXTENSION CONTEXTS"
 298 An extension context defines which messages and under which conditions an
 299 extension should be added or expected. The context is built up by performing
 300 a bitwise \s-1OR\s0 of multiple pre-defined values together. The valid context values
 301 are:
 302 .IP "\s-1SSL_EXT_TLS_ONLY\s0" 4
 303 .IX Item "SSL_EXT_TLS_ONLY"
 304 The extension is only allowed in \s-1TLS\s0
 305 .IP "\s-1SSL_EXT_DTLS_ONLY\s0" 4
 306 .IX Item "SSL_EXT_DTLS_ONLY"
 307 The extension is only allowed in \s-1DTLS\s0
 308 .IP "\s-1SSL_EXT_TLS_IMPLEMENTATION_ONLY\s0" 4
 309 .IX Item "SSL_EXT_TLS_IMPLEMENTATION_ONLY"
 310 The extension is allowed in \s-1DTLS,\s0 but there is only a \s-1TLS\s0 implementation
 311 available (so it is ignored in \s-1DTLS\s0).
 312 .IP "\s-1SSL_EXT_SSL3_ALLOWED\s0" 4
 313 .IX Item "SSL_EXT_SSL3_ALLOWED"
 314 Extensions are not typically defined for SSLv3. Setting this value will allow
 315 the extension in SSLv3. Applications will not typically need to use this.
 316 .IP "\s-1SSL_EXT_TLS1_2_AND_BELOW_ONLY\s0" 4
 317 .IX Item "SSL_EXT_TLS1_2_AND_BELOW_ONLY"
 318 The extension is only defined for TLSv1.2/DTLSv1.2 and below. Servers will
 319 ignore this extension if it is present in the ClientHello and TLSv1.3 is
 320 negotiated.
 321 .IP "\s-1SSL_EXT_TLS1_3_ONLY\s0" 4
 322 .IX Item "SSL_EXT_TLS1_3_ONLY"
 323 The extension is only defined for \s-1TLS1.3\s0 and above. Servers will ignore this
 324 extension if it is present in the ClientHello and TLSv1.2 or below is
 325 negotiated.
 326 .IP "\s-1SSL_EXT_IGNORE_ON_RESUMPTION\s0" 4
 327 .IX Item "SSL_EXT_IGNORE_ON_RESUMPTION"
 328 The extension will be ignored during parsing if a previous session is being
 329 successfully resumed.
 330 .IP "\s-1SSL_EXT_CLIENT_HELLO\s0" 4
 331 .IX Item "SSL_EXT_CLIENT_HELLO"
 332 The extension may be present in the ClientHello message.
 333 .IP "\s-1SSL_EXT_TLS1_2_SERVER_HELLO\s0" 4
 334 .IX Item "SSL_EXT_TLS1_2_SERVER_HELLO"
 335 The extension may be present in a TLSv1.2 or below compatible ServerHello
 336 message.
 337 .IP "\s-1SSL_EXT_TLS1_3_SERVER_HELLO\s0" 4
 338 .IX Item "SSL_EXT_TLS1_3_SERVER_HELLO"
 339 The extension may be present in a TLSv1.3 compatible ServerHello message.
 340 .IP "\s-1SSL_EXT_TLS1_3_ENCRYPTED_EXTENSIONS\s0" 4
 341 .IX Item "SSL_EXT_TLS1_3_ENCRYPTED_EXTENSIONS"
 342 The extension may be present in an EncryptedExtensions message.
 343 .IP "\s-1SSL_EXT_TLS1_3_HELLO_RETRY_REQUEST\s0" 4
 344 .IX Item "SSL_EXT_TLS1_3_HELLO_RETRY_REQUEST"
 345 The extension may be present in a HelloRetryRequest message.
 346 .IP "\s-1SSL_EXT_TLS1_3_CERTIFICATE\s0" 4
 347 .IX Item "SSL_EXT_TLS1_3_CERTIFICATE"
 348 The extension may be present in a TLSv1.3 compatible Certificate message.
 349 .IP "\s-1SSL_EXT_TLS1_3_NEW_SESSION_TICKET\s0" 4
 350 .IX Item "SSL_EXT_TLS1_3_NEW_SESSION_TICKET"
 351 The extension may be present in a TLSv1.3 compatible NewSessionTicket message.
 352 .IP "\s-1SSL_EXT_TLS1_3_CERTIFICATE_REQUEST\s0" 4
 353 .IX Item "SSL_EXT_TLS1_3_CERTIFICATE_REQUEST"
 354 The extension may be present in a TLSv1.3 compatible CertificateRequest message.
 355 .PP
 356 The context must include at least one message value (otherwise the extension
 357 will never be used).
 358 .SH "NOTES"
 359 .IX Header "NOTES"
 360 The \fBadd_arg\fR and \fBparse_arg\fR parameters can be set to arbitrary values
 361 which will be passed to the corresponding callbacks. They can, for example,
 362 be used to store the extension data received in a convenient structure or
 363 pass the extension data to be added or freed when adding extensions.
 364 .PP
 365 If the same custom extension type is received multiple times a fatal
 366 \&\fBdecode_error\fR alert is sent and the handshake aborts. If a custom extension
 367 is received in a ServerHello/EncryptedExtensions message which was not sent in
 368 the ClientHello a fatal \fBunsupported_extension\fR alert is sent and the
 369 handshake is aborted. The ServerHello/EncryptedExtensions \fBadd_cb\fR callback is
 370 only called if the corresponding extension was received in the ClientHello. This
 371 is compliant with the \s-1TLS\s0 specifications. This behaviour ensures that each
 372 callback is called at most once and that an application can never send
 373 unsolicited extensions.
 374 .SH "RETURN VALUES"
 375 .IX Header "RETURN VALUES"
 376 \&\fISSL_CTX_add_custom_ext()\fR, \fISSL_CTX_add_client_custom_ext()\fR and
 377 \&\fISSL_CTX_add_server_custom_ext()\fR return 1 for success and 0 for failure. A
 378 failure can occur if an attempt is made to add the same \fBext_type\fR more than
 379 once, if an attempt is made to use an extension type handled internally by
 380 OpenSSL or if an internal error occurs (for example a memory allocation
 381 failure).
 382 .PP
 383 \&\fISSL_extension_supported()\fR returns 1 if the extension \fBext_type\fR is handled
 384 internally by OpenSSL and 0 otherwise.
 385 .SH "HISTORY"
 386 .IX Header "HISTORY"
 387 The function \fISSL_CTX_add_custom_ext()\fR was added in OpenSSL 1.1.1.
 388 .SH "COPYRIGHT"
 389 .IX Header "COPYRIGHT"
 390 Copyright 2014\-2017 The OpenSSL Project Authors. All Rights Reserved.
 391 .PP
 392 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 393 this file except in compliance with the License.  You can obtain a copy
 394 in the file \s-1LICENSE\s0 in the source distribution or at
 395 <https://www.openssl.org/source/license.html>.