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