aboutsummaryrefslogtreecommitdiffstats
path: root/doc/ssl
diff options
context:
space:
mode:
authorJung-uk Kim <jkim@FreeBSD.org>2014-08-07 16:49:55 +0000
committerJung-uk Kim <jkim@FreeBSD.org>2014-08-07 16:49:55 +0000
commitcb6864802ed26a1031701a6a385961592a5cac25 (patch)
tree785ec650cf5f2272f38035e18a3251735344f96d /doc/ssl
parent2e22f5e2e00c1f1f599b03634ca27bb5b9ac471e (diff)
downloadsrc-cb6864802ed26a1031701a6a385961592a5cac25.tar.gz
src-cb6864802ed26a1031701a6a385961592a5cac25.zip
Import OpenSSL 1.0.1i.vendor/openssl/1.0.1i
Notes
Notes: svn path=/vendor-crypto/openssl/dist/; revision=269670 svn path=/vendor-crypto/openssl/1.0.1i/; revision=269671; tag=vendor/openssl/1.0.1i
Diffstat (limited to 'doc/ssl')
-rw-r--r--doc/ssl/SSL_CIPHER_get_name.pod15
-rw-r--r--doc/ssl/SSL_CTX_add_extra_chain_cert.pod10
-rw-r--r--doc/ssl/SSL_CTX_add_session.pod2
-rw-r--r--doc/ssl/SSL_CTX_new.pod34
-rw-r--r--doc/ssl/SSL_CTX_set_cipher_list.pod4
-rw-r--r--doc/ssl/SSL_CTX_set_client_CA_list.pod2
-rw-r--r--doc/ssl/SSL_CTX_set_client_cert_cb.pod2
-rw-r--r--doc/ssl/SSL_CTX_set_options.pod2
-rw-r--r--doc/ssl/SSL_CTX_set_tlsext_ticket_key_cb.pod195
-rw-r--r--doc/ssl/SSL_CTX_set_tmp_dh_callback.pod6
-rw-r--r--doc/ssl/SSL_CTX_set_verify.pod4
-rw-r--r--doc/ssl/SSL_get_version.pod14
-rw-r--r--doc/ssl/d2i_SSL_SESSION.pod10
13 files changed, 274 insertions, 26 deletions
diff --git a/doc/ssl/SSL_CIPHER_get_name.pod b/doc/ssl/SSL_CIPHER_get_name.pod
index eb772b55de4a..2e113be6065c 100644
--- a/doc/ssl/SSL_CIPHER_get_name.pod
+++ b/doc/ssl/SSL_CIPHER_get_name.pod
@@ -23,8 +23,12 @@ SSL_CIPHER_get_bits() returns the number of secret bits used for B<cipher>. If
B<alg_bits> is not NULL, it contains the number of bits processed by the
chosen algorithm. If B<cipher> is NULL, 0 is returned.
-SSL_CIPHER_get_version() returns the protocol version for B<cipher>, currently
-"SSLv2", "SSLv3", or "TLSv1". If B<cipher> is NULL, "(NONE)" is returned.
+SSL_CIPHER_get_version() returns string which indicates the SSL/TLS protocol
+version that first defined the cipher.
+This is currently B<SSLv2> or B<TLSv1/SSLv3>.
+In some cases it should possibly return "TLSv1.2" but does not;
+use SSL_CIPHER_description() instead.
+If B<cipher> is NULL, "(NONE)" is returned.
SSL_CIPHER_description() returns a textual description of the cipher used
into the buffer B<buf> of length B<len> provided. B<len> must be at least
@@ -52,7 +56,8 @@ Textual representation of the cipher name.
=item <protocol version>
-Protocol version: B<SSLv2>, B<SSLv3>. The TLSv1 ciphers are flagged with SSLv3.
+Protocol version: B<SSLv2>, B<SSLv3>, B<TLSv1.2>. The TLSv1.0 ciphers are
+flagged with SSLv3. No new ciphers were added by TLSv1.1.
=item Kx=<key exchange>
@@ -91,6 +96,10 @@ Some examples for the output of SSL_CIPHER_description():
RC4-MD5 SSLv3 Kx=RSA Au=RSA Enc=RC4(128) Mac=MD5
EXP-RC4-MD5 SSLv3 Kx=RSA(512) Au=RSA Enc=RC4(40) Mac=MD5 export
+A comp[lete list can be retrieved by invoking the following command:
+
+ openssl ciphers -v ALL
+
=head1 BUGS
If SSL_CIPHER_description() is called with B<cipher> being NULL, the
diff --git a/doc/ssl/SSL_CTX_add_extra_chain_cert.pod b/doc/ssl/SSL_CTX_add_extra_chain_cert.pod
index ee28f5ccc3a3..5955ee1cb415 100644
--- a/doc/ssl/SSL_CTX_add_extra_chain_cert.pod
+++ b/doc/ssl/SSL_CTX_add_extra_chain_cert.pod
@@ -24,6 +24,16 @@ the library will try to complete the chain from the available CA
certificates in the trusted CA storage, see
L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>.
+The B<x509> certificate provided to SSL_CTX_add_extra_chain_cert() will be freed by the library when the B<SSL_CTX> is destroyed. An application B<should not> free the B<x509> object.
+
+=head1 RESTRICTIONS
+
+Only one set of extra chain certificates can be specified per SSL_CTX
+structure. Different chains for different certificates (for example if both
+RSA and DSA certificates are specified by the same server) or different SSL
+structures with the same parent SSL_CTX cannot be specified using this
+function.
+
=head1 RETURN VALUES
SSL_CTX_add_extra_chain_cert() returns 1 on success. Check out the
diff --git a/doc/ssl/SSL_CTX_add_session.pod b/doc/ssl/SSL_CTX_add_session.pod
index 8e0abd36cd68..c660a18fc2a1 100644
--- a/doc/ssl/SSL_CTX_add_session.pod
+++ b/doc/ssl/SSL_CTX_add_session.pod
@@ -41,7 +41,7 @@ If a server SSL_CTX is configured with the SSL_SESS_CACHE_NO_INTERNAL_STORE
flag then the internal cache will not be populated automatically by new
sessions negotiated by the SSL/TLS implementation, even though the internal
cache will be searched automatically for session-resume requests (the
-latter can be surpressed by SSL_SESS_CACHE_NO_INTERNAL_LOOKUP). So the
+latter can be suppressed by SSL_SESS_CACHE_NO_INTERNAL_LOOKUP). So the
application can use SSL_CTX_add_session() directly to have full control
over the sessions that can be resumed if desired.
diff --git a/doc/ssl/SSL_CTX_new.pod b/doc/ssl/SSL_CTX_new.pod
index 73e8c47f9a2e..491ac8c172cb 100644
--- a/doc/ssl/SSL_CTX_new.pod
+++ b/doc/ssl/SSL_CTX_new.pod
@@ -51,22 +51,36 @@ SSLv3 client hello messages.
=item SSLv23_method(void), SSLv23_server_method(void), SSLv23_client_method(void)
-A TLS/SSL connection established with these methods will understand the SSLv2,
-SSLv3, and TLSv1 protocol. A client will send out SSLv2 client hello messages
-and will indicate that it also understands SSLv3 and TLSv1. A server will
-understand SSLv2, SSLv3, and TLSv1 client hello messages. This is the best
-choice when compatibility is a concern.
+A TLS/SSL connection established with these methods may understand the SSLv2,
+SSLv3, TLSv1, TLSv1.1 and TLSv1.2 protocols.
+
+If the cipher list does not contain any SSLv2 ciphersuites (the default
+cipher list does not) or extensions are required (for example server name)
+a client will send out TLSv1 client hello messages including extensions and
+will indicate that it also understands TLSv1.1, TLSv1.2 and permits a
+fallback to SSLv3. A server will support SSLv3, TLSv1, TLSv1.1 and TLSv1.2
+protocols. This is the best choice when compatibility is a concern.
+
+If any SSLv2 ciphersuites are included in the cipher list and no extensions
+are required then SSLv2 compatible client hellos will be used by clients and
+SSLv2 will be accepted by servers. This is B<not> recommended due to the
+insecurity of SSLv2 and the limited nature of the SSLv2 client hello
+prohibiting the use of extensions.
=back
The list of protocols available can later be limited using the SSL_OP_NO_SSLv2,
-SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1 options of the B<SSL_CTX_set_options()> or
-B<SSL_set_options()> functions. Using these options it is possible to choose
-e.g. SSLv23_server_method() and be able to negotiate with all possible
-clients, but to only allow newer protocols like SSLv3 or TLSv1.
+SSL_OP_NO_SSLv3, SSL_OP_NO_TLSv1, SSL_OP_NO_TLSv1_1 and SSL_OP_NO_TLSv1_2
+options of the SSL_CTX_set_options() or SSL_set_options() functions.
+Using these options it is possible to choose e.g. SSLv23_server_method() and
+be able to negotiate with all possible clients, but to only allow newer
+protocols like TLSv1, TLSv1.1 or TLS v1.2.
+
+Applications which never want to support SSLv2 (even is the cipher string
+is configured to use SSLv2 ciphersuites) can set SSL_OP_NO_SSLv2.
SSL_CTX_new() initializes the list of ciphers, the session cache setting,
-the callbacks, the keys and certificates, and the options to its default
+the callbacks, the keys and certificates and the options to its default
values.
=head1 RETURN VALUES
diff --git a/doc/ssl/SSL_CTX_set_cipher_list.pod b/doc/ssl/SSL_CTX_set_cipher_list.pod
index ed64f6415702..bd4df4abd461 100644
--- a/doc/ssl/SSL_CTX_set_cipher_list.pod
+++ b/doc/ssl/SSL_CTX_set_cipher_list.pod
@@ -54,6 +54,10 @@ of 512 bits and the server is not configured to use temporary RSA
keys), the "no shared cipher" (SSL_R_NO_SHARED_CIPHER) error is generated
and the handshake will fail.
+If the cipher list does not contain any SSLv2 cipher suites (this is the
+default) then SSLv2 is effectively disabled and neither clients nor servers
+will attempt to use SSLv2.
+
=head1 RETURN VALUES
SSL_CTX_set_cipher_list() and SSL_set_cipher_list() return 1 if any cipher
diff --git a/doc/ssl/SSL_CTX_set_client_CA_list.pod b/doc/ssl/SSL_CTX_set_client_CA_list.pod
index 5e97392668a2..4965385e97ae 100644
--- a/doc/ssl/SSL_CTX_set_client_CA_list.pod
+++ b/doc/ssl/SSL_CTX_set_client_CA_list.pod
@@ -35,7 +35,7 @@ the chosen B<ssl>, overriding the setting valid for B<ssl>'s SSL_CTX object.
=head1 NOTES
When a TLS/SSL server requests a client certificate (see
-B<SSL_CTX_set_verify_options()>), it sends a list of CAs, for which
+B<SSL_CTX_set_verify(3)>), it sends a list of CAs, for which
it will accept certificates, to the client.
This list must explicitly be set using SSL_CTX_set_client_CA_list() for
diff --git a/doc/ssl/SSL_CTX_set_client_cert_cb.pod b/doc/ssl/SSL_CTX_set_client_cert_cb.pod
index 3465b5c7bbaf..d0df69a9bc18 100644
--- a/doc/ssl/SSL_CTX_set_client_cert_cb.pod
+++ b/doc/ssl/SSL_CTX_set_client_cert_cb.pod
@@ -29,7 +29,7 @@ using the B<x509> and B<pkey> arguments and "1" must be returned. The
certificate will be installed into B<ssl>, see the NOTES and BUGS sections.
If no certificate should be set, "0" has to be returned and no certificate
will be sent. A negative return value will suspend the handshake and the
-handshake function will return immediatly. L<SSL_get_error(3)|SSL_get_error(3)>
+handshake function will return immediately. L<SSL_get_error(3)|SSL_get_error(3)>
will return SSL_ERROR_WANT_X509_LOOKUP to indicate, that the handshake was
suspended. The next call to the handshake function will again lead to the call
of client_cert_cb(). It is the job of the client_cert_cb() to store information
diff --git a/doc/ssl/SSL_CTX_set_options.pod b/doc/ssl/SSL_CTX_set_options.pod
index d8866927a262..6e6b5e6d8082 100644
--- a/doc/ssl/SSL_CTX_set_options.pod
+++ b/doc/ssl/SSL_CTX_set_options.pod
@@ -256,7 +256,7 @@ Connections and renegotiation are always permitted by OpenSSL implementations.
=head2 Unpatched client and patched OpenSSL server
-The initial connection suceeds but client renegotiation is denied by the
+The initial connection succeeds but client renegotiation is denied by the
server with a B<no_renegotiation> warning alert if TLS v1.0 is used or a fatal
B<handshake_failure> alert in SSL v3.0.
diff --git a/doc/ssl/SSL_CTX_set_tlsext_ticket_key_cb.pod b/doc/ssl/SSL_CTX_set_tlsext_ticket_key_cb.pod
new file mode 100644
index 000000000000..da0dd0f597e4
--- /dev/null
+++ b/doc/ssl/SSL_CTX_set_tlsext_ticket_key_cb.pod
@@ -0,0 +1,195 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_tlsext_ticket_key_cb - set a callback for session ticket processing
+
+=head1 SYNOPSIS
+
+ #include <openssl/tls1.h>
+
+ long SSL_CTX_set_tlsext_ticket_key_cb(SSL_CTX sslctx,
+ int (*cb)(SSL *s, unsigned char key_name[16],
+ unsigned char iv[EVP_MAX_IV_LENGTH],
+ EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc));
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_tlsext_ticket_key_cb() sets a callback fuction I<cb> for handling
+session tickets for the ssl context I<sslctx>. Session tickets, defined in
+RFC5077 provide an enhanced session resumption capability where the server
+implementation is not required to maintain per session state. It only applies
+to TLS and there is no SSLv3 implementation.
+
+The callback is available when the OpenSSL library was built without
+I<OPENSSL_NO_TLSEXT> being defined.
+
+The callback function I<cb> will be called for every client instigated TLS
+session when session ticket extension is presented in the TLS hello
+message. It is the responsibility of this function to create or retrieve the
+cryptographic parameters and to maintain their state.
+
+The OpenSSL library uses your callback function to help implement a common TLS
+ticket construction state according to RFC5077 Section 4 such that per session
+state is unnecessary and a small set of cryptographic variables needs to be
+maintained by the callback function implementation.
+
+In order to reuse a session, a TLS client must send the a session ticket
+extension to the server. The client can only send exactly one session ticket.
+The server, through the callback function, either agrees to reuse the session
+ticket information or it starts a full TLS handshake to create a new session
+ticket.
+
+Before the callback function is started I<ctx> and I<hctx> have been
+initialised with EVP_CIPHER_CTX_init and HMAC_CTX_init respectively.
+
+For new sessions tickets, when the client doesn't present a session ticket, or
+an attempted retreival of the ticket failed, or a renew option was indicated,
+the callback function will be called with I<enc> equal to 1. The OpenSSL
+library expects that the function will set an arbitary I<name>, initialize
+I<iv>, and set the cipher context I<ctx> and the hash context I<hctx>.
+
+The I<name> is 16 characters long and is used as a key identifier.
+
+The I<iv> length is the length of the IV of the corresponding cipher. The
+maximum IV length is L<EVP_MAX_IV_LENGTH> bytes defined in B<evp.h>.
+
+The initialization vector I<iv> should be a random value. The cipher context
+I<ctx> should use the initialisation vector I<iv>. The cipher context can be
+set using L<EVP_EncryptInit_ex>. The hmac context can be set using L<HMAC_Init_ex>.
+
+When the client presents a session ticket, the callback function with be called
+with I<enc> set to 0 indicating that the I<cb> function should retreive a set
+of parameters. In this case I<name> and I<iv> have already been parsed out of
+the session ticket. The OpenSSL library expects that the I<name> will be used
+to retrieve a cryptographic parameters and that the cryptographic context
+I<ctx> will be set with the retreived parameters and the initialization vector
+I<iv>. using a function like L<EVP_DecryptInit_ex>. The I<hctx> needs to be set
+using L<HMAC_Init_ex>.
+
+If the I<name> is still valid but a renewal of the ticket is required the
+callback function should return 2. The library will call the callback again
+with an arguement of enc equal to 1 to set the new ticket.
+
+The return value of the I<cb> function is used by OpenSSL to determine what
+further processing will occur. The following return values have meaning:
+
+=over 4
+
+=item Z<>2
+
+This indicates that the I<ctx> and I<hctx> have been set and the session can
+continue on those parameters. Additionally it indicates that the session
+ticket is in a renewal period and should be replaced. The OpenSSL library will
+call I<cb> again with an enc argument of 1 to set the new ticket (see RFC5077
+3.3 paragraph 2).
+
+=item Z<>1
+
+This indicates that the I<ctx> and I<hctx> have been set and the session can
+continue on those parameters.
+
+=item Z<>0
+
+This indicates that it was not possible to set/retrieve a session ticket and
+the SSL/TLS session will continue by by negiotationing a set of cryptographic
+parameters or using the alternate SSL/TLS resumption mechanism, session ids.
+
+If called with enc equal to 0 the library will call the I<cb> again to get
+a new set of parameters.
+
+=item less than 0
+
+This indicates an error.
+
+=back
+
+=head1 NOTES
+
+Session resumption shortcuts the TLS so that the client certificate
+negiotation don't occur. It makes up for this by storing client certificate
+an all other negotiated state information encrypted within the ticket. In a
+resumed session the applications will have all this state information available
+exactly as if a full negiotation had occured.
+
+If an attacker can obtain the key used to encrypt a session ticket, they can
+obtain the master secret for any ticket using that key and decrypt any traffic
+using that session: even if the ciphersuite supports forward secrecy. As
+a result applications may wish to use multiple keys and avoid using long term
+keys stored in files.
+
+Applications can use longer keys to maintain a consistent level of security.
+For example if a ciphersuite uses 256 bit ciphers but only a 128 bit ticket key
+the overall security is only 128 bits because breaking the ticket key will
+enable an attacker to obtain the session keys.
+
+=head1 EXAMPLES
+
+Reference Implemention:
+ SSL_CTX_set_tlsext_ticket_key_cb(SSL,ssl_tlsext_ticket_key_cb);
+ ....
+
+ static int ssl_tlsext_ticket_key_cb(SSL *s, unsigned char key_name[16], unsigned char *iv, EVP_CIPHER_CTX *ctx, HMAC_CTX *hctx, int enc)
+ {
+ if (enc) { /* create new session */
+ if (RAND_bytes(iv, EVP_MAX_IV_LENGTH) ) {
+ return -1; /* insufficient random */
+ }
+
+ key = currentkey(); /* something that you need to implement */
+ if ( !key ) {
+ /* current key doesn't exist or isn't valid */
+ key = createkey(); /* something that you need to implement.
+ * createkey needs to initialise, a name,
+ * an aes_key, a hmac_key and optionally
+ * an expire time. */
+ if ( !key ) { /* key couldn't be created */
+ return 0;
+ }
+ }
+ memcpy(key_name, key->name, 16);
+
+ EVP_EncryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key->aes_key, iv);
+ HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL);
+
+ return 1;
+
+ } else { /* retrieve session */
+ key = findkey(name);
+
+ if (!key || key->expire < now() ) {
+ return 0;
+ }
+
+ HMAC_Init_ex(&hctx, key->hmac_key, 16, EVP_sha256(), NULL);
+ EVP_DecryptInit_ex(&ctx, EVP_aes_128_cbc(), NULL, key->aes_key, iv );
+
+ if (key->expire < ( now() - RENEW_TIME ) ) {
+ /* return 2 - this session will get a new ticket even though the current is still valid */
+ return 2;
+ }
+ return 1;
+
+ }
+ }
+
+
+
+=head1 RETURN VALUES
+
+returns 0 to indicate the callback function was set.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_set_session(3)|SSL_set_session(3)>,
+L<SSL_session_reused(3)|SSL_session_reused(3)>,
+L<SSL_CTX_add_session(3)|SSL_CTX_add_session(3)>,
+L<SSL_CTX_sess_number(3)|SSL_CTX_sess_number(3)>,
+L<SSL_CTX_sess_set_get_cb(3)|SSL_CTX_sess_set_get_cb(3)>,
+L<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>,
+
+=head1 HISTORY
+
+This function was introduced in OpenSSL 0.9.8h
+
+=cut
diff --git a/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod b/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod
index 29d1f8a6fbfe..b34c68aba343 100644
--- a/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod
+++ b/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod
@@ -12,12 +12,10 @@ SSL_CTX_set_tmp_dh_callback, SSL_CTX_set_tmp_dh, SSL_set_tmp_dh_callback, SSL_se
DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength));
long SSL_CTX_set_tmp_dh(SSL_CTX *ctx, DH *dh);
- void SSL_set_tmp_dh_callback(SSL_CTX *ctx,
+ void SSL_set_tmp_dh_callback(SSL *ctx,
DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength));
long SSL_set_tmp_dh(SSL *ssl, DH *dh)
- DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength));
-
=head1 DESCRIPTION
SSL_CTX_set_tmp_dh_callback() sets the callback function for B<ctx> to be
@@ -81,7 +79,7 @@ instead (see L<dhparam(1)|dhparam(1)>), but in this case SSL_OP_SINGLE_DH_USE
is mandatory.
Application authors may compile in DH parameters. Files dh512.pem,
-dh1024.pem, dh2048.pem, and dh4096 in the 'apps' directory of current
+dh1024.pem, dh2048.pem, and dh4096.pem in the 'apps' directory of current
version of the OpenSSL distribution contain the 'SKIP' DH parameters,
which use safe primes and were generated verifiably pseudo-randomly.
These files can be converted into C code using the B<-C> option of the
diff --git a/doc/ssl/SSL_CTX_set_verify.pod b/doc/ssl/SSL_CTX_set_verify.pod
index 6fd6c0321551..b6ba6bb51cad 100644
--- a/doc/ssl/SSL_CTX_set_verify.pod
+++ b/doc/ssl/SSL_CTX_set_verify.pod
@@ -109,8 +109,8 @@ certificates would not be present, most likely a
X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY will be issued.
The depth count is "level 0:peer certificate", "level 1: CA certificate",
"level 2: higher level CA certificate", and so on. Setting the maximum
-depth to 2 allows the levels 0, 1, and 2. The default depth limit is 9,
-allowing for the peer certificate and additional 9 CA certificates.
+depth to 2 allows the levels 0, 1, and 2. The default depth limit is 100,
+allowing for the peer certificate and additional 100 CA certificates.
The B<verify_callback> function is used to control the behaviour when the
SSL_VERIFY_PEER flag is set. It must be supplied by the application and
diff --git a/doc/ssl/SSL_get_version.pod b/doc/ssl/SSL_get_version.pod
index cc271db2c534..9ae6f2550858 100644
--- a/doc/ssl/SSL_get_version.pod
+++ b/doc/ssl/SSL_get_version.pod
@@ -12,12 +12,12 @@ SSL_get_version - get the protocol version of a connection.
=head1 DESCRIPTION
-SSL_get_cipher_version() returns the name of the protocol used for the
+SSL_get_version() returns the name of the protocol used for the
connection B<ssl>.
=head1 RETURN VALUES
-The following strings can occur:
+The following strings can be returned:
=over 4
@@ -31,7 +31,15 @@ The connection uses the SSLv3 protocol.
=item TLSv1
-The connection uses the TLSv1 protocol.
+The connection uses the TLSv1.0 protocol.
+
+=item TLSv1.1
+
+The connection uses the TLSv1.1 protocol.
+
+=item TLSv1.2
+
+The connection uses the TLSv1.2 protocol.
=item unknown
diff --git a/doc/ssl/d2i_SSL_SESSION.pod b/doc/ssl/d2i_SSL_SESSION.pod
index 81d276477f9f..bce06e23b619 100644
--- a/doc/ssl/d2i_SSL_SESSION.pod
+++ b/doc/ssl/d2i_SSL_SESSION.pod
@@ -48,6 +48,16 @@ known limit on the size of the created ASN1 representation, so the necessary
amount of space should be obtained by first calling i2d_SSL_SESSION() with
B<pp=NULL>, and obtain the size needed, then allocate the memory and
call i2d_SSL_SESSION() again.
+Note that this will advance the value contained in B<*pp> so it is necessary
+to save a copy of the original allocation.
+For example:
+ int i,j;
+ char *p, *temp;
+ i = i2d_SSL_SESSION(sess, NULL);
+ p = temp = malloc(i);
+ j = i2d_SSL_SESSION(sess, &temp);
+ assert(i == j);
+ assert(p+i == temp);
=head1 RETURN VALUES