aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorSimon L. B. Nielsen <simon@FreeBSD.org>2010-02-28 18:49:43 +0000
committerSimon L. B. Nielsen <simon@FreeBSD.org>2010-02-28 18:49:43 +0000
commitf7a1b4761cf3f798e1b42d703d38221b47ce1eec (patch)
tree21770f10e7f26d05fc9b0fa96a7b6d7b107552c5 /doc
parentf0c2a617dfb432d01bc5a716eb18dae12e6b45e3 (diff)
downloadsrc-f7a1b4761cf3f798e1b42d703d38221b47ce1eec.tar.gz
src-f7a1b4761cf3f798e1b42d703d38221b47ce1eec.zip
Import OpenSSL 0.9.8m.vendor/openssl/0.9.8m
Notes
Notes: svn path=/vendor-crypto/openssl/dist/; revision=204477 svn path=/vendor-crypto/openssl/0.9.8m/; revision=204478; tag=vendor/openssl/0.9.8m
Diffstat (limited to 'doc')
-rw-r--r--doc/apps/enc.pod10
-rw-r--r--doc/apps/verify.pod17
-rw-r--r--doc/crypto/ASN1_generate_nconf.pod2
-rw-r--r--doc/crypto/EVP_DigestInit.pod6
-rw-r--r--doc/crypto/PKCS12_parse.pod31
-rw-r--r--doc/crypto/bn_internal.pod28
-rw-r--r--doc/crypto/d2i_X509.pod12
-rw-r--r--doc/crypto/d2i_X509_CRL.pod4
-rw-r--r--doc/crypto/d2i_X509_REQ.pod4
-rw-r--r--doc/crypto/hmac.pod2
-rw-r--r--doc/crypto/pem.pod2
-rw-r--r--doc/ssl/SSL_CIPHER_get_name.pod2
-rw-r--r--doc/ssl/SSL_CTX_set_options.pod120
13 files changed, 188 insertions, 52 deletions
diff --git a/doc/apps/enc.pod b/doc/apps/enc.pod
index 4391c933600f..d3049e82e969 100644
--- a/doc/apps/enc.pod
+++ b/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/doc/apps/verify.pod b/doc/apps/verify.pod
index ff2629d2cf85..31875773e385 100644
--- a/doc/apps/verify.pod
+++ b/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/doc/crypto/ASN1_generate_nconf.pod b/doc/crypto/ASN1_generate_nconf.pod
index 1157cff510d6..179132d012e3 100644
--- a/doc/crypto/ASN1_generate_nconf.pod
+++ b/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/doc/crypto/EVP_DigestInit.pod b/doc/crypto/EVP_DigestInit.pod
index 130cd7f60adb..98b1368d08d8 100644
--- a/doc/crypto/EVP_DigestInit.pod
+++ b/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/doc/crypto/PKCS12_parse.pod b/doc/crypto/PKCS12_parse.pod
index 51344f883a9b..c54cf2ad613e 100644
--- a/doc/crypto/PKCS12_parse.pod
+++ b/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/doc/crypto/bn_internal.pod b/doc/crypto/bn_internal.pod
index 891914678c47..d39ce90939a2 100644
--- a/doc/crypto/bn_internal.pod
+++ b/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/doc/crypto/d2i_X509.pod b/doc/crypto/d2i_X509.pod
index 5bfa18afbb3d..298ec54a4c3b 100644
--- a/doc/crypto/d2i_X509.pod
+++ b/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/doc/crypto/d2i_X509_CRL.pod b/doc/crypto/d2i_X509_CRL.pod
index e7295a5d6153..224f9e082b7a 100644
--- a/doc/crypto/d2i_X509_CRL.pod
+++ b/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/doc/crypto/d2i_X509_REQ.pod b/doc/crypto/d2i_X509_REQ.pod
index ae32a3891d67..91c0c1974b49 100644
--- a/doc/crypto/d2i_X509_REQ.pod
+++ b/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/doc/crypto/hmac.pod b/doc/crypto/hmac.pod
index 0bd79a6d3a98..484e349fd1d6 100644
--- a/doc/crypto/hmac.pod
+++ b/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/doc/crypto/pem.pod b/doc/crypto/pem.pod
index 4f9a27df0cc4..d5b189611956 100644
--- a/doc/crypto/pem.pod
+++ b/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/doc/ssl/SSL_CIPHER_get_name.pod b/doc/ssl/SSL_CIPHER_get_name.pod
index f62a869a9bba..eb772b55de4a 100644
--- a/doc/ssl/SSL_CIPHER_get_name.pod
+++ b/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/doc/ssl/SSL_CTX_set_options.pod b/doc/ssl/SSL_CTX_set_options.pod
index eaed19080975..06025d13fafb 100644
--- a/doc/ssl/SSL_CTX_set_options.pod
+++ b/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