From beaf6d7ab9d7d5a2d7afefdd5cf9ddf04e732d18 Mon Sep 17 00:00:00 2001
From: Nikos Mavrogiannopoulos <nmav@redhat.com>
Date: Thu, 14 Apr 2016 11:02:59 +0200
Subject: doc: updated docs related to private key generation

---
 lib/privkey.c         | 16 ++++++++++------
 lib/x509/privkey.c    | 13 +++++++------
 src/certtool-args.def |  2 +-
 3 files changed, 18 insertions(+), 13 deletions(-)

diff --git a/lib/privkey.c b/lib/privkey.c
index 90a6304796..0f63649ec2 100644
--- 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 b36a140c29..4d6a3a32eb 100644
--- 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 d93f954104..737c00306d 100644
--- 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 = {
-- 
cgit v1.2.1