CRYPTO_KEY_EXCHANGE(3MONOCYPHER)

✨ CRYPTO_KEY_EXCHANGE ✨

okay so bestie, we're in monocypher, section 3, and it's LOCAL — and today's topic is Elliptic Curve Diffie-Hellman key exchange. like, the actual "two people who've never met agree on a secret" magic trick. it's giving ✨main character energy✨ fr fr 🦋

two functions in the squad:

• crypto_key_exchange
• crypto_key_exchange_public_key

let's go 💅

---

🌸 SYNOPSIS 🌸

#include <monocypher.h>

void
crypto_key_exchange(uint8_t shared_key[32],
    const uint8_t your_secret_key[32],
    const uint8_t their_public_key[32]);

void
crypto_key_exchange_public_key(uint8_t your_public_key[32],
    const uint8_t your_secret_key[32]);

---

💖 DESCRIPTION 💖

crypto_key_exchange() computes a shared key with your secret key and their public key. that's it, that's the whole vibe. two of you, one shared secret, nobody eavesdropping. periodt.

crypto_key_exchange_public_key() deterministically computes the public key from a random secret key. same secret key in → same public key out, every single time. no randomness, no surprises, just math being math 🔥

🎀 the arguments 🎀

• shared_key — the shared secret, known only to those who know a relevant secret key (yours or theirs). it's cryptographically random, and it's suitable for use with the crypto_lock(3monocypher) family of functions. so like, this is your group-chat DM key, bestie 🤫
• your_secret_key — a 32-byte random number, known only to you. see intro(3monocypher) for advice about generating random bytes (use the operating system's random number generator — yes, <em>the OS one</em>, not your cousin's homemade RNG, pls 😭).
• their_public_key — the public key of the other party. the person you're exchanging with. your pen pal. your situationship. whoever 💜
• your_public_key — your public key, generated from your_secret_key with crypto_key_exchange_public_key(). your little badge you hand out to everyone.

shared_key and your_secret_key may overlap if the secret is no longer required. cute, lowkey efficient, slay.

---

some poorly designed protocols require you to test for "contributory" behaviour, which ensures that no untrusted party forces the shared secret to a known constant. the move here is to not do that — protocols should instead be designed in such a way that no such check is necessary, namely by authenticating the other party or exchanging keys over a trusted channel. fix the protocol, not the symptom, bestie 🫶

---

🚨 DO NOT use the same secret key for both key exchanges and signatures. the public keys are <em>different</em>, and revealing both may leak information. like, that's a whole mess. if there really is no room to store or derive two different secret keys, consider generating a key pair for signatures and then converting it with crypto_from_eddsa_private(3monocypher) and crypto_from_eddsa_public(3monocypher). problem solved, iconic 💅

---

⭐ RETURN VALUES ⭐

crypto_key_exchange() and crypto_key_exchange_public_key() return nothing. they just do the thing and dip. no return value, no drama, no notes 👑

---

🌈 EXAMPLES 🌈

the following examples assume the existence of arc4random_buf(), which fills the given buffer with cryptographically secure random bytes. if arc4random_buf() does not exist on your system, see intro(3monocypher) for advice about how to generate cryptographically secure random bytes. (ngl, read that one, it matters 🙈)

🦋 generate a public key from a randomly generated secret key

uint8_t sk[32]; /* Random secret key */
uint8_t pk[32]; /* Public key        */
arc4random_buf(sk, 32);
crypto_key_exchange_public_key(pk, sk);
/* Wipe secrets if they are no longer needed */
crypto_wipe(sk, 32);

🍓 generate a shared, symmetric key with your secret key and their public key

(the other party will generate the same shared key with your public key and their secret key. yes, <em>the same one</em>. that's the whole point and it's honestly so iconic 🌸)

const uint8_t their_pk  [32]; /* Their public key   */
uint8_t       your_sk   [32]; /* Your secret key    */
uint8_t       shared_key[32]; /* Shared session key */
crypto_key_exchange(shared_key, your_sk, their_pk);
/* Wipe secrets if they are no longer needed */
crypto_wipe(your_sk, 32);

---

👑 SEE ALSO 👑

• crypto_lock(3monocypher)
• intro(3monocypher)

---

💜 STANDARDS 💜

these functions implement X25519, described in RFC 7748. and crypto_key_exchange() uses HChacha20 as well. certified, standardized, no cap ✨

---

🎀 HISTORY 🎀

• the crypto_key_exchange() function first appeared in Monocypher 0.2.
• the crypto_key_exchange_public_key() macro alias first appeared in Monocypher 1.1.0.

a glow-up timeline fr fr 💅

---

🚨 SECURITY CONSIDERATIONS 🚨

if either of the long term secret keys leaks, it may compromise all past messages. like, all of them. retroactively. the receipts 😭

this can be avoided by using protocols that provide forward secrecy, such as the X3DH key agreement protocol. use those. protect your past self. she deserves it 🫶

---

🔥 IMPLEMENTATION DETAILS 🔥

crypto_key_exchange_public_key() is an alias to crypto_x25519_public_key(3monocypher). that's the tea ☕

---

and that's the page, bestie!! this one shipped with Debian, dated March 31, 2020 — go forth and exchange some keys responsibly, mwah 💖✨🎀