Unclear documentation of crypto Edwards25519 key generation

[ostcar]

From zig 0.13 to zig 0.14, the API to generate Edwards25519 key pairs changed. The new documentation is unclear, how to save and restore a private Edwards25519 key.

For the function std.crypto.sign.Ed25519.KeyPair it says, that the keypair should be restored by using the seed:

zig/lib/std/crypto/25519/ed25519.zig

Lines 288 to 294 in bd237bc

	/// Create a key pair from an existing secret key.
	///
	/// Note that with EdDSA, storing the seed, and recovering the key pair
	/// from it is recommended over storing the entire secret key.
	/// The seed of an exiting key pair can be obtained with
	/// `key_pair.secret_key.seed()`.
	pub fn fromSecretKey(secret_key: SecretKey) (NonCanonicalError || EncodingError || IdentityElementError)!KeyPair {

There are two ways, how to create a private key from a seed. Either with KeyPair.generateDeterministic() or with SecretKey.fromBytes() followed by KeyPair.fromSecretKey(). It does not say, which way is the preferred way. I guess it is KeyPair.generateDeterministic() because SecretKey.fromBytes() returns an error type.

But the documentation for KeyPair.generateDeterministic() says, that it should only be used in tests:

zig/lib/std/crypto/25519/ed25519.zig

Lines 248 to 258 in bd237bc

	/// Deterministically derive a key pair from a cryptograpically secure secret seed.
	///
	/// Except in tests, applications should generally call `generate()` instead of this function.
	///
	/// As in RFC 8032, an Ed25519 public key is generated by hashing
	/// the secret key using the SHA-512 function, and interpreting the
	/// bit-swapped, clamped lower-half of the output as the secret scalar.
	///
	/// For this reason, an EdDSA secret key is commonly called a seed,
	/// from which the actual secret is derived.
	pub fn generateDeterministic(seed: [seed_length]u8) IdentityElementError!KeyPair {

I think, that the documentation for KeyPair.generateDeterministic() is wrong. This function should not only be used in tests, but also, if a key is recovered from a seed. If this is true, then the documentation should be changed, since it gives the impression, that using the function to recover a key from its seed in production (not in a test) is unsafe.

[alexrp]

cc @jedisct1