envelope

Documentation

Overview

Package envelope implements the amadan cryptographic envelope: ECDH P-256 asymmetric sealing and ECDSA P-256 signing, both domain-separated by a caller-supplied context string.

This is upstream debt (recorded 2026-08-03): it duplicates the designed github.com/carlosframework/rastrillo/crypto package (see docs/superpowers/specs/2026-08-03-rastrillo-crypto-prompt.md). When that package lands, amadan swaps its imports to it and deletes this copy; the golden vectors in testdata/golden.json are the compatibility contract that proves the two are interchangeable.

Wire format for Seal/Open: ephPub(65, uncompressed point) || iv(12) || AES-256-GCM ciphertext (no additional data). The shared secret is the raw ECDH X output, expanded via HKDF-SHA256 (salt=nil, info=context) to a 32-byte AES-256 key.

Sign/Verify: ECDSA P-256 over SHA-256(context || 0x00 || msg), producing a raw r||s signature (32 bytes each, zero-padded) — no ASN.1 framing.

🤖 generated in Task 1 (crypto foundation), 2026-08-03.

Index

• func MarshalKeypair(kp *Keypair) ([]byte, error)
• func Open(kp *Keypair, context string, sealed []byte) ([]byte, error)
• func Seal(recipientBoxPub []byte, context string, plaintext []byte) ([]byte, error)
• func Sign(kp *Keypair, context string, msg []byte) ([]byte, error)
• func Verify(signPub []byte, context string, msg, sig []byte) bool
• type Keypair
  • func Generate() (*Keypair, error)
  • func UnmarshalKeypair(b []byte) (*Keypair, error)
  • func (kp *Keypair) BoxPub() []byte
  • func (kp *Keypair) SignPub() []byte

Functions

func MarshalKeypair

func MarshalKeypair(kp *Keypair) ([]byte, error)

MarshalKeypair serializes kp as JSON for on-disk storage (e.g. ~/.amadan/key, mode 0600).

func Open

func Open(kp *Keypair, context string, sealed []byte) ([]byte, error)

Open decrypts a blob produced by Seal, using kp's box private key. It returns an error if the blob is malformed, the context does not match, the recipient is wrong, or the ciphertext has been tampered with.

func Seal

func Seal(recipientBoxPub []byte, context string, plaintext []byte) ([]byte, error)

Seal encrypts plaintext for recipientBoxPub (a 65-byte uncompressed P-256 point) under an ephemeral ECDH keypair, domain-separated by context. The output is ephPub(65) || iv(12) || ciphertext.

func Sign

func Sign(kp *Keypair, context string, msg []byte) ([]byte, error)

Sign produces a raw 64-byte r||s ECDSA P-256 signature over SHA-256(context || 0x00 || msg).

func Verify

func Verify(signPub []byte, context string, msg, sig []byte) bool

Verify reports whether sig is a valid signature over msg under signPub (a 65-byte uncompressed P-256 point) and context.

Types

type Keypair

type Keypair struct {
	SignPriv *ecdsa.PrivateKey // P-256
	BoxPriv  *ecdh.PrivateKey  // P-256
}

Keypair holds one party's dual keypair: an ECDSA P-256 signing key and an ECDH P-256 box (encryption) key.

func Generate

func Generate() (*Keypair, error)

Generate creates a fresh Keypair using crypto/rand.

func UnmarshalKeypair

func UnmarshalKeypair(b []byte) (*Keypair, error)

UnmarshalKeypair parses JSON produced by MarshalKeypair back into a Keypair with both private and (derived) public halves populated.

func (*Keypair) BoxPub

func (kp *Keypair) BoxPub() []byte

BoxPub returns the 65-byte uncompressed public box (ECDH) key.

func (*Keypair) SignPub

func (kp *Keypair) SignPub() []byte

SignPub returns the 65-byte uncompressed public signing key.