pub struct SecretKey { /* private fields */ }Expand description
X25519 Diffie-Hellman key exchange private key (RFC 7748).
§Generating a key
use crypto::curve25519::x25519::SecretKey;
let alice = SecretKey::generate().unwrap();
let bob = SecretKey::generate().unwrap();§Diffie-Hellman key exchange
use crypto::curve25519::x25519::SecretKey;
let alice = SecretKey::generate().unwrap();
let bob = SecretKey::generate().unwrap();
let alice_shared = alice.ecdh(&bob.public_key()).unwrap();
let bob_shared = bob.ecdh(&alice.public_key()).unwrap();
assert_eq!(alice_shared, bob_shared);ecdh returns EllipticCurveError::InvalidSharedSecret
when the computed shared secret is all zeros. This happens whenever the
peer public key is a low-order point (u = 0, u = 1, u = p - 1, or
one of the two order-8 points), because the clamped scalar is a multiple
of the curve’s cofactor and therefore annihilates such a point.
Security impact: an all-zero shared secret is not secret at all. Every peer that sends a low-order public key — including a malicious one — knows the value, so any key derived from it (even through a KDF) is known to the attacker. This yields a complete confidentiality and authentication break for protocols that do not independently detect the degenerate output. Callers should therefore treat the error as a fatal protocol failure and abort the handshake.
If the caller’s protocol already binds both public keys into the derived key (so that a non-contributory secret cannot be exploited), the error can be deliberately ignored by substituting the all-zero secret:
let shared = alice.ecdh(&bob.public_key()).unwrap_or_default();§Conversion from Ed25519
An Ed25519 SecretKey can be
converted to an X25519 key via From<&ed25519::SecretKey>.
§Security
The shared secret produced by ecdh must not be used
directly as an encryption key. Apply a KDF (e.g. HKDF) first.
Implementations§
Source§impl SecretKey
impl SecretKey
Sourcepub fn generate() -> Result<SecretKey, EllipticCurveError>
pub fn generate() -> Result<SecretKey, EllipticCurveError>
Generates a fresh random secret key.
Returns EllipticCurveError::Random when the operating system’s
random number generator is unavailable or fails.
pub fn from_bytes(bytes: &[u8; 32]) -> SecretKey
pub fn to_bytes(&self) -> [u8; 32]
pub fn public_key(&self) -> PublicKey
Sourcepub fn ecdh(&self, peer: &PublicKey) -> Result<[u8; 32], EllipticCurveError>
pub fn ecdh(&self, peer: &PublicKey) -> Result<[u8; 32], EllipticCurveError>
Perform a Diffie-Hellman key exchange to derive a shared secret. The shared secret IS NOT SAFE to use directly as an encryption key and an additional key derivation operation must be applied to it.
§Errors
Returns EllipticCurveError::InvalidSharedSecret if the computed
shared secret is all zeros, which occurs when peer is a low-order
public key. Such a secret is publicly known and must not be used to
derive keys unless the protocol independently binds the peer public
key into the derivation. See the type-level documentation
for details.