import openssl-0.9.7-stable-SNAP-20020911 (without idea)

15 files changed, 941 insertions, 174 deletions

diff --git a/src/lib/libcrypto/doc/DH_set_method.pod b/src/lib/libcrypto/doc/DH_set_method.pod
index d990bf8786..73261fc467 100644
--- a/src/lib/libcrypto/doc/DH_set_method.pod
+++ b/src/lib/libcrypto/doc/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/src/lib/libcrypto/doc/DSA_dup_DH.pod b/src/lib/libcrypto/doc/DSA_dup_DH.pod
index 29cb1075d1..fdfe125ab0 100644
--- a/src/lib/libcrypto/doc/DSA_dup_DH.pod
+++ b/src/lib/libcrypto/doc/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/src/lib/libcrypto/doc/DSA_new.pod b/src/lib/libcrypto/doc/DSA_new.pod
index 7dde54445b..546146d9de 100644
--- a/src/lib/libcrypto/doc/DSA_new.pod
+++ b/src/lib/libcrypto/doc/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/src/lib/libcrypto/doc/DSA_set_method.pod b/src/lib/libcrypto/doc/DSA_set_method.pod
index 36a1052d27..bc3cfb1f0a 100644
--- a/src/lib/libcrypto/doc/DSA_set_method.pod
+++ b/src/lib/libcrypto/doc/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/src/lib/libcrypto/doc/DSA_size.pod b/src/lib/libcrypto/doc/DSA_size.pod
index 23b6320a4d..ba4f650361 100644
--- a/src/lib/libcrypto/doc/DSA_size.pod
+++ b/src/lib/libcrypto/doc/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/src/lib/libcrypto/doc/EVP_SealInit.pod b/src/lib/libcrypto/doc/EVP_SealInit.pod
index 0451eb648a..25ef07f7c7 100644
--- a/src/lib/libcrypto/doc/EVP_SealInit.pod
+++ b/src/lib/libcrypto/doc/EVP_SealInit.pod
@@ -73,4 +73,6 @@ L<EVP_OpenInit(3)|EVP_OpenInit(3)>
 
 =head1 HISTORY
 
+EVP_SealFinal() did not return a value before OpenSSL 0.9.7.
+
 =cut
diff --git a/src/lib/libcrypto/doc/RAND_set_rand_method.pod b/src/lib/libcrypto/doc/RAND_set_rand_method.pod
index 464eba416d..c9bb6d9f27 100644
--- a/src/lib/libcrypto/doc/RAND_set_rand_method.pod
+++ b/src/lib/libcrypto/doc/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/src/lib/libcrypto/doc/RSA_new.pod b/src/lib/libcrypto/doc/RSA_new.pod
index f16490ea6a..f0d996c40f 100644
--- a/src/lib/libcrypto/doc/RSA_new.pod
+++ b/src/lib/libcrypto/doc/RSA_new.pod
@@ -14,7 +14,8 @@ RSA_new, RSA_free - allocate and free RSA objects
 
 =head1 DESCRIPTION
 
-RSA_new() allocates and initializes an B<RSA> structure.
+RSA_new() allocates and initializes an B<RSA> structure. It is equivalent to
+calling RSA_new_method(NULL).
 
 RSA_free() frees the B<RSA> structure and its components. The key is
 erased before the memory is returned to the system.
@@ -29,7 +30,8 @@ RSA_free() returns no value.
 
 =head1 SEE ALSO
 
-L<err(3)|err(3)>, L<rsa(3)|rsa(3)>, L<RSA_generate_key(3)|RSA_generate_key(3)>
+L<err(3)|err(3)>, L<rsa(3)|rsa(3)>, L<RSA_generate_key(3)|RSA_generate_key(3)>,
+L<RSA_new_method(3)|RSA_new_method(3)>
 
 =head1 HISTORY
 
diff --git a/src/lib/libcrypto/doc/RSA_set_method.pod b/src/lib/libcrypto/doc/RSA_set_method.pod
index 14917dd35f..0687c2242a 100644
--- a/src/lib/libcrypto/doc/RSA_set_method.pod
+++ b/src/lib/libcrypto/doc/RSA_set_method.pod
@@ -11,52 +11,64 @@ RSA_null_method, RSA_flags, RSA_new_method - select RSA method
  #include <openssl/rsa.h>
  #include <openssl/engine.h>
 
- void RSA_set_default_openssl_method(RSA_METHOD *meth);
+ void RSA_set_default_method(const RSA_METHOD *meth);
 
- RSA_METHOD *RSA_get_default_openssl_method(void);
+ RSA_METHOD *RSA_get_default_method(void);
 
- int RSA_set_method(RSA *rsa, ENGINE *engine);
+ int RSA_set_method(RSA *rsa, const RSA_METHOD *meth);
 
- RSA_METHOD *RSA_get_method(RSA *rsa);
+ RSA_METHOD *RSA_get_method(const RSA *rsa);
 
  RSA_METHOD *RSA_PKCS1_SSLeay(void);
 
  RSA_METHOD *RSA_null_method(void);
 
- int RSA_flags(RSA *rsa);
+ int RSA_flags(const RSA *rsa);
 
  RSA *RSA_new_method(ENGINE *engine);
 
 =head1 DESCRIPTION
 
 An B<RSA_METHOD> specifies the functions that OpenSSL uses for RSA
-operations. By modifying the method, alternative implementations
-such as hardware accelerators may be used.
-
-Initially, the default is to use the OpenSSL internal implementation.
-RSA_PKCS1_SSLeay() returns a pointer to that method.
-
-RSA_set_default_openssl_method() makes B<meth> the default method for all B<RSA>
-structures created later. B<NB:> This is true only whilst the default engine
-for RSA operations remains as "openssl". ENGINEs provide an
-encapsulation for implementations of one or more algorithms at a time, and all
-the RSA functions mentioned here operate within the scope of the default
-"openssl" engine.
-
-RSA_get_default_openssl_method() returns a pointer to the current default
-method for the "openssl" engine.
-
-RSA_set_method() selects B<engine> for all operations using the key
-B<rsa>.
-
-RSA_get_method() returns a pointer to the RSA_METHOD from the currently
-selected ENGINE for B<rsa>.
-
-RSA_flags() returns the B<flags> that are set for B<rsa>'s current method.
+operations. By modifying the method, alternative implementations such as
+hardware accelerators may be used. IMPORTANT: See the NOTES section for
+important information about how these RSA API functions are affected by the
+use of B<ENGINE> API calls.
+
+Initially, the default RSA_METHOD is the OpenSSL internal implementation,
+as returned by RSA_PKCS1_SSLeay().
+
+RSA_set_default_method() makes B<meth> the default method for all RSA
+structures created later. B<NB>: This is true only whilst no ENGINE has
+been set as a default for RSA, so this function is no longer recommended.
+
+RSA_get_default_method() returns a pointer to the current default
+RSA_METHOD. However, the meaningfulness of this result is dependant on
+whether the ENGINE API is being used, so this function is no longer 
+recommended.
+
+RSA_set_method() selects B<meth> to perform all operations using the key
+B<rsa>. This will replace the RSA_METHOD used by the RSA 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 RSA keys that only
+work with certain RSA_METHOD implementations (eg. from an ENGINE module
+that supports embedded hardware-protected keys), and in such cases
+attempting to change the RSA_METHOD for the key can have unexpected
+results.
+
+RSA_get_method() returns a pointer to the RSA_METHOD being used by B<rsa>.
+This method may or may not be supplied by an ENGINE implementation, but if
+it is, the return value can only be guaranteed to be valid as long as the
+RSA key itself is valid and does not have its implementation changed by
+RSA_set_method().
+
+RSA_flags() returns the B<flags> that are set for B<rsa>'s current
+RSA_METHOD. See the BUGS section.
 
 RSA_new_method() allocates and initializes an RSA structure so that
-B<engine> will be used for the RSA operations. If B<engine> is NULL,
-the default engine for RSA operations is used.
+B<engine> will be used for the RSA operations. If B<engine> is NULL, the
+default ENGINE for RSA operations is used, and if no default ENGINE is set,
+the RSA_METHOD controlled by RSA_set_default_method() is used.
 
 =head1 THE RSA_METHOD STRUCTURE
 
@@ -121,22 +133,45 @@ the default engine for RSA operations is used.
 
 =head1 RETURN VALUES
 
-RSA_PKCS1_SSLeay(), RSA_PKCS1_null_method(), RSA_get_default_openssl_method()
+RSA_PKCS1_SSLeay(), RSA_PKCS1_null_method(), RSA_get_default_method()
 and RSA_get_method() return pointers to the respective RSA_METHODs.
 
-RSA_set_default_openssl_method() returns no value.
+RSA_set_default_method() returns no value.
 
-RSA_set_method() selects B<engine> as the engine that will be responsible for
-all operations using the structure B<rsa>. If this function completes successfully,
-then the B<rsa> 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 RSA_METHOD can be retrieved (or set) by
-ENGINE_get_RSA() or ENGINE_set_RSA().
+RSA_set_method() returns a pointer to the old RSA_METHOD implementation
+that was replaced. However, this return value should probably be ignored
+because if it was supplied by an ENGINE, the pointer could be invalidated
+at any time if the ENGINE is unloaded (in fact it could be unloaded as a
+result of the RSA_set_method() function releasing its handle to the
+ENGINE). For this reason, the return type may be replaced with a B<void>
+declaration in a future release.
 
-RSA_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
+RSA_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, RSA_METHOD implementations are grouped together with
+other algorithmic APIs (eg. DSA_METHOD, EVP_CIPHER, etc) into B<ENGINE>
+modules. If a default ENGINE is specified for RSA functionality using an
+ENGINE API function, that will override any RSA defaults set using the RSA
+API (ie.  RSA_set_default_method()). For this reason, the ENGINE API is the
+recommended way to control default implementations for use in RSA and other
+cryptographic algorithms.
+
+=head1 BUGS
+
+The behaviour of RSA_flags() is a mis-feature that is left as-is for now
+to avoid creating compatibility problems. RSA functionality, such as the
+encryption functions, are controlled by the B<flags> value in the RSA key
+itself, not by the B<flags> value in the RSA_METHOD attached to the RSA key
+(which is what this function returns). If the flags element of an RSA key
+is changed, the changes will be honoured by RSA functionality but will not
+be reflected in the return value of the RSA_flags() function - in effect
+RSA_flags() behaves more like an RSA_default_flags() function (which does
+not currently exist).
+
 =head1 SEE ALSO
 
 L<rsa(3)|rsa(3)>, L<RSA_new(3)|RSA_new(3)>
@@ -149,8 +184,14 @@ well as the rsa_sign and rsa_verify components of RSA_METHOD were
 added in OpenSSL 0.9.4.
 
 RSA_set_default_openssl_method() and RSA_get_default_openssl_method()
-replaced RSA_set_default_method() and RSA_get_default_method() respectively,
-and RSA_set_method() and RSA_new_method() were altered to use B<ENGINE>s
-rather than B<RSA_METHOD>s during development of OpenSSL 0.9.6.
+replaced RSA_set_default_method() and RSA_get_default_method()
+respectively, and RSA_set_method() and RSA_new_method() were altered to use
+B<ENGINE>s rather than B<RSA_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 RSA API without requiring changing these
+function prototypes.
 
 =cut
diff --git a/src/lib/libcrypto/doc/RSA_size.pod b/src/lib/libcrypto/doc/RSA_size.pod
index b36b4d58d5..5b7f835f95 100644
--- a/src/lib/libcrypto/doc/RSA_size.pod
+++ b/src/lib/libcrypto/doc/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/src/lib/libcrypto/doc/dh.pod b/src/lib/libcrypto/doc/dh.pod
index b4be4be405..c3ccd06207 100644
--- a/src/lib/libcrypto/doc/dh.pod
+++ b/src/lib/libcrypto/doc/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/src/lib/libcrypto/doc/dsa.pod b/src/lib/libcrypto/doc/dsa.pod
index 82d7fb77cd..da07d2b930 100644
--- a/src/lib/libcrypto/doc/dsa.pod
+++ b/src/lib/libcrypto/doc/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/src/lib/libcrypto/doc/engine.pod b/src/lib/libcrypto/doc/engine.pod
new file mode 100644
index 0000000000..61e0264bb7
--- /dev/null
+++ b/src/lib/libcrypto/doc/engine.pod
@@ -0,0 +1,621 @@
+=pod
+
+=head1 NAME
+
+engine - ENGINE cryptographic module support
+
+=head1 SYNOPSIS
+
+ #include <openssl/engine.h>
+
+ ENGINE *ENGINE_get_first(void);
+ ENGINE *ENGINE_get_last(void);
+ ENGINE *ENGINE_get_next(ENGINE *e);
+ ENGINE *ENGINE_get_prev(ENGINE *e);
+
+ int ENGINE_add(ENGINE *e);
+ int ENGINE_remove(ENGINE *e);
+
+ ENGINE *ENGINE_by_id(const char *id);
+
+ int ENGINE_init(ENGINE *e);
+ int ENGINE_finish(ENGINE *e);
+
+ void ENGINE_load_openssl(void);
+ void ENGINE_load_dynamic(void);
+ void ENGINE_load_cswift(void);
+ void ENGINE_load_chil(void);
+ void ENGINE_load_atalla(void);
+ void ENGINE_load_nuron(void);
+ void ENGINE_load_ubsec(void);
+ void ENGINE_load_aep(void);
+ void ENGINE_load_sureware(void);
+ void ENGINE_load_4758cca(void);
+ void ENGINE_load_openbsd_dev_crypto(void);
+ void ENGINE_load_builtin_engines(void);
+
+ void ENGINE_cleanup(void);
+
+ ENGINE *ENGINE_get_default_RSA(void);
+ ENGINE *ENGINE_get_default_DSA(void);
+ ENGINE *ENGINE_get_default_DH(void);
+ ENGINE *ENGINE_get_default_RAND(void);
+ ENGINE *ENGINE_get_cipher_engine(int nid);
+ ENGINE *ENGINE_get_digest_engine(int nid);
+
+ int ENGINE_set_default_RSA(ENGINE *e);
+ int ENGINE_set_default_DSA(ENGINE *e);
+ int ENGINE_set_default_DH(ENGINE *e);
+ int ENGINE_set_default_RAND(ENGINE *e);
+ int ENGINE_set_default_ciphers(ENGINE *e);
+ int ENGINE_set_default_digests(ENGINE *e);
+ int ENGINE_set_default_string(ENGINE *e, const char *list);
+
+ int ENGINE_set_default(ENGINE *e, unsigned int flags);
+
+ unsigned int ENGINE_get_table_flags(void);
+ void ENGINE_set_table_flags(unsigned int flags);
+
+ int ENGINE_register_RSA(ENGINE *e);
+ void ENGINE_unregister_RSA(ENGINE *e);
+ void ENGINE_register_all_RSA(void);
+ int ENGINE_register_DSA(ENGINE *e);
+ void ENGINE_unregister_DSA(ENGINE *e);
+ void ENGINE_register_all_DSA(void);
+ int ENGINE_register_DH(ENGINE *e);
+ void ENGINE_unregister_DH(ENGINE *e);
+ void ENGINE_register_all_DH(void);
+ int ENGINE_register_RAND(ENGINE *e);
+ void ENGINE_unregister_RAND(ENGINE *e);
+ void ENGINE_register_all_RAND(void);
+ int ENGINE_register_ciphers(ENGINE *e);
+ void ENGINE_unregister_ciphers(ENGINE *e);
+ void ENGINE_register_all_ciphers(void);
+ int ENGINE_register_digests(ENGINE *e);
+ void ENGINE_unregister_digests(ENGINE *e);
+ void ENGINE_register_all_digests(void);
+ int ENGINE_register_complete(ENGINE *e);
+ int ENGINE_register_all_complete(void);
+
+ int ENGINE_ctrl(ENGINE *e, int cmd, long i, void *p, void (*f)());
+ int ENGINE_cmd_is_executable(ENGINE *e, int cmd);
+ int ENGINE_ctrl_cmd(ENGINE *e, const char *cmd_name,
+         long i, void *p, void (*f)(), int cmd_optional);
+ int ENGINE_ctrl_cmd_string(ENGINE *e, const char *cmd_name, const char *arg,
+                 int cmd_optional);
+
+ int ENGINE_set_ex_data(ENGINE *e, int idx, void *arg);
+ void *ENGINE_get_ex_data(const ENGINE *e, int idx);
+
+ int ENGINE_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,
+         CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func);
+
+ ENGINE *ENGINE_new(void);
+ int ENGINE_free(ENGINE *e);
+
+ int ENGINE_set_id(ENGINE *e, const char *id);
+ int ENGINE_set_name(ENGINE *e, const char *name);
+ int ENGINE_set_RSA(ENGINE *e, const RSA_METHOD *rsa_meth);
+ int ENGINE_set_DSA(ENGINE *e, const DSA_METHOD *dsa_meth);
+ int ENGINE_set_DH(ENGINE *e, const DH_METHOD *dh_meth);
+ int ENGINE_set_RAND(ENGINE *e, const RAND_METHOD *rand_meth);
+ int ENGINE_set_destroy_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR destroy_f);
+ int ENGINE_set_init_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR init_f);
+ int ENGINE_set_finish_function(ENGINE *e, ENGINE_GEN_INT_FUNC_PTR finish_f);
+ int ENGINE_set_ctrl_function(ENGINE *e, ENGINE_CTRL_FUNC_PTR ctrl_f);
+ int ENGINE_set_load_privkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpriv_f);
+ int ENGINE_set_load_pubkey_function(ENGINE *e, ENGINE_LOAD_KEY_PTR loadpub_f);
+ int ENGINE_set_ciphers(ENGINE *e, ENGINE_CIPHERS_PTR f);
+ int ENGINE_set_digests(ENGINE *e, ENGINE_DIGESTS_PTR f);
+ int ENGINE_set_flags(ENGINE *e, int flags);
+ int ENGINE_set_cmd_defns(ENGINE *e, const ENGINE_CMD_DEFN *defns);
+
+ const char *ENGINE_get_id(const ENGINE *e);
+ const char *ENGINE_get_name(const ENGINE *e);
+ const RSA_METHOD *ENGINE_get_RSA(const ENGINE *e);
+ const DSA_METHOD *ENGINE_get_DSA(const ENGINE *e);
+ const DH_METHOD *ENGINE_get_DH(const ENGINE *e);
+ const RAND_METHOD *ENGINE_get_RAND(const ENGINE *e);
+ ENGINE_GEN_INT_FUNC_PTR ENGINE_get_destroy_function(const ENGINE *e);
+ ENGINE_GEN_INT_FUNC_PTR ENGINE_get_init_function(const ENGINE *e);
+ ENGINE_GEN_INT_FUNC_PTR ENGINE_get_finish_function(const ENGINE *e);
+ ENGINE_CTRL_FUNC_PTR ENGINE_get_ctrl_function(const ENGINE *e);
+ ENGINE_LOAD_KEY_PTR ENGINE_get_load_privkey_function(const ENGINE *e);
+ ENGINE_LOAD_KEY_PTR ENGINE_get_load_pubkey_function(const ENGINE *e);
+ ENGINE_CIPHERS_PTR ENGINE_get_ciphers(const ENGINE *e);
+ ENGINE_DIGESTS_PTR ENGINE_get_digests(const ENGINE *e);
+ const EVP_CIPHER *ENGINE_get_cipher(ENGINE *e, int nid);
+ const EVP_MD *ENGINE_get_digest(ENGINE *e, int nid);
+ int ENGINE_get_flags(const ENGINE *e);
+ const ENGINE_CMD_DEFN *ENGINE_get_cmd_defns(const ENGINE *e);
+
+ EVP_PKEY *ENGINE_load_private_key(ENGINE *e, const char *key_id,
+     UI_METHOD *ui_method, void *callback_data);
+ EVP_PKEY *ENGINE_load_public_key(ENGINE *e, const char *key_id,
+     UI_METHOD *ui_method, void *callback_data);
+
+ void ENGINE_add_conf_module(void);
+
+=head1 DESCRIPTION
+
+These functions create, manipulate, and use cryptographic modules in the
+form of B<ENGINE> objects. These objects act as containers for
+implementations of cryptographic algorithms, and support a
+reference-counted mechanism to allow them to be dynamically loaded in and
+out of the running application.
+
+The cryptographic functionality that can be provided by an B<ENGINE>
+implementation includes the following abstractions;
+
+ RSA_METHOD - for providing alternative RSA implementations
+ DSA_METHOD, DH_METHOD, RAND_METHOD - alternative DSA, DH, and RAND
+ EVP_CIPHER - potentially multiple cipher algorithms (indexed by 'nid')
+ EVP_DIGEST - potentially multiple hash algorithms (indexed by 'nid')
+ key-loading - loading public and/or private EVP_PKEY keys
+
+=head2 Reference counting and handles
+
+Due to the modular nature of the ENGINE API, pointers to ENGINEs need to be
+treated as handles - ie. not only as pointers, but also as references to
+the underlying ENGINE object. Ie. you should obtain a new reference when
+making copies of an ENGINE pointer if the copies will be used (and
+released) independantly.
+
+ENGINE objects have two levels of reference-counting to match the way in
+which the objects are used. At the most basic level, each ENGINE pointer is
+inherently a B<structural> reference - you need a structural reference
+simply to refer to the pointer value at all, as this kind of reference is
+your guarantee that the structure can not be deallocated until you release
+your reference.
+
+However, a structural reference provides no guarantee that the ENGINE has
+been initiliased to be usable to perform any of its cryptographic
+implementations - and indeed it's quite possible that most ENGINEs will not
+initialised at all on standard setups, as ENGINEs are typically used to
+support specialised hardware. To use an ENGINE's functionality, you need a
+B<functional> reference. This kind of reference can be considered a
+specialised form of structural reference, because each functional reference
+implicitly contains a structural reference as well - however to avoid
+difficult-to-find programming bugs, it is recommended to treat the two
+kinds of reference independantly. If you have a functional reference to an
+ENGINE, you have a guarantee that the ENGINE has been initialised ready to
+perform cryptographic operations and will not be uninitialised or cleaned
+up until after you have released your reference.
+
+We will discuss the two kinds of reference separately, including how to
+tell which one you are dealing with at any given point in time (after all
+they are both simply (ENGINE *) pointers, the difference is in the way they
+are used).
+
+=head3 Structural references
+
+This basic type of reference is typically used for creating new ENGINEs
+dynamically, iterating across OpenSSL's internal linked-list of loaded
+ENGINEs, reading information about an ENGINE, etc. Essentially a structural
+reference is sufficient if you only need to query or manipulate the data of
+an ENGINE implementation rather than use its functionality.
+
+The ENGINE_new() function returns a structural reference to a new (empty)
+ENGINE object. Other than that, structural references come from return
+values to various ENGINE API functions such as; ENGINE_by_id(),
+ENGINE_get_first(), ENGINE_get_last(), ENGINE_get_next(),
+ENGINE_get_prev(). All structural references should be released by a
+corresponding to call to the ENGINE_free() function - the ENGINE object
+itself will only actually be cleaned up and deallocated when the last
+structural reference is released.
+
+It should also be noted that many ENGINE API function calls that accept a
+structural reference will internally obtain another reference - typically
+this happens whenever the supplied ENGINE will be needed by OpenSSL after
+the function has returned. Eg. the function to add a new ENGINE to
+OpenSSL's internal list is ENGINE_add() - if this function returns success,
+then OpenSSL will have stored a new structural reference internally so the
+caller is still responsible for freeing their own reference with
+ENGINE_free() when they are finished with it. In a similar way, some
+functions will automatically release the structural reference passed to it
+if part of the function's job is to do so. Eg. the ENGINE_get_next() and
+ENGINE_get_prev() functions are used for iterating across the internal
+ENGINE list - they will return a new structural reference to the next (or
+previous) ENGINE in the list or NULL if at the end (or beginning) of the
+list, but in either case the structural reference passed to the function is
+released on behalf of the caller.
+
+To clarify a particular function's handling of references, one should
+always consult that function's documentation "man" page, or failing that
+the openssl/engine.h header file includes some hints.
+
+=head3 Functional references
+
+As mentioned, functional references exist when the cryptographic
+functionality of an ENGINE is required to be available. A functional
+reference can be obtained in one of two ways; from an existing structural
+reference to the required ENGINE, or by asking OpenSSL for the default
+operational ENGINE for a given cryptographic purpose.
+
+To obtain a functional reference from an existing structural reference,
+call the ENGINE_init() function. This returns zero if the ENGINE was not
+already operational and couldn't be successfully initialised (eg. lack of
+system drivers, no special hardware attached, etc), otherwise it will
+return non-zero to indicate that the ENGINE is now operational and will
+have allocated a new B<functional> reference to the ENGINE. In this case,
+the supplied ENGINE pointer is, from the point of the view of the caller,
+both a structural reference and a functional reference - so if the caller
+intends to use it as a functional reference it should free the structural
+reference with ENGINE_free() first. If the caller wishes to use it only as
+a structural reference (eg. if the ENGINE_init() call was simply to test if
+the ENGINE seems available/online), then it should free the functional
+reference; all functional references are released by the ENGINE_finish()
+function.
+
+The second way to get a functional reference is by asking OpenSSL for a
+default implementation for a given task, eg. by ENGINE_get_default_RSA(),
+ENGINE_get_default_cipher_engine(), etc. These are discussed in the next
+section, though they are not usually required by application programmers as
+they are used automatically when creating and using the relevant
+algorithm-specific types in OpenSSL, such as RSA, DSA, EVP_CIPHER_CTX, etc.
+
+=head2 Default implementations
+
+For each supported abstraction, the ENGINE code maintains an internal table
+of state to control which implementations are available for a given
+abstraction and which should be used by default. These implementations are
+registered in the tables separated-out by an 'nid' index, because
+abstractions like EVP_CIPHER and EVP_DIGEST support many distinct
+algorithms and modes - ENGINEs will support different numbers and
+combinations of these. In the case of other abstractions like RSA, DSA,
+etc, there is only one "algorithm" so all implementations implicitly
+register using the same 'nid' index. ENGINEs can be B<registered> into
+these tables to make themselves available for use automatically by the
+various abstractions, eg. RSA. For illustrative purposes, we continue with
+the RSA example, though all comments apply similarly to the other
+abstractions (they each get their own table and linkage to the
+corresponding section of openssl code).
+
+When a new RSA key is being created, ie. in RSA_new_method(), a
+"get_default" call will be made to the ENGINE subsystem to process the RSA
+state table and return a functional reference to an initialised ENGINE
+whose RSA_METHOD should be used. If no ENGINE should (or can) be used, it
+will return NULL and the RSA key will operate with a NULL ENGINE handle by
+using the conventional RSA implementation in OpenSSL (and will from then on
+behave the way it used to before the ENGINE API existed - for details see
+L<RSA_new_method(3)|RSA_new_method(3)>).
+
+Each state table has a flag to note whether it has processed this
+"get_default" query since the table was last modified, because to process
+this question it must iterate across all the registered ENGINEs in the
+table trying to initialise each of them in turn, in case one of them is
+operational. If it returns a functional reference to an ENGINE, it will
+also cache another reference to speed up processing future queries (without
+needing to iterate across the table). Likewise, it will cache a NULL
+response if no ENGINE was available so that future queries won't repeat the
+same iteration unless the state table changes. This behaviour can also be
+changed; if the ENGINE_TABLE_FLAG_NOINIT flag is set (using
+ENGINE_set_table_flags()), no attempted initialisations will take place,
+instead the only way for the state table to return a non-NULL ENGINE to the
+"get_default" query will be if one is expressly set in the table. Eg.
+ENGINE_set_default_RSA() does the same job as ENGINE_register_RSA() except
+that it also sets the state table's cached response for the "get_default"
+query.
+
+In the case of abstractions like EVP_CIPHER, where implementations are
+indexed by 'nid', these flags and cached-responses are distinct for each
+'nid' value.
+
+It is worth illustrating the difference between "registration" of ENGINEs
+into these per-algorithm state tables and using the alternative
+"set_default" functions. The latter handles both "registration" and also
+setting the cached "default" ENGINE in each relevant state table - so
+registered ENGINEs will only have a chance to be initialised for use as a
+default if a default ENGINE wasn't already set for the same state table.
+Eg. if ENGINE X supports cipher nids {A,B} and RSA, ENGINE Y supports
+ciphers {A} and DSA, and the following code is executed;
+
+ ENGINE_register_complete(X);
+ ENGINE_set_default(Y, ENGINE_METHOD_ALL);
+ e1 = ENGINE_get_default_RSA();
+ e2 = ENGINE_get_cipher_engine(A);
+ e3 = ENGINE_get_cipher_engine(B);
+ e4 = ENGINE_get_default_DSA();
+ e5 = ENGINE_get_cipher_engine(C);
+
+The results would be as follows;
+
+ assert(e1 == X);
+ assert(e2 == Y);
+ assert(e3 == X);
+ assert(e4 == Y);
+ assert(e5 == NULL);
+
+=head2 Application requirements
+
+This section will explain the basic things an application programmer should
+support to make the most useful elements of the ENGINE functionality
+available to the user. The first thing to consider is whether the
+programmer wishes to make alternative ENGINE modules available to the
+application and user. OpenSSL maintains an internal linked list of
+"visible" ENGINEs from which it has to operate - at start-up, this list is
+empty and in fact if an application does not call any ENGINE API calls and
+it uses static linking against openssl, then the resulting application
+binary will not contain any alternative ENGINE code at all. So the first
+consideration is whether any/all available ENGINE implementations should be
+made visible to OpenSSL - this is controlled by calling the various "load"
+functions, eg.
+
+ /* Make the "dynamic" ENGINE available */
+ void ENGINE_load_dynamic(void);
+ /* Make the CryptoSwift hardware acceleration support available */
+ void ENGINE_load_cswift(void);
+ /* Make support for nCipher's "CHIL" hardware available */
+ void ENGINE_load_chil(void);
+ ...
+ /* Make ALL ENGINE implementations bundled with OpenSSL available */
+ void ENGINE_load_builtin_engines(void);
+
+Having called any of these functions, ENGINE objects would have been
+dynamically allocated and populated with these implementations and linked
+into OpenSSL's internal linked list. At this point it is important to
+mention an important API function;
+
+ void ENGINE_cleanup(void);
+
+If no ENGINE API functions are called at all in an application, then there
+are no inherent memory leaks to worry about from the ENGINE functionality,
+however if any ENGINEs are "load"ed, even if they are never registered or
+used, it is necessary to use the ENGINE_cleanup() function to
+correspondingly cleanup before program exit, if the caller wishes to avoid
+memory leaks. This mechanism uses an internal callback registration table
+so that any ENGINE API functionality that knows it requires cleanup can
+register its cleanup details to be called during ENGINE_cleanup(). This
+approach allows ENGINE_cleanup() to clean up after any ENGINE functionality
+at all that your program uses, yet doesn't automatically create linker
+dependencies to all possible ENGINE functionality - only the cleanup
+callbacks required by the functionality you do use will be required by the
+linker.
+
+The fact that ENGINEs are made visible to OpenSSL (and thus are linked into
+the program and loaded into memory at run-time) does not mean they are
+"registered" or called into use by OpenSSL automatically - that behaviour
+is something for the application to have control over. Some applications
+will want to allow the user to specify exactly which ENGINE they want used
+if any is to be used at all. Others may prefer to load all support and have
+OpenSSL automatically use at run-time any ENGINE that is able to
+successfully initialise - ie. to assume that this corresponds to
+acceleration hardware attached to the machine or some such thing. There are
+probably numerous other ways in which applications may prefer to handle
+things, so we will simply illustrate the consequences as they apply to a
+couple of simple cases and leave developers to consider these and the
+source code to openssl's builtin utilities as guides.
+
+=head3 Using a specific ENGINE implementation
+
+Here we'll assume an application has been configured by its user or admin
+to want to use the "ACME" ENGINE if it is available in the version of
+OpenSSL the application was compiled with. If it is available, it should be
+used by default for all RSA, DSA, and symmetric cipher operation, otherwise
+OpenSSL should use its builtin software as per usual. The following code
+illustrates how to approach this;
+
+ ENGINE *e;
+ const char *engine_id = "ACME";
+ ENGINE_load_builtin_engines();
+ e = ENGINE_by_id(engine_id);
+ if(!e)
+     /* the engine isn't available */
+     return;
+ if(!ENGINE_init(e)) {
+     /* the engine couldn't initialise, release 'e' */
+     ENGINE_free(e);
+     return;
+ }
+ if(!ENGINE_set_default_RSA(e))
+     /* This should only happen when 'e' can't initialise, but the previous
+      * statement suggests it did. */
+     abort();
+ ENGINE_set_default_DSA(e);
+ ENGINE_set_default_ciphers(e);
+ /* Release the functional reference from ENGINE_init() */
+ ENGINE_finish(e);
+ /* Release the structural reference from ENGINE_by_id() */
+ ENGINE_free(e);
+
+=head3 Automatically using builtin ENGINE implementations
+
+Here we'll assume we want to load and register all ENGINE implementations
+bundled with OpenSSL, such that for any cryptographic algorithm required by
+OpenSSL - if there is an ENGINE that implements it and can be initialise,
+it should be used. The following code illustrates how this can work;
+
+ /* Load all bundled ENGINEs into memory and make them visible */
+ ENGINE_load_builtin_engines();
+ /* Register all of them for every algorithm they collectively implement */
+ ENGINE_register_all_complete();
+
+That's all that's required. Eg. the next time OpenSSL tries to set up an
+RSA key, any bundled ENGINEs that implement RSA_METHOD will be passed to
+ENGINE_init() and if any of those succeed, that ENGINE will be set as the
+default for use with RSA from then on.
+
+=head2 Advanced configuration support
+
+There is a mechanism supported by the ENGINE framework that allows each
+ENGINE implementation to define an arbitrary set of configuration
+"commands" and expose them to OpenSSL and any applications based on
+OpenSSL. This mechanism is entirely based on the use of name-value pairs
+and and assumes ASCII input (no unicode or UTF for now!), so it is ideal if
+applications want to provide a transparent way for users to provide
+arbitrary configuration "directives" directly to such ENGINEs. It is also
+possible for the application to dynamically interrogate the loaded ENGINE
+implementations for the names, descriptions, and input flags of their
+available "control commands", providing a more flexible configuration
+scheme. However, if the user is expected to know which ENGINE device he/she
+is using (in the case of specialised hardware, this goes without saying)
+then applications may not need to concern themselves with discovering the
+supported control commands and simply prefer to allow settings to passed
+into ENGINEs exactly as they are provided by the user.
+
+Before illustrating how control commands work, it is worth mentioning what
+they are typically used for. Broadly speaking there are two uses for
+control commands; the first is to provide the necessary details to the
+implementation (which may know nothing at all specific to the host system)
+so that it can be initialised for use. This could include the path to any
+driver or config files it needs to load, required network addresses,
+smart-card identifiers, passwords to initialise password-protected devices,
+logging information, etc etc. This class of commands typically needs to be
+passed to an ENGINE B<before> attempting to initialise it, ie. before
+calling ENGINE_init(). The other class of commands consist of settings or
+operations that tweak certain behaviour or cause certain operations to take
+place, and these commands may work either before or after ENGINE_init(), or
+in same cases both. ENGINE implementations should provide indications of
+this in the descriptions attached to builtin control commands and/or in
+external product documentation.
+
+=head3 Issuing control commands to an ENGINE
+
+Let's illustrate by example; a function for which the caller supplies the
+name of the ENGINE it wishes to use, a table of string-pairs for use before
+initialisation, and another table for use after initialisation. Note that
+the string-pairs used for control commands consist of a command "name"
+followed by the command "parameter" - the parameter could be NULL in some
+cases but the name can not. This function should initialise the ENGINE
+(issuing the "pre" commands beforehand and the "post" commands afterwards)
+and set it as the default for everything except RAND and then return a
+boolean success or failure.
+
+ int generic_load_engine_fn(const char *engine_id,
+                            const char **pre_cmds, int pre_num,
+                            const char **post_cmds, int post_num)
+ {
+     ENGINE *e = ENGINE_by_id(engine_id);
+     if(!e) return 0;
+     while(pre_num--) {
+         if(!ENGINE_ctrl_cmd_string(e, pre_cmds[0], pre_cmds[1], 0)) {
+             fprintf(stderr, "Failed command (%s - %s:%s)\n", engine_id,
+                 pre_cmds[0], pre_cmds[1] ? pre_cmds[1] : "(NULL)");
+             ENGINE_free(e);
+             return 0;
+         }
+         pre_cmds += 2;
+     }
+     if(!ENGINE_init(e)) {
+         fprintf(stderr, "Failed initialisation\n");
+         ENGINE_free(e);
+         return 0;
+     }
+     /* ENGINE_init() returned a functional reference, so free the structural
+      * reference from ENGINE_by_id(). */
+     ENGINE_free(e);
+     while(post_num--) {
+         if(!ENGINE_ctrl_cmd_string(e, post_cmds[0], post_cmds[1], 0)) {
+             fprintf(stderr, "Failed command (%s - %s:%s)\n", engine_id,
+                 post_cmds[0], post_cmds[1] ? post_cmds[1] : "(NULL)");
+             ENGINE_finish(e);
+             return 0;
+         }
+         post_cmds += 2;
+     }
+     ENGINE_set_default(e, ENGINE_METHOD_ALL & ~ENGINE_METHOD_RAND);
+     /* Success */
+     return 1;
+ }
+
+Note that ENGINE_ctrl_cmd_string() accepts a boolean argument that can
+relax the semantics of the function - if set non-zero it will only return
+failure if the ENGINE supported the given command name but failed while
+executing it, if the ENGINE doesn't support the command name it will simply
+return success without doing anything. In this case we assume the user is
+only supplying commands specific to the given ENGINE so we set this to
+FALSE.
+
+=head3 Discovering supported control commands
+
+It is possible to discover at run-time the names, numerical-ids, descriptions
+and input parameters of the control commands supported from a structural
+reference to any ENGINE. It is first important to note that some control
+commands are defined by OpenSSL itself and it will intercept and handle these
+control commands on behalf of the ENGINE, ie. the ENGINE's ctrl() handler is not
+used for the control command. openssl/engine.h defines a symbol,
+ENGINE_CMD_BASE, that all control commands implemented by ENGINEs from. Any
+command value lower than this symbol is considered a "generic" command is
+handled directly by the OpenSSL core routines.
+
+It is using these "core" control commands that one can discover the the control
+commands implemented by a given ENGINE, specifically the commands;
+
+ #define ENGINE_HAS_CTRL_FUNCTION               10
+ #define ENGINE_CTRL_GET_FIRST_CMD_TYPE         11
+ #define ENGINE_CTRL_GET_NEXT_CMD_TYPE          12
+ #define ENGINE_CTRL_GET_CMD_FROM_NAME          13
+ #define ENGINE_CTRL_GET_NAME_LEN_FROM_CMD      14
+ #define ENGINE_CTRL_GET_NAME_FROM_CMD          15
+ #define ENGINE_CTRL_GET_DESC_LEN_FROM_CMD      16
+ #define ENGINE_CTRL_GET_DESC_FROM_CMD          17
+ #define ENGINE_CTRL_GET_CMD_FLAGS              18
+
+Whilst these commands are automatically processed by the OpenSSL framework code,
+they use various properties exposed by each ENGINE by which to process these
+queries. An ENGINE has 3 properties it exposes that can affect this behaviour;
+it can supply a ctrl() handler, it can specify ENGINE_FLAGS_MANUAL_CMD_CTRL in
+the ENGINE's flags, and it can expose an array of control command descriptions.
+If an ENGINE specifies the ENGINE_FLAGS_MANUAL_CMD_CTRL flag, then it will
+simply pass all these "core" control commands directly to the ENGINE's ctrl()
+handler (and thus, it must have supplied one), so it is up to the ENGINE to
+reply to these "discovery" commands itself. If that flag is not set, then the
+OpenSSL framework code will work with the following rules;
+
+ if no ctrl() handler supplied;
+     ENGINE_HAS_CTRL_FUNCTION returns FALSE (zero),
+     all other commands fail.
+ if a ctrl() handler was supplied but no array of control commands;
+     ENGINE_HAS_CTRL_FUNCTION returns TRUE,
+     all other commands fail.
+ if a ctrl() handler and array of control commands was supplied;
+     ENGINE_HAS_CTRL_FUNCTION returns TRUE,
+     all other commands proceed processing ...
+
+If the ENGINE's array of control commands is empty then all other commands will
+fail, otherwise; ENGINE_CTRL_GET_FIRST_CMD_TYPE returns the identifier of
+the first command supported by the ENGINE, ENGINE_GET_NEXT_CMD_TYPE takes the
+identifier of a command supported by the ENGINE and returns the next command
+identifier or fails if there are no more, ENGINE_CMD_FROM_NAME takes a string
+name for a command and returns the corresponding identifier or fails if no such
+command name exists, and the remaining commands take a command identifier and
+return properties of the corresponding commands. All except
+ENGINE_CTRL_GET_FLAGS return the string length of a command name or description,
+or populate a supplied character buffer with a copy of the command name or
+description. ENGINE_CTRL_GET_FLAGS returns a bitwise-OR'd mask of the following
+possible values;
+
+ #define ENGINE_CMD_FLAG_NUMERIC                (unsigned int)0x0001
+ #define ENGINE_CMD_FLAG_STRING                 (unsigned int)0x0002
+ #define ENGINE_CMD_FLAG_NO_INPUT               (unsigned int)0x0004
+ #define ENGINE_CMD_FLAG_INTERNAL               (unsigned int)0x0008
+
+If the ENGINE_CMD_FLAG_INTERNAL flag is set, then any other flags are purely
+informational to the caller - this flag will prevent the command being usable
+for any higher-level ENGINE functions such as ENGINE_ctrl_cmd_string().
+"INTERNAL" commands are not intended to be exposed to text-based configuration
+by applications, administrations, users, etc. These can support arbitrary
+operations via ENGINE_ctrl(), including passing to and/or from the control
+commands data of any arbitrary type. These commands are supported in the
+discovery mechanisms simply to allow applications determinie if an ENGINE
+supports certain specific commands it might want to use (eg. application "foo"
+might query various ENGINEs to see if they implement "FOO_GET_VENDOR_LOGO_GIF" -
+and ENGINE could therefore decide whether or not to support this "foo"-specific
+extension).
+
+=head2 Future developments
+
+The ENGINE API and internal architecture is currently being reviewed. Slated for
+possible release in 0.9.8 is support for transparent loading of "dynamic"
+ENGINEs (built as self-contained shared-libraries). This would allow ENGINE
+implementations to be provided independantly of OpenSSL libraries and/or
+OpenSSL-based applications, and would also remove any requirement for
+applications to explicitly use the "dynamic" ENGINE to bind to shared-library
+implementations.
+
+=head1 SEE ALSO
+
+L<rsa(3)|rsa(3)>, L<dsa(3)|dsa(3)>, L<dh(3)|dh(3)>, L<rand(3)|rand(3)>,
+L<RSA_new_method(3)|RSA_new_method(3)>
+
+=cut
diff --git a/src/lib/libcrypto/doc/evp.pod b/src/lib/libcrypto/doc/evp.pod
index edf47dbde6..b3ca14314f 100644
--- a/src/lib/libcrypto/doc/evp.pod
+++ b/src/lib/libcrypto/doc/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/src/lib/libcrypto/doc/rsa.pod b/src/lib/libcrypto/doc/rsa.pod
index 2b93a12b65..45ac53ffc1 100644
--- a/src/lib/libcrypto/doc/rsa.pod
+++ b/src/lib/libcrypto/doc/rsa.pod
@@ -16,13 +16,17 @@ rsa - RSA public key cryptosystem
     unsigned char *to, RSA *rsa, int padding);
  int RSA_private_decrypt(int flen, unsigned char *from,
     unsigned char *to, RSA *rsa, int padding);
+ int RSA_private_encrypt(int flen, unsigned char *from,
+    unsigned char *to, RSA *rsa,int padding);
+ int RSA_public_decrypt(int flen, unsigned char *from, 
+    unsigned char *to, RSA *rsa,int padding);
 
  int RSA_sign(int type, unsigned char *m, unsigned int m_len,
     unsigned char *sigret, unsigned int *siglen, RSA *rsa);
  int RSA_verify(int type, unsigned char *m, unsigned int m_len,
     unsigned char *sigbuf, unsigned int siglen, RSA *rsa);
 
- int RSA_size(RSA *rsa);
+ int RSA_size(const RSA *rsa);
 
  RSA *RSA_generate_key(int num, unsigned long e,
     void (*callback)(int,int,void *), void *cb_arg);
@@ -32,13 +36,13 @@ rsa - RSA public key cryptosystem
  int RSA_blinding_on(RSA *rsa, BN_CTX *ctx);
  void RSA_blinding_off(RSA *rsa);
 
- void RSA_set_default_openssl_method(RSA_METHOD *meth);
- RSA_METHOD *RSA_get_default_openssl_method(void);
- int RSA_set_method(RSA *rsa, ENGINE *engine);
- RSA_METHOD *RSA_get_method(RSA *rsa);
+ void RSA_set_default_method(const RSA_METHOD *meth);
+ const RSA_METHOD *RSA_get_default_method(void);
+ int RSA_set_method(RSA *rsa, const RSA_METHOD *meth);
+ const RSA_METHOD *RSA_get_method(const RSA *rsa);
  RSA_METHOD *RSA_PKCS1_SSLeay(void);
  RSA_METHOD *RSA_null_method(void);
- int RSA_flags(RSA *rsa);
+ int RSA_flags(const RSA *rsa);
  RSA *RSA_new_method(ENGINE *engine);
 
  int RSA_print(BIO *bp, RSA *x, int offset);
@@ -49,11 +53,6 @@ rsa - RSA public key cryptosystem
  int RSA_set_ex_data(RSA *r,int idx,char *arg);
  char *RSA_get_ex_data(RSA *r, int idx);
 
- int RSA_private_encrypt(int flen, unsigned char *from,
-    unsigned char *to, RSA *rsa,int padding);
- int RSA_public_decrypt(int flen, unsigned char *from, 
-    unsigned char *to, RSA *rsa,int padding);
-
  int RSA_sign_ASN1_OCTET_STRING(int dummy, unsigned char *m,
     unsigned int m_len, unsigned char *sigret, unsigned int *siglen,
     RSA *rsa);
@@ -90,6 +89,14 @@ B<p>, B<q>, B<dmp1>, B<dmq1> and B<iqmp> may be B<NULL> in private
 keys, but the RSA operations are much faster when these values are
 available.
 
+Note that RSA keys may use non-standard B<RSA_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 RSA
+structure elements directly and instead use API functions to query or
+modify keys.
+
 =head1 CONFORMING TO
 
 SSL, PKCS #1 v2.0
@@ -101,7 +108,7 @@ RSA was covered by a US patent which expired in September 2000.
 =head1 SEE ALSO
 
 L<rsa(1)|rsa(1)>, L<bn(3)|bn(3)>, L<dsa(3)|dsa(3)>, L<dh(3)|dh(3)>,
-L<rand(3)|rand(3)>, L<RSA_new(3)|RSA_new(3)>,
+L<rand(3)|rand(3)>, L<engine(3)|engine(3)>, L<RSA_new(3)|RSA_new(3)>,
 L<RSA_public_encrypt(3)|RSA_public_encrypt(3)>,
 L<RSA_sign(3)|RSA_sign(3)>, L<RSA_size(3)|RSA_size(3)>,
 L<RSA_generate_key(3)|RSA_generate_key(3)>,