From 7b1fbfefe466a8761190805ded6c2fd1d2466662 Mon Sep 17 00:00:00 2001 From: Nikos Mavrogiannopoulos Date: Sat, 7 Oct 2017 10:06:09 +0200 Subject: doc: improve documentation on provable private keys Resolves #301 Signed-off-by: Nikos Mavrogiannopoulos --- doc/cha-crypto.texi | 9 +++++++++ lib/includes/gnutls/x509.h | 2 +- lib/privkey.c | 33 +++++++++++++++++++++++++++------ lib/x509/privkey.c | 37 +++++++++++++++++++++++++++---------- src/certtool-args.def | 2 +- 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 -- cgit v1.2.1