These are updates/fixes to DH/DSA/RAND docs based on the fixes to the RSA

docs. There were a couple of other places (including RSA) where the docs
were not quite synchronised with the API that are now fixed. One or two
still remain to be fixed though ...

11 files changed, 232 insertions, 120 deletions

diff --git a/doc/crypto/DH_set_method.pod b/doc/crypto/DH_set_method.pod
index d990bf8786..73261fc467 100644
--- a/doc/crypto/DH_set_method.pod
+++ b/doc/crypto/DH_set_method.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-DH_set_default_openssl_method, DH_get_default_openssl_method,
+DH_set_default_method, DH_get_default_method,
 DH_set_method, DH_new_method, DH_OpenSSL - select DH method
 
 =head1 SYNOPSIS
@@ -10,45 +10,47 @@ DH_set_method, DH_new_method, DH_OpenSSL - select DH method
  #include <openssl/dh.h>
  #include <openssl/engine.h>
 
- void DH_set_default_openssl_method(DH_METHOD *meth);
+ void DH_set_default_method(const DH_METHOD *meth);
 
- DH_METHOD *DH_get_default_openssl_method(void);
+ const DH_METHOD *DH_get_default_method(void);
 
- int DH_set_method(DH *dh, ENGINE *engine);
+ int DH_set_method(DH *dh, const DH_METHOD *meth);
 
  DH *DH_new_method(ENGINE *engine);
 
- DH_METHOD *DH_OpenSSL(void);
+ const DH_METHOD *DH_OpenSSL(void);
 
 =head1 DESCRIPTION
 
 A B<DH_METHOD> specifies the functions that OpenSSL uses for Diffie-Hellman
 operations. By modifying the method, alternative implementations
-such as hardware accelerators may be used.
-
-Initially, the default is to use the OpenSSL internal implementation.
-DH_OpenSSL() returns a pointer to that method.
-
-DH_set_default_openssl_method() makes B<meth> the default method for all DH
-structures created later. B<NB:> This is true only whilst the default engine
-for Diffie-Hellman operations remains as "openssl". ENGINEs provide an
-encapsulation for implementations of one or more algorithms, and all the DH
-functions mentioned here operate within the scope of the default
-"openssl" engine.
-
-DH_get_default_openssl_method() returns a pointer to the current default
-method for the "openssl" engine.
-
-DH_set_method() selects B<engine> as the engine that will be responsible for
-all operations using the structure B<dh>. If this function completes successfully,
-then the B<dh> structure will have its own functional reference of B<engine>, so
-the caller should remember to free their own reference to B<engine> when they are
-finished with it. NB: An ENGINE's DH_METHOD can be retrieved (or set) by
-ENGINE_get_DH() or ENGINE_set_DH().
-
-DH_new_method() allocates and initializes a DH structure so that
-B<engine> will be used for the DH operations. If B<engine> is NULL,
-the default engine for Diffie-Hellman opertaions is used.
+such as hardware accelerators may be used. IMPORTANT: See the NOTES section for
+important information about how these DH API functions are affected by the use
+of B<ENGINE> API calls.
+
+Initially, the default DH_METHOD is the OpenSSL internal implementation, as
+returned by DH_OpenSSL().
+
+DH_set_default_method() makes B<meth> the default method for all DH
+structures created later. B<NB>: This is true only whilst no ENGINE has been set
+as a default for DH, so this function is no longer recommended.
+
+DH_get_default_method() returns a pointer to the current default DH_METHOD.
+However, the meaningfulness of this result is dependant on whether the ENGINE
+API is being used, so this function is no longer recommended.
+
+DH_set_method() selects B<meth> to perform all operations using the key B<dh>.
+This will replace the DH_METHOD used by the DH key and if the previous method
+was supplied by an ENGINE, the handle to that ENGINE will be released during the
+change. It is possible to have DH keys that only work with certain DH_METHOD
+implementations (eg. from an ENGINE module that supports embedded
+hardware-protected keys), and in such cases attempting to change the DH_METHOD
+for the key can have unexpected results.
+
+DH_new_method() allocates and initializes a DH structure so that B<engine> will
+be used for the DH operations. If B<engine> is NULL, the default ENGINE for DH
+operations is used, and if no default ENGINE is set, the DH_METHOD controlled by
+DH_set_default_method() is used.
 
 =head1 THE DH_METHOD STRUCTURE
 
@@ -82,17 +84,28 @@ the default engine for Diffie-Hellman opertaions is used.
 
 =head1 RETURN VALUES
 
-DH_OpenSSL() and DH_get_default_openssl_method() return pointers to the
-respective B<DH_METHOD>s.
+DH_OpenSSL() and DH_get_default_method() return pointers to the respective
+B<DH_METHOD>s.
+
+DH_set_default_method() returns no value.
+
+DH_set_method() returns non-zero if the provided B<meth> was successfully set as
+the method for B<dh> (including unloading the ENGINE handle if the previous
+method was supplied by an ENGINE).
 
-DH_set_default_openssl_method() returns no value.
+DH_new_method() returns NULL and sets an error code that can be obtained by
+L<ERR_get_error(3)|ERR_get_error(3)> if the allocation fails. Otherwise it
+returns a pointer to the newly allocated structure.
 
-DH_set_method() returns non-zero if the ENGINE associated with B<dh>
-was successfully changed to B<engine>.
+=head1 NOTES
 
-DH_new_method() returns NULL and sets an error code that can be
-obtained by L<ERR_get_error(3)|ERR_get_error(3)> if the allocation fails.
-Otherwise it returns a pointer to the newly allocated structure.
+As of version 0.9.7, DH_METHOD implementations are grouped together with other
+algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in B<ENGINE> modules. If a
+default ENGINE is specified for DH functionality using an ENGINE API function,
+that will override any DH defaults set using the DH API (ie.
+DH_set_default_method()). For this reason, the ENGINE API is the recommended way
+to control default implementations for use in DH and other cryptographic
+algorithms.
 
 =head1 SEE ALSO
 
@@ -103,9 +116,14 @@ L<dh(3)|dh(3)>, L<DH_new(3)|DH_new(3)>
 DH_set_default_method(), DH_get_default_method(), DH_set_method(),
 DH_new_method() and DH_OpenSSL() were added in OpenSSL 0.9.4.
 
-DH_set_default_openssl_method() and DH_get_default_openssl_method()
-replaced DH_set_default_method() and DH_get_default_method() respectively,
-and DH_set_method() and DH_new_method() were altered to use B<ENGINE>s
-rather than B<DH_METHOD>s during development of OpenSSL 0.9.6.
+DH_set_default_openssl_method() and DH_get_default_openssl_method() replaced
+DH_set_default_method() and DH_get_default_method() respectively, and
+DH_set_method() and DH_new_method() were altered to use B<ENGINE>s rather than
+B<DH_METHOD>s during development of the engine version of OpenSSL 0.9.6. For
+0.9.7, the handling of defaults in the ENGINE API was restructured so that this
+change was reversed, and behaviour of the other functions resembled more closely
+the previous behaviour. The behaviour of defaults in the ENGINE API now
+transparently overrides the behaviour of defaults in the DH API without
+requiring changing these function prototypes.
 
 =cut
diff --git a/doc/crypto/DSA_dup_DH.pod b/doc/crypto/DSA_dup_DH.pod
index 29cb1075d1..fdfe125ab0 100644
--- a/doc/crypto/DSA_dup_DH.pod
+++ b/doc/crypto/DSA_dup_DH.pod
@@ -8,7 +8,7 @@ DSA_dup_DH - create a DH structure out of DSA structure
 
  #include <openssl/dsa.h>
 
- DH * DSA_dup_DH(DSA *r);
+ DH * DSA_dup_DH(const DSA *r);
 
 =head1 DESCRIPTION
 
diff --git a/doc/crypto/DSA_new.pod b/doc/crypto/DSA_new.pod
index 7dde54445b..546146d9de 100644
--- a/doc/crypto/DSA_new.pod
+++ b/doc/crypto/DSA_new.pod
@@ -14,7 +14,8 @@ DSA_new, DSA_free - allocate and free DSA objects
 
 =head1 DESCRIPTION
 
-DSA_new() allocates and initializes a B<DSA> structure.
+DSA_new() allocates and initializes a B<DSA> structure. It is equivalent to
+calling DSA_new_method(NULL).
 
 DSA_free() frees the B<DSA> structure and its components. The values are
 erased before the memory is returned to the system.
diff --git a/doc/crypto/DSA_set_method.pod b/doc/crypto/DSA_set_method.pod
index 36a1052d27..bc3cfb1f0a 100644
--- a/doc/crypto/DSA_set_method.pod
+++ b/doc/crypto/DSA_set_method.pod
@@ -2,7 +2,7 @@
 
 =head1 NAME
 
-DSA_set_default_openssl_method, DSA_get_default_openssl_method,
+DSA_set_default_method, DSA_get_default_method,
 DSA_set_method, DSA_new_method, DSA_OpenSSL - select DSA method
 
 =head1 SYNOPSIS
@@ -10,11 +10,11 @@ DSA_set_method, DSA_new_method, DSA_OpenSSL - select DSA method
  #include <openssl/dsa.h>
  #include <openssl/engine.h>
 
- void DSA_set_default_openssl_method(DSA_METHOD *meth);
+ void DSA_set_default_method(const DSA_METHOD *meth);
 
- DSA_METHOD *DSA_get_default_openssl_method(void);
+ const DSA_METHOD *DSA_get_default_method(void);
 
- int DSA_set_method(DSA *dsa, ENGINE *engine);
+ int DSA_set_method(DSA *dsa, const DSA_METHOD *meth);
 
  DSA *DSA_new_method(ENGINE *engine);
 
@@ -24,26 +24,35 @@ DSA_set_method, DSA_new_method, DSA_OpenSSL - select DSA method
 
 A B<DSA_METHOD> specifies the functions that OpenSSL uses for DSA
 operations. By modifying the method, alternative implementations
-such as hardware accelerators may be used.
-
-Initially, the default is to use the OpenSSL internal implementation.
-DSA_OpenSSL() returns a pointer to that method.
-
-DSA_set_default_openssl_method() makes B<meth> the default method for
-all DSA structures created later. B<NB:> This is true only whilst the
-default engine for DSA operations remains as "openssl". ENGINEs
-provide an encapsulation for implementations of one or more algorithms at a
-time, and all the DSA functions mentioned here operate within the scope
-of the default "openssl" engine.
-
-DSA_get_default_openssl_method() returns a pointer to the current default
-method for the "openssl" engine.
-
-DSA_set_method() selects B<engine> for all operations using the structure B<dsa>.
-
-DSA_new_method() allocates and initializes a DSA structure so that
-B<engine> will be used for the DSA operations. If B<engine> is NULL,
-the default engine for DSA operations is used.
+such as hardware accelerators may be used. IMPORTANT: See the NOTES section for
+important information about how these DSA API functions are affected by the use
+of B<ENGINE> API calls.
+
+Initially, the default DSA_METHOD is the OpenSSL internal implementation,
+as returned by DSA_OpenSSL().
+
+DSA_set_default_method() makes B<meth> the default method for all DSA
+structures created later. B<NB>: This is true only whilst no ENGINE has
+been set as a default for DSA, so this function is no longer recommended.
+
+DSA_get_default_method() returns a pointer to the current default
+DSA_METHOD. However, the meaningfulness of this result is dependant on
+whether the ENGINE API is being used, so this function is no longer 
+recommended.
+
+DSA_set_method() selects B<meth> to perform all operations using the key
+B<rsa>. This will replace the DSA_METHOD used by the DSA key and if the
+previous method was supplied by an ENGINE, the handle to that ENGINE will
+be released during the change. It is possible to have DSA keys that only
+work with certain DSA_METHOD implementations (eg. from an ENGINE module
+that supports embedded hardware-protected keys), and in such cases
+attempting to change the DSA_METHOD for the key can have unexpected
+results.
+
+DSA_new_method() allocates and initializes a DSA structure so that B<engine>
+will be used for the DSA operations. If B<engine> is NULL, the default engine
+for DSA operations is used, and if no default ENGINE is set, the DSA_METHOD
+controlled by DSA_set_default_method() is used.
 
 =head1 THE DSA_METHOD STRUCTURE
 
@@ -89,18 +98,29 @@ struct
 
 =head1 RETURN VALUES
 
-DSA_OpenSSL() and DSA_get_default_openssl_method() return pointers to the
-respective B<DSA_METHOD>s.
+DSA_OpenSSL() and DSA_get_default_method() return pointers to the respective
+B<DSA_METHOD>s.
 
-DSA_set_default_openssl_method() returns no value.
+DSA_set_default_method() returns no value.
 
-DSA_set_method() returns non-zero if the ENGINE associated with B<dsa>
-was successfully changed to B<engine>.
+DSA_set_method() returns non-zero if the provided B<meth> was successfully set as
+the method for B<dsa> (including unloading the ENGINE handle if the previous
+method was supplied by an ENGINE).
 
 DSA_new_method() returns NULL and sets an error code that can be
 obtained by L<ERR_get_error(3)|ERR_get_error(3)> if the allocation
 fails. Otherwise it returns a pointer to the newly allocated structure.
 
+=head1 NOTES
+
+As of version 0.9.7, DSA_METHOD implementations are grouped together with other
+algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in B<ENGINE> modules. If a
+default ENGINE is specified for DSA functionality using an ENGINE API function,
+that will override any DSA defaults set using the DSA API (ie.
+DSA_set_default_method()). For this reason, the ENGINE API is the recommended way
+to control default implementations for use in DSA and other cryptographic
+algorithms.
+
 =head1 SEE ALSO
 
 L<dsa(3)|dsa(3)>, L<DSA_new(3)|DSA_new(3)>
@@ -110,9 +130,14 @@ L<dsa(3)|dsa(3)>, L<DSA_new(3)|DSA_new(3)>
 DSA_set_default_method(), DSA_get_default_method(), DSA_set_method(),
 DSA_new_method() and DSA_OpenSSL() were added in OpenSSL 0.9.4.
 
-DSA_set_default_openssl_method() and DSA_get_default_openssl_method()
-replaced DSA_set_default_method() and DSA_get_default_method() respectively,
-and DSA_set_method() and DSA_new_method() were altered to use B<ENGINE>s
-rather than B<DSA_METHOD>s during development of OpenSSL 0.9.6.
+DSA_set_default_openssl_method() and DSA_get_default_openssl_method() replaced
+DSA_set_default_method() and DSA_get_default_method() respectively, and
+DSA_set_method() and DSA_new_method() were altered to use B<ENGINE>s rather than
+B<DSA_METHOD>s during development of the engine version of OpenSSL 0.9.6. For
+0.9.7, the handling of defaults in the ENGINE API was restructured so that this
+change was reversed, and behaviour of the other functions resembled more closely
+the previous behaviour. The behaviour of defaults in the ENGINE API now
+transparently overrides the behaviour of defaults in the DSA API without
+requiring changing these function prototypes.
 
 =cut
diff --git a/doc/crypto/DSA_size.pod b/doc/crypto/DSA_size.pod
index 23b6320a4d..ba4f650361 100644
--- a/doc/crypto/DSA_size.pod
+++ b/doc/crypto/DSA_size.pod
@@ -8,7 +8,7 @@ DSA_size - get DSA signature size
 
  #include <openssl/dsa.h>
 
- int DSA_size(DSA *dsa);
+ int DSA_size(const DSA *dsa);
 
 =head1 DESCRIPTION
 
diff --git a/doc/crypto/RAND_set_rand_method.pod b/doc/crypto/RAND_set_rand_method.pod
index 464eba416d..c9bb6d9f27 100644
--- a/doc/crypto/RAND_set_rand_method.pod
+++ b/doc/crypto/RAND_set_rand_method.pod
@@ -8,22 +8,30 @@ RAND_set_rand_method, RAND_get_rand_method, RAND_SSLeay - select RAND method
 
  #include <openssl/rand.h>
 
- void RAND_set_rand_method(RAND_METHOD *meth);
+ void RAND_set_rand_method(const RAND_METHOD *meth);
 
- RAND_METHOD *RAND_get_rand_method(void);
+ const RAND_METHOD *RAND_get_rand_method(void);
 
  RAND_METHOD *RAND_SSLeay(void);
 
 =head1 DESCRIPTION
 
-A B<RAND_METHOD> specifies the functions that OpenSSL uses for random
-number generation. By modifying the method, alternative
-implementations such as hardware RNGs may be used.  Initially, the
-default is to use the OpenSSL internal implementation. RAND_SSLeay()
-returns a pointer to that method.
+A B<RAND_METHOD> specifies the functions that OpenSSL uses for random number
+generation. By modifying the method, alternative implementations such as
+hardware RNGs may be used. IMPORTANT: See the NOTES section for important
+information about how these RAND API functions are affected by the use of
+B<ENGINE> API calls.
 
-RAND_set_rand_method() sets the RAND method to B<meth>.
-RAND_get_rand_method() returns a pointer to the current method.
+Initially, the default RAND_METHOD is the OpenSSL internal implementation, as
+returned by RAND_SSLeay().
+
+RAND_set_default_method() makes B<meth> the method for PRNG use. B<NB>: This is
+true only whilst no ENGINE has been set as a default for RAND, so this function
+is no longer recommended.
+
+RAND_get_default_method() returns a pointer to the current RAND_METHOD.
+However, the meaningfulness of this result is dependant on whether the ENGINE
+API is being used, so this function is no longer recommended.
 
 =head1 THE RAND_METHOD STRUCTURE
 
@@ -47,13 +55,29 @@ Each component may be NULL if the function is not implemented.
 RAND_set_rand_method() returns no value. RAND_get_rand_method() and
 RAND_SSLeay() return pointers to the respective methods.
 
+=head1 NOTES
+
+As of version 0.9.7, RAND_METHOD implementations are grouped together with other
+algorithmic APIs (eg. RSA_METHOD, EVP_CIPHER, etc) in B<ENGINE> modules. If a
+default ENGINE is specified for RAND functionality using an ENGINE API function,
+that will override any RAND defaults set using the RAND API (ie.
+RAND_set_rand_method()). For this reason, the ENGINE API is the recommended way
+to control default implementations for use in RAND and other cryptographic
+algorithms.
+
 =head1 SEE ALSO
 
-L<rand(3)|rand(3)>
+L<rand(3)|rand(3)>, L<engine(3)|engine(3)>
 
 =head1 HISTORY
 
 RAND_set_rand_method(), RAND_get_rand_method() and RAND_SSLeay() are
 available in all versions of OpenSSL.
 
+In the engine version of version 0.9.6, RAND_set_rand_method() was altered to
+take an ENGINE pointer as its argument. As of version 0.9.7, that has been
+reverted as the ENGINE API transparently overrides RAND defaults if used,
+otherwise RAND API functions work as before. RAND_set_rand_engine() was also
+introduced in version 0.9.7.
+
 =cut
diff --git a/doc/crypto/RSA_size.pod b/doc/crypto/RSA_size.pod
index b36b4d58d5..5b7f835f95 100644
--- a/doc/crypto/RSA_size.pod
+++ b/doc/crypto/RSA_size.pod
@@ -8,7 +8,7 @@ RSA_size - get RSA modulus size
 
  #include <openssl/rsa.h>
 
- int RSA_size(RSA *rsa);
+ int RSA_size(const RSA *rsa);
 
 =head1 DESCRIPTION
 
diff --git a/doc/crypto/dh.pod b/doc/crypto/dh.pod
index b4be4be405..c3ccd06207 100644
--- a/doc/crypto/dh.pod
+++ b/doc/crypto/dh.pod
@@ -12,20 +12,20 @@ dh - Diffie-Hellman key agreement
  DH *	DH_new(void);
  void	DH_free(DH *dh);
 
- int	DH_size(DH *dh);
+ int	DH_size(const DH *dh);
 
  DH *	DH_generate_parameters(int prime_len, int generator,
 		void (*callback)(int, int, void *), void *cb_arg);
- int	DH_check(DH *dh, int *codes);
+ int	DH_check(const DH *dh, int *codes);
 
  int	DH_generate_key(DH *dh);
  int	DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh);
 
- void DH_set_default_openssl_method(DH_METHOD *meth);
- DH_METHOD *DH_get_default_openssl_method(void);
- int DH_set_method(DH *dh, ENGINE *engine);
+ void DH_set_default_method(const DH_METHOD *meth);
+ const DH_METHOD *DH_get_default_method(void);
+ int DH_set_method(DH *dh, const DH_METHOD *meth);
  DH *DH_new_method(ENGINE *engine);
- DH_METHOD *DH_OpenSSL(void);
+ const DH_METHOD *DH_OpenSSL(void);
 
  int DH_get_ex_new_index(long argl, char *argp, int (*new_func)(),
 	     int (*dup_func)(), void (*free_func)());
@@ -33,10 +33,10 @@ dh - Diffie-Hellman key agreement
  char *DH_get_ex_data(DH *d, int idx);
 
  DH *	d2i_DHparams(DH **a, unsigned char **pp, long length);
- int	i2d_DHparams(DH *a, unsigned char **pp);
+ int	i2d_DHparams(const DH *a, unsigned char **pp);
 
- int	DHparams_print_fp(FILE *fp, DH *x);
- int	DHparams_print(BIO *bp, DH *x);
+ int	DHparams_print_fp(FILE *fp, const DH *x);
+ int	DHparams_print(BIO *bp, const DH *x);
 
 =head1 DESCRIPTION
 
@@ -57,11 +57,20 @@ The B<DH> structure consists of several BIGNUM components.
         };
  DH
 
+Note that DH keys may use non-standard B<DH_METHOD> implementations,
+either directly or by the use of B<ENGINE> modules. In some cases (eg. an
+ENGINE providing support for hardware-embedded keys), these BIGNUM values
+will not be used by the implementation or may be used for alternative data
+storage. For this reason, applications should generally avoid using DH
+structure elements directly and instead use API functions to query or
+modify keys.
+
 =head1 SEE ALSO
 
 L<dhparam(1)|dhparam(1)>, L<bn(3)|bn(3)>, L<dsa(3)|dsa(3)>, L<err(3)|err(3)>,
-L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, L<DH_set_method(3)|DH_set_method(3)>,
-L<DH_new(3)|DH_new(3)>, L<DH_get_ex_new_index(3)|DH_get_ex_new_index(3)>,
+L<rand(3)|rand(3)>, L<rsa(3)|rsa(3)>, L<engine(3)|engine(3)>,
+L<DH_set_method(3)|DH_set_method(3)>, L<DH_new(3)|DH_new(3)>,
+L<DH_get_ex_new_index(3)|DH_get_ex_new_index(3)>,
 L<DH_generate_parameters(3)|DH_generate_parameters(3)>,
 L<DH_compute_key(3)|DH_compute_key(3)>, L<d2i_DHparams(3)|d2i_DHparams(3)>,
 L<RSA_print(3)|RSA_print(3)> 
diff --git a/doc/crypto/dsa.pod b/doc/crypto/dsa.pod
index 82d7fb77cd..da07d2b930 100644
--- a/doc/crypto/dsa.pod
+++ b/doc/crypto/dsa.pod
@@ -12,13 +12,13 @@ dsa - Digital Signature Algorithm
  DSA *	DSA_new(void);
  void	DSA_free(DSA *dsa);
 
- int	DSA_size(DSA *dsa);
+ int	DSA_size(const DSA *dsa);
 
  DSA *	DSA_generate_parameters(int bits, unsigned char *seed,
                 int seed_len, int *counter_ret, unsigned long *h_ret,
 		void (*callback)(int, int, void *), void *cb_arg);
 
- DH *	DSA_dup_DH(DSA *r);
+ DH *	DSA_dup_DH(const DSA *r);
 
  int	DSA_generate_key(DSA *dsa);
 
@@ -27,13 +27,13 @@ dsa - Digital Signature Algorithm
  int	DSA_sign_setup(DSA *dsa, BN_CTX *ctx, BIGNUM **kinvp,
                 BIGNUM **rp);
  int	DSA_verify(int dummy, const unsigned char *dgst, int len,
-		unsigned char *sigbuf, int siglen, DSA *dsa);
+		const unsigned char *sigbuf, int siglen, DSA *dsa);
 
- void DSA_set_default_openssl_method(DSA_METHOD *meth);
- DSA_METHOD *DSA_get_default_openssl_method(void);
- int DSA_set_method(DSA *dsa, ENGINE *engine);
+ void DSA_set_default_method(const DSA_METHOD *meth);
+ const DSA_METHOD *DSA_get_default_method(void);
+ int DSA_set_method(DSA *dsa, const DSA_METHOD *meth);
  DSA *DSA_new_method(ENGINE *engine);
- DSA_METHOD *DSA_OpenSSL(void);
+ const DSA_METHOD *DSA_OpenSSL(void);
 
  int DSA_get_ex_new_index(long argl, char *argp, int (*new_func)(),
 	     int (*dup_func)(), void (*free_func)());
@@ -42,7 +42,7 @@ dsa - Digital Signature Algorithm
 
  DSA_SIG *DSA_SIG_new(void);
  void	DSA_SIG_free(DSA_SIG *a);
- int	i2d_DSA_SIG(DSA_SIG *a, unsigned char **pp);
+ int	i2d_DSA_SIG(const DSA_SIG *a, unsigned char **pp);
  DSA_SIG *d2i_DSA_SIG(DSA_SIG **v, unsigned char **pp, long length);
 
  DSA_SIG *DSA_do_sign(const unsigned char *dgst, int dlen, DSA *dsa);
@@ -52,14 +52,14 @@ dsa - Digital Signature Algorithm
  DSA *	d2i_DSAPublicKey(DSA **a, unsigned char **pp, long length);
  DSA *	d2i_DSAPrivateKey(DSA **a, unsigned char **pp, long length);
  DSA * 	d2i_DSAparams(DSA **a, unsigned char **pp, long length);
- int	i2d_DSAPublicKey(DSA *a, unsigned char **pp);
- int 	i2d_DSAPrivateKey(DSA *a, unsigned char **pp);
- int	i2d_DSAparams(DSA *a,unsigned char **pp);
+ int	i2d_DSAPublicKey(const DSA *a, unsigned char **pp);
+ int 	i2d_DSAPrivateKey(const DSA *a, unsigned char **pp);
+ int	i2d_DSAparams(const DSA *a,unsigned char **pp);
 
- int	DSAparams_print(BIO *bp, DSA *x);
- int	DSAparams_print_fp(FILE *fp, DSA *x);
- int	DSA_print(BIO *bp, DSA *x, int off);
- int	DSA_print_fp(FILE *bp, DSA *x, int off);
+ int	DSAparams_print(BIO *bp, const DSA *x);
+ int	DSAparams_print_fp(FILE *fp, const DSA *x);
+ int	DSA_print(BIO *bp, const DSA *x, int off);
+ int	DSA_print_fp(FILE *bp, const DSA *x, int off);
 
 =head1 DESCRIPTION
 
@@ -85,6 +85,14 @@ The B<DSA> structure consists of several BIGNUM components.
 
 In public keys, B<priv_key> is NULL.
 
+Note that DSA keys may use non-standard B<DSA_METHOD> implementations,
+either directly or by the use of B<ENGINE> modules. In some cases (eg. an
+ENGINE providing support for hardware-embedded keys), these BIGNUM values
+will not be used by the implementation or may be used for alternative data
+storage. For this reason, applications should generally avoid using DSA
+structure elements directly and instead use API functions to query or
+modify keys.
+
 =head1 CONFORMING TO
 
 US Federal Information Processing Standard FIPS 186 (Digital Signature
@@ -93,7 +101,8 @@ Standard, DSS), ANSI X9.30
 =head1 SEE ALSO
 
 L<bn(3)|bn(3)>, L<dh(3)|dh(3)>, L<err(3)|err(3)>, L<rand(3)|rand(3)>,
-L<rsa(3)|rsa(3)>, L<sha(3)|sha(3)>, L<DSA_new(3)|DSA_new(3)>,
+L<rsa(3)|rsa(3)>, L<sha(3)|sha(3)>, L<engine(3)|engine(3)>,
+L<DSA_new(3)|DSA_new(3)>,
 L<DSA_size(3)|DSA_size(3)>,
 L<DSA_generate_parameters(3)|DSA_generate_parameters(3)>,
 L<DSA_dup_DH(3)|DSA_dup_DH(3)>,
diff --git a/doc/crypto/evp.pod b/doc/crypto/evp.pod
index edf47dbde6..b3ca14314f 100644
--- a/doc/crypto/evp.pod
+++ b/doc/crypto/evp.pod
@@ -24,6 +24,13 @@ functions.  The B<EVP_Digest>I<...> functions provide message digests.
 
 Algorithms are loaded with OpenSSL_add_all_algorithms(3).
 
+All the symmetric algorithms (ciphers) and digests can be replaced by ENGINE
+modules providing alternative implementations. If ENGINE implementations of
+ciphers or digests are registered as defaults, then the various EVP functions
+will automatically use those implementations automatically in preference to
+built in software implementations. For more information, consult the engine(3)
+man page.
+
 =head1 SEE ALSO
 
 L<EVP_DigestInit(3)|EVP_DigestInit(3)>,
@@ -32,6 +39,7 @@ L<EVP_OpenInit(3)|EVP_OpenInit(3)>,
 L<EVP_SealInit(3)|EVP_SealInit(3)>,
 L<EVP_SignInit(3)|EVP_SignInit(3)>,
 L<EVP_VerifyInit(3)|EVP_VerifyInit(3)>,
-L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)>
+L<OpenSSL_add_all_algorithms(3)|OpenSSL_add_all_algorithms(3)>,
+L<engine(3)|engine(3)>
 
 =cut
diff --git a/doc/crypto/rand.pod b/doc/crypto/rand.pod
index 96901f109e..1c068c85b3 100644
--- a/doc/crypto/rand.pod
+++ b/doc/crypto/rand.pod
@@ -8,13 +8,14 @@ rand - pseudo-random number generator
 
  #include <openssl/rand.h>
 
+ int  RAND_set_rand_engine(ENGINE *engine);
+
  int  RAND_bytes(unsigned char *buf, int num);
  int  RAND_pseudo_bytes(unsigned char *buf, int num);
 
  void RAND_seed(const void *buf, int num);
  void RAND_add(const void *buf, int num, int entropy);
  int  RAND_status(void);
- void RAND_screen(void);
 
  int  RAND_load_file(const char *file, long max_bytes);
  int  RAND_write_file(const char *file);
@@ -22,14 +23,31 @@ rand - pseudo-random number generator
 
  int  RAND_egd(const char *path);
 
- void RAND_set_rand_method(RAND_METHOD *meth);
- RAND_METHOD *RAND_get_rand_method(void);
+ void RAND_set_rand_method(const RAND_METHOD *meth);
+ const RAND_METHOD *RAND_get_rand_method(void);
  RAND_METHOD *RAND_SSLeay(void);
 
  void RAND_cleanup(void);
 
+ /* For Win32 only */
+ void RAND_screen(void);
+ int RAND_event(UINT, WPARAM, LPARAM);
+
 =head1 DESCRIPTION
 
+Since the introduction of the ENGINE API, the recommended way of controlling
+default implementations is by using the ENGINE API functions. The default
+B<RAND_METHOD>, as set by RAND_set_rand_method() and returned by
+RAND_get_rand_method(), is only used if no ENGINE has been set as the default
+"rand" implementation. Hence, these two functions are no longer the recommened
+way to control defaults.
+
+If an alternative B<RAND_METHOD> implementation is being used (either set
+directly or as provided by an ENGINE module), then it is entirely responsible
+for the generation and management of a cryptographically secure PRNG stream. The
+mechanisms described below relate solely to the software PRNG implementation
+built in to OpenSSL and used by default.
+
 These functions implement a cryptographically secure pseudo-random
 number generator (PRNG). It is used by other library functions for
 example to generate random keys, and applications can use it when they