]>
Commit | Line | Data |
---|---|---|
a9c0d8be DB |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | SSL_CTX_set_client_hello_cb, SSL_client_hello_cb_fn, SSL_client_hello_isv2, SSL_client_hello_get0_legacy_version, SSL_client_hello_get0_random, SSL_client_hello_get0_session_id, SSL_client_hello_get0_ciphers, SSL_client_hello_get0_compression_methods, SSL_client_hello_get1_extensions_present, SSL_client_hello_get0_ext - callback functions for early server-side ClientHello processing | |
6 | ||
7 | =head1 SYNOPSIS | |
8 | ||
9 | typedef int (*SSL_client_hello_cb_fn)(SSL *s, int *al, void *arg); | |
10 | void SSL_CTX_set_client_hello_cb(SSL_CTX *c, SSL_client_hello_cb_fn *f, | |
11 | void *arg); | |
12 | int SSL_client_hello_isv2(SSL *s); | |
13 | unsigned int SSL_client_hello_get0_legacy_version(SSL *s); | |
14 | size_t SSL_client_hello_get0_random(SSL *s, const unsigned char **out); | |
15 | size_t SSL_client_hello_get0_session_id(SSL *s, const unsigned char **out); | |
16 | size_t SSL_client_hello_get0_ciphers(SSL *s, const unsigned char **out); | |
17 | size_t SSL_client_hello_get0_compression_methods(SSL *s, | |
18 | const unsigned char **out); | |
19 | int SSL_client_hello_get1_extensions_present(SSL *s, int **out, | |
20 | size_t *outlen); | |
21 | int SSL_client_hello_get0_ext(SSL *s, int type, const unsigned char **out, | |
22 | size_t *outlen); | |
23 | ||
24 | =head1 DESCRIPTION | |
25 | ||
26 | SSL_CTX_set_client_hello_cb() sets the callback function, which is automatically | |
27 | called during the early stages of ClientHello processing on the server. | |
28 | The argument supplied when setting the callback is passed back to the | |
29 | callback at runtime. A callback that returns failure (0) will cause the | |
30 | connection to terminate, and callbacks returning failure should indicate | |
31 | what alert value is to be sent in the B<al> parameter. A callback may | |
32 | also return a negative value to suspend the handshake, and the handshake | |
33 | function will return immediately. L<SSL_get_error(3)> will return | |
34 | SSL_ERROR_WANT_CLIENT_HELLO_CB to indicate that the handshake was suspended. | |
35 | It is the job of the ClientHello callback to store information about the state | |
36 | of the last call if needed to continue. On the next call into the handshake | |
37 | function, the ClientHello callback will be called again, and, if it returns | |
38 | success, normal handshake processing will continue from that point. | |
39 | ||
40 | SSL_client_hello_isv2() indicates whether the ClientHello was carried in a | |
41 | SSLv2 record and is in the SSLv2 format. The SSLv2 format has substantial | |
42 | differences from the normal SSLv3 format, including using three bytes per | |
43 | cipher suite, and not allowing extensions. Additionally, the SSLv2 format | |
44 | 'challenge' field is exposed via SSL_client_hello_get0_random(), padded to | |
45 | SSL3_RANDOM_SIZE bytes with zeros if needed. For SSLv2 format ClientHellos, | |
46 | SSL_client_hello_get0_compression_methods() returns a dummy list that only includes | |
47 | the null compression method, since the SSLv2 format does not include a | |
48 | mechanism by which to negotiate compression. | |
49 | ||
50 | SSL_client_hello_get0_random(), SSL_client_hello_get0_session_id(), | |
51 | SSL_client_hello_get0_ciphers(), and | |
52 | SSL_client_hello_get0_compression_methods() provide access to the corresponding | |
53 | ClientHello fields, returning the field length and optionally setting an out | |
54 | pointer to the octets of that field. | |
55 | ||
56 | Similarly, SSL_client_hello_get0_ext() provides access to individual extensions | |
57 | from the ClientHello on a per-extension basis. For the provided wire | |
58 | protocol extension type value, the extension value and length are returned | |
59 | in the output parameters (if present). | |
60 | ||
61 | SSL_client_hello_get1_extensions_present() can be used prior to | |
62 | SSL_client_hello_get0_ext(), to determine which extensions are present in the | |
63 | ClientHello before querying for them. The B<out> and B<outlen> parameters are | |
64 | both required, and on success the caller must release the storage allocated for | |
65 | B<*out> using OPENSSL_free(). The contents of B<*out> is an array of integers | |
66 | holding the numerical value of the TLS extension types in the order they appear | |
67 | in the ClientHello. B<*outlen> contains the number of elements in the array. | |
68 | ||
69 | =head1 NOTES | |
70 | ||
71 | The ClientHello callback provides a vast window of possibilities for application | |
72 | code to affect the TLS handshake. A primary use of the callback is to | |
73 | allow the server to examine the server name indication extension provided | |
74 | by the client in order to select an appropriate certificate to present, | |
75 | and make other configuration adjustments relevant to that server name | |
76 | and its configuration. Such configuration changes can include swapping out | |
77 | the associated SSL_CTX pointer, modifying the server's list of permitted TLS | |
78 | versions, changing the server's cipher list in response to the client's | |
79 | cipher list, etc. | |
80 | ||
81 | It is also recommended that applications utilize a ClientHello callback and | |
82 | not use a servername callback, in order to avoid unexpected behavior that | |
83 | occurs due to the relative order of processing between things like session | |
84 | resumption and the historical servername callback. | |
85 | ||
86 | The SSL_client_hello_* family of functions may only be called from code executing | |
87 | within a ClientHello callback. | |
88 | ||
89 | =head1 RETURN VALUES | |
90 | ||
f1b97da1 DB |
91 | The application's supplied ClientHello callback returns |
92 | SSL_CLIENT_HELLO_SUCCESS on success, SSL_CLIENT_HELLO_ERROR on failure, and | |
93 | SSL_CLIENT_HELLO_RETRY to suspend processing. | |
a9c0d8be DB |
94 | |
95 | SSL_client_hello_isv2() returns 1 for SSLv2-format ClientHellos and 0 otherwise. | |
96 | ||
97 | SSL_client_hello_get0_random(), SSL_client_hello_get0_session_id(), | |
98 | SSL_client_hello_get0_ciphers(), and | |
99 | SSL_client_hello_get0_compression_methods() return the length of the | |
100 | corresponding ClientHello fields. If zero is returned, the output pointer | |
101 | should not be assumed to be valid. | |
102 | ||
103 | SSL_client_hello_get0_ext() returns 1 if the extension of type 'type' is present, and | |
104 | 0 otherwise. | |
105 | ||
106 | SSL_client_hello_get1_extensions_present() returns 1 on success and 0 on failure. | |
107 | ||
108 | =head1 SEE ALSO | |
109 | ||
110 | L<ssl(7)>, L<SSL_CTX_set_tlsext_servername_callback(3)>, | |
111 | L<SSL_bytes_to_cipher_list> | |
112 | ||
113 | =head1 HISTORY | |
114 | ||
115 | The SSL ClientHello callback, SSL_client_hello_isv2(), | |
116 | SSL_client_hello_get0_random(), SSL_client_hello_get0_session_id(), | |
117 | SSL_client_hello_get0_ciphers(), SSL_client_hello_get0_compression_methods(), | |
118 | SSL_client_hello_get0_ext(), and SSL_client_hello_get1_extensions_present() | |
119 | were added in OpenSSL 1.1.1. | |
120 | ||
121 | =head1 COPYRIGHT | |
122 | ||
123 | Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. | |
124 | ||
4746f25a | 125 | Licensed under the Apache License 2.0 (the "License"). You may not use |
a9c0d8be DB |
126 | this file except in compliance with the License. You can obtain a copy |
127 | in the file LICENSE in the source distribution or at | |
128 | L<https://www.openssl.org/source/license.html>. | |
129 | ||
130 | =cut |