8 releases (5 breaking)
0.6.0  Jun 2, 2020 

0.5.0  Jun 2, 2020 
0.4.1  Jun 2, 2020 
0.3.0  Jun 2, 2020 
0.1.1  May 30, 2020 
#661 in Cryptography
1,896 downloads per month
Used in vrunoise
19KB
297 lines
X448
This is a pure Rust implementation of the Diffie hellman key exchange protocol, X448.
Example
In the following example, Alice has an Ephemeral(OneTime use) Secret key and Bob has a Static(Multiple use) Key.
Setup Phase
In this stage, both parties generate a secret and send the corresponding public key to the other party.
Alice
 Alice generates a new onetime use secret key using randomness.
 Alice sends her public key to Bob, so that Bob can compute the shared key.
let alice_secret = Secret::new(&mut OsRng);
let alice_public_key = PublicKey::from(&alice_secret);
Bob
 Bob loads a secret key from his storage.
 Bob sends her public key to Alice, so that Alice can compute the shared key.
let bob_secret = Secret::from_bytes(bytes_of_key);
let bob_public_key = PublicKey::from(&bob_secret);
Key Exchange Phase
Both parties now have enough information to compute the shared key. They now independently compute the shared key.
Alice
let alices_shared_secret = alice_secret.to_diffie_hellman(&bob_public_key);
Bob
let bobs_shared_secret = bob_secret.as_diffie_hellman(&alice_public_key);
That's it. Kinda.

If neither Alice or Bob used a low order point, then they will both have the same shared_key. If one party, did indeed manage to circumvent the API and the honest party tries to use this low order point in a Diffiehellman key exchange, the shared key will return None.

Notice that Alice used a method named
to_diffie_hellman
while Bob used a method namedas_diffie_hellman
. Usingto_diffie_hellman
will consume the Secret key, denoting that the key can only be used once in a DiffieHellman Key exchange. Of course, you could copy it before it was consumed, but then it would have been more efficient to useas_diffie_hellman
.
API Discussion
The API exposes 3 structures; a public key , a shared secret key and a secret key.
 The public key is an elliptic curve point. It corresponds to a Scalar that the user owns.
 The secret key is a Scalar. This Scalar corresponds to the user's public key and the generator specified in the RFC.
 The shared secret key is an elliptic curve point. It is the key that is computed by both parties in the diffiehellman key exchange algorithm.
Differences to X25519Dalek
In our API there is only one Secret Scalar Key. In X25519Dalek there are two types of secret scalar keys;
 An ephemeral secret key which can only be used once in a DiffieHellman key exchange.
 A static secret key which can be used multiple times in a diffie hellman key exchange.
Following the example above, this API achieves this example by using two methods on the same struct to_diffie_hellman
and as_diffie_hellman
. The rationale for choosing this API is that there will be less code duplication, as there is only one struct. Furthermore, this API also achieves the compile time guarantee that if the user wants to treat the Secret key as Ephemeral, then it will only be used once. One disadvantage of this API, is the lack of distinction between Secrets. For example, as a consumer of an API it would be advantageous to state that the type I want to accept is an EphemeralSecret
, this decreases the reading complexity as the type encodes the fact that it can only be used once in an diffiehellman key exchange.
Dependencies
~340KB