mleku
e0a95ca1cd
- Replaced all instances of p256k1signer with the new p8k.Signer across various modules, including event creation, policy handling, and database interactions. - Updated related test cases and benchmarks to ensure compatibility with the new signer interface. - Bumped version to v0.25.0 to reflect these significant changes and improvements in cryptographic operations.
13 KiB
API Documentation - p8k.mleku.dev
Complete API reference for the libsecp256k1 Go bindings.
Table of Contents
- Context Management
- Public Key Operations
- ECDSA Signatures
- Schnorr Signatures
- ECDH
- Recovery
- Utility Functions
- Constants
- Types
Context Management
NewContext
Creates a new secp256k1 context.
func NewContext(flags uint32) (c *Context, err error)
Parameters:
flags: Context flags (ContextSign, ContextVerify, or combined with|)
Returns:
c: Context pointererr: Error if context creation failed
Example:
ctx, err := secp.NewContext(secp.ContextSign | secp.ContextVerify)
if err != nil {
log.Fatal(err)
}
defer ctx.Destroy()
Context.Destroy
Destroys the context and frees resources.
func (c *Context) Destroy()
Note: Contexts are automatically destroyed via finalizer, but explicit cleanup is recommended.
Context.Randomize
Randomizes the context with entropy for additional security.
func (c *Context) Randomize(seed32 []byte) (err error)
Parameters:
seed32: 32 bytes of random data
Returns:
err: Error if randomization failed
Public Key Operations
Context.CreatePublicKey
Creates a public key from a private key.
func (c *Context) CreatePublicKey(seckey []byte) (pubkey []byte, err error)
Parameters:
seckey: 32-byte private key
Returns:
pubkey: 64-byte internal public key representationerr: Error if key creation failed
Context.SerializePublicKey
Serializes a public key to compressed or uncompressed format.
func (c *Context) SerializePublicKey(pubkey []byte, compressed bool) (output []byte, err error)
Parameters:
pubkey: 64-byte internal public keycompressed: true for compressed (33 bytes), false for uncompressed (65 bytes)
Returns:
output: Serialized public keyerr: Error if serialization failed
Context.ParsePublicKey
Parses a serialized public key.
func (c *Context) ParsePublicKey(input []byte) (pubkey []byte, err error)
Parameters:
input: Serialized public key (33 or 65 bytes)
Returns:
pubkey: 64-byte internal public key representationerr: Error if parsing failed
ECDSA Signatures
Context.Sign
Creates an ECDSA signature.
func (c *Context) Sign(msg32 []byte, seckey []byte) (sig []byte, err error)
Parameters:
msg32: 32-byte message hashseckey: 32-byte private key
Returns:
sig: 64-byte internal signature representationerr: Error if signing failed
Context.Verify
Verifies an ECDSA signature.
func (c *Context) Verify(msg32 []byte, sig []byte, pubkey []byte) (valid bool, err error)
Parameters:
msg32: 32-byte message hashsig: 64-byte internal signaturepubkey: 64-byte internal public key
Returns:
valid: true if signature is validerr: Error if verification failed
Context.SerializeSignatureDER
Serializes a signature to DER format.
func (c *Context) SerializeSignatureDER(sig []byte) (output []byte, err error)
Parameters:
sig: 64-byte internal signature
Returns:
output: DER-encoded signature (variable length, max 72 bytes)err: Error if serialization failed
Context.ParseSignatureDER
Parses a DER-encoded signature.
func (c *Context) ParseSignatureDER(input []byte) (sig []byte, err error)
Parameters:
input: DER-encoded signature
Returns:
sig: 64-byte internal signature representationerr: Error if parsing failed
Context.SerializeSignatureCompact
Serializes a signature to compact format (64 bytes).
func (c *Context) SerializeSignatureCompact(sig []byte) (output []byte, err error)
Parameters:
sig: 64-byte internal signature
Returns:
output: 64-byte compact signatureerr: Error if serialization failed
Context.ParseSignatureCompact
Parses a compact (64-byte) signature.
func (c *Context) ParseSignatureCompact(input64 []byte) (sig []byte, err error)
Parameters:
input64: 64-byte compact signature
Returns:
sig: 64-byte internal signature representationerr: Error if parsing failed
Context.NormalizeSignature
Normalizes a signature to lower-S form.
func (c *Context) NormalizeSignature(sig []byte) (normalized []byte, wasNormalized bool, err error)
Parameters:
sig: 64-byte internal signature
Returns:
normalized: Normalized signaturewasNormalized: true if signature was modifiederr: Error if normalization failed
Schnorr Signatures
Context.CreateKeypair
Creates a keypair for Schnorr signatures.
func (c *Context) CreateKeypair(seckey []byte) (keypair Keypair, err error)
Parameters:
seckey: 32-byte private key
Returns:
keypair: 96-byte keypair structureerr: Error if creation failed
Context.KeypairXOnlyPub
Extracts the x-only public key from a keypair.
func (c *Context) KeypairXOnlyPub(keypair Keypair) (xonly XOnlyPublicKey, pkParity int32, err error)
Parameters:
keypair: 96-byte keypair
Returns:
xonly: 32-byte x-only public keypkParity: Public key parity (0 or 1)err: Error if extraction failed
Context.SchnorrSign
Creates a Schnorr signature (BIP-340).
func (c *Context) SchnorrSign(msg32 []byte, keypair Keypair, auxRand32 []byte) (sig []byte, err error)
Parameters:
msg32: 32-byte message hashkeypair: 96-byte keypairauxRand32: 32 bytes of auxiliary random data (can be nil)
Returns:
sig: 64-byte Schnorr signatureerr: Error if signing failed
Context.SchnorrVerify
Verifies a Schnorr signature (BIP-340).
func (c *Context) SchnorrVerify(sig64 []byte, msg []byte, xonlyPubkey []byte) (valid bool, err error)
Parameters:
sig64: 64-byte Schnorr signaturemsg: Message (any length)xonlyPubkey: 32-byte x-only public key
Returns:
valid: true if signature is validerr: Error if verification failed
Context.ParseXOnlyPublicKey
Parses a 32-byte x-only public key.
func (c *Context) ParseXOnlyPublicKey(input32 []byte) (xonly []byte, err error)
Parameters:
input32: 32-byte x-only public key
Returns:
xonly: 64-byte internal representationerr: Error if parsing failed
Context.SerializeXOnlyPublicKey
Serializes an x-only public key to 32 bytes.
func (c *Context) SerializeXOnlyPublicKey(xonly []byte) (output32 []byte, err error)
Parameters:
xonly: 64-byte internal x-only public key
Returns:
output32: 32-byte serialized x-only public keyerr: Error if serialization failed
Context.XOnlyPublicKeyFromPublicKey
Converts a regular public key to an x-only public key.
func (c *Context) XOnlyPublicKeyFromPublicKey(pubkey []byte) (xonly []byte, pkParity int32, err error)
Parameters:
pubkey: 64-byte internal public key
Returns:
xonly: 64-byte internal x-only public keypkParity: Public key parityerr: Error if conversion failed
ECDH
Context.ECDH
Computes an EC Diffie-Hellman shared secret.
func (c *Context) ECDH(pubkey []byte, seckey []byte) (output []byte, err error)
Parameters:
pubkey: 64-byte internal public keyseckey: 32-byte private key
Returns:
output: 32-byte shared secreterr: Error if computation failed
Recovery
Context.SignRecoverable
Creates a recoverable ECDSA signature.
func (c *Context) SignRecoverable(msg32 []byte, seckey []byte) (sig []byte, err error)
Parameters:
msg32: 32-byte message hashseckey: 32-byte private key
Returns:
sig: 65-byte recoverable signatureerr: Error if signing failed
Context.SerializeRecoverableSignatureCompact
Serializes a recoverable signature.
func (c *Context) SerializeRecoverableSignatureCompact(sig []byte) (output64 []byte, recid int32, err error)
Parameters:
sig: 65-byte recoverable signature
Returns:
output64: 64-byte compact signaturerecid: Recovery ID (0-3)err: Error if serialization failed
Context.ParseRecoverableSignatureCompact
Parses a compact recoverable signature.
func (c *Context) ParseRecoverableSignatureCompact(input64 []byte, recid int32) (sig []byte, err error)
Parameters:
input64: 64-byte compact signaturerecid: Recovery ID (0-3)
Returns:
sig: 65-byte recoverable signatureerr: Error if parsing failed
Context.Recover
Recovers a public key from a recoverable signature.
func (c *Context) Recover(sig []byte, msg32 []byte) (pubkey []byte, err error)
Parameters:
sig: 65-byte recoverable signaturemsg32: 32-byte message hash
Returns:
pubkey: 64-byte internal public keyerr: Error if recovery failed
Utility Functions
Convenience functions that manage contexts automatically.
GeneratePrivateKey
func GeneratePrivateKey() (privKey []byte, err error)
Generates a random 32-byte private key.
PublicKeyFromPrivate
func PublicKeyFromPrivate(privKey []byte, compressed bool) (pubKey []byte, err error)
Generates a serialized public key from a private key.
SignMessage
func SignMessage(msgHash []byte, privKey []byte) (sig []byte, err error)
Signs a message and returns compact signature (64 bytes).
VerifyMessage
func VerifyMessage(msgHash []byte, compactSig []byte, serializedPubKey []byte) (valid bool, err error)
Verifies a compact signature.
SignMessageDER
func SignMessageDER(msgHash []byte, privKey []byte) (derSig []byte, err error)
Signs a message and returns DER-encoded signature.
VerifyMessageDER
func VerifyMessageDER(msgHash []byte, derSig []byte, serializedPubKey []byte) (valid bool, err error)
Verifies a DER-encoded signature.
SchnorrSign
func SchnorrSign(msgHash []byte, privKey []byte, auxRand []byte) (sig []byte, err error)
Creates a Schnorr signature (64 bytes).
SchnorrVerifyWithPubKey
func SchnorrVerifyWithPubKey(msgHash []byte, sig []byte, xonlyPubKey []byte) (valid bool, err error)
Verifies a Schnorr signature.
XOnlyPubKeyFromPrivate
func XOnlyPubKeyFromPrivate(privKey []byte) (xonly []byte, pkParity int32, err error)
Generates x-only public key from private key.
ComputeECDH
func ComputeECDH(serializedPubKey []byte, privKey []byte) (secret []byte, err error)
Computes ECDH shared secret.
SignRecoverableCompact
func SignRecoverableCompact(msgHash []byte, privKey []byte) (sig []byte, recID int32, err error)
Signs with recovery information.
RecoverPubKey
func RecoverPubKey(msgHash []byte, compactSig []byte, recID int32, compressed bool) (pubKey []byte, err error)
Recovers public key from signature.
ValidatePrivateKey
func ValidatePrivateKey(privKey []byte) (valid bool, err error)
Checks if a private key is valid.
IsPublicKeyValid
func IsPublicKeyValid(serializedPubKey []byte) (valid bool, err error)
Checks if a serialized public key is valid.
Constants
Context Flags
const (
ContextNone = 1
ContextVerify = 257
ContextSign = 513
ContextDeclassify = 1025
)
EC Flags
const (
ECCompressed = 258
ECUncompressed = 2
)
Size Constants
const (
PublicKeySize = 64
CompressedPublicKeySize = 33
UncompressedPublicKeySize = 65
SignatureSize = 64
CompactSignatureSize = 64
PrivateKeySize = 32
SharedSecretSize = 32
SchnorrSignatureSize = 64
RecoverableSignatureSize = 65
)
Types
Context
type Context struct {
ctx uintptr
}
Opaque context handle.
Keypair
type Keypair [96]byte
Schnorr keypair structure.
XOnlyPublicKey
type XOnlyPublicKey [64]byte
64-byte x-only public key (internal representation).
Error Handling
All functions return errors. Common error conditions:
- Library not loaded or not found
- Invalid parameter sizes
- Invalid keys or signatures
- Module not available (Schnorr, ECDH, Recovery)
Always check returned errors:
result, err := secp.SomeFunction(...)
if err != nil {
// Handle error
return err
}
Thread Safety
Context objects are NOT thread-safe. Each goroutine should create its own context.
Utility functions are safe to use concurrently as they create temporary contexts.
Memory Management
Contexts are automatically cleaned up via finalizers, but explicit cleanup with Destroy() is recommended:
ctx, _ := secp.NewContext(secp.ContextSign)
defer ctx.Destroy()
All byte slices returned by the library are copies and safe to use/modify.