diff --git a/include/psa/crypto.h b/include/psa/crypto.h index 08bdb8468..2b95f238f 100644 --- a/include/psa/crypto.h +++ b/include/psa/crypto.h @@ -641,10 +641,6 @@ psa_status_t psa_destroy_key(psa_key_handle_t handle); * coefficient INTEGER, -- (inverse of q) mod p * } * ``` - * - For DSA private keys (#PSA_KEY_TYPE_DSA_KEYPAIR), the format is the - * representation of the private key `x` as a big-endian byte string. The - * length of the byte string is the private key size in bytes (leading zeroes - * are not stripped). * - For elliptic curve key pairs (key types for which * #PSA_KEY_TYPE_IS_ECC_KEYPAIR is true), the format is * a representation of the private value as a `ceiling(m/8)`-byte string @@ -726,10 +722,6 @@ psa_status_t psa_export_key(psa_key_handle_t handle, * - The byte 0x04; * - `x_P` as a `ceiling(m/8)`-byte string, big-endian; * - `y_P` as a `ceiling(m/8)`-byte string, big-endian. - * - For DSA public keys (#PSA_KEY_TYPE_DSA_PUBLIC_KEY), the format is the - * representation of the public key `y = g^x mod p` as a big-endian byte - * string. The length of the byte string is the length of the base prime `p` - * in bytes. * - For Diffie-Hellman key exchange public keys (key types for which * #PSA_KEY_TYPE_IS_DH_PUBLIC_KEY is true), * the format is the representation of the public key `y = g^x mod p` as a @@ -3256,8 +3248,7 @@ psa_status_t psa_key_derivation_output_bytes( * and continue reading output from the operation to derive the other * two keys). * - Finite-field Diffie-Hellman keys (#PSA_KEY_TYPE_DH_KEYPAIR(\c group) - * where \c group designates any Diffie-Hellman group), - * DSA keys (#PSA_KEY_TYPE_DSA_KEYPAIR), and + * where \c group designates any Diffie-Hellman group) and * ECC keys on a Weierstrass elliptic curve * (#PSA_KEY_TYPE_ECC_KEYPAIR(\c curve) where \c curve designates a * Weierstrass curve). diff --git a/include/psa/crypto_extra.h b/include/psa/crypto_extra.h index 5a066146b..732149dcd 100644 --- a/include/psa/crypto_extra.h +++ b/include/psa/crypto_extra.h @@ -449,10 +449,33 @@ psa_status_t psa_generate_random_key_to_handle(psa_key_handle_t handle, * @{ */ -/** DSA public key. */ +/** DSA public key. + * + * The import and export format is the + * representation of the public key `y = g^x mod p` as a big-endian byte + * string. The length of the byte string is the length of the base prime `p` + * in bytes. + */ #define PSA_KEY_TYPE_DSA_PUBLIC_KEY ((psa_key_type_t)0x60020000) -/** DSA key pair (private and public key). */ + +/** DSA key pair (private and public key). + * + * The import and export format is the + * representation of the private key `x` as a big-endian byte string. The + * length of the byte string is the private key size in bytes (leading zeroes + * are not stripped). + * + * Determinstic DSA key derivation with psa_generate_derived_key follows + * FIPS 186-4 §B.1.2: interpret the byte string as integer + * in big-endian order. Discard it if it is not in the range + * [0, *N* - 2] where *N* is the boundary of the private key domain + * (the prime *p* for Diffie-Hellman, the subprime *q* for DSA, + * or the order of the curve's base point for ECC). + * Add 1 to the resulting integer and use this as the private key *x*. + * + */ #define PSA_KEY_TYPE_DSA_KEYPAIR ((psa_key_type_t)0x70020000) + /** Whether a key type is an DSA key (pair or public-only). */ #define PSA_KEY_TYPE_IS_DSA(type) \ (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEYPAIR(type) == PSA_KEY_TYPE_DSA_PUBLIC_KEY) diff --git a/include/psa/crypto_values.h b/include/psa/crypto_values.h index 823d04450..bab706339 100644 --- a/include/psa/crypto_values.h +++ b/include/psa/crypto_values.h @@ -690,7 +690,6 @@ * * That is, suppose that `PSA_xxx_SIGNATURE` is one of the following macros: * - #PSA_ALG_RSA_PKCS1V15_SIGN, #PSA_ALG_RSA_PSS, - * - #PSA_ALG_DSA, #PSA_ALG_DETERMINISTIC_DSA, * - #PSA_ALG_ECDSA, #PSA_ALG_DETERMINISTIC_ECDSA. * Then you may create and use a key as follows: * - Set the key usage field using #PSA_ALG_ANY_HASH, for example: