Clarify deterministic generation by re-drawing
For DH, ECC (Weierstrass curves) and DSA, specify that the re-drawing
method is the one defined by NIST as
"key-pair generation by testing candidates", and describe it
unambiguously.
Also specify DES explicitly.
diff --git a/include/psa/crypto.h b/include/psa/crypto.h
index b683766..fbfdbc4 100644
--- a/include/psa/crypto.h
+++ b/include/psa/crypto.h
@@ -2924,12 +2924,31 @@
* for the output produced by psa_export_key().
* The following key types defined in this specification follow this scheme:
*
- * - #PSA_KEY_TYPE_DES;
- * - #PSA_KEY_TYPE_DH_KEYPAIR;
- * - #PSA_KEY_TYPE_DSA_KEYPAIR;
- * - ECC keys on a Weierstrass elliptic curve, i.e.
- * #PSA_KEY_TYPE_ECC_KEYPAIR(\c curve) where \c curve designates a
- * Weierstrass curve.
+ * - #PSA_KEY_TYPE_DES.
+ * Force-set the parity bits, but discard forbidden weak keys.
+ * For 2-key and 3-key triple-DES, the three keys are generated
+ * successively (for example, for 3-key triple-DES,
+ * if the first 8 bytes specify a weak key and the next 8 bytes do not,
+ * discard the first 8 bytes, use the next 8 bytes as the first key,
+ * and continue reading output from the generator to derive the other
+ * two keys).
+ * - Finite-field Diffie-Hellman keys (#PSA_KEY_TYPE_DH_KEYPAIR),
+ * DSA keys (#PSA_KEY_TYPE_DSA_KEYPAIR), and
+ * ECC keys on a Weierstrass elliptic curve
+ * (#PSA_KEY_TYPE_ECC_KEYPAIR(\c curve) where \c curve designates a
+ * Weierstrass curve).
+ * For these key types, 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 coordinate field for ECC).
+ * Add 1 to the resulting integer and use this as the private key *x*.
+ * This is the method described as
+ * "key-pair generation by testing candidates"
+ * in NIST SP 800-56A §5.6.1.1.4 for Diffie-Hellman,
+ * in FIPS 186-4 §B.1.2 for DSA, and
+ * in NIST SP 800-56A §5.6.1.2.2 or
+ * FIPS 186-4 §B.4.2 for elliptic curve keys.
*
* - For other key types, including #PSA_KEY_TYPE_RSA_KEYPAIR,
* the way in which the generator output is consumed is