doc.go raw

   1  // Package p256k1 provides a pure Go implementation of the secp256k1 elliptic curve
   2  // cryptographic operations, including ECDSA signatures, Schnorr signatures (BIP-340),
   3  // and Elliptic Curve Diffie-Hellman (ECDH) key exchange.
   4  //
   5  // # Architecture Overview
   6  //
   7  // This package is organized into several conceptual layers, following Domain-Driven Design
   8  // principles where cryptographic primitives form the core domain:
   9  //
  10  // ## Layer 1: Field Arithmetic (Bounded Context: Finite Field)
  11  //
  12  // Operations in the finite field F_p where p = 2^256 - 2^32 - 977 (the secp256k1 field prime).
  13  //
  14  // Types:
  15  //   - FieldElement: A field element in 5x52-bit limb representation
  16  //   - FieldElementStorage: Compact 4x64-bit storage format
  17  //
  18  // Files: field.go, field_mul.go, field_4x64.go, field_32bit.go, field_amd64.go
  19  //
  20  // ## Layer 2: Scalar Arithmetic (Bounded Context: Group Order)
  21  //
  22  // Operations modulo the group order n = 0xFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFEBAAEDCE6AF48A03BBFD25E8CD0364141.
  23  //
  24  // Types:
  25  //   - Scalar: A 256-bit scalar in 4x64-bit representation
  26  //
  27  // Files: scalar.go, scalar_32bit.go, scalar_amd64.go
  28  //
  29  // ## Layer 3: Group Operations (Bounded Context: Elliptic Curve Points)
  30  //
  31  // Point operations on the secp256k1 curve: y^2 = x^3 + 7.
  32  //
  33  // Types:
  34  //   - GroupElementAffine: Point in affine coordinates (x, y)
  35  //   - GroupElementJacobian: Point in Jacobian coordinates (X, Y, Z) where x = X/Z^2, y = Y/Z^3
  36  //   - GroupElementStorage: Compact storage format
  37  //
  38  // Files: group.go, group_4x64.go
  39  //
  40  // ## Layer 4: Cryptographic Hashing (Supporting Domain)
  41  //
  42  // Hash functions used by signature schemes and key derivation.
  43  //
  44  // Types:
  45  //   - SHA256: SHA-256 hash context
  46  //   - HMACSHA256: HMAC-SHA256 context
  47  //   - RFC6979HMACSHA256: Deterministic nonce generation
  48  //
  49  // Files: hash.go
  50  //
  51  // ## Layer 5: Signature Schemes (Core Domain Services)
  52  //
  53  // ECDSA and Schnorr signature creation and verification.
  54  //
  55  // Types:
  56  //   - ECDSASignature: ECDSA signature (r, s)
  57  //   - ECDSARecoverableSignature: ECDSA with recovery ID
  58  //   - SchnorrSignature: BIP-340 Schnorr signature
  59  //
  60  // Files: ecdsa.go, schnorr.go, schnorr_batch.go, verify.go
  61  //
  62  // ## Layer 6: Key Management (Aggregate Root)
  63  //
  64  // Public keys, key pairs, and key operations.
  65  //
  66  // Types:
  67  //   - PublicKey: Secp256k1 public key
  68  //   - XOnlyPubkey: X-only public key (BIP-340)
  69  //   - KeyPair: Secret/public key pair (Aggregate Root)
  70  //
  71  // Files: pubkey.go, eckey.go, extrakeys.go
  72  //
  73  // ## Layer 7: Key Exchange (Domain Service)
  74  //
  75  // Elliptic Curve Diffie-Hellman key exchange.
  76  //
  77  // Functions: ECDH, ECDHXOnly, ECDHWithHKDF
  78  //
  79  // Files: ecdh.go, ecdh_amd64.go
  80  //
  81  // # Performance Optimizations
  82  //
  83  // This implementation includes several performance optimizations:
  84  //
  85  //   - GLV Endomorphism: Splits 256-bit scalar multiplication into two ~128-bit operations
  86  //   - Strauss Algorithm: Combines multiple scalar multiplications to share doublings
  87  //   - wNAF Representation: Windowed Non-Adjacent Form reduces point additions
  88  //   - Precomputed Tables: Generator point multiples precomputed at init time
  89  //   - Platform-Specific Assembly: AMD64 assembly for field/scalar operations
  90  //   - Batch Operations: Batch normalization and batch Schnorr verification
  91  //   - Zero-Allocation Hot Paths: Critical paths avoid heap allocations
  92  //
  93  // # Platform Support
  94  //
  95  // The package supports multiple platforms through build tags:
  96  //
  97  //   - AMD64: Optimized assembly with AVX2/BMI2 support
  98  //   - 32-bit: Pure Go implementation for 32-bit systems
  99  //   - WASM: WebAssembly-compatible implementation
 100  //   - Generic: Fallback implementation for other platforms
 101  //
 102  // # Thread Safety
 103  //
 104  // All public functions are safe for concurrent use. Internal hash contexts use
 105  // sync.Pool for efficient reuse across goroutines.
 106  //
 107  // # Security Considerations
 108  //
 109  //   - Constant-time operations where required (e.g., scalar multiplication with secrets)
 110  //   - Secure memory clearing for sensitive data
 111  //   - RFC 6979 deterministic nonce generation for ECDSA
 112  //   - BIP-340 compliant Schnorr signatures
 113  //
 114  // # Usage Examples
 115  //
 116  // See the examples/ directory for complete usage examples, or use the higher-level
 117  // signer.P256K1Signer type for a simplified interface.
 118  //
 119  // # Related Packages
 120  //
 121  // Domain-focused wrapper packages (recommended for most use cases):
 122  //
 123  //   - ecdsa: ECDSA signature operations with clean API
 124  //   - schnorr: BIP-340 Schnorr signatures with batch verification
 125  //   - keys: Key generation, parsing, serialization, and tweaking
 126  //   - exchange: ECDH key exchange and key derivation (HKDF)
 127  //
 128  // Internal/advanced packages:
 129  //
 130  //   - signer: High-level signer abstraction with simplified API
 131  //   - wnaf: Windowed Non-Adjacent Form encoding utilities
 132  //   - avx: Experimental AVX2-accelerated operations
 133  package p256k1
 134