doc: updated docs related to private key generation

diff --git a/lib/privkey.c b/lib/privkey.c
index 90a63047963af287401b5f4902d4cead283ebc66..0f63649ec256820ba8e674c04899d6d4cd997985 100644 (file)
--- a/lib/privkey.c
+++ b/lib/privkey.c
@@ -782,9 +782,9 @@ gnutls_privkey_export_x509(gnutls_privkey_t pkey,
 
 /**
  * gnutls_privkey_generate:
- * @pkey: The private key
+ * @pkey: An initialized private key
  * @algo: is one of the algorithms in #gnutls_pk_algorithm_t.
- * @bits: the size of the modulus
+ * @bits: the size of the parameters to generate
  * @flags: Must be zero or flags from #gnutls_privkey_flags_t.
  *
  * This function will generate a random private key. Note that this
@@ -794,9 +794,13 @@ gnutls_privkey_export_x509(gnutls_privkey_t pkey,
  *
  * Note that when generating an elliptic curve key, the curve
  * can be substituted in the place of the bits parameter using the
- * GNUTLS_CURVE_TO_BITS() macro.
+ * GNUTLS_CURVE_TO_BITS() macro. The input to the macro is any curve from
+ * %gnutls_ecc_curve_t.
  *
- * Do not set the number of bits directly, use gnutls_sec_param_to_pk_bits().
+ * For DSA keys, if the subgroup size needs to be specified check
+ * the GNUTLS_SUBGROUP_TO_BITS() macro.
+ *
+ * It is recommended to do not set the number of @bits directly, use gnutls_sec_param_to_pk_bits() instead .
  *
  * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise a
  *   negative error value.
@@ -822,8 +826,8 @@ gnutls_privkey_generate(gnutls_privkey_t pkey,
  *
  * This function will generate a random private key. Note that this
  * function must be called on an empty private key. The flag %GNUTLS_PRIVKEY_FLAG_PROVABLE
- * instructs the key generation process to use algorithms which generate
- * provable parameters out of a seed.
+ * instructs the key generation process to use algorithms like Shawe-Taylor
+ * which generate provable parameters out of a seed.
  *
  * Note that when generating an elliptic curve key, the curve
  * can be substituted in the place of the bits parameter using the

diff --git a/lib/x509/privkey.c b/lib/x509/privkey.c
index b36a140c29698aba9c1ac3791b2f351e3c52a341..4d6a3a32ebcdb409c9c057bf6cd42a3bf36cd90d 100644 (file)
--- a/lib/x509/privkey.c
+++ b/lib/x509/privkey.c
@@ -1537,24 +1537,25 @@ cleanup:
 
 /**
  * gnutls_x509_privkey_generate:
- * @key: a key
+ * @key: an initialized key
  * @algo: is one of the algorithms in #gnutls_pk_algorithm_t.
- * @bits: the size of the modulus
+ * @bits: the size of the parameters to generate
  * @flags: Must be zero or flags from #gnutls_privkey_flags_t.
  *
  * This function will generate a random private key. Note that this
  * function must be called on an empty private key. The flag %GNUTLS_PRIVKEY_FLAG_PROVABLE
- * instructs the key generation process to use algorithms which generate
- * provable parameters out of a seed.
+ * instructs the key generation process to use algorithms like Shawe-Taylor
+ * which generate provable parameters out of a seed.
  *
  * Note that when generating an elliptic curve key, the curve
  * can be substituted in the place of the bits parameter using the
- * GNUTLS_CURVE_TO_BITS() macro.
+ * GNUTLS_CURVE_TO_BITS() macro. The input to the macro is any curve from
+ * %gnutls_ecc_curve_t.
  *
  * For DSA keys, if the subgroup size needs to be specified check
  * the GNUTLS_SUBGROUP_TO_BITS() macro.
  *
- * Do not set the number of bits directly, use gnutls_sec_param_to_pk_bits().
+ * It is recommended to do not set the number of @bits directly, use gnutls_sec_param_to_pk_bits() instead .
  *
  * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise a
  *   negative error value.

diff --git a/src/certtool-args.def b/src/certtool-args.def
index d93f954104c929ec90879c06e633a7f4b4c6c656..737c00306d20c9d8ef2f8b429990e744dc4a9980 100644 (file)
--- a/src/certtool-args.def
+++ b/src/certtool-args.def
@@ -60,7 +60,7 @@ flag = {
 flag = {
     name      = provable;
     descrip   = "Generate a private key or parameters from a seed using a provable method";
-    doc = "This will use the FIPS-186-4 algorithms for provable key generation. You may specify --seed or allow GnuTLS to generate one (recommended). This option can be combined with --generate-privkey or --generate-dh-params.";
+    doc = "This will use the FIPS-186-4 algorithms (i.e., Shawe-Taylor) for provable key generation. When specified the private keys or parameters will be generated from a seed, and can be proven to be correctly generated from the seed. You may specify --seed or allow GnuTLS to generate one (recommended). This option can be combined with --generate-privkey or --generate-dh-params.";
 };
 
 flag = {