]>
Commit | Line | Data |
---|---|---|
9cd50f73 T |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
fb29c0f0 MC |
5 | SSL_CTX_use_serverinfo_ex, |
6 | SSL_CTX_use_serverinfo, | |
7 | SSL_CTX_use_serverinfo_file | |
8 | - use serverinfo extension | |
9cd50f73 T |
9 | |
10 | =head1 SYNOPSIS | |
11 | ||
12 | #include <openssl/ssl.h> | |
13 | ||
fb29c0f0 MC |
14 | int SSL_CTX_use_serverinfo_ex(SSL_CTX *ctx, unsigned int version, |
15 | const unsigned char *serverinfo, | |
16 | size_t serverinfo_length); | |
17 | ||
9cd50f73 T |
18 | int SSL_CTX_use_serverinfo(SSL_CTX *ctx, const unsigned char *serverinfo, |
19 | size_t serverinfo_length); | |
20 | ||
21 | int SSL_CTX_use_serverinfo_file(SSL_CTX *ctx, const char *file); | |
22 | ||
23 | =head1 DESCRIPTION | |
24 | ||
fb29c0f0 MC |
25 | These functions load "serverinfo" TLS extensions into the SSL_CTX. A |
26 | "serverinfo" extension is returned in response to an empty ClientHello | |
9cd50f73 T |
27 | Extension. |
28 | ||
fb29c0f0 MC |
29 | SSL_CTX_use_serverinfo_ex() loads one or more serverinfo extensions from |
30 | a byte array into B<ctx>. The B<version> parameter specifies the format of the | |
31 | byte array provided in B<*serverinfo> which is of length B<serverinfo_length>. | |
32 | ||
33 | If B<version> is B<SSL_SERVERINFOV2> then the extensions in the array must | |
34 | consist of a 4-byte context, a 2-byte Extension Type, a 2-byte length, and then | |
35 | length bytes of extension_data. The context and type values have the same | |
f233a9d1 MC |
36 | meaning as for L<SSL_CTX_add_custom_ext(3)>. If serverinfo is being loaded for |
37 | extensions to be added to a Certificate message, then the extension will only | |
6d9d8019 MC |
38 | be added for the first certificate in the message (which is always the |
39 | end-entity certificate). | |
fb29c0f0 MC |
40 | |
41 | If B<version> is B<SSL_SERVERINFOV1> then the extensions in the array must | |
42 | consist of a 2-byte Extension Type, a 2-byte length, and then length bytes of | |
43 | extension_data. The type value has the same meaning as for | |
44 | L<SSL_CTX_add_custom_ext(3)>. The following default context value will be used | |
45 | in this case: | |
46 | ||
47 | SSL_EXT_TLS1_2_AND_BELOW_ONLY | SSL_EXT_CLIENT_HELLO | |
48 | | SSL_EXT_TLS1_2_SERVER_HELLO | SSL_EXT_IGNORE_ON_RESUMPTION | |
49 | ||
50 | SSL_CTX_use_serverinfo() does the same thing as SSL_CTX_use_serverinfo_ex() | |
51 | except that there is no B<version> parameter so a default version of | |
52 | SSL_SERVERINFOV1 is used instead. | |
9cd50f73 T |
53 | |
54 | SSL_CTX_use_serverinfo_file() loads one or more serverinfo extensions from | |
deda5ea7 | 55 | B<file> into B<ctx>. The extensions must be in PEM format. Each extension |
fb29c0f0 MC |
56 | must be in a format as described above for SSL_CTX_use_serverinfo_ex(). Each |
57 | PEM extension name must begin with the phrase "BEGIN SERVERINFOV2 FOR " for | |
58 | SSL_SERVERINFOV2 data or "BEGIN SERVERINFO FOR " for SSL_SERVERINFOV1 data. | |
9cd50f73 | 59 | |
5f18bc58 TS |
60 | If more than one certificate (RSA/DSA) is installed using |
61 | SSL_CTX_use_certificate(), the serverinfo extension will be loaded into the | |
62 | last certificate installed. If e.g. the last item was a RSA certificate, the | |
63 | loaded serverinfo extension data will be loaded for that certificate. To | |
64 | use the serverinfo extension for multiple certificates, | |
65 | SSL_CTX_use_serverinfo() needs to be called multiple times, once B<after> | |
6d9d8019 | 66 | each time a certificate is loaded via a call to SSL_CTX_use_certificate(). |
5f18bc58 | 67 | |
9cd50f73 T |
68 | =head1 RETURN VALUES |
69 | ||
70 | On success, the functions return 1. | |
71 | On failure, the functions return 0. Check out the error stack to find out | |
72 | the reason. | |
73 | ||
98ca37e4 RS |
74 | =head1 SEE ALSO |
75 | ||
76 | L<ssl(7)> | |
77 | ||
e2f92610 RS |
78 | =head1 COPYRIGHT |
79 | ||
fb29c0f0 | 80 | Copyright 2013-2017 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 81 | |
4746f25a | 82 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
83 | this file except in compliance with the License. You can obtain a copy |
84 | in the file LICENSE in the source distribution or at | |
85 | L<https://www.openssl.org/source/license.html>. | |
86 | ||
9cd50f73 | 87 | =cut |