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