Merge OpenSSL 0.9.8m into head.

This also "reverts" some FreeBSD local changes so we should now
be back to using entirely stock OpenSSL.  The local changes were
simple $FreeBSD$ lines additions, which were required in the CVS
days, and the patch for FreeBSD-SA-09:15.ssl which has been
superseded with OpenSSL 0.9.8m's RFC5746 'TLS renegotiation
extension' support.

MFC after:	3 weeks

13 files changed, 188 insertions, 52 deletions

diff --git a/crypto/openssl/doc/apps/enc.pod b/crypto/openssl/doc/apps/enc.pod
index 4391c93..d3049e8 100644
--- a/crypto/openssl/doc/apps/enc.pod
+++ b/crypto/openssl/doc/apps/enc.pod
@@ -50,15 +50,13 @@ see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>.
 
 =item B<-salt>
 
-use a salt in the key derivation routines. This option should B<ALWAYS>
-be used unless compatibility with previous versions of OpenSSL or SSLeay
-is required. This option is only present on OpenSSL versions 0.9.5 or
-above.
+use a salt in the key derivation routines. This is the default.
 
 =item B<-nosalt>
 
-don't use a salt in the key derivation routines. This is the default for
-compatibility with previous versions of OpenSSL and SSLeay.
+don't use a salt in the key derivation routines. This option B<SHOULD NOT> be
+used except for test purposes or compatibility with ancient versions of OpenSSL
+and SSLeay.
 
 =item B<-e>
 
diff --git a/crypto/openssl/doc/apps/verify.pod b/crypto/openssl/doc/apps/verify.pod
index ff2629d..3187577 100644
--- a/crypto/openssl/doc/apps/verify.pod
+++ b/crypto/openssl/doc/apps/verify.pod
@@ -66,6 +66,11 @@ certificate was rejected. However the presence of rejection messages
 does not itself imply that anything is wrong: during the normal
 verify process several rejections may take place.
 
+=item B<-check_ss_sig>
+
+Verify the signature on the self-signed root CA. This is disabled by default
+because it doesn't add any security.
+
 =item B<->
 
 marks the last option. All arguments following this are assumed to be
@@ -166,8 +171,8 @@ the operation was successful.
 
 =item B<2 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate>
 
-the issuer certificate could not be found: this occurs if the issuer certificate
-of an untrusted certificate cannot be found.
+the issuer certificate of a looked up certificate could not be found. This
+normally means the list of trusted certificates is not complete.
 
 =item B<3 X509_V_ERR_UNABLE_TO_GET_CRL: unable to get certificate CRL>
 
@@ -244,8 +249,8 @@ be found locally.
 
 =item B<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate>
 
-the issuer certificate of a locally looked up certificate could not be found. This normally means
-the list of trusted certificates is not complete.
+the issuer certificate could not be found: this occurs if the issuer
+certificate of an untrusted certificate cannot be found.
 
 =item B<21 X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate>
 
@@ -321,6 +326,10 @@ the certificates in the file will be recognised.
 Previous versions of OpenSSL assume certificates with matching subject name are identical and
 mishandled them.
 
+Previous versions of this documentation swapped the meaning of the
+B<X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT> and
+B<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY> error codes.
+
 =head1 SEE ALSO
 
 L<x509(1)|x509(1)>
diff --git a/crypto/openssl/doc/crypto/ASN1_generate_nconf.pod b/crypto/openssl/doc/crypto/ASN1_generate_nconf.pod
index 1157cff..179132d 100644
--- a/crypto/openssl/doc/crypto/ASN1_generate_nconf.pod
+++ b/crypto/openssl/doc/crypto/ASN1_generate_nconf.pod
@@ -175,7 +175,7 @@ An IA5String explicitly tagged using APPLICATION tagging:
 
 A BITSTRING with bits 1 and 5 set and all others zero:
 
- FORMAT=BITLIST,BITSTRING:1,5
+ FORMAT:BITLIST,BITSTRING:1,5
 
 A more complex example using a config file to produce a
 SEQUENCE consiting of a BOOL an OID and a UTF8String:
diff --git a/crypto/openssl/doc/crypto/EVP_DigestInit.pod b/crypto/openssl/doc/crypto/EVP_DigestInit.pod
index 130cd7f..98b1368 100644
--- a/crypto/openssl/doc/crypto/EVP_DigestInit.pod
+++ b/crypto/openssl/doc/crypto/EVP_DigestInit.pod
@@ -64,9 +64,9 @@ EVP digest routines
 
 The EVP digest routines are a high level interface to message digests.
 
-EVP_MD_CTX_init() initializes digest contet B<ctx>.
+EVP_MD_CTX_init() initializes digest context B<ctx>.
 
-EVP_MD_CTX_create() allocates, initializes and returns a digest contet.
+EVP_MD_CTX_create() allocates, initializes and returns a digest context.
 
 EVP_DigestInit_ex() sets up digest context B<ctx> to use a digest
 B<type> from ENGINE B<impl>. B<ctx> must be initialized before calling this
@@ -102,7 +102,7 @@ the passed context B<ctx> does not have to be initialized, and it always
 uses the default digest implementation.
 
 EVP_DigestFinal() is similar to EVP_DigestFinal_ex() except the digest
-contet B<ctx> is automatically cleaned up.
+context B<ctx> is automatically cleaned up.
 
 EVP_MD_CTX_copy() is similar to EVP_MD_CTX_copy_ex() except the destination
 B<out> does not have to be initialized.
diff --git a/crypto/openssl/doc/crypto/PKCS12_parse.pod b/crypto/openssl/doc/crypto/PKCS12_parse.pod
index 51344f8..c54cf2a 100644
--- a/crypto/openssl/doc/crypto/PKCS12_parse.pod
+++ b/crypto/openssl/doc/crypto/PKCS12_parse.pod
@@ -20,24 +20,31 @@ certificate to B<*cert> and any additional certificates to B<*ca>.
 
 =head1 NOTES
 
-The parameters B<pkey> and B<cert> cannot be B<NULL>. B<ca> can be <NULL>
-in which case additional certificates will be discarded. B<*ca> can also
-be a valid STACK in which case additional certificates are appended to
-B<*ca>. If B<*ca> is B<NULL> a new STACK will be allocated.
+The parameters B<pkey> and B<cert> cannot be B<NULL>. B<ca> can be <NULL> in
+which case additional certificates will be discarded. B<*ca> can also be a
+valid STACK in which case additional certificates are appended to B<*ca>. If
+B<*ca> is B<NULL> a new STACK will be allocated.
 
-The B<friendlyName> and B<localKeyID> attributes (if present) on each certificate
-will be stored in the B<alias> and B<keyid> attributes of the B<X509> structure.
+The B<friendlyName> and B<localKeyID> attributes (if present) on each
+certificate will be stored in the B<alias> and B<keyid> attributes of the
+B<X509> structure.
+
+=head1 RETURN VALUES
+
+PKCS12_parse() returns 1 for success and zero if an error occurred.
+
+The error can be obtained from L<ERR_get_error(3)|ERR_get_error(3)>
 
 =head1 BUGS
 
-Only a single private key and corresponding certificate is returned by this function.
-More complex PKCS#12 files with multiple private keys will only return the first
-match.
+Only a single private key and corresponding certificate is returned by this
+function. More complex PKCS#12 files with multiple private keys will only
+return the first match.
 
-Only B<friendlyName> and B<localKeyID> attributes are currently stored in certificates.
-Other attributes are discarded.
+Only B<friendlyName> and B<localKeyID> attributes are currently stored in
+certificates. Other attributes are discarded.
 
-Attributes currently cannot be store in the private key B<EVP_PKEY> structure.
+Attributes currently cannot be stored in the private key B<EVP_PKEY> structure.
 
 =head1 SEE ALSO
 
diff --git a/crypto/openssl/doc/crypto/bn_internal.pod b/crypto/openssl/doc/crypto/bn_internal.pod
index 8919146..d39ce90 100644
--- a/crypto/openssl/doc/crypto/bn_internal.pod
+++ b/crypto/openssl/doc/crypto/bn_internal.pod
@@ -70,24 +70,34 @@ applications.
 
 =head2 The BIGNUM structure
 
- typedef struct bignum_st
+ typedef struct bignum_st BIGNUM;
+
+ struct bignum_st
         {
-        int top;      /* number of words used in d */
-        BN_ULONG *d;  /* pointer to an array containing the integer value */
-        int max;      /* size of the d array */
-        int neg;      /* sign */
-        } BIGNUM;
+        BN_ULONG *d;    /* Pointer to an array of 'BN_BITS2' bit chunks. */
+        int top;        /* Index of last used d +1. */
+        /* The next are internal book keeping for bn_expand. */
+        int dmax;       /* Size of the d array. */
+        int neg;        /* one if the number is negative */
+        int flags;
+        };
+
 
 The integer value is stored in B<d>, a malloc()ed array of words (B<BN_ULONG>),
 least significant word first. A B<BN_ULONG> can be either 16, 32 or 64 bits
 in size, depending on the 'number of bits' (B<BITS2>) specified in
 C<openssl/bn.h>.
 
-B<max> is the size of the B<d> array that has been allocated.  B<top>
+B<dmax> is the size of the B<d> array that has been allocated.  B<top>
 is the number of words being used, so for a value of 4, bn.d[0]=4 and
 bn.top=1.  B<neg> is 1 if the number is negative.  When a B<BIGNUM> is
 B<0>, the B<d> field can be B<NULL> and B<top> == B<0>.
 
+B<flags> is a bit field of flags which are defined in C<openssl/bn.h>. The 
+flags begin with B<BN_FLG_>. The macros BN_set_flags(b,n) and 
+BN_get_flags(b,n) exist to enable or fetch flag(s) B<n> from B<BIGNUM>
+structure B<b>.
+
 Various routines in this library require the use of temporary
 B<BIGNUM> variables during their execution.  Since dynamic memory
 allocation to create B<BIGNUM>s is rather expensive when used in
@@ -207,12 +217,12 @@ significant non-zero word plus one when B<a> has shrunk.
 =head2 Debugging
 
 bn_check_top() verifies that C<((a)-E<gt>top E<gt>= 0 && (a)-E<gt>top
-E<lt>= (a)-E<gt>max)>.  A violation will cause the program to abort.
+E<lt>= (a)-E<gt>dmax)>.  A violation will cause the program to abort.
 
 bn_print() prints B<a> to stderr. bn_dump() prints B<n> words at B<d>
 (in reverse order, i.e. most significant word first) to stderr.
 
-bn_set_max() makes B<a> a static number with a B<max> of its current size.
+bn_set_max() makes B<a> a static number with a B<dmax> of its current size.
 This is used by bn_set_low() and bn_set_high() to make B<r> a read-only
 B<BIGNUM> that contains the B<n> low or high words of B<a>.
 
diff --git a/crypto/openssl/doc/crypto/d2i_X509.pod b/crypto/openssl/doc/crypto/d2i_X509.pod
index 5bfa18a..298ec54 100644
--- a/crypto/openssl/doc/crypto/d2i_X509.pod
+++ b/crypto/openssl/doc/crypto/d2i_X509.pod
@@ -15,8 +15,8 @@ i2d_X509_fp - X509 encode and decode functions
  X509 *d2i_X509_bio(BIO *bp, X509 **x);
  X509 *d2i_X509_fp(FILE *fp, X509 **x);
 
- int i2d_X509_bio(X509 *x, BIO *bp);
- int i2d_X509_fp(X509 *x, FILE *fp);
+ int i2d_X509_bio(BIO *bp, X509 *x);
+ int i2d_X509_fp(FILE *fp, X509 *x);
 
 =head1 DESCRIPTION
 
@@ -212,11 +212,11 @@ d2i_X509(), d2i_X509_bio() and d2i_X509_fp() return a valid B<X509> structure
 or B<NULL> if an error occurs. The error code that can be obtained by
 L<ERR_get_error(3)|ERR_get_error(3)>. 
 
-i2d_X509(), i2d_X509_bio() and i2d_X509_fp() return a the number of bytes
-successfully encoded or a negative value if an error occurs. The error code
-can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. 
+i2d_X509() returns the number of bytes successfully encoded or a negative
+value if an error occurs. The error code can be obtained by
+L<ERR_get_error(3)|ERR_get_error(3)>. 
 
-i2d_X509_bio() and i2d_X509_fp() returns 1 for success and 0 if an error 
+i2d_X509_bio() and i2d_X509_fp() return 1 for success and 0 if an error 
 occurs The error code can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. 
 
 =head1 SEE ALSO
diff --git a/crypto/openssl/doc/crypto/d2i_X509_CRL.pod b/crypto/openssl/doc/crypto/d2i_X509_CRL.pod
index e7295a5..224f9e0 100644
--- a/crypto/openssl/doc/crypto/d2i_X509_CRL.pod
+++ b/crypto/openssl/doc/crypto/d2i_X509_CRL.pod
@@ -15,8 +15,8 @@ i2d_X509_CRL_bio, i2d_X509_CRL_fp - PKCS#10 certificate request functions.
  X509_CRL *d2i_X509_CRL_bio(BIO *bp, X509_CRL **x);
  X509_CRL *d2i_X509_CRL_fp(FILE *fp, X509_CRL **x);
 
- int i2d_X509_CRL_bio(X509_CRL *x, BIO *bp);
- int i2d_X509_CRL_fp(X509_CRL *x, FILE *fp);
+ int i2d_X509_CRL_bio(BIO *bp, X509_CRL *x);
+ int i2d_X509_CRL_fp(FILE *fp, X509_CRL *x);
 
 =head1 DESCRIPTION
 
diff --git a/crypto/openssl/doc/crypto/d2i_X509_REQ.pod b/crypto/openssl/doc/crypto/d2i_X509_REQ.pod
index ae32a38..91c0c19 100644
--- a/crypto/openssl/doc/crypto/d2i_X509_REQ.pod
+++ b/crypto/openssl/doc/crypto/d2i_X509_REQ.pod
@@ -15,8 +15,8 @@ i2d_X509_REQ_bio, i2d_X509_REQ_fp - PKCS#10 certificate request functions.
  X509_REQ *d2i_X509_REQ_bio(BIO *bp, X509_REQ **x);
  X509_REQ *d2i_X509_REQ_fp(FILE *fp, X509_REQ **x);
 
- int i2d_X509_REQ_bio(X509_REQ *x, BIO *bp);
- int i2d_X509_REQ_fp(X509_REQ *x, FILE *fp);
+ int i2d_X509_REQ_bio(BIO *bp, X509_REQ *x);
+ int i2d_X509_REQ_fp(FILE *fp, X509_REQ *x);
 
 =head1 DESCRIPTION
 
diff --git a/crypto/openssl/doc/crypto/hmac.pod b/crypto/openssl/doc/crypto/hmac.pod
index 0bd79a6..484e349 100644
--- a/crypto/openssl/doc/crypto/hmac.pod
+++ b/crypto/openssl/doc/crypto/hmac.pod
@@ -41,8 +41,6 @@ If B<md> is NULL, the digest is placed in a static array.  The size of
 the output is placed in B<md_len>, unless it is B<NULL>.
 
 B<evp_md> can be EVP_sha1(), EVP_ripemd160() etc.
-B<key> and B<evp_md> may be B<NULL> if a key and hash function have
-been set in a previous call to HMAC_Init() for that B<HMAC_CTX>.
 
 HMAC_CTX_init() initialises a B<HMAC_CTX> before first use. It must be
 called.
diff --git a/crypto/openssl/doc/crypto/pem.pod b/crypto/openssl/doc/crypto/pem.pod
index 4f9a27d..d5b1896 100644
--- a/crypto/openssl/doc/crypto/pem.pod
+++ b/crypto/openssl/doc/crypto/pem.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-PEM - PEM routines
+PEM, PEM_read_bio_PrivateKey, PEM_read_PrivateKey, PEM_write_bio_PrivateKey, PEM_write_PrivateKey, PEM_write_bio_PKCS8PrivateKey, PEM_write_PKCS8PrivateKey, PEM_write_bio_PKCS8PrivateKey_nid, PEM_write_PKCS8PrivateKey_nid, PEM_read_bio_PUBKEY, PEM_read_PUBKEY, PEM_write_bio_PUBKEY, PEM_write_PUBKEY, PEM_read_bio_RSAPrivateKey, PEM_read_RSAPrivateKey, PEM_write_bio_RSAPrivateKey, PEM_write_RSAPrivateKey, PEM_read_bio_RSAPublicKey, PEM_read_RSAPublicKey, PEM_write_bio_RSAPublicKey, PEM_write_RSAPublicKey, PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY, PEM_write_bio_RSA_PUBKEY, PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey, PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey, PEM_write_DSAPrivateKey, PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY, PEM_write_bio_DSA_PUBKEY, PEM_write_DSA_PUBKEY, PEM_read_bio_DSAparams, PEM_read_DSAparams, PEM_write_bio_DSAparams, PEM_write_DSAparams, PEM_read_bio_DHparams, PEM_read_DHparams, PEM_write_bio_DHparams, PEM_write_DHparams, PEM_read_bio_X509, PEM_read_X509, PEM_write_bio_X509, PEM_write_X509, PEM_read_bio_X509_AUX, PEM_read_X509_AUX, PEM_write_bio_X509_AUX, PEM_write_X509_AUX, PEM_read_bio_X509_REQ, PEM_read_X509_REQ, PEM_write_bio_X509_REQ, PEM_write_X509_REQ, PEM_write_bio_X509_REQ_NEW, PEM_write_X509_REQ_NEW, PEM_read_bio_X509_CRL, PEM_read_X509_CRL, PEM_write_bio_X509_CRL, PEM_write_X509_CRL, PEM_read_bio_PKCS7, PEM_read_PKCS7, PEM_write_bio_PKCS7, PEM_write_PKCS7, PEM_read_bio_NETSCAPE_CERT_SEQUENCE, PEM_read_NETSCAPE_CERT_SEQUENCE, PEM_write_bio_NETSCAPE_CERT_SEQUENCE, PEM_write_NETSCAPE_CERT_SEQUENCE - PEM routines
 
 =head1 SYNOPSIS
 
diff --git a/crypto/openssl/doc/ssl/SSL_CIPHER_get_name.pod b/crypto/openssl/doc/ssl/SSL_CIPHER_get_name.pod
index f62a869..eb772b5 100644
--- a/crypto/openssl/doc/ssl/SSL_CIPHER_get_name.pod
+++ b/crypto/openssl/doc/ssl/SSL_CIPHER_get_name.pod
@@ -11,7 +11,7 @@ SSL_CIPHER_get_name, SSL_CIPHER_get_bits, SSL_CIPHER_get_version, SSL_CIPHER_des
  const char *SSL_CIPHER_get_name(const SSL_CIPHER *cipher);
  int SSL_CIPHER_get_bits(const SSL_CIPHER *cipher, int *alg_bits);
  char *SSL_CIPHER_get_version(const SSL_CIPHER *cipher);
- char *SSL_CIPHER_description(SSL_CIPHER *cipher, char *buf, int size);
+ char *SSL_CIPHER_description(const SSL_CIPHER *cipher, char *buf, int size);
 
 =head1 DESCRIPTION
 
diff --git a/crypto/openssl/doc/ssl/SSL_CTX_set_options.pod b/crypto/openssl/doc/ssl/SSL_CTX_set_options.pod
index eaed190..06025d1 100644
--- a/crypto/openssl/doc/ssl/SSL_CTX_set_options.pod
+++ b/crypto/openssl/doc/ssl/SSL_CTX_set_options.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-SSL_CTX_set_options, SSL_set_options, SSL_CTX_get_options, SSL_get_options - manipulate SSL engine options
+SSL_CTX_set_options, SSL_set_options, SSL_CTX_clear_options, SSL_clear_options, SSL_CTX_get_options, SSL_get_options, SSL_get_secure_renegotiation_support - manipulate SSL options
 
 =head1 SYNOPSIS
 
@@ -11,26 +11,41 @@ SSL_CTX_set_options, SSL_set_options, SSL_CTX_get_options, SSL_get_options - man
  long SSL_CTX_set_options(SSL_CTX *ctx, long options);
  long SSL_set_options(SSL *ssl, long options);
 
+ long SSL_CTX_clear_options(SSL_CTX *ctx, long options);
+ long SSL_clear_options(SSL *ssl, long options);
+
  long SSL_CTX_get_options(SSL_CTX *ctx);
  long SSL_get_options(SSL *ssl);
 
+ long SSL_get_secure_renegotiation_support(SSL *ssl);
+
 =head1 DESCRIPTION
 
+Note: all these functions are implemented using macros.
+
 SSL_CTX_set_options() adds the options set via bitmask in B<options> to B<ctx>.
 Options already set before are not cleared!
 
 SSL_set_options() adds the options set via bitmask in B<options> to B<ssl>.
 Options already set before are not cleared!
 
+SSL_CTX_clear_options() clears the options set via bitmask in B<options>
+to B<ctx>.
+
+SSL_clear_options() clears the options set via bitmask in B<options> to B<ssl>.
+
 SSL_CTX_get_options() returns the options set for B<ctx>.
 
 SSL_get_options() returns the options set for B<ssl>.
 
+SSL_get_secure_renegotiation_support() indicates whether the peer supports
+secure renegotiation.
+
 =head1 NOTES
 
 The behaviour of the SSL library can be changed by setting several options.
 The options are coded as bitmasks and can be combined by a logical B<or>
-operation (|). Options can only be added but can never be reset.
+operation (|).
 
 SSL_CTX_set_options() and SSL_set_options() affect the (external)
 protocol behaviour of the SSL library. The (internal) behaviour of
@@ -199,7 +214,7 @@ Do not use the TLSv1 protocol.
 
 When performing renegotiation as a server, always start a new session
 (i.e., session resumption requests are only accepted in the initial
-handshake).  This option is not needed for clients.
+handshake). This option is not needed for clients.
 
 =item SSL_OP_NO_TICKET
 
@@ -210,15 +225,107 @@ is explicitly set when OpenSSL is compiled.
 If this option is set this functionality is disabled and tickets will
 not be used by clients or servers.
 
+=item SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION
+
+Allow legacy insecure renegotiation between OpenSSL and unpatched clients or
+servers. See the B<SECURE RENEGOTIATION> section for more details.
+
+=item SSL_OP_LEGACY_SERVER_CONNECT
+
+Allow legacy insecure renegotiation between OpenSSL and unpatched servers
+B<only>: this option is currently set by default. See the
+B<SECURE RENEGOTIATION> section for more details.
+
 =back
 
+=head1 SECURE RENEGOTIATION
+
+OpenSSL 0.9.8m and later always attempts to use secure renegotiation as
+described in RFC5746. This counters the prefix attack described in
+CVE-2009-3555 and elsewhere.
+
+The deprecated and highly broken SSLv2 protocol does not support
+renegotiation at all: its use is B<strongly> discouraged.
+
+This attack has far reaching consequences which application writers should be
+aware of. In the description below an implementation supporting secure
+renegotiation is referred to as I<patched>. A server not supporting secure
+renegotiation is referred to as I<unpatched>.
+
+The following sections describe the operations permitted by OpenSSL's secure
+renegotiation implementation.
+
+=head2 Patched client and server
+
+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
+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.
+
+If the patched OpenSSL server attempts to renegotiate a fatal
+B<handshake_failure> alert is sent. This is because the server code may be
+unaware of the unpatched nature of the client.
+
+If the option B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then
+renegotiation B<always> succeeds.
+
+B<NB:> a bug in OpenSSL clients earlier than 0.9.8m (all of which are
+unpatched) will result in the connection hanging if it receives a
+B<no_renegotiation> alert. OpenSSL versions 0.9.8m and later will regard
+a B<no_renegotiation> alert as fatal and respond with a fatal
+B<handshake_failure> alert. This is because the OpenSSL API currently has
+no provision to indicate to an application that a renegotiation attempt
+was refused.
+
+=head2 Patched OpenSSL client and unpatched server.
+
+If the option B<SSL_OP_LEGACY_SERVER_CONNECT> or
+B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> is set then initial connections
+and renegotiation between patched OpenSSL clients and unpatched servers
+succeeds. If neither option is set then initial connections to unpatched
+servers will fail.
+
+The option B<SSL_OP_LEGACY_SERVER_CONNECT> is currently set by default even
+though it has security implications: otherwise it would be impossible to
+connect to unpatched servers (i.e. all of them initially) and this is clearly
+not acceptable. Renegotiation is permitted because this does not add any
+additional security issues: during an attack clients do not see any
+renegotiations anyway.
+
+As more servers become patched the option B<SSL_OP_LEGACY_SERVER_CONNECT> will
+B<not> be set by default in a future version of OpenSSL.
+
+OpenSSL client applications wishing to ensure they can connect to unpatched
+servers should always B<set> B<SSL_OP_LEGACY_SERVER_CONNECT>
+
+OpenSSL client applications that want to ensure they can B<not> connect to
+unpatched servers (and thus avoid any security issues) should always B<clear>
+B<SSL_OP_LEGACY_SERVER_CONNECT> using SSL_CTX_clear_options() or
+SSL_clear_options().
+
+The difference between the B<SSL_OP_LEGACY_SERVER_CONNECT> and
+B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> options is that
+B<SSL_OP_LEGACY_SERVER_CONNECT> enables initial connections and secure
+renegotiation between OpenSSL clients and unpatched servers B<only>, while
+B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION> allows initial connections
+and renegotiation between OpenSSL and unpatched clients or servers.
+
 =head1 RETURN VALUES
 
 SSL_CTX_set_options() and SSL_set_options() return the new options bitmask
 after adding B<options>.
 
+SSL_CTX_clear_options() and SSL_clear_options() return the new options bitmask
+after clearing B<options>.
+
 SSL_CTX_get_options() and SSL_get_options() return the current bitmask.
 
+SSL_get_secure_renegotiation_support() returns 1 is the peer supports
+secure renegotiation and 0 if it does not.
+
 =head1 SEE ALSO
 
 L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>,
@@ -241,4 +348,11 @@ Versions up to OpenSSL 0.9.6c do not include the countermeasure that
 can be disabled with this option (in OpenSSL 0.9.6d, it was always
 enabled).
 
+SSL_CTX_clear_options() and SSL_clear_options() were first added in OpenSSL
+0.9.8m.
+
+B<SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION>, B<SSL_OP_LEGACY_SERVER_CONNECT>
+and the function SSL_get_secure_renegotiation_support() were first added in
+OpenSSL 0.9.8m.
+
 =cut