doc.go raw

   1  // Package exchange provides Elliptic Curve Diffie-Hellman (ECDH) key exchange
   2  // operations on the secp256k1 curve.
   3  //
   4  // This package is a domain-focused wrapper around the core p256k1 primitives,
   5  // providing a clean API for key exchange and shared secret derivation.
   6  //
   7  // # Bounded Context: Key Exchange
   8  //
   9  // This bounded context encompasses:
  10  //   - ECDH shared secret computation
  11  //   - X-only ECDH (BIP-340 compatible)
  12  //   - Key derivation from shared secrets (HKDF)
  13  //
  14  // # Domain Services
  15  //
  16  //   - SharedSecret: Compute ECDH shared secret
  17  //   - SharedSecretXOnly: Compute X-only shared secret
  18  //   - DeriveKey: Derive keys using HKDF
  19  //
  20  // # Usage
  21  //
  22  //	import "next.orly.dev/pkg/p256k1/exchange"
  23  //
  24  //	// Compute shared secret between Alice and Bob
  25  //	// Alice has alicePrivate, Bob has bobPublic
  26  //	shared, err := exchange.SharedSecret(bobPublic, alicePrivate)
  27  //	if err != nil {
  28  //	    // handle error
  29  //	}
  30  //
  31  //	// Derive an encryption key from the shared secret
  32  //	key := make([]byte, 32)
  33  //	err = exchange.DeriveKey(key, shared, nil, []byte("encryption"))
  34  //
  35  // # Thread Safety
  36  //
  37  // All functions in this package are safe for concurrent use.
  38  //
  39  // # Security Notes
  40  //
  41  //   - Shared secrets should be used with a KDF (like HKDF) for key derivation
  42  //   - Clear shared secret material when no longer needed
  43  //   - Use X-only mode for BIP-340 compatible protocols
  44  package exchange
  45