doc.go raw

   1  // Package keys provides secp256k1 key management operations.
   2  //
   3  // This package is a domain-focused wrapper around the core p256k1 primitives,
   4  // providing a clean API for key generation, parsing, and serialization.
   5  //
   6  // # Bounded Context: Key Management
   7  //
   8  // This bounded context encompasses:
   9  //   - Key pair generation (secret + public key)
  10  //   - Public key creation from private key
  11  //   - Key parsing and serialization
  12  //   - Key validation
  13  //   - Key tweaking (for advanced protocols)
  14  //
  15  // # Aggregate Root: KeyPair
  16  //
  17  // The KeyPair type is the aggregate root for key management. It encapsulates
  18  // the relationship between a secret key and its corresponding public key,
  19  // ensuring consistency and providing a unified interface for key operations.
  20  //
  21  // # Value Objects
  22  //
  23  //   - PublicKey: A secp256k1 public key (can be compressed or uncompressed)
  24  //   - XOnlyPubkey: A 32-byte x-only public key (BIP-340 style)
  25  //   - SecretKey: A 32-byte private key (represented as []byte)
  26  //
  27  // # Domain Services
  28  //
  29  //   - Generate: Generate a new random key pair
  30  //   - Create: Create a key pair from an existing private key
  31  //   - ParsePublicKey: Parse a serialized public key
  32  //   - SerializePublicKey: Serialize a public key
  33  //
  34  // # Usage
  35  //
  36  //	import "next.orly.dev/pkg/p256k1/keys"
  37  //
  38  //	// Generate a new key pair
  39  //	keypair, err := keys.Generate()
  40  //	if err != nil {
  41  //	    // handle error
  42  //	}
  43  //
  44  //	// Get the public key in compressed format
  45  //	pubkeyBytes := keys.SerializePublic(keypair.PublicKey(), keys.Compressed)
  46  //
  47  //	// Parse a public key
  48  //	pubkey, err := keys.ParsePublic(pubkeyBytes)
  49  //	if err != nil {
  50  //	    // handle error
  51  //	}
  52  //
  53  // # Thread Safety
  54  //
  55  // All functions in this package are safe for concurrent use.
  56  //
  57  // # Security Notes
  58  //
  59  //   - Private keys should be generated with a cryptographically secure random source
  60  //   - Clear private key material when no longer needed using KeyPair.Clear()
  61  //   - Never log or expose private key bytes
  62  package keys
  63