These are updates/fixes to DH/DSA/RAND docs based on the fixes to the RSA

[openssl.git] / doc / crypto / dh.pod

diff --git a/doc/crypto/dh.pod b/doc/crypto/dh.pod
index b4be4be4058d97b757c93d63f112229b16a580a3..c3ccd062078304ad6f237417dae48047bfe0c4f8 100644 (file)
--- 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)>