]>
Commit | Line | Data |
---|---|---|
c0f5dd07 LJ |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
bebbb11d | 5 | SSL_CTX_set_max_cert_list, SSL_CTX_get_max_cert_list, SSL_set_max_cert_list, SSL_get_max_cert_list - manipulate allowed size for the peer's certificate chain |
c0f5dd07 LJ |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/ssl.h> | |
10 | ||
11 | long SSL_CTX_set_max_cert_list(SSL_CTX *ctx, long size); | |
12 | long SSL_CTX_get_max_cert_list(SSL_CTX *ctx); | |
13 | ||
14 | long SSL_set_max_cert_list(SSL *ssl, long size); | |
15 | long SSL_get_max_cert_list(SSL *ctx); | |
16 | ||
17 | =head1 DESCRIPTION | |
18 | ||
19 | SSL_CTX_set_max_cert_list() sets the maximum size allowed for the peer's | |
20 | certificate chain for all SSL objects created from B<ctx> to be <size> bytes. | |
21 | The SSL objects inherit the setting valid for B<ctx> at the time | |
9b86974e | 22 | L<SSL_new(3)> is being called. |
c0f5dd07 LJ |
23 | |
24 | SSL_CTX_get_max_cert_list() returns the currently set maximum size for B<ctx>. | |
25 | ||
26 | SSL_set_max_cert_list() sets the maximum size allowed for the peer's | |
27 | certificate chain for B<ssl> to be <size> bytes. This setting stays valid | |
28 | until a new value is set. | |
29 | ||
30 | SSL_get_max_cert_list() returns the currently set maximum size for B<ssl>. | |
31 | ||
32 | =head1 NOTES | |
33 | ||
34 | During the handshake process, the peer may send a certificate chain. | |
35 | The TLS/SSL standard does not give any maximum size of the certificate chain. | |
36 | The OpenSSL library handles incoming data by a dynamically allocated buffer. | |
37 | In order to prevent this buffer from growing without bounds due to data | |
38 | received from a faulty or malicious peer, a maximum size for the certificate | |
39 | chain is set. | |
40 | ||
41 | The default value for the maximum certificate chain size is 100kB (30kB | |
42 | on the 16bit DOS platform). This should be sufficient for usual certificate | |
43 | chains (OpenSSL's default maximum chain length is 10, see | |
9b86974e | 44 | L<SSL_CTX_set_verify(3)>, and certificates |
c0f5dd07 LJ |
45 | without special extensions have a typical size of 1-2kB). |
46 | ||
47 | For special applications it can be necessary to extend the maximum certificate | |
48 | chain size allowed to be sent by the peer, see e.g. the work on | |
49 | "Internet X.509 Public Key Infrastructure Proxy Certificate Profile" | |
50 | and "TLS Delegation Protocol" at http://www.ietf.org/ and | |
51 | http://www.globus.org/ . | |
52 | ||
53 | Under normal conditions it should never be necessary to set a value smaller | |
54 | than the default, as the buffer is handled dynamically and only uses the | |
55 | memory actually required by the data sent by the peer. | |
56 | ||
57 | If the maximum certificate chain size allowed is exceeded, the handshake will | |
58 | fail with a SSL_R_EXCESSIVE_MESSAGE_SIZE error. | |
59 | ||
60 | =head1 RETURN VALUES | |
61 | ||
62 | SSL_CTX_set_max_cert_list() and SSL_set_max_cert_list() return the previously | |
63 | set value. | |
64 | ||
65 | SSL_CTX_get_max_cert_list() and SSL_get_max_cert_list() return the currently | |
66 | set value. | |
67 | ||
68 | =head1 SEE ALSO | |
69 | ||
9b86974e RS |
70 | L<ssl(3)>, L<SSL_new(3)>, |
71 | L<SSL_CTX_set_verify(3)> | |
c0f5dd07 LJ |
72 | |
73 | =head1 HISTORY | |
74 | ||
75 | SSL*_set/get_max_cert_list() have been introduced in OpenSSL 0.9.7. | |
76 | ||
77 | =cut |