Fixed error in pod files with latest versions of pod2man
[openssl.git] / doc / ssl / SSL_CTX_set_tlsext_ticket_key_cb.pod
index 610523407a5e3ed8c4f6c2168adb57a2b323164a..da0dd0f597e40de8d636a871bf17ccb1d9802e01 100644 (file)
@@ -49,8 +49,10 @@ 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 only 16 characters long. The I<iv> is of length
-L<EVP_MAX_IV_LENGTH> defined in B<evp.h>.
+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 
@@ -74,7 +76,7 @@ further processing will occur. The following return values have meaning:
 
 =over 4
 
-=item 2
+=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
@@ -82,12 +84,12 @@ 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 1
+=item Z<>1
 
 This indicates that the I<ctx> and I<hctx> have been set and the session can 
 continue on those parameters.
 
-=item 0
+=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
@@ -110,6 +112,17 @@ 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: