diff options
Diffstat (limited to 'lib/libcrypto/doc')
| -rw-r--r-- | lib/libcrypto/doc/DH_set_method.pod | 102 | ||||
| -rw-r--r-- | lib/libcrypto/doc/DSA_dup_DH.pod | 2 | ||||
| -rw-r--r-- | lib/libcrypto/doc/DSA_new.pod | 3 | ||||
| -rw-r--r-- | lib/libcrypto/doc/DSA_set_method.pod | 91 | ||||
| -rw-r--r-- | lib/libcrypto/doc/DSA_size.pod | 2 | ||||
| -rw-r--r-- | lib/libcrypto/doc/EVP_SealInit.pod | 2 | ||||
| -rw-r--r-- | lib/libcrypto/doc/RAND_set_rand_method.pod | 44 | ||||
| -rw-r--r-- | lib/libcrypto/doc/RSA_new.pod | 6 | ||||
| -rw-r--r-- | lib/libcrypto/doc/RSA_set_method.pod | 127 | ||||
| -rw-r--r-- | lib/libcrypto/doc/RSA_size.pod | 2 | ||||
| -rw-r--r-- | lib/libcrypto/doc/dh.pod | 31 | ||||
| -rw-r--r-- | lib/libcrypto/doc/dsa.pod | 38 | ||||
| -rw-r--r-- | lib/libcrypto/doc/evp.pod | 10 | ||||
| -rw-r--r-- | lib/libcrypto/doc/rsa.pod | 31 |
14 files changed, 318 insertions, 173 deletions
diff --git a/lib/libcrypto/doc/DH_set_method.pod b/lib/libcrypto/doc/DH_set_method.pod index d990bf87860..73261fc4675 100644 --- a/lib/libcrypto/doc/DH_set_method.pod +++ b/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/lib/libcrypto/doc/DSA_dup_DH.pod b/lib/libcrypto/doc/DSA_dup_DH.pod index 695f99a13b1..7f6f0d1115a 100644 --- a/lib/libcrypto/doc/DSA_dup_DH.pod +++ b/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/lib/libcrypto/doc/DSA_new.pod b/lib/libcrypto/doc/DSA_new.pod index 301af912dd5..48e9b82a09c 100644 --- a/lib/libcrypto/doc/DSA_new.pod +++ b/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/lib/libcrypto/doc/DSA_set_method.pod b/lib/libcrypto/doc/DSA_set_method.pod index 36a1052d276..bc3cfb1f0a7 100644 --- a/lib/libcrypto/doc/DSA_set_method.pod +++ b/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/lib/libcrypto/doc/DSA_size.pod b/lib/libcrypto/doc/DSA_size.pod index 23b6320a4d4..ba4f650361c 100644 --- a/lib/libcrypto/doc/DSA_size.pod +++ b/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/lib/libcrypto/doc/EVP_SealInit.pod b/lib/libcrypto/doc/EVP_SealInit.pod index 0451eb648a3..25ef07f7c7b 100644 --- a/lib/libcrypto/doc/EVP_SealInit.pod +++ b/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/lib/libcrypto/doc/RAND_set_rand_method.pod b/lib/libcrypto/doc/RAND_set_rand_method.pod index 464eba416d4..c9bb6d9f27b 100644 --- a/lib/libcrypto/doc/RAND_set_rand_method.pod +++ b/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/lib/libcrypto/doc/RSA_new.pod b/lib/libcrypto/doc/RSA_new.pod index 299047f31fa..3d15b928243 100644 --- a/lib/libcrypto/doc/RSA_new.pod +++ b/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. @@ -30,7 +31,8 @@ RSA_free() returns no value. =head1 SEE ALSO L<ERR_get_error(3)|ERR_get_error(3)>, L<rsa(3)|rsa(3)>, -L<RSA_generate_key(3)|RSA_generate_key(3)> +L<RSA_generate_key(3)|RSA_generate_key(3)>, +L<RSA_new_method(3)|RSA_new_method(3)> =head1 HISTORY diff --git a/lib/libcrypto/doc/RSA_set_method.pod b/lib/libcrypto/doc/RSA_set_method.pod index 14917dd35f9..0687c2242a5 100644 --- a/lib/libcrypto/doc/RSA_set_method.pod +++ b/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/lib/libcrypto/doc/RSA_size.pod b/lib/libcrypto/doc/RSA_size.pod index b36b4d58d54..5b7f835f95d 100644 --- a/lib/libcrypto/doc/RSA_size.pod +++ b/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/lib/libcrypto/doc/dh.pod b/lib/libcrypto/doc/dh.pod index b4be4be4058..c3ccd062078 100644 --- a/lib/libcrypto/doc/dh.pod +++ b/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/lib/libcrypto/doc/dsa.pod b/lib/libcrypto/doc/dsa.pod index 573500204bb..ae2e5d81f9a 100644 --- a/lib/libcrypto/doc/dsa.pod +++ b/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 diff --git a/lib/libcrypto/doc/evp.pod b/lib/libcrypto/doc/evp.pod index edf47dbde66..b3ca14314fa 100644 --- a/lib/libcrypto/doc/evp.pod +++ b/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/lib/libcrypto/doc/rsa.pod b/lib/libcrypto/doc/rsa.pod index 2b93a12b654..45ac53ffc14 100644 --- a/lib/libcrypto/doc/rsa.pod +++ b/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)>, |