diff options
author | Simon L. B. Nielsen <simon@FreeBSD.org> | 2010-03-13 19:22:41 +0000 |
---|---|---|
committer | Simon L. B. Nielsen <simon@FreeBSD.org> | 2010-03-13 19:22:41 +0000 |
commit | 6a599222bb564010b80b78eef3f2b6ba6c8db14a (patch) | |
tree | 909a7c21b7df72ae8c08b80b468a4dd75b3820be /crypto/openssl/doc | |
parent | c5af82e51782b019d13e562a07c17dc19a282de2 (diff) | |
parent | f7a1b4761cf3f798e1b42d703d38221b47ce1eec (diff) | |
download | src-6a599222bb564010b80b78eef3f2b6ba6c8db14a.tar.gz src-6a599222bb564010b80b78eef3f2b6ba6c8db14a.zip |
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
Notes
Notes:
svn path=/head/; revision=205128
Diffstat (limited to 'crypto/openssl/doc')
-rw-r--r-- | crypto/openssl/doc/apps/enc.pod | 10 | ||||
-rw-r--r-- | crypto/openssl/doc/apps/verify.pod | 17 | ||||
-rw-r--r-- | crypto/openssl/doc/crypto/ASN1_generate_nconf.pod | 2 | ||||
-rw-r--r-- | crypto/openssl/doc/crypto/EVP_DigestInit.pod | 6 | ||||
-rw-r--r-- | crypto/openssl/doc/crypto/PKCS12_parse.pod | 31 | ||||
-rw-r--r-- | crypto/openssl/doc/crypto/bn_internal.pod | 28 | ||||
-rw-r--r-- | crypto/openssl/doc/crypto/d2i_X509.pod | 12 | ||||
-rw-r--r-- | crypto/openssl/doc/crypto/d2i_X509_CRL.pod | 4 | ||||
-rw-r--r-- | crypto/openssl/doc/crypto/d2i_X509_REQ.pod | 4 | ||||
-rw-r--r-- | crypto/openssl/doc/crypto/hmac.pod | 2 | ||||
-rw-r--r-- | crypto/openssl/doc/crypto/pem.pod | 2 | ||||
-rw-r--r-- | crypto/openssl/doc/ssl/SSL_CIPHER_get_name.pod | 2 | ||||
-rw-r--r-- | crypto/openssl/doc/ssl/SSL_CTX_set_options.pod | 120 |
13 files changed, 188 insertions, 52 deletions
diff --git a/crypto/openssl/doc/apps/enc.pod b/crypto/openssl/doc/apps/enc.pod index 4391c933600f..d3049e82e969 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 ff2629d2cf85..31875773e385 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 1157cff510d6..179132d012e3 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 130cd7f60adb..98b1368d08d8 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 51344f883a9b..c54cf2ad613e 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 891914678c47..d39ce90939a2 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 5bfa18afbb3d..298ec54a4c3b 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 e7295a5d6153..224f9e082b7a 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 ae32a3891d67..91c0c1974b49 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 0bd79a6d3a98..484e349fd1d6 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 4f9a27df0cc4..d5b189611956 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 f62a869a9bba..eb772b55de4a 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 eaed19080975..06025d13fafb 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 |