doc: improve documentation on provable private keystmp-doc-update

Resolves #301

Signed-off-by: Nikos Mavrogiannopoulos <nmav@gnutls.org>

5 files changed, 65 insertions, 18 deletions

diff --git a/doc/cha-crypto.texi b/doc/cha-crypto.texi
index 80a9e072ab..dc28a42a94 100644
--- a/doc/cha-crypto.texi
+++ b/doc/cha-crypto.texi
@@ -61,6 +61,15 @@ either by setting the global PIN function
 (@funcref{gnutls_pkcs11_set_pin_function}), or better with the targetted to
 structures functions such as @funcref{gnutls_privkey_set_pin_function}.
 
+
+@subsection Key generation
+
+All supported key types (including RSA, DSA, ECDSA, Ed25519) can be generated
+with GnuTLS. They can be generated with the simpler @funcref{gnutls_privkey_generate}
+or with the more advanced @funcref{gnutls_privkey_generate2}.
+
+@showfuncdesc{gnutls_privkey_generate2}
+
 @node Cryptographic Message Syntax / PKCS#7
 @section Cryptographic Message Syntax / PKCS#7
 @cindex public key algorithms
diff --git a/lib/includes/gnutls/x509.h b/lib/includes/gnutls/x509.h
index 8adb5e4941..1246a30eb2 100644
--- a/lib/includes/gnutls/x509.h
+++ b/lib/includes/gnutls/x509.h
@@ -1214,7 +1214,7 @@ void gnutls_x509_privkey_set_flags(gnutls_x509_privkey_t key, unsigned int flags
  * @GNUTLS_KEYGEN_DIGEST: The size field specifies the hash algorithm to be used in key generation.
  * @GNUTLS_KEYGEN_SPKI: data points to a %gnutls_x509_spki_t structure; it is not used after the key generation call.
  *
- * Enumeration of different key exchange algorithms.
+ * Enumeration of different key generation data options.
  */
 typedef enum {
 	GNUTLS_KEYGEN_SEED = 1,
diff --git a/lib/privkey.c b/lib/privkey.c
index cfd3341fd9..6c1a52ee30 100644
--- a/lib/privkey.c
+++ b/lib/privkey.c
@@ -962,9 +962,13 @@ gnutls_privkey_export_x509(gnutls_privkey_t pkey,
  * @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.
+ * function must be called on an initialized private key.
+ *
+ * The flag %GNUTLS_PRIVKEY_FLAG_PROVABLE
+ * instructs the key generation process to use algorithms like Shawe-Taylor
+ * (from FIPS PUB186-4) which generate provable parameters out of a seed
+ * for RSA and DSA keys. See gnutls_privkey_generate2() for more
+ * information.
  *
  * Note that when generating an elliptic curve key, the curve
  * can be substituted in the place of the bits parameter using the
@@ -976,6 +980,8 @@ gnutls_privkey_export_x509(gnutls_privkey_t pkey,
  *
  * It is recommended to do not set the number of @bits directly, use gnutls_sec_param_to_pk_bits() instead .
  *
+ * See also gnutls_privkey_generate2().
+ *
  * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise a
  *   negative error value.
  *
@@ -999,15 +1005,30 @@ gnutls_privkey_generate(gnutls_privkey_t pkey,
  * @data_size: The number of @data available.
  *
  * 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
+ * function must be called on an initialized private key.
+ *
+ * The flag %GNUTLS_PRIVKEY_FLAG_PROVABLE
  * instructs the key generation process to use algorithms like Shawe-Taylor
- * which generate provable parameters out of a seed.
+ * (from FIPS PUB186-4) which generate provable parameters out of a seed
+ * for RSA and DSA keys. On DSA keys the PQG parameters are generated using the
+ * seed, while on RSA the two primes. To specify an explicit seed
+ * (by default a random seed is used), use the @data with a %GNUTLS_KEYGEN_SEED
+ * type.
  *
  * 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.
  *
- * Do not set the number of bits directly, use gnutls_sec_param_to_pk_bits().
+ * To export the generated keys in memory or in files it is recommended to use the
+ * PKCS#8 form as it can handle all key types, and can store additional parameters
+ * such as the seed, in case of provable RSA or DSA keys.
+ * Generated keys can be exported in memory using gnutls_privkey_export_x509(),
+ * and then with gnutls_x509_privkey_export2_pkcs8().
+ *
+ * If key generation is part of your application, avoid setting the number
+ * of bits directly, and instead use gnutls_sec_param_to_pk_bits().
+ * That way the generated keys will adapt to the security levels
+ * of the underlying GnuTLS library.
  *
  * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise a
  *   negative error value.
diff --git a/lib/x509/privkey.c b/lib/x509/privkey.c
index 7bf5a9f14a..badeb945df 100644
--- a/lib/x509/privkey.c
+++ b/lib/x509/privkey.c
@@ -1546,9 +1546,13 @@ gnutls_x509_privkey_export_dsa_raw(gnutls_x509_privkey_t key,
  * @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
+ * function must be called on an initialized private key.
+ *
+ * The flag %GNUTLS_PRIVKEY_FLAG_PROVABLE
  * instructs the key generation process to use algorithms like Shawe-Taylor
- * which generate provable parameters out of a seed.
+ * (from FIPS PUB186-4) which generate provable parameters out of a seed
+ * for RSA and DSA keys. See gnutls_x509_privkey_generate2() for more
+ * information.
  *
  * Note that when generating an elliptic curve key, the curve
  * can be substituted in the place of the bits parameter using the
@@ -1560,6 +1564,8 @@ gnutls_x509_privkey_export_dsa_raw(gnutls_x509_privkey_t key,
  *
  * It is recommended to do not set the number of @bits directly, use gnutls_sec_param_to_pk_bits() instead .
  *
+ * See also gnutls_privkey_generate(), gnutls_x509_privkey_generate2().
+ *
  * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise a
  *   negative error value.
  **/
@@ -1581,21 +1587,32 @@ gnutls_x509_privkey_generate(gnutls_x509_privkey_t key,
  * @data_size: The number of @data available.
  *
  * 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.
+ * function must be called on an initialized private key.
+ *
+ * The flag %GNUTLS_PRIVKEY_FLAG_PROVABLE
+ * instructs the key generation process to use algorithms like Shawe-Taylor
+ * (from FIPS PUB186-4) which generate provable parameters out of a seed
+ * for RSA and DSA keys. On DSA keys the PQG parameters are generated using the
+ * seed, while on RSA the two primes. To specify an explicit seed
+ * (by default a random seed is used), use the @data with a %GNUTLS_KEYGEN_SEED
+ * type.
  *
  * 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.
  *
- * For DSA keys, if the subgroup size needs to be specified check
- * the GNUTLS_SUBGROUP_TO_BITS() macro.
+ * To export the generated keys in memory or in files it is recommended to use the
+ * PKCS#8 form as it can handle all key types, and can store additional parameters
+ * such as the seed, in case of provable RSA or DSA keys.
+ * Generated keys can be exported in memory using gnutls_privkey_export_x509(),
+ * and then with gnutls_x509_privkey_export2_pkcs8().
  *
- * When generating RSA-PSS keys which should require specific parameters, you should
- * use @data of type %GNUTLS_KEYGEN_SPKI to specify the SubjectPublicKeyInfo parameters.
+ * If key generation is part of your application, avoid setting the number
+ * of bits directly, and instead use gnutls_sec_param_to_pk_bits().
+ * That way the generated keys will adapt to the security levels
+ * of the underlying GnuTLS library.
  *
- * Do not set the number of bits directly, use gnutls_sec_param_to_pk_bits().
+ * See also gnutls_privkey_generate2().
  *
  * 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 2b96716773..ab8a550275 100644
--- a/src/certtool-args.def
+++ b/src/certtool-args.def
@@ -232,7 +232,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 (i.e., Shawe-Taylor) for provable key generation.
+    doc = "This will use the FIPS PUB186-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
 later validated with --verify-provable-privkey to be correctly generated from the seed. You may
 specify --seed or allow GnuTLS to generate one (recommended). This option can be combined with