diff options
Diffstat (limited to 'secure/lib/libcrypto/man/RSA_set_method.3')
-rw-r--r-- | secure/lib/libcrypto/man/RSA_set_method.3 | 123 |
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. |