diff options
Diffstat (limited to 'lib')
| -rw-r--r-- | lib/includes/gnutls/x509.h | 2 | ||||
| -rw-r--r-- | lib/privkey.c | 33 | ||||
| -rw-r--r-- | lib/x509/privkey.c | 37 |
3 files changed, 55 insertions, 17 deletions
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. |