api.go raw
1 package p256k1
2
3 // =============================================================================
4 // PUBLIC API REFERENCE
5 // =============================================================================
6 //
7 // This file documents the intended public API surface of the p256k1 package.
8 // While Go exports all capitalized identifiers, users should prefer the types
9 // and functions documented here for stability guarantees.
10 //
11 // # Domain-Focused Packages (Recommended)
12 //
13 // For most use cases, prefer the domain-focused wrapper packages that provide
14 // cleaner, more focused APIs:
15 //
16 // - p256k1.mleku.dev/ecdsa - ECDSA signature operations
17 // - p256k1.mleku.dev/schnorr - BIP-340 Schnorr signatures
18 // - p256k1.mleku.dev/keys - Key generation and management
19 // - p256k1.mleku.dev/exchange - ECDH key exchange
20 //
21 // These packages re-export the core types and provide domain-specific functions
22 // with better ergonomics and documentation.
23 //
24 // For a high-level signer abstraction, see the signer.P256K1Signer type.
25 // =============================================================================
26
27 // =============================================================================
28 // KEY TYPES (Aggregate Root: KeyPair)
29 // =============================================================================
30
31 // PublicKey represents a secp256k1 public key.
32 // Use ECPubkeyCreate to generate from a private key, or ECPubkeyParse to load
33 // from serialized form.
34 //
35 // The internal representation stores the uncompressed point coordinates.
36 // Use ECPubkeySerialize to export in compressed (33 bytes) or uncompressed
37 // (65 bytes) format.
38
39 // XOnlyPubkey represents a BIP-340 x-only public key (32 bytes).
40 // X-only keys are used with Schnorr signatures and implicitly have even Y.
41 // Use XOnlyPubkeyParse to load, XOnlyPubkeySerialize to export.
42
43 // KeyPair represents a secp256k1 key pair (secret key + public key).
44 // This is the Aggregate Root for key management operations.
45 // Use KeyPairCreate to generate from a secret key.
46
47 // =============================================================================
48 // SIGNATURE TYPES (Value Objects)
49 // =============================================================================
50
51 // ECDSASignature represents an ECDSA signature with r and s components.
52 // Use ECDSASign to create, ECDSAVerify to verify.
53
54 // ECDSASignatureCompact is a 64-byte compact signature format (r || s).
55 // Use ToCompact/FromCompact methods on ECDSASignature.
56
57 // ECDSARecoverableSignature includes a recovery ID for public key recovery.
58 // Use ECDSASignRecoverable to create, ECDSARecover to recover public key.
59
60 // SchnorrSignature is a 64-byte BIP-340 Schnorr signature (r || s).
61 // Use SchnorrSign to create, SchnorrVerify to verify.
62
63 // =============================================================================
64 // KEY MANAGEMENT FUNCTIONS
65 // =============================================================================
66
67 // Key Generation and Parsing:
68 // - ECPubkeyCreate(pubkey *PublicKey, seckey []byte) error
69 // - ECPubkeyParse(pubkey *PublicKey, input []byte) error
70 // - ECPubkeySerialize(output []byte, pubkey *PublicKey, flags uint) int
71 // - ECSecKeyVerify(seckey []byte) error
72 //
73 // X-Only Keys (BIP-340):
74 // - XOnlyPubkeyParse(pubkey *XOnlyPubkey, input []byte) error
75 // - XOnlyPubkeySerialize(output []byte, pubkey *XOnlyPubkey) int
76 // - XOnlyPubkeyFromPubkey(xonly *XOnlyPubkey, pk *PublicKey) bool
77 //
78 // Key Pairs:
79 // - KeyPairCreate(keypair *KeyPair, seckey []byte) error
80 // - KeyPairXOnlyPub(xonly *XOnlyPubkey, keypair *KeyPair) error
81
82 // =============================================================================
83 // ECDSA SIGNATURE FUNCTIONS
84 // =============================================================================
85
86 // Signing:
87 // - ECDSASign(sig *ECDSASignature, msghash32 []byte, seckey []byte) error
88 // - ECDSASignCompact(compact *ECDSASignatureCompact, msghash32, seckey []byte) error
89 // - ECDSASignDER(msghash32, seckey []byte) ([]byte, error)
90 // - ECDSASignRecoverable(sig *ECDSARecoverableSignature, msghash32, seckey []byte) error
91 //
92 // Verification:
93 // - ECDSAVerify(sig *ECDSASignature, msghash32 []byte, pubkey *PublicKey) bool
94 // - ECDSAVerifyCompact(compact *ECDSASignatureCompact, msghash32 []byte, pubkey *PublicKey) bool
95 // - ECDSAVerifyDER(sigDER, msghash32 []byte, pubkey *PublicKey) bool
96 //
97 // Recovery:
98 // - ECDSARecover(pubkey *PublicKey, sig *ECDSARecoverableSignature, msghash32 []byte) error
99 // - ECDSARecoverCompact(pubkey *PublicKey, sig64 []byte, recid int, msghash32 []byte) error
100
101 // =============================================================================
102 // SCHNORR SIGNATURE FUNCTIONS (BIP-340)
103 // =============================================================================
104
105 // Signing:
106 // - SchnorrSign(sig64, msg32 []byte, keypair *KeyPair, auxRand32 []byte) error
107 //
108 // Verification:
109 // - SchnorrVerify(sig64, msg32 []byte, xonlyPubkey *XOnlyPubkey) bool
110 // - SchnorrVerifyBatch(items []SchnorrVerifyItem) bool
111
112 // =============================================================================
113 // ECDH KEY EXCHANGE FUNCTIONS
114 // =============================================================================
115
116 // Key Exchange:
117 // - ECDH(output []byte, pubkey *PublicKey, seckey []byte, hashfp ECDHHashFunction) error
118 // - ECDHXOnly(output []byte, pubkey *PublicKey, seckey []byte) error
119 // - ECDHWithHKDF(output []byte, pubkey *PublicKey, seckey []byte, salt, info []byte) error
120
121 // =============================================================================
122 // SCALAR MULTIPLICATION FUNCTIONS
123 // =============================================================================
124
125 // Generator Multiplication (computes scalar * G):
126 // - EcmultGen(r *GroupElementJacobian, q *Scalar)
127 //
128 // Point Multiplication (computes scalar * point):
129 // - Ecmult(r *GroupElementJacobian, a *GroupElementJacobian, q *Scalar)
130 // - EcmultConst(r *GroupElementJacobian, a *GroupElementAffine, q *Scalar)
131 //
132 // Combined Multiplication (computes na*a + ng*G):
133 // - EcmultCombined(r *GroupElementJacobian, a *GroupElementJacobian, na, ng *Scalar)
134
135 // =============================================================================
136 // HASHING FUNCTIONS
137 // =============================================================================
138
139 // SHA-256:
140 // - NewSHA256() *SHA256
141 // - (h *SHA256) Write(data []byte)
142 // - (h *SHA256) Finalize(out32 []byte)
143 //
144 // HMAC-SHA256:
145 // - NewHMACSHA256(key []byte) *HMACSHA256
146 // - (h *HMACSHA256) Write(data []byte)
147 // - (h *HMACSHA256) Finalize(out32 []byte)
148 //
149 // Tagged Hash (BIP-340):
150 // - TaggedHash(tag, data []byte) [32]byte
151 //
152 // Key Derivation:
153 // - HKDF(output, ikm, salt, info []byte) error
154
155 // =============================================================================
156 // CONSTANTS
157 // =============================================================================
158
159 // Compression flags for ECPubkeySerialize:
160 // - ECCompressed = 0x02 (33-byte output)
161 // - ECUncompressed = 0x04 (65-byte output)
162
163 // =============================================================================
164 // INTERNAL TYPES (Use with caution - not part of stable API)
165 // =============================================================================
166
167 // The following types are exported but considered internal implementation details:
168 //
169 // Primitives:
170 // - FieldElement, FieldElementStorage
171 // - Scalar, ScalarZero, ScalarOne
172 // - GroupElementAffine, GroupElementJacobian, GroupElementStorage
173 //
174 // These are exposed for advanced users who need low-level access to the
175 // cryptographic primitives, but their API may change between versions.
176