1: =pod
    2: 
    3: =head1 NAME
    4: 
    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 for the peer's certificate chain
    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
   22: L<SSL_new(3)|SSL_new(3)> is being called.
   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
   44: L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>, and certificates
   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: 
   70: L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>,
   71: L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>
   72: 
   73: =head1 HISTORY
   74: 
   75: SSL*_set/get_max_cert_list() have been introduced in OpenSSL 0.9.7.
   76: 
   77: =cut