Update for OpenSSL 0.9.7. No assembler code at the moment. This

will follow.

1 files changed, 84 insertions, 39 deletions

diff --git a/secure/lib/libcrypto/man/RSA_set_method.3 b/secure/lib/libcrypto/man/RSA_set_method.3
index df55757..ee2ada5 100644
--- a/secure/lib/libcrypto/man/RSA_set_method.3
+++ b/secure/lib/libcrypto/man/RSA_set_method.3
@@ -1,5 +1,5 @@
 .\" Automatically generated by Pod::Man version 1.15
-.\" Tue Jul 30 09:21:54 2002
+.\" Mon Jan 13 19:28:40 2003
 .\"
 .\" Standard preamble:
 .\" ======================================================================
@@ -138,40 +138,37 @@
 .\" ======================================================================
 .\"
 .IX Title "RSA_set_method 3"
-.TH RSA_set_method 3 "0.9.6e" "2000-11-12" "OpenSSL"
+.TH RSA_set_method 3 "0.9.7" "2003-01-13" "OpenSSL"
 .UC
 .SH "NAME"
 RSA_set_default_method, RSA_get_default_method, RSA_set_method,
-RSA_get_method, RSA_PKCS1_SSLeay, RSA_PKCS1_RSAref,
-RSA_null_method, RSA_flags, RSA_new_method \- select \s-1RSA\s0 method
+RSA_get_method, RSA_PKCS1_SSLeay, RSA_null_method, RSA_flags,
+RSA_new_method \- select \s-1RSA\s0 method
 .SH "SYNOPSIS"
 .IX Header "SYNOPSIS"
 .Vb 1
 \& #include <openssl/rsa.h>
 .Ve
 .Vb 1
-\& void RSA_set_default_method(RSA_METHOD *meth);
+\& void RSA_set_default_method(const RSA_METHOD *meth);
 .Ve
 .Vb 1
 \& RSA_METHOD *RSA_get_default_method(void);
 .Ve
 .Vb 1
-\& RSA_METHOD *RSA_set_method(RSA *rsa, RSA_METHOD *meth);
+\& int RSA_set_method(RSA *rsa, const RSA_METHOD *meth);
 .Ve
 .Vb 1
-\& RSA_METHOD *RSA_get_method(RSA *rsa);
+\& RSA_METHOD *RSA_get_method(const RSA *rsa);
 .Ve
 .Vb 1
 \& RSA_METHOD *RSA_PKCS1_SSLeay(void);
 .Ve
 .Vb 1
-\& RSA_METHOD *RSA_PKCS1_RSAref(void);
-.Ve
-.Vb 1
 \& RSA_METHOD *RSA_null_method(void);
 .Ve
 .Vb 1
-\& int RSA_flags(RSA *rsa);
+\& int RSA_flags(const RSA *rsa);
 .Ve
 .Vb 1
 \& RSA *RSA_new_method(RSA_METHOD *method);
@@ -179,32 +176,45 @@ RSA_null_method, RSA_flags, RSA_new_method \- select \s-1RSA\s0 method
 .SH "DESCRIPTION"
 .IX Header "DESCRIPTION"
 An \fB\s-1RSA_METHOD\s0\fR specifies the functions that OpenSSL uses for \s-1RSA\s0
-operations. By modifying the method, alternative implementations
-such as hardware accelerators may be used.
-.PP
-Initially, the default is to use the OpenSSL internal implementation,
-unless OpenSSL was configured with the \f(CW\*(C`rsaref\*(C'\fR or \f(CW\*(C`\-DRSA_NULL\*(C'\fR
-options. \fIRSA_PKCS1_SSLeay()\fR returns a pointer to that method.
+operations. By modifying the method, alternative implementations such as
+hardware accelerators may be used. \s-1IMPORTANT:\s0 See the \s-1NOTES\s0 section for
+important information about how these \s-1RSA\s0 \s-1API\s0 functions are affected by the
+use of \fB\s-1ENGINE\s0\fR \s-1API\s0 calls.
 .PP
-\&\fIRSA_PKCS1_RSAref()\fR returns a pointer to a method that uses the RSAref
-library. This is the default method in the \f(CW\*(C`rsaref\*(C'\fR configuration;
-the function is not available in other configurations.
-\&\fIRSA_null_method()\fR returns a pointer to a method that does not support
-the \s-1RSA\s0 transformation. It is the default if OpenSSL is compiled with
-\&\f(CW\*(C`\-DRSA_NULL\*(C'\fR. These methods may be useful in the \s-1USA\s0 because of a
-patent on the \s-1RSA\s0 cryptosystem.
+Initially, the default \s-1RSA_METHOD\s0 is the OpenSSL internal implementation,
+as returned by \fIRSA_PKCS1_SSLeay()\fR.
 .PP
-\&\fIRSA_set_default_method()\fR makes \fBmeth\fR the default method for all \fB\s-1RSA\s0\fR
-structures created later.
+\&\fIRSA_set_default_method()\fR makes \fBmeth\fR the default method for all \s-1RSA\s0
+structures created later. \fB\s-1NB\s0\fR: This is true only whilst no \s-1ENGINE\s0 has
+been set as a default for \s-1RSA\s0, so this function is no longer recommended.
 .PP
 \&\fIRSA_get_default_method()\fR returns a pointer to the current default
-method.
+\&\s-1RSA_METHOD\s0. However, the meaningfulness of this result is dependant on
+whether the \s-1ENGINE\s0 \s-1API\s0 is being used, so this function is no longer 
+recommended.
 .PP
-\&\fIRSA_set_method()\fR selects \fBmeth\fR for all operations using the key
-\&\fBrsa\fR.
+\&\fIRSA_set_method()\fR selects \fBmeth\fR to perform all operations using the key
+\&\fBrsa\fR. This will replace the \s-1RSA_METHOD\s0 used by the \s-1RSA\s0 key and if the
+previous method was supplied by an \s-1ENGINE\s0, the handle to that \s-1ENGINE\s0 will
+be released during the change. It is possible to have \s-1RSA\s0 keys that only
+work with certain \s-1RSA_METHOD\s0 implementations (eg. from an \s-1ENGINE\s0 module
+that supports embedded hardware-protected keys), and in such cases
+attempting to change the \s-1RSA_METHOD\s0 for the key can have unexpected
+results.
 .PP
-\&\fIRSA_get_method()\fR returns a pointer to the method currently selected
-for \fBrsa\fR.
+\&\fIRSA_get_method()\fR returns a pointer to the \s-1RSA_METHOD\s0 being used by \fBrsa\fR.
+This method may or may not be supplied by an \s-1ENGINE\s0 implementation, but if
+it is, the return value can only be guaranteed to be valid as long as the
+\&\s-1RSA\s0 key itself is valid and does not have its implementation changed by
+\&\fIRSA_set_method()\fR.
+.PP
+\&\fIRSA_flags()\fR returns the \fBflags\fR that are set for \fBrsa\fR's current
+\&\s-1RSA_METHOD\s0. See the \s-1BUGS\s0 section.
+.PP
+\&\fIRSA_new_method()\fR allocates and initializes an \s-1RSA\s0 structure so that
+\&\fBengine\fR will be used for the \s-1RSA\s0 operations. If \fBengine\fR is \s-1NULL\s0, the
+default \s-1ENGINE\s0 for \s-1RSA\s0 operations is used, and if no default \s-1ENGINE\s0 is set,
+the \s-1RSA_METHOD\s0 controlled by \fIRSA_set_default_method()\fR is used.
 .PP
 \&\fIRSA_flags()\fR returns the \fBflags\fR that are set for \fBrsa\fR's current method.
 .PP
@@ -288,18 +298,42 @@ the default method is used.
 .Ve
 .SH "RETURN VALUES"
 .IX Header "RETURN VALUES"
-\&\fIRSA_PKCS1_SSLeay()\fR, \fIRSA_PKCS1_RSAref()\fR, \fIRSA_PKCS1_null_method()\fR,
-\&\fIRSA_get_default_method()\fR and \fIRSA_get_method()\fR return pointers to the
-respective \fB\s-1RSA_METHOD\s0\fRs.
+\&\fIRSA_PKCS1_SSLeay()\fR, \fIRSA_PKCS1_null_method()\fR, \fIRSA_get_default_method()\fR
+and \fIRSA_get_method()\fR return pointers to the respective RSA_METHODs.
 .PP
 \&\fIRSA_set_default_method()\fR returns no value.
 .PP
-\&\fIRSA_set_method()\fR returns a pointer to the \fB\s-1RSA_METHOD\s0\fR previously
-associated with \fBrsa\fR.
+\&\fIRSA_set_method()\fR returns a pointer to the old \s-1RSA_METHOD\s0 implementation
+that was replaced. However, this return value should probably be ignored
+because if it was supplied by an \s-1ENGINE\s0, the pointer could be invalidated
+at any time if the \s-1ENGINE\s0 is unloaded (in fact it could be unloaded as a
+result of the \fIRSA_set_method()\fR function releasing its handle to the
+\&\s-1ENGINE\s0). For this reason, the return type may be replaced with a \fBvoid\fR
+declaration in a future release.
 .PP
-\&\fIRSA_new_method()\fR returns \fB\s-1NULL\s0\fR and sets an error code that can be
-obtained by ERR_get_error(3) if the allocation fails. Otherwise it
-returns a pointer to the newly allocated structure.
+\&\fIRSA_new_method()\fR returns \s-1NULL\s0 and sets an error code that can be obtained
+by ERR_get_error(3) if the allocation fails. Otherwise
+it returns a pointer to the newly allocated structure.
+.SH "NOTES"
+.IX Header "NOTES"
+As of version 0.9.7, \s-1RSA_METHOD\s0 implementations are grouped together with
+other algorithmic APIs (eg. \s-1DSA_METHOD\s0, \s-1EVP_CIPHER\s0, etc) into \fB\s-1ENGINE\s0\fR
+modules. If a default \s-1ENGINE\s0 is specified for \s-1RSA\s0 functionality using an
+\&\s-1ENGINE\s0 \s-1API\s0 function, that will override any \s-1RSA\s0 defaults set using the \s-1RSA\s0
+\&\s-1API\s0 (ie.  \fIRSA_set_default_method()\fR). For this reason, the \s-1ENGINE\s0 \s-1API\s0 is the
+recommended way to control default implementations for use in \s-1RSA\s0 and other
+cryptographic algorithms.
+.SH "BUGS"
+.IX Header "BUGS"
+The behaviour of \fIRSA_flags()\fR is a mis-feature that is left as-is for now
+to avoid creating compatibility problems. \s-1RSA\s0 functionality, such as the
+encryption functions, are controlled by the \fBflags\fR value in the \s-1RSA\s0 key
+itself, not by the \fBflags\fR value in the \s-1RSA_METHOD\s0 attached to the \s-1RSA\s0 key
+(which is what this function returns). If the flags element of an \s-1RSA\s0 key
+is changed, the changes will be honoured by \s-1RSA\s0 functionality but will not
+be reflected in the return value of the \fIRSA_flags()\fR function \- in effect
+\&\fIRSA_flags()\fR behaves more like an \fIRSA_default_flags()\fR function (which does
+not currently exist).
 .SH "SEE ALSO"
 .IX Header "SEE ALSO"
 rsa(3), RSA_new(3)
@@ -309,3 +343,14 @@ rsa(3), RSA_new(3)
 \&\fIRSA_get_default_method()\fR, \fIRSA_set_method()\fR and \fIRSA_get_method()\fR as
 well as the rsa_sign and rsa_verify components of \s-1RSA_METHOD\s0 were
 added in OpenSSL 0.9.4.
+.PP
+\&\fIRSA_set_default_openssl_method()\fR and \fIRSA_get_default_openssl_method()\fR
+replaced \fIRSA_set_default_method()\fR and \fIRSA_get_default_method()\fR
+respectively, and \fIRSA_set_method()\fR and \fIRSA_new_method()\fR were altered to use
+\&\fB\s-1ENGINE\s0\fRs rather than \fB\s-1RSA_METHOD\s0\fRs during development of the engine
+version of OpenSSL 0.9.6. For 0.9.7, the handling of defaults in the \s-1ENGINE\s0
+\&\s-1API\s0 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 \s-1ENGINE\s0 \s-1API\s0 now transparently overrides the
+behaviour of defaults in the \s-1RSA\s0 \s-1API\s0 without requiring changing these
+function prototypes.