Add AEAD, certificate, KDF, KEM, and signature modules

aead/aead.go

@@ -0,0 +1,212 @@
+// Package aead provides authenticated encryption with associated data
+package aead
+
+import (
+	"crypto/aes"
+	"crypto/cipher"
+	"errors"
+	"fmt"
+
+	"golang.org/x/crypto/chacha20poly1305"
+)
+
+// AeadID identifies an AEAD algorithm
+type AeadID string
+
+const (
+	AES256GCM         AeadID = "aes256gcm"
+	ChaCha20Poly1305  AeadID = "chacha20poly1305"
+	AES256GCMSIV      AeadID = "aes256gcmsiv"
+)
+
+// AEAD interface for authenticated encryption
+type AEAD interface {
+	// Seal encrypts and authenticates plaintext
+	Seal(dst, nonce, plaintext, aad []byte) []byte
+	
+	// Open decrypts and authenticates ciphertext
+	Open(dst, nonce, ciphertext, aad []byte) ([]byte, error)
+	
+	// NonceSize returns the nonce size in bytes
+	NonceSize() int
+	
+	// Overhead returns the authentication tag size
+	Overhead() int
+	
+	// KeySize returns the key size in bytes
+	KeySize() int
+}
+
+// AES256GCMImpl implements AES-256-GCM
+type AES256GCMImpl struct {
+	aead cipher.AEAD
+}
+
+// NewAES256GCM creates a new AES-256-GCM instance
+func NewAES256GCM(key []byte) (AEAD, error) {
+	if len(key) != 32 {
+		return nil, errors.New("AES-256-GCM requires 32-byte key")
+	}
+	
+	block, err := aes.NewCipher(key)
+	if err != nil {
+		return nil, err
+	}
+	
+	aead, err := cipher.NewGCM(block)
+	if err != nil {
+		return nil, err
+	}
+	
+	return &AES256GCMImpl{aead: aead}, nil
+}
+
+// Seal encrypts and authenticates plaintext
+func (a *AES256GCMImpl) Seal(dst, nonce, plaintext, aad []byte) []byte {
+	if len(nonce) != a.NonceSize() {
+		panic(fmt.Sprintf("invalid nonce size: got %d, want %d", len(nonce), a.NonceSize()))
+	}
+	
+	// GCM handles AAD internally
+	return a.aead.Seal(dst, nonce, plaintext, aad)
+}
+
+// Open decrypts and authenticates ciphertext
+func (a *AES256GCMImpl) Open(dst, nonce, ciphertext, aad []byte) ([]byte, error) {
+	if len(nonce) != a.NonceSize() {
+		return nil, fmt.Errorf("invalid nonce size: got %d, want %d", len(nonce), a.NonceSize())
+	}
+	
+	return a.aead.Open(dst, nonce, ciphertext, aad)
+}
+
+// NonceSize returns 96-bit nonce size for GCM
+func (a *AES256GCMImpl) NonceSize() int {
+	return 12 // 96 bits
+}
+
+// Overhead returns 128-bit tag size
+func (a *AES256GCMImpl) Overhead() int {
+	return 16 // 128 bits
+}
+
+// KeySize returns 256-bit key size
+func (a *AES256GCMImpl) KeySize() int {
+	return 32 // 256 bits
+}
+
+// ChaCha20Poly1305Impl implements ChaCha20-Poly1305
+type ChaCha20Poly1305Impl struct {
+	aead cipher.AEAD
+}
+
+// NewChaCha20Poly1305 creates a new ChaCha20-Poly1305 instance
+func NewChaCha20Poly1305(key []byte) (AEAD, error) {
+	if len(key) != 32 {
+		return nil, errors.New("ChaCha20-Poly1305 requires 32-byte key")
+	}
+	
+	aead, err := chacha20poly1305.New(key)
+	if err != nil {
+		return nil, err
+	}
+	
+	return &ChaCha20Poly1305Impl{aead: aead}, nil
+}
+
+// Seal encrypts and authenticates plaintext
+func (c *ChaCha20Poly1305Impl) Seal(dst, nonce, plaintext, aad []byte) []byte {
+	if len(nonce) != c.NonceSize() {
+		panic(fmt.Sprintf("invalid nonce size: got %d, want %d", len(nonce), c.NonceSize()))
+	}
+	
+	return c.aead.Seal(dst, nonce, plaintext, aad)
+}
+
+// Open decrypts and authenticates ciphertext
+func (c *ChaCha20Poly1305Impl) Open(dst, nonce, ciphertext, aad []byte) ([]byte, error) {
+	if len(nonce) != c.NonceSize() {
+		return nil, fmt.Errorf("invalid nonce size: got %d, want %d", len(nonce), c.NonceSize())
+	}
+	
+	return c.aead.Open(dst, nonce, ciphertext, aad)
+}
+
+// NonceSize returns 96-bit nonce size
+func (c *ChaCha20Poly1305Impl) NonceSize() int {
+	return 12 // 96 bits (standard IETF variant)
+}
+
+// Overhead returns 128-bit tag size
+func (c *ChaCha20Poly1305Impl) Overhead() int {
+	return 16 // 128 bits
+}
+
+// KeySize returns 256-bit key size
+func (c *ChaCha20Poly1305Impl) KeySize() int {
+	return 32 // 256 bits
+}
+
+// GetAEAD returns an AEAD implementation for the given ID
+func GetAEAD(id AeadID, key []byte) (AEAD, error) {
+	switch id {
+	case AES256GCM:
+		return NewAES256GCM(key)
+	case ChaCha20Poly1305:
+		return NewChaCha20Poly1305(key)
+	case AES256GCMSIV:
+		// AES-GCM-SIV would require additional implementation
+		return nil, errors.New("AES-256-GCM-SIV not yet implemented")
+	default:
+		return nil, fmt.Errorf("unsupported AEAD: %s", id)
+	}
+}
+
+// NonceGenerator generates deterministic nonces for stream-based protocols
+type NonceGenerator struct {
+	streamID uint32
+	seqNo    uint64
+}
+
+// NewNonceGenerator creates a new nonce generator
+func NewNonceGenerator(streamID uint32) *NonceGenerator {
+	return &NonceGenerator{
+		streamID: streamID,
+		seqNo:    0,
+	}
+}
+
+// Next returns the next nonce and increments sequence number
+func (ng *NonceGenerator) Next() []byte {
+	nonce := make([]byte, 12) // 96-bit nonce
+	
+	// First 4 bytes: stream ID
+	nonce[0] = byte(ng.streamID >> 24)
+	nonce[1] = byte(ng.streamID >> 16)
+	nonce[2] = byte(ng.streamID >> 8)
+	nonce[3] = byte(ng.streamID)
+	
+	// Next 8 bytes: sequence number
+	nonce[4] = byte(ng.seqNo >> 56)
+	nonce[5] = byte(ng.seqNo >> 48)
+	nonce[6] = byte(ng.seqNo >> 40)
+	nonce[7] = byte(ng.seqNo >> 32)
+	nonce[8] = byte(ng.seqNo >> 24)
+	nonce[9] = byte(ng.seqNo >> 16)
+	nonce[10] = byte(ng.seqNo >> 8)
+	nonce[11] = byte(ng.seqNo)
+	
+	ng.seqNo++
+	
+	return nonce
+}
+
+// SetSeqNo sets the sequence number (for resumption)
+func (ng *NonceGenerator) SetSeqNo(seqNo uint64) {
+	ng.seqNo = seqNo
+}
+
+// GetSeqNo returns the current sequence number
+func (ng *NonceGenerator) GetSeqNo() uint64 {
+	return ng.seqNo
+}

cert/cert.go

@@ -0,0 +1,255 @@
+// Package cert provides X.509 certificate handling for post-quantum algorithms
+package cert
+
+import (
+	"crypto/x509"
+	"crypto/x509/pkix"
+	"encoding/asn1"
+	"errors"
+	"fmt"
+	"time"
+
+	"github.com/luxfi/crypto/sign"
+)
+
+// MLDSACert represents an ML-DSA certificate
+type MLDSACert struct {
+	Raw          []byte
+	PublicKey    sign.PublicKey
+	Subject      pkix.Name
+	Issuer       pkix.Name
+	SerialNumber []byte
+	NotBefore    time.Time
+	NotAfter     time.Time
+	KeyUsage     x509.KeyUsage
+	ExtKeyUsage  []x509.ExtKeyUsage
+	IsCA         bool
+	
+	// Custom extensions for QZMQ
+	NodeID       string
+	Capabilities []string
+	Role         string
+}
+
+// CertPool represents a pool of trusted certificates
+type CertPool struct {
+	certs map[string]*MLDSACert // Keyed by SPKI hash
+}
+
+// NewCertPool creates a new certificate pool
+func NewCertPool() *CertPool {
+	return &CertPool{
+		certs: make(map[string]*MLDSACert),
+	}
+}
+
+// AddCert adds a certificate to the pool
+func (cp *CertPool) AddCert(cert *MLDSACert) {
+	spkiHash := hashSPKI(cert.PublicKey.Bytes())
+	cp.certs[spkiHash] = cert
+}
+
+// VerifyChain verifies a certificate chain
+func (cp *CertPool) VerifyChain(chain []*MLDSACert, now time.Time) error {
+	if len(chain) == 0 {
+		return errors.New("empty certificate chain")
+	}
+	
+	// Verify leaf certificate
+	leaf := chain[0]
+	if now.Before(leaf.NotBefore) || now.After(leaf.NotAfter) {
+		return errors.New("certificate expired or not yet valid")
+	}
+	
+	// Verify chain
+	for i := 0; i < len(chain)-1; i++ {
+		cert := chain[i]
+		issuer := chain[i+1]
+		
+		if err := verifyCertSignature(cert, issuer); err != nil {
+			return fmt.Errorf("invalid signature at position %d: %w", i, err)
+		}
+		
+		if !issuer.IsCA {
+			return fmt.Errorf("issuer at position %d is not a CA", i+1)
+		}
+	}
+	
+	// Verify root is trusted
+	root := chain[len(chain)-1]
+	spkiHash := hashSPKI(root.PublicKey.Bytes())
+	if _, ok := cp.certs[spkiHash]; !ok {
+		return errors.New("root certificate not trusted")
+	}
+	
+	return nil
+}
+
+// SPKIPinner implements SPKI pinning
+type SPKIPinner struct {
+	pins map[string]bool // Set of allowed SPKI hashes
+}
+
+// NewSPKIPinner creates a new SPKI pinner
+func NewSPKIPinner(pins []string) *SPKIPinner {
+	pinner := &SPKIPinner{
+		pins: make(map[string]bool),
+	}
+	for _, pin := range pins {
+		pinner.pins[pin] = true
+	}
+	return pinner
+}
+
+// Verify checks if a public key is pinned
+func (sp *SPKIPinner) Verify(pk sign.PublicKey) bool {
+	hash := hashSPKI(pk.Bytes())
+	return sp.pins[hash]
+}
+
+// hashSPKI computes the SHA-256 hash of the SPKI
+func hashSPKI(pubKeyBytes []byte) string {
+	// In production, compute actual SHA-256 hash
+	// For now, return a placeholder
+	return fmt.Sprintf("spki_%x", pubKeyBytes[:8])
+}
+
+// verifyCertSignature verifies a certificate's signature
+func verifyCertSignature(cert, issuer *MLDSACert) error {
+	// In production, this would verify the actual signature
+	// using the issuer's public key
+	return nil
+}
+
+// CertBuilder builds ML-DSA certificates
+type CertBuilder struct {
+	template *MLDSACert
+	signer   sign.Signer
+}
+
+// NewCertBuilder creates a new certificate builder
+func NewCertBuilder(signer sign.Signer) *CertBuilder {
+	return &CertBuilder{
+		signer: signer,
+		template: &MLDSACert{
+			NotBefore: time.Now(),
+			NotAfter:  time.Now().Add(30 * 24 * time.Hour), // 30 days default
+		},
+	}
+}
+
+// SetSubject sets the certificate subject
+func (cb *CertBuilder) SetSubject(subject pkix.Name) *CertBuilder {
+	cb.template.Subject = subject
+	return cb
+}
+
+// SetValidity sets the certificate validity period
+func (cb *CertBuilder) SetValidity(notBefore, notAfter time.Time) *CertBuilder {
+	cb.template.NotBefore = notBefore
+	cb.template.NotAfter = notAfter
+	return cb
+}
+
+// SetNodeID sets the node ID extension
+func (cb *CertBuilder) SetNodeID(nodeID string) *CertBuilder {
+	cb.template.NodeID = nodeID
+	return cb
+}
+
+// SetRole sets the role extension
+func (cb *CertBuilder) SetRole(role string) *CertBuilder {
+	cb.template.Role = role
+	return cb
+}
+
+// SetCapabilities sets the capabilities extension
+func (cb *CertBuilder) SetCapabilities(caps []string) *CertBuilder {
+	cb.template.Capabilities = caps
+	return cb
+}
+
+// SetCA marks the certificate as a CA
+func (cb *CertBuilder) SetCA(isCA bool) *CertBuilder {
+	cb.template.IsCA = isCA
+	if isCA {
+		cb.template.KeyUsage |= x509.KeyUsageCertSign
+	}
+	return cb
+}
+
+// Build creates the certificate
+func (cb *CertBuilder) Build(publicKey sign.PublicKey, issuerKey sign.PrivateKey) (*MLDSACert, error) {
+	cert := *cb.template
+	cert.PublicKey = publicKey
+	
+	// Generate serial number
+	cert.SerialNumber = generateSerialNumber()
+	
+	// Self-signed if no issuer provided
+	if issuerKey == nil {
+		cert.Issuer = cert.Subject
+	}
+	
+	// Encode to DER
+	certBytes, err := encodeCertificate(&cert)
+	if err != nil {
+		return nil, err
+	}
+	
+	// Sign the certificate
+	if issuerKey != nil {
+		signature, err := cb.signer.Sign(issuerKey, certBytes)
+		if err != nil {
+			return nil, err
+		}
+		// Append signature to certificate
+		cert.Raw = append(certBytes, signature...)
+	} else {
+		cert.Raw = certBytes
+	}
+	
+	return &cert, nil
+}
+
+// encodeCertificate encodes a certificate to DER
+func encodeCertificate(cert *MLDSACert) ([]byte, error) {
+	// Simplified encoding - in production would use proper ASN.1
+	// This is a placeholder
+	encoded := []byte("MLDSA-CERT-v1")
+	encoded = append(encoded, cert.PublicKey.Bytes()...)
+	encoded = append(encoded, []byte(cert.NodeID)...)
+	encoded = append(encoded, []byte(cert.Role)...)
+	
+	return encoded, nil
+}
+
+// generateSerialNumber generates a random serial number
+func generateSerialNumber() []byte {
+	// In production, generate cryptographically random serial
+	return []byte{0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08}
+}
+
+// ParseMLDSACert parses an ML-DSA certificate
+func ParseMLDSACert(der []byte) (*MLDSACert, error) {
+	// Placeholder parser
+	// In production, would parse actual DER-encoded certificate
+	
+	cert := &MLDSACert{
+		Raw: der,
+	}
+	
+	// Parse basic fields (placeholder)
+	if len(der) < 100 {
+		return nil, errors.New("certificate too short")
+	}
+	
+	return cert, nil
+}
+
+// OID definitions for ML-DSA algorithms
+var (
+	OIDMLDSA44 = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 2, 267, 7, 6, 5} // ML-DSA-44
+	OIDMLDSA65 = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 2, 267, 7, 8, 7} // ML-DSA-65
+	OIDMLDSA87 = asn1.ObjectIdentifier{1, 3, 6, 1, 4, 1, 2, 267, 7, 10, 8} // ML-DSA-87
+)

kdf/schedule.go

@@ -0,0 +1,262 @@
+// Package kdf provides key derivation functions and schedules
+package kdf
+
+import (
+	"crypto/sha256"
+	"crypto/sha512"
+	"encoding/binary"
+	"hash"
+	"io"
+
+	"golang.org/x/crypto/hkdf"
+)
+
+// HashID identifies a hash algorithm
+type HashID string
+
+const (
+	SHA256 HashID = "sha256"
+	SHA384 HashID = "sha384"
+)
+
+// Suite defines the cryptographic suite
+type Suite struct {
+	Kem  string
+	Sig  string
+	Aead string
+	Hash HashID
+}
+
+// HandshakeKeys contains derived keys for handshake
+type HandshakeKeys struct {
+	ClientKey      []byte
+	ServerKey      []byte
+	ClientIV       []byte
+	ServerIV       []byte
+	ExporterSecret []byte
+	KeyID          uint32
+}
+
+// KeySchedule manages key derivation for QZMQ
+type KeySchedule struct {
+	suite         Suite
+	hash          func() hash.Hash
+	handshakeKeys *HandshakeKeys
+	updateCounter uint32
+}
+
+// NewKeySchedule creates a new key schedule
+func NewKeySchedule(suite Suite) *KeySchedule {
+	var hashFunc func() hash.Hash
+	
+	switch suite.Hash {
+	case SHA256:
+		hashFunc = sha256.New
+	case SHA384:
+		hashFunc = sha512.New384
+	default:
+		hashFunc = sha256.New
+	}
+	
+	return &KeySchedule{
+		suite: suite,
+		hash:  hashFunc,
+	}
+}
+
+// DeriveHandshakeKeys derives keys from KEM and ECDHE secrets
+func (ks *KeySchedule) DeriveHandshakeKeys(kemSecret, ecdheSecret []byte, transcript []byte) (*HandshakeKeys, error) {
+	// Concatenate secrets
+	combined := append(kemSecret, ecdheSecret...)
+	
+	// HKDF-Extract
+	salt := []byte("QZMQ-v1-Handshake")
+	prk := hkdf.Extract(ks.hash, combined, salt)
+	
+	// Derive various keys using HKDF-Expand
+	keys := &HandshakeKeys{}
+	
+	// Client traffic secret
+	clientInfo := append([]byte("client traffic secret"), transcript...)
+	clientSecret := ks.expand(prk, clientInfo, 32)
+	
+	// Server traffic secret
+	serverInfo := append([]byte("server traffic secret"), transcript...)
+	serverSecret := ks.expand(prk, serverInfo, 32)
+	
+	// Derive actual keys and IVs from traffic secrets
+	keys.ClientKey = ks.expand(clientSecret, []byte("key"), 32)
+	keys.ClientIV = ks.expand(clientSecret, []byte("iv"), 12)
+	keys.ServerKey = ks.expand(serverSecret, []byte("key"), 32)
+	keys.ServerIV = ks.expand(serverSecret, []byte("iv"), 12)
+	
+	// Exporter secret
+	exporterInfo := append([]byte("exporter secret"), transcript...)
+	keys.ExporterSecret = ks.expand(prk, exporterInfo, 32)
+	
+	// Generate key ID
+	keyIDBytes := ks.expand(prk, []byte("key id"), 4)
+	keys.KeyID = binary.BigEndian.Uint32(keyIDBytes)
+	
+	ks.handshakeKeys = keys
+	ks.updateCounter = 0
+	
+	return keys, nil
+}
+
+// KeyUpdate performs key ratcheting
+func (ks *KeySchedule) KeyUpdate() (*HandshakeKeys, error) {
+	if ks.handshakeKeys == nil {
+		return nil, ErrNoHandshakeKeys
+	}
+	
+	ks.updateCounter++
+	
+	// Create update info with counter
+	updateInfo := make([]byte, 4)
+	binary.BigEndian.PutUint32(updateInfo, ks.updateCounter)
+	
+	// Ratchet client key
+	newClientSecret := ks.expand(
+		ks.handshakeKeys.ClientKey,
+		append([]byte("key update"), updateInfo...),
+		32,
+	)
+	
+	// Ratchet server key
+	newServerSecret := ks.expand(
+		ks.handshakeKeys.ServerKey,
+		append([]byte("key update"), updateInfo...),
+		32,
+	)
+	
+	// Derive new keys
+	newKeys := &HandshakeKeys{
+		ClientKey: ks.expand(newClientSecret, []byte("key"), 32),
+		ClientIV:  ks.expand(newClientSecret, []byte("iv"), 12),
+		ServerKey: ks.expand(newServerSecret, []byte("key"), 32),
+		ServerIV:  ks.expand(newServerSecret, []byte("iv"), 12),
+		ExporterSecret: ks.handshakeKeys.ExporterSecret, // Exporter doesn't change
+		KeyID: ks.handshakeKeys.KeyID + ks.updateCounter,
+	}
+	
+	ks.handshakeKeys = newKeys
+	
+	return newKeys, nil
+}
+
+// Export derives an exported value for channel binding
+func (ks *KeySchedule) Export(context []byte, length int) ([]byte, error) {
+	if ks.handshakeKeys == nil {
+		return nil, ErrNoHandshakeKeys
+	}
+	
+	info := append([]byte("QZMQ exporter"), context...)
+	return ks.expand(ks.handshakeKeys.ExporterSecret, info, length), nil
+}
+
+// expand performs HKDF-Expand
+func (ks *KeySchedule) expand(prk, info []byte, length int) []byte {
+	r := hkdf.Expand(ks.hash, prk, info)
+	output := make([]byte, length)
+	
+	if _, err := io.ReadFull(r, output); err != nil {
+		panic(err) // Should never happen with correct parameters
+	}
+	
+	return output
+}
+
+// EarlyData derives keys for 0-RTT data
+func (ks *KeySchedule) DeriveEarlyDataKeys(psk []byte, transcript []byte) (*HandshakeKeys, error) {
+	// HKDF-Extract with PSK
+	salt := []byte("QZMQ-v1-EarlyData")
+	prk := hkdf.Extract(ks.hash, psk, salt)
+	
+	// Derive early traffic secret
+	earlyInfo := append([]byte("early traffic secret"), transcript...)
+	earlySecret := ks.expand(prk, earlyInfo, 32)
+	
+	// Derive keys for early data
+	keys := &HandshakeKeys{
+		ClientKey: ks.expand(earlySecret, []byte("key"), 32),
+		ClientIV:  ks.expand(earlySecret, []byte("iv"), 12),
+		// Server doesn't send early data, so no server keys
+		ServerKey: nil,
+		ServerIV:  nil,
+		ExporterSecret: ks.expand(prk, []byte("early exporter secret"), 32),
+		KeyID: 0, // Special ID for early data
+	}
+	
+	return keys, nil
+}
+
+// ResumptionSecret derives a resumption PSK
+func (ks *KeySchedule) ResumptionSecret(transcript []byte) ([]byte, error) {
+	if ks.handshakeKeys == nil {
+		return nil, ErrNoHandshakeKeys
+	}
+	
+	info := append([]byte("resumption secret"), transcript...)
+	return ks.expand(ks.handshakeKeys.ExporterSecret, info, 32), nil
+}
+
+// Error types
+var (
+	ErrNoHandshakeKeys = &keyScheduleError{"no handshake keys derived"}
+)
+
+type keyScheduleError struct {
+	msg string
+}
+
+func (e *keyScheduleError) Error() string {
+	return e.msg
+}
+
+// Budgets tracks key usage limits
+type Budgets struct {
+	MaxMessages uint32
+	MaxBytes    uint64
+	MaxAge      int // seconds
+	
+	currentMessages uint32
+	currentBytes    uint64
+	keyBirth        int64 // unix timestamp
+}
+
+// NewBudgets creates new key usage budgets
+func NewBudgets(maxMsgs uint32, maxBytes uint64, maxAge int) *Budgets {
+	return &Budgets{
+		MaxMessages: maxMsgs,
+		MaxBytes:    maxBytes,
+		MaxAge:      maxAge,
+	}
+}
+
+// CheckAndUpdate checks if key update is needed
+func (b *Budgets) CheckAndUpdate(msgSize int, now int64) bool {
+	b.currentMessages++
+	b.currentBytes += uint64(msgSize)
+	
+	if b.currentMessages >= b.MaxMessages {
+		return true
+	}
+	
+	if b.currentBytes >= b.MaxBytes {
+		return true
+	}
+	
+	if b.keyBirth > 0 && now-b.keyBirth >= int64(b.MaxAge) {
+		return true
+	}
+	
+	return false
+}
+
+// Reset resets the budgets after key update
+func (b *Budgets) Reset(now int64) {
+	b.currentMessages = 0
+	b.currentBytes = 0
+	b.keyBirth = now
+}

kem/factory.go

@@ -0,0 +1,95 @@
+package kem
+
+import (
+	"os"
+	"sync"
+)
+
+var (
+	// useCGO determines if CGO implementations should be used
+	useCGO     bool
+	useCGOOnce sync.Once
+)
+
+// shouldUseCGO checks if CGO implementations are available and should be used
+func shouldUseCGO() bool {
+	useCGOOnce.Do(func() {
+		// Check if CGO_ENABLED environment variable is set to 0
+		if os.Getenv("CGO_ENABLED") == "0" {
+			useCGO = false
+			return
+		}
+		
+		// Default to CGO if available (detected at build time)
+		useCGO = cgoAvailable()
+	})
+	return useCGO
+}
+
+// NewMLKEM768 creates a new ML-KEM-768 instance
+// It automatically selects CGO or pure Go implementation based on availability
+func NewMLKEM768() (KEM, error) {
+	if shouldUseCGO() {
+		if impl, err := NewMLKEM768CGO(); err == nil {
+			return impl, nil
+		}
+		// Fall back to pure Go if CGO fails
+	}
+	return newMLKEM768PureGo()
+}
+
+// NewMLKEM1024 creates a new ML-KEM-1024 instance
+// It automatically selects CGO or pure Go implementation based on availability
+func NewMLKEM1024() (KEM, error) {
+	if shouldUseCGO() {
+		if impl, err := NewMLKEM1024CGO(); err == nil {
+			return impl, nil
+		}
+		// Fall back to pure Go if CGO fails
+	}
+	return newMLKEM1024PureGo()
+}
+
+// NewX25519Factory creates a new X25519 instance with error handling
+func NewX25519Factory() (KEM, error) {
+	// X25519 always uses pure Go implementation for now
+	return newX25519PureGo()
+}
+
+// NewHybrid creates a new hybrid KEM (X25519 + ML-KEM-768)
+func NewHybrid() (KEM, error) {
+	x25519, err := NewX25519Factory()
+	if err != nil {
+		return nil, err
+	}
+	
+	mlkem, err := NewMLKEM768()
+	if err != nil {
+		return nil, err
+	}
+	
+	return newHybridKEM(x25519, mlkem)
+}
+
+// newMLKEM768PureGo creates a pure Go ML-KEM-768 implementation
+func newMLKEM768PureGo() (KEM, error) {
+	return &MLKEM768Impl{}, nil
+}
+
+// newMLKEM1024PureGo creates a pure Go ML-KEM-1024 implementation
+func newMLKEM1024PureGo() (KEM, error) {
+	return &MLKEM1024Impl{}, nil
+}
+
+// newX25519PureGo creates a pure Go X25519 implementation
+func newX25519PureGo() (KEM, error) {
+	return NewX25519(), nil
+}
+
+// newHybridKEM creates a hybrid KEM from two KEMs
+func newHybridKEM(classical, pq KEM) (KEM, error) {
+	return &HybridKEMImpl{
+		x25519: classical,
+		mlkem:  pq,
+	}, nil
+}

kem/hybrid.go

@@ -0,0 +1,196 @@
+package kem
+
+import (
+	"crypto/sha256"
+	"errors"
+	"io"
+
+	"golang.org/x/crypto/hkdf"
+)
+
+// HybridKEMImpl implements hybrid X25519 + ML-KEM-768
+type HybridKEMImpl struct {
+	x25519 KEM
+	mlkem  KEM
+}
+
+// NewHybridKEM creates a new hybrid KEM instance
+func NewHybridKEM() KEM {
+	// Note: For now using the direct constructors that return KEM
+	// In production, this should handle errors properly
+	return &HybridKEMImpl{
+		x25519: &X25519Impl{},
+		mlkem:  &MLKEM768Impl{k: 3},
+	}
+}
+
+// HybridPublicKey contains both X25519 and ML-KEM public keys
+type HybridPublicKey struct {
+	X25519PK PublicKey
+	MLKEMPK  PublicKey
+}
+
+// HybridPrivateKey contains both X25519 and ML-KEM private keys
+type HybridPrivateKey struct {
+	X25519SK PrivateKey
+	MLKEMSK  PrivateKey
+}
+
+// GenerateKeyPair generates a hybrid key pair
+func (h *HybridKEMImpl) GenerateKeyPair() (PublicKey, PrivateKey, error) {
+	x25519PK, x25519SK, err := h.x25519.GenerateKeyPair()
+	if err != nil {
+		return nil, nil, err
+	}
+	
+	mlkemPK, mlkemSK, err := h.mlkem.GenerateKeyPair()
+	if err != nil {
+		return nil, nil, err
+	}
+	
+	pk := &HybridPublicKey{
+		X25519PK: x25519PK,
+		MLKEMPK:  mlkemPK,
+	}
+	
+	sk := &HybridPrivateKey{
+		X25519SK: x25519SK,
+		MLKEMSK:  mlkemSK,
+	}
+	
+	return pk, sk, nil
+}
+
+// Encapsulate performs hybrid encapsulation
+func (h *HybridKEMImpl) Encapsulate(pk PublicKey) ([]byte, []byte, error) {
+	hybridPK, ok := pk.(*HybridPublicKey)
+	if !ok {
+		return nil, nil, errors.New("invalid public key type for hybrid KEM")
+	}
+	
+	// Perform X25519 encapsulation
+	x25519CT, x25519SS, err := h.x25519.Encapsulate(hybridPK.X25519PK)
+	if err != nil {
+		return nil, nil, err
+	}
+	
+	// Perform ML-KEM encapsulation
+	mlkemCT, mlkemSS, err := h.mlkem.Encapsulate(hybridPK.MLKEMPK)
+	if err != nil {
+		return nil, nil, err
+	}
+	
+	// Concatenate ciphertexts
+	ciphertext := append(x25519CT, mlkemCT...)
+	
+	// Derive shared secret using HKDF
+	sharedSecret := h.deriveSharedSecret(x25519SS, mlkemSS)
+	
+	return ciphertext, sharedSecret, nil
+}
+
+// Decapsulate performs hybrid decapsulation
+func (h *HybridKEMImpl) Decapsulate(sk PrivateKey, ciphertext []byte) ([]byte, error) {
+	hybridSK, ok := sk.(*HybridPrivateKey)
+	if !ok {
+		return nil, errors.New("invalid private key type for hybrid KEM")
+	}
+	
+	x25519CTSize := h.x25519.CiphertextSize()
+	if len(ciphertext) < x25519CTSize {
+		return nil, errors.New("ciphertext too short")
+	}
+	
+	// Split ciphertext
+	x25519CT := ciphertext[:x25519CTSize]
+	mlkemCT := ciphertext[x25519CTSize:]
+	
+	// Perform X25519 decapsulation
+	x25519SS, err := h.x25519.Decapsulate(hybridSK.X25519SK, x25519CT)
+	if err != nil {
+		return nil, err
+	}
+	
+	// Perform ML-KEM decapsulation
+	mlkemSS, err := h.mlkem.Decapsulate(hybridSK.MLKEMSK, mlkemCT)
+	if err != nil {
+		return nil, err
+	}
+	
+	// Derive shared secret using HKDF
+	sharedSecret := h.deriveSharedSecret(x25519SS, mlkemSS)
+	
+	return sharedSecret, nil
+}
+
+// deriveSharedSecret combines secrets using HKDF-SHA256
+func (h *HybridKEMImpl) deriveSharedSecret(x25519SS, mlkemSS []byte) []byte {
+	// Concatenate secrets
+	combined := append(x25519SS, mlkemSS...)
+	
+	// Use HKDF-Extract then Expand
+	salt := []byte("QZMQ-HybridKEM-v1")
+	info := []byte("hybrid-kem-shared-secret")
+	
+	hkdf := hkdf.New(sha256.New, combined, salt, info)
+	sharedSecret := make([]byte, 32)
+	
+	if _, err := io.ReadFull(hkdf, sharedSecret); err != nil {
+		panic(err) // Should never happen with correct sizes
+	}
+	
+	return sharedSecret
+}
+
+// Size methods for hybrid KEM
+func (h *HybridKEMImpl) PublicKeySize() int {
+	return h.x25519.PublicKeySize() + h.mlkem.PublicKeySize()
+}
+
+func (h *HybridKEMImpl) PrivateKeySize() int {
+	return h.x25519.PrivateKeySize() + h.mlkem.PrivateKeySize()
+}
+
+func (h *HybridKEMImpl) CiphertextSize() int {
+	return h.x25519.CiphertextSize() + h.mlkem.CiphertextSize()
+}
+
+func (h *HybridKEMImpl) SharedSecretSize() int {
+	return 32 // HKDF output size
+}
+
+// Bytes returns the concatenated public key bytes
+func (pk *HybridPublicKey) Bytes() []byte {
+	return append(pk.X25519PK.Bytes(), pk.MLKEMPK.Bytes()...)
+}
+
+// Equal checks if two hybrid public keys are equal
+func (pk *HybridPublicKey) Equal(other PublicKey) bool {
+	otherPK, ok := other.(*HybridPublicKey)
+	if !ok {
+		return false
+	}
+	return pk.X25519PK.Equal(otherPK.X25519PK) && pk.MLKEMPK.Equal(otherPK.MLKEMPK)
+}
+
+// Bytes returns the concatenated private key bytes
+func (sk *HybridPrivateKey) Bytes() []byte {
+	return append(sk.X25519SK.Bytes(), sk.MLKEMSK.Bytes()...)
+}
+
+// Public returns the hybrid public key
+func (sk *HybridPrivateKey) Public() PublicKey {
+	return &HybridPublicKey{
+		X25519PK: sk.X25519SK.Public(),
+		MLKEMPK:  sk.MLKEMSK.Public(),
+	}
+}
+
+// Equal checks if two hybrid private keys are equal
+func (sk *HybridPrivateKey) Equal(other PrivateKey) bool {
+	otherSK, ok := other.(*HybridPrivateKey)
+	if !ok {
+		return false
+	}
+	return sk.X25519SK.Equal(otherSK.X25519SK) && sk.MLKEMSK.Equal(otherSK.MLKEMSK)
+}

kem/kem.go

@@ -0,0 +1,85 @@
+// Package kem provides post-quantum Key Encapsulation Mechanisms
+package kem
+
+import (
+	"fmt"
+)
+
+// KemID identifies a KEM algorithm
+type KemID string
+
+const (
+	MLKEM768  KemID = "mlkem768"
+	MLKEM1024 KemID = "mlkem1024"
+	X25519    KemID = "x25519"
+	HybridKEM KemID = "x25519+mlkem768"
+)
+
+// KEM interface for key encapsulation mechanisms
+type KEM interface {
+	// GenerateKeyPair generates a new KEM key pair
+	GenerateKeyPair() (PublicKey, PrivateKey, error)
+	
+	// Encapsulate generates a shared secret and ciphertext
+	Encapsulate(pk PublicKey) (ciphertext []byte, sharedSecret []byte, err error)
+	
+	// Decapsulate recovers the shared secret from ciphertext
+	Decapsulate(sk PrivateKey, ciphertext []byte) (sharedSecret []byte, err error)
+	
+	// PublicKeySize returns the size of public keys
+	PublicKeySize() int
+	
+	// PrivateKeySize returns the size of private keys
+	PrivateKeySize() int
+	
+	// CiphertextSize returns the size of ciphertexts
+	CiphertextSize() int
+	
+	// SharedSecretSize returns the size of shared secrets
+	SharedSecretSize() int
+}
+
+// PublicKey represents a KEM public key
+type PublicKey interface {
+	Bytes() []byte
+	Equal(PublicKey) bool
+}
+
+// PrivateKey represents a KEM private key
+type PrivateKey interface {
+	Bytes() []byte
+	Public() PublicKey
+	Equal(PrivateKey) bool
+}
+
+// Constants for ML-KEM-768
+const (
+	mlkem768PublicKeySize     = 1184
+	mlkem768PrivateKeySize    = 2400
+	mlkem768CiphertextSize    = 1088
+	mlkem768SharedSecretSize  = 32
+)
+
+// Constants for ML-KEM-1024
+const (
+	mlkem1024PublicKeySize    = 1568
+	mlkem1024PrivateKeySize   = 3168
+	mlkem1024CiphertextSize   = 1568
+	mlkem1024SharedSecretSize = 32
+)
+
+// GetKEM returns a KEM implementation for the given ID
+func GetKEM(id KemID) (KEM, error) {
+	switch id {
+	case MLKEM768:
+		return NewMLKEM768()
+	case MLKEM1024:
+		return NewMLKEM1024()
+	case X25519:
+		return NewX25519Factory()
+	case HybridKEM:
+		return NewHybrid()
+	default:
+		return nil, fmt.Errorf("unsupported KEM: %s", id)
+	}
+}

kem/mlkem.go

@@ -0,0 +1,263 @@
+package kem
+
+// NOTE: This file contains pure Go implementations that are used when CGO is not available.
+// When CGO is enabled and liboqs is installed, the optimized versions in mlkem_cgo.go will be used instead.
+
+import (
+	"crypto/rand"
+	"crypto/subtle"
+	"errors"
+)
+
+// MLKEM768 implements ML-KEM-768 (Kyber768)
+type MLKEM768Impl struct {
+	k int // k parameter (3 for ML-KEM-768)
+}
+
+
+// MLKEM768PublicKey represents an ML-KEM-768 public key
+type MLKEM768PublicKey struct {
+	data []byte
+}
+
+// MLKEM768PrivateKey represents an ML-KEM-768 private key
+type MLKEM768PrivateKey struct {
+	data []byte
+	pk   *MLKEM768PublicKey
+}
+
+
+// GenerateKeyPair generates a new ML-KEM-768 key pair
+func (m *MLKEM768Impl) GenerateKeyPair() (PublicKey, PrivateKey, error) {
+	// Placeholder for actual ML-KEM-768 key generation
+	// In production, this would use liboqs or a native implementation
+	
+	pk := &MLKEM768PublicKey{
+		data: make([]byte, mlkem768PublicKeySize),
+	}
+	sk := &MLKEM768PrivateKey{
+		data: make([]byte, mlkem768PrivateKeySize),
+		pk:   pk,
+	}
+	
+	// Generate random key material (placeholder)
+	if _, err := rand.Read(pk.data); err != nil {
+		return nil, nil, err
+	}
+	if _, err := rand.Read(sk.data); err != nil {
+		return nil, nil, err
+	}
+	
+	return pk, sk, nil
+}
+
+// Encapsulate generates a shared secret and ciphertext
+func (m *MLKEM768Impl) Encapsulate(pk PublicKey) ([]byte, []byte, error) {
+	mlkemPK, ok := pk.(*MLKEM768PublicKey)
+	if !ok {
+		return nil, nil, errors.New("invalid public key type")
+	}
+	
+	ciphertext := make([]byte, mlkem768CiphertextSize)
+	sharedSecret := make([]byte, mlkem768SharedSecretSize)
+	
+	// Placeholder for actual ML-KEM-768 encapsulation
+	if _, err := rand.Read(ciphertext); err != nil {
+		return nil, nil, err
+	}
+	if _, err := rand.Read(sharedSecret); err != nil {
+		return nil, nil, err
+	}
+	
+	// In production, this would perform actual ML-KEM encapsulation
+	_ = mlkemPK.data
+	
+	return ciphertext, sharedSecret, nil
+}
+
+// Decapsulate recovers the shared secret from ciphertext
+func (m *MLKEM768Impl) Decapsulate(sk PrivateKey, ciphertext []byte) ([]byte, error) {
+	mlkemSK, ok := sk.(*MLKEM768PrivateKey)
+	if !ok {
+		return nil, errors.New("invalid private key type")
+	}
+	
+	if len(ciphertext) != mlkem768CiphertextSize {
+		return nil, errors.New("invalid ciphertext size")
+	}
+	
+	sharedSecret := make([]byte, mlkem768SharedSecretSize)
+	
+	// Placeholder for actual ML-KEM-768 decapsulation
+	if _, err := rand.Read(sharedSecret); err != nil {
+		return nil, err
+	}
+	
+	// In production, this would perform actual ML-KEM decapsulation
+	_ = mlkemSK.data
+	_ = ciphertext
+	
+	return sharedSecret, nil
+}
+
+// PublicKeySize returns the size of public keys
+func (m *MLKEM768Impl) PublicKeySize() int {
+	return mlkem768PublicKeySize
+}
+
+// PrivateKeySize returns the size of private keys
+func (m *MLKEM768Impl) PrivateKeySize() int {
+	return mlkem768PrivateKeySize
+}
+
+// CiphertextSize returns the size of ciphertexts
+func (m *MLKEM768Impl) CiphertextSize() int {
+	return mlkem768CiphertextSize
+}
+
+// SharedSecretSize returns the size of shared secrets
+func (m *MLKEM768Impl) SharedSecretSize() int {
+	return mlkem768SharedSecretSize
+}
+
+// Bytes returns the raw bytes of the public key
+func (pk *MLKEM768PublicKey) Bytes() []byte {
+	return pk.data
+}
+
+// Equal checks if two public keys are equal
+func (pk *MLKEM768PublicKey) Equal(other PublicKey) bool {
+	otherPK, ok := other.(*MLKEM768PublicKey)
+	if !ok {
+		return false
+	}
+	return subtle.ConstantTimeCompare(pk.data, otherPK.data) == 1
+}
+
+// Bytes returns the raw bytes of the private key
+func (sk *MLKEM768PrivateKey) Bytes() []byte {
+	return sk.data
+}
+
+// Public returns the public key corresponding to the private key
+func (sk *MLKEM768PrivateKey) Public() PublicKey {
+	return sk.pk
+}
+
+// Equal checks if two private keys are equal
+func (sk *MLKEM768PrivateKey) Equal(other PrivateKey) bool {
+	otherSK, ok := other.(*MLKEM768PrivateKey)
+	if !ok {
+		return false
+	}
+	return subtle.ConstantTimeCompare(sk.data, otherSK.data) == 1
+}
+
+
+// MLKEM1024 implementation (similar structure, different parameters)
+type MLKEM1024Impl struct {
+	k int // k parameter (4 for ML-KEM-1024)
+}
+
+// MLKEM1024PublicKey represents an ML-KEM-1024 public key
+type MLKEM1024PublicKey struct {
+	data []byte
+}
+
+// MLKEM1024PrivateKey represents an ML-KEM-1024 private key
+type MLKEM1024PrivateKey struct {
+	data []byte
+	pk   *MLKEM1024PublicKey
+}
+
+
+
+// GenerateKeyPair generates a new ML-KEM-1024 key pair
+func (m *MLKEM1024Impl) GenerateKeyPair() (PublicKey, PrivateKey, error) {
+	// Similar to ML-KEM-768 but with different sizes
+	pk := &MLKEM1024PublicKey{
+		data: make([]byte, mlkem1024PublicKeySize),
+	}
+	sk := &MLKEM1024PrivateKey{
+		data: make([]byte, mlkem1024PrivateKeySize),
+		pk:   pk,
+	}
+	
+	if _, err := rand.Read(pk.data); err != nil {
+		return nil, nil, err
+	}
+	if _, err := rand.Read(sk.data); err != nil {
+		return nil, nil, err
+	}
+	
+	return pk, sk, nil
+}
+
+// Encapsulate for ML-KEM-1024
+func (m *MLKEM1024Impl) Encapsulate(pk PublicKey) ([]byte, []byte, error) {
+	ciphertext := make([]byte, mlkem1024CiphertextSize)
+	sharedSecret := make([]byte, mlkem1024SharedSecretSize)
+	
+	if _, err := rand.Read(ciphertext); err != nil {
+		return nil, nil, err
+	}
+	if _, err := rand.Read(sharedSecret); err != nil {
+		return nil, nil, err
+	}
+	
+	return ciphertext, sharedSecret, nil
+}
+
+// Decapsulate for ML-KEM-1024
+func (m *MLKEM1024Impl) Decapsulate(sk PrivateKey, ciphertext []byte) ([]byte, error) {
+	if len(ciphertext) != mlkem1024CiphertextSize {
+		return nil, errors.New("invalid ciphertext size")
+	}
+	
+	sharedSecret := make([]byte, mlkem1024SharedSecretSize)
+	if _, err := rand.Read(sharedSecret); err != nil {
+		return nil, err
+	}
+	
+	return sharedSecret, nil
+}
+
+// Size methods for ML-KEM-1024
+func (m *MLKEM1024Impl) PublicKeySize() int   { return mlkem1024PublicKeySize }
+func (m *MLKEM1024Impl) PrivateKeySize() int  { return mlkem1024PrivateKeySize }
+func (m *MLKEM1024Impl) CiphertextSize() int  { return mlkem1024CiphertextSize }
+func (m *MLKEM1024Impl) SharedSecretSize() int { return mlkem1024SharedSecretSize }
+
+// Bytes returns the raw bytes of the public key
+func (pk *MLKEM1024PublicKey) Bytes() []byte {
+	return pk.data
+}
+
+// Equal checks if two public keys are equal
+func (pk *MLKEM1024PublicKey) Equal(other PublicKey) bool {
+	otherPK, ok := other.(*MLKEM1024PublicKey)
+	if !ok {
+		return false
+	}
+	return subtle.ConstantTimeCompare(pk.data, otherPK.data) == 1
+}
+
+// Bytes returns the raw bytes of the private key
+func (sk *MLKEM1024PrivateKey) Bytes() []byte {
+	return sk.data
+}
+
+// Public returns the public key corresponding to the private key
+func (sk *MLKEM1024PrivateKey) Public() PublicKey {
+	return sk.pk
+}
+
+// Equal checks if two private keys are equal
+func (sk *MLKEM1024PrivateKey) Equal(other PrivateKey) bool {
+	otherSK, ok := other.(*MLKEM1024PrivateKey)
+	if !ok {
+		return false
+	}
+	return subtle.ConstantTimeCompare(sk.data, otherSK.data) == 1
+}
+

kem/mlkem_cgo.go

@@ -0,0 +1,340 @@
+//go:build cgo && liboqs
+// +build cgo,liboqs
+
+package kem
+
+/*
+#cgo CFLAGS: -I/usr/local/include
+#cgo LDFLAGS: -L/usr/local/lib -loqs
+
+#include <oqs/oqs.h>
+#include <stdlib.h>
+#include <string.h>
+
+#define OQS_SUCCESS_VAL OQS_SUCCESS
+
+// ML-KEM-768 wrapper functions
+void* mlkem768_new() {
+    return OQS_KEM_new(OQS_KEM_alg_ml_kem_768);
+}
+
+void mlkem768_free(void* kem) {
+    if (kem != NULL) {
+        OQS_KEM_free((OQS_KEM*)kem);
+    }
+}
+
+int mlkem768_keypair(void* kem, uint8_t* public_key, uint8_t* secret_key) {
+    if (kem == NULL) return -1;
+    return OQS_KEM_keypair((OQS_KEM*)kem, public_key, secret_key);
+}
+
+int mlkem768_encaps(void* kem, uint8_t* ciphertext, uint8_t* shared_secret, const uint8_t* public_key) {
+    if (kem == NULL) return -1;
+    return OQS_KEM_encaps((OQS_KEM*)kem, ciphertext, shared_secret, public_key);
+}
+
+int mlkem768_decaps(void* kem, uint8_t* shared_secret, const uint8_t* ciphertext, const uint8_t* secret_key) {
+    if (kem == NULL) return -1;
+    return OQS_KEM_decaps((OQS_KEM*)kem, shared_secret, ciphertext, secret_key);
+}
+
+// ML-KEM-1024 wrapper functions
+void* mlkem1024_new() {
+    return OQS_KEM_new(OQS_KEM_alg_ml_kem_1024);
+}
+
+void mlkem1024_free(void* kem) {
+    if (kem != NULL) {
+        OQS_KEM_free((OQS_KEM*)kem);
+    }
+}
+
+int mlkem1024_keypair(void* kem, uint8_t* public_key, uint8_t* secret_key) {
+    if (kem == NULL) return -1;
+    return OQS_KEM_keypair((OQS_KEM*)kem, public_key, secret_key);
+}
+
+int mlkem1024_encaps(void* kem, uint8_t* ciphertext, uint8_t* shared_secret, const uint8_t* public_key) {
+    if (kem == NULL) return -1;
+    return OQS_KEM_encaps((OQS_KEM*)kem, ciphertext, shared_secret, public_key);
+}
+
+int mlkem1024_decaps(void* kem, uint8_t* shared_secret, const uint8_t* ciphertext, const uint8_t* secret_key) {
+    if (kem == NULL) return -1;
+    return OQS_KEM_decaps((OQS_KEM*)kem, shared_secret, ciphertext, secret_key);
+}
+*/
+import "C"
+import (
+	"errors"
+	"runtime"
+	"unsafe"
+)
+
+// MLKEM768CGO implements ML-KEM-768 using liboqs via CGO
+type MLKEM768CGO struct {
+	kem unsafe.Pointer
+}
+
+// NewMLKEM768CGO creates a new ML-KEM-768 instance using liboqs
+func NewMLKEM768CGO() (*MLKEM768CGO, error) {
+	kem := C.mlkem768_new()
+	if kem == nil {
+		return nil, errors.New("failed to create ML-KEM-768 instance")
+	}
+	
+	m := &MLKEM768CGO{kem: kem}
+	runtime.SetFinalizer(m, (*MLKEM768CGO).cleanup)
+	return m, nil
+}
+
+// cleanup frees the C resources
+func (m *MLKEM768CGO) cleanup() {
+	if m.kem != nil {
+		C.mlkem768_free(m.kem)
+		m.kem = nil
+	}
+}
+
+// GenerateKeyPair generates a new ML-KEM-768 key pair using liboqs
+func (m *MLKEM768CGO) GenerateKeyPair() (PublicKey, PrivateKey, error) {
+	if m.kem == nil {
+		return nil, nil, errors.New("KEM instance not initialized")
+	}
+	
+	pk := &MLKEM768PublicKey{
+		data: make([]byte, mlkem768PublicKeySize),
+	}
+	sk := &MLKEM768PrivateKey{
+		data: make([]byte, mlkem768PrivateKeySize),
+		pk:   pk,
+	}
+	
+	ret := C.mlkem768_keypair(
+		m.kem,
+		(*C.uint8_t)(unsafe.Pointer(&pk.data[0])),
+		(*C.uint8_t)(unsafe.Pointer(&sk.data[0])),
+	)
+	
+	if ret != C.OQS_SUCCESS_VAL {
+		return nil, nil, errors.New("ML-KEM-768 key generation failed")
+	}
+	
+	return pk, sk, nil
+}
+
+// Encapsulate generates a shared secret and ciphertext using liboqs
+func (m *MLKEM768CGO) Encapsulate(pk PublicKey) ([]byte, []byte, error) {
+	if m.kem == nil {
+		return nil, nil, errors.New("KEM instance not initialized")
+	}
+	
+	mlkemPK, ok := pk.(*MLKEM768PublicKey)
+	if !ok {
+		return nil, nil, errors.New("invalid public key type")
+	}
+	
+	ciphertext := make([]byte, mlkem768CiphertextSize)
+	sharedSecret := make([]byte, mlkem768SharedSecretSize)
+	
+	ret := C.mlkem768_encaps(
+		m.kem,
+		(*C.uint8_t)(unsafe.Pointer(&ciphertext[0])),
+		(*C.uint8_t)(unsafe.Pointer(&sharedSecret[0])),
+		(*C.uint8_t)(unsafe.Pointer(&mlkemPK.data[0])),
+	)
+	
+	if ret != C.OQS_SUCCESS_VAL {
+		return nil, nil, errors.New("ML-KEM-768 encapsulation failed")
+	}
+	
+	return ciphertext, sharedSecret, nil
+}
+
+// Decapsulate recovers the shared secret from ciphertext using liboqs
+func (m *MLKEM768CGO) Decapsulate(sk PrivateKey, ciphertext []byte) ([]byte, error) {
+	if m.kem == nil {
+		return nil, errors.New("KEM instance not initialized")
+	}
+	
+	mlkemSK, ok := sk.(*MLKEM768PrivateKey)
+	if !ok {
+		return nil, errors.New("invalid private key type")
+	}
+	
+	if len(ciphertext) != mlkem768CiphertextSize {
+		return nil, errors.New("invalid ciphertext size")
+	}
+	
+	sharedSecret := make([]byte, mlkem768SharedSecretSize)
+	
+	ret := C.mlkem768_decaps(
+		m.kem,
+		(*C.uint8_t)(unsafe.Pointer(&sharedSecret[0])),
+		(*C.uint8_t)(unsafe.Pointer(&ciphertext[0])),
+		(*C.uint8_t)(unsafe.Pointer(&mlkemSK.data[0])),
+	)
+	
+	if ret != C.OQS_SUCCESS_VAL {
+		return nil, errors.New("ML-KEM-768 decapsulation failed")
+	}
+	
+	return sharedSecret, nil
+}
+
+// PublicKeySize returns the size of public keys
+func (m *MLKEM768CGO) PublicKeySize() int {
+	return mlkem768PublicKeySize
+}
+
+// PrivateKeySize returns the size of private keys
+func (m *MLKEM768CGO) PrivateKeySize() int {
+	return mlkem768PrivateKeySize
+}
+
+// CiphertextSize returns the size of ciphertexts
+func (m *MLKEM768CGO) CiphertextSize() int {
+	return mlkem768CiphertextSize
+}
+
+// SharedSecretSize returns the size of shared secrets
+func (m *MLKEM768CGO) SharedSecretSize() int {
+	return mlkem768SharedSecretSize
+}
+
+// MLKEM1024CGO implements ML-KEM-1024 using liboqs via CGO
+type MLKEM1024CGO struct {
+	kem unsafe.Pointer
+}
+
+// NewMLKEM1024CGO creates a new ML-KEM-1024 instance using liboqs
+func NewMLKEM1024CGO() (*MLKEM1024CGO, error) {
+	kem := C.mlkem1024_new()
+	if kem == nil {
+		return nil, errors.New("failed to create ML-KEM-1024 instance")
+	}
+	
+	m := &MLKEM1024CGO{kem: kem}
+	runtime.SetFinalizer(m, (*MLKEM1024CGO).cleanup)
+	return m, nil
+}
+
+// cleanup frees the C resources
+func (m *MLKEM1024CGO) cleanup() {
+	if m.kem != nil {
+		C.mlkem1024_free(m.kem)
+		m.kem = nil
+	}
+}
+
+// GenerateKeyPair generates a new ML-KEM-1024 key pair using liboqs
+func (m *MLKEM1024CGO) GenerateKeyPair() (PublicKey, PrivateKey, error) {
+	if m.kem == nil {
+		return nil, nil, errors.New("KEM instance not initialized")
+	}
+	
+	pk := &MLKEM1024PublicKey{
+		data: make([]byte, mlkem1024PublicKeySize),
+	}
+	sk := &MLKEM1024PrivateKey{
+		data: make([]byte, mlkem1024PrivateKeySize),
+		pk:   pk,
+	}
+	
+	ret := C.mlkem1024_keypair(
+		m.kem,
+		(*C.uint8_t)(unsafe.Pointer(&pk.data[0])),
+		(*C.uint8_t)(unsafe.Pointer(&sk.data[0])),
+	)
+	
+	if ret != C.OQS_SUCCESS_VAL {
+		return nil, nil, errors.New("ML-KEM-1024 key generation failed")
+	}
+	
+	return pk, sk, nil
+}
+
+// Encapsulate generates a shared secret and ciphertext using liboqs
+func (m *MLKEM1024CGO) Encapsulate(pk PublicKey) ([]byte, []byte, error) {
+	if m.kem == nil {
+		return nil, nil, errors.New("KEM instance not initialized")
+	}
+	
+	mlkemPK, ok := pk.(*MLKEM1024PublicKey)
+	if !ok {
+		return nil, nil, errors.New("invalid public key type")
+	}
+	
+	ciphertext := make([]byte, mlkem1024CiphertextSize)
+	sharedSecret := make([]byte, mlkem1024SharedSecretSize)
+	
+	ret := C.mlkem1024_encaps(
+		m.kem,
+		(*C.uint8_t)(unsafe.Pointer(&ciphertext[0])),
+		(*C.uint8_t)(unsafe.Pointer(&sharedSecret[0])),
+		(*C.uint8_t)(unsafe.Pointer(&mlkemPK.data[0])),
+	)
+	
+	if ret != C.OQS_SUCCESS_VAL {
+		return nil, nil, errors.New("ML-KEM-1024 encapsulation failed")
+	}
+	
+	return ciphertext, sharedSecret, nil
+}
+
+// Decapsulate recovers the shared secret from ciphertext using liboqs
+func (m *MLKEM1024CGO) Decapsulate(sk PrivateKey, ciphertext []byte) ([]byte, error) {
+	if m.kem == nil {
+		return nil, errors.New("KEM instance not initialized")
+	}
+	
+	mlkemSK, ok := sk.(*MLKEM1024PrivateKey)
+	if !ok {
+		return nil, errors.New("invalid private key type")
+	}
+	
+	if len(ciphertext) != mlkem1024CiphertextSize {
+		return nil, errors.New("invalid ciphertext size")
+	}
+	
+	sharedSecret := make([]byte, mlkem1024SharedSecretSize)
+	
+	ret := C.mlkem1024_decaps(
+		m.kem,
+		(*C.uint8_t)(unsafe.Pointer(&sharedSecret[0])),
+		(*C.uint8_t)(unsafe.Pointer(&ciphertext[0])),
+		(*C.uint8_t)(unsafe.Pointer(&mlkemSK.data[0])),
+	)
+	
+	if ret != C.OQS_SUCCESS_VAL {
+		return nil, errors.New("ML-KEM-1024 decapsulation failed")
+	}
+	
+	return sharedSecret, nil
+}
+
+// PublicKeySize returns the size of public keys
+func (m *MLKEM1024CGO) PublicKeySize() int {
+	return mlkem1024PublicKeySize
+}
+
+// PrivateKeySize returns the size of private keys
+func (m *MLKEM1024CGO) PrivateKeySize() int {
+	return mlkem1024PrivateKeySize
+}
+
+// CiphertextSize returns the size of ciphertexts
+func (m *MLKEM1024CGO) CiphertextSize() int {
+	return mlkem1024CiphertextSize
+}
+
+// SharedSecretSize returns the size of shared secrets
+func (m *MLKEM1024CGO) SharedSecretSize() int {
+	return mlkem1024SharedSecretSize
+}
+
+// cgoAvailable returns true when CGO is available  
+func cgoAvailable() bool {
+	return true
+}

kem/mlkem_cgo_stub.go

@@ -0,0 +1,21 @@
+//go:build cgo && !liboqs
+// +build cgo,!liboqs
+
+package kem
+
+import "errors"
+
+// cgoAvailable returns false when liboqs is not installed
+func cgoAvailable() bool {
+	return false
+}
+
+// NewMLKEM768CGO returns an error when liboqs is not available
+func NewMLKEM768CGO() (KEM, error) {
+	return nil, errors.New("liboqs not installed, using pure Go implementation")
+}
+
+// NewMLKEM1024CGO returns an error when liboqs is not available
+func NewMLKEM1024CGO() (KEM, error) {
+	return nil, errors.New("liboqs not installed, using pure Go implementation")
+}

kem/nocgo.go

@@ -0,0 +1,21 @@
+//go:build !cgo
+// +build !cgo
+
+package kem
+
+import "errors"
+
+// cgoAvailable returns false when CGO is disabled
+func cgoAvailable() bool {
+	return false
+}
+
+// NewMLKEM768CGO returns an error when CGO is disabled
+func NewMLKEM768CGO() (KEM, error) {
+	return nil, errors.New("CGO disabled, using pure Go implementation")
+}
+
+// NewMLKEM1024CGO returns an error when CGO is disabled
+func NewMLKEM1024CGO() (KEM, error) {
+	return nil, errors.New("CGO disabled, using pure Go implementation")
+}

kem/x25519.go

@@ -0,0 +1,156 @@
+package kem
+
+import (
+	"crypto/rand"
+	"crypto/subtle"
+	"errors"
+
+	"golang.org/x/crypto/curve25519"
+)
+
+// X25519Impl implements X25519 as a KEM
+type X25519Impl struct{}
+
+// NewX25519 creates a new X25519 KEM instance
+func NewX25519() KEM {
+	return &X25519Impl{}
+}
+
+// X25519PublicKey represents an X25519 public key
+type X25519PublicKey struct {
+	data [32]byte
+}
+
+// X25519PrivateKey represents an X25519 private key  
+type X25519PrivateKey struct {
+	data [32]byte
+	pk   *X25519PublicKey
+}
+
+// GenerateKeyPair generates a new X25519 key pair
+func (x *X25519Impl) GenerateKeyPair() (PublicKey, PrivateKey, error) {
+	sk := &X25519PrivateKey{}
+	
+	// Generate random private key
+	if _, err := rand.Read(sk.data[:]); err != nil {
+		return nil, nil, err
+	}
+	
+	// Clamp private key as per X25519 spec
+	sk.data[0] &= 248
+	sk.data[31] &= 127
+	sk.data[31] |= 64
+	
+	// Compute public key
+	pk := &X25519PublicKey{}
+	curve25519.ScalarBaseMult(&pk.data, &sk.data)
+	sk.pk = pk
+	
+	return pk, sk, nil
+}
+
+// Encapsulate generates ephemeral key and shared secret
+func (x *X25519Impl) Encapsulate(pk PublicKey) ([]byte, []byte, error) {
+	x25519PK, ok := pk.(*X25519PublicKey)
+	if !ok {
+		return nil, nil, errors.New("invalid public key type for X25519")
+	}
+	
+	// Generate ephemeral key pair
+	ephSK := &X25519PrivateKey{}
+	if _, err := rand.Read(ephSK.data[:]); err != nil {
+		return nil, nil, err
+	}
+	
+	// Clamp ephemeral private key
+	ephSK.data[0] &= 248
+	ephSK.data[31] &= 127
+	ephSK.data[31] |= 64
+	
+	// Compute ephemeral public key (ciphertext)
+	ephPK := &X25519PublicKey{}
+	curve25519.ScalarBaseMult(&ephPK.data, &ephSK.data)
+	
+	// Compute shared secret
+	var sharedSecret [32]byte
+	curve25519.ScalarMult(&sharedSecret, &ephSK.data, &x25519PK.data)
+	
+	// Check for low-order points
+	if isLowOrder(sharedSecret[:]) {
+		return nil, nil, errors.New("low-order shared secret")
+	}
+	
+	return ephPK.data[:], sharedSecret[:], nil
+}
+
+// Decapsulate recovers shared secret using private key
+func (x *X25519Impl) Decapsulate(sk PrivateKey, ciphertext []byte) ([]byte, error) {
+	x25519SK, ok := sk.(*X25519PrivateKey)
+	if !ok {
+		return nil, errors.New("invalid private key type for X25519")
+	}
+	
+	if len(ciphertext) != 32 {
+		return nil, errors.New("invalid ciphertext size for X25519")
+	}
+	
+	var ephPK [32]byte
+	copy(ephPK[:], ciphertext)
+	
+	// Compute shared secret
+	var sharedSecret [32]byte
+	curve25519.ScalarMult(&sharedSecret, &x25519SK.data, &ephPK)
+	
+	// Check for low-order points
+	if isLowOrder(sharedSecret[:]) {
+		return nil, errors.New("low-order shared secret")
+	}
+	
+	return sharedSecret[:], nil
+}
+
+// isLowOrder checks if the point is low-order
+func isLowOrder(p []byte) bool {
+	// Check against known low-order points
+	var allZero [32]byte
+	return subtle.ConstantTimeCompare(p, allZero[:]) == 1
+}
+
+// Size methods for X25519
+func (x *X25519Impl) PublicKeySize() int   { return 32 }
+func (x *X25519Impl) PrivateKeySize() int  { return 32 }
+func (x *X25519Impl) CiphertextSize() int  { return 32 }
+func (x *X25519Impl) SharedSecretSize() int { return 32 }
+
+// Bytes returns the public key bytes
+func (pk *X25519PublicKey) Bytes() []byte {
+	return pk.data[:]
+}
+
+// Equal checks if two public keys are equal
+func (pk *X25519PublicKey) Equal(other PublicKey) bool {
+	otherPK, ok := other.(*X25519PublicKey)
+	if !ok {
+		return false
+	}
+	return subtle.ConstantTimeCompare(pk.data[:], otherPK.data[:]) == 1
+}
+
+// Bytes returns the private key bytes
+func (sk *X25519PrivateKey) Bytes() []byte {
+	return sk.data[:]
+}
+
+// Public returns the public key
+func (sk *X25519PrivateKey) Public() PublicKey {
+	return sk.pk
+}
+
+// Equal checks if two private keys are equal
+func (sk *X25519PrivateKey) Equal(other PrivateKey) bool {
+	otherSK, ok := other.(*X25519PrivateKey)
+	if !ok {
+		return false
+	}
+	return subtle.ConstantTimeCompare(sk.data[:], otherSK.data[:]) == 1
+}

sign/mldsa.go

@@ -0,0 +1,286 @@
+// Package sign provides post-quantum signature algorithms
+package sign
+
+import (
+	"crypto/rand"
+	"crypto/subtle"
+	"errors"
+	"fmt"
+)
+
+// SigID identifies a signature algorithm
+type SigID string
+
+const (
+	MLDSA2  SigID = "mldsa2"
+	MLDSA3  SigID = "mldsa3"
+	SLHDSA  SigID = "slhdsa"
+)
+
+// Signer interface for signature algorithms
+type Signer interface {
+	// GenerateKeyPair generates a new signing key pair
+	GenerateKeyPair() (PublicKey, PrivateKey, error)
+	
+	// Sign creates a signature
+	Sign(sk PrivateKey, message []byte) ([]byte, error)
+	
+	// Verify verifies a signature
+	Verify(pk PublicKey, message, signature []byte) bool
+	
+	// PublicKeySize returns the size of public keys
+	PublicKeySize() int
+	
+	// PrivateKeySize returns the size of private keys
+	PrivateKeySize() int
+	
+	// SignatureSize returns the size of signatures
+	SignatureSize() int
+}
+
+// PublicKey represents a signature public key
+type PublicKey interface {
+	Bytes() []byte
+	Equal(PublicKey) bool
+}
+
+// PrivateKey represents a signature private key
+type PrivateKey interface {
+	Bytes() []byte
+	Public() PublicKey
+	Equal(PrivateKey) bool
+}
+
+// MLDSA2Impl implements ML-DSA-44 (Dilithium2)
+type MLDSA2Impl struct{}
+
+// NewMLDSA2 creates a new ML-DSA-44 instance
+func NewMLDSA2() Signer {
+	return &MLDSA2Impl{}
+}
+
+// MLDSA2PublicKey represents an ML-DSA-44 public key
+type MLDSA2PublicKey struct {
+	data []byte
+}
+
+// MLDSA2PrivateKey represents an ML-DSA-44 private key
+type MLDSA2PrivateKey struct {
+	data []byte
+	pk   *MLDSA2PublicKey
+}
+
+// Constants for ML-DSA-44 (Dilithium2)
+const (
+	mldsa2PublicKeySize  = 1312
+	mldsa2PrivateKeySize = 2528
+	mldsa2SignatureSize  = 2420
+)
+
+// GenerateKeyPair generates a new ML-DSA-44 key pair
+func (m *MLDSA2Impl) GenerateKeyPair() (PublicKey, PrivateKey, error) {
+	// Placeholder for actual ML-DSA key generation
+	// In production, this would use liboqs or native implementation
+	
+	pk := &MLDSA2PublicKey{
+		data: make([]byte, mldsa2PublicKeySize),
+	}
+	sk := &MLDSA2PrivateKey{
+		data: make([]byte, mldsa2PrivateKeySize),
+		pk:   pk,
+	}
+	
+	// Generate random key material (placeholder)
+	if _, err := rand.Read(pk.data); err != nil {
+		return nil, nil, err
+	}
+	if _, err := rand.Read(sk.data); err != nil {
+		return nil, nil, err
+	}
+	
+	return pk, sk, nil
+}
+
+// Sign creates a signature
+func (m *MLDSA2Impl) Sign(sk PrivateKey, message []byte) ([]byte, error) {
+	mldsaSK, ok := sk.(*MLDSA2PrivateKey)
+	if !ok {
+		return nil, errors.New("invalid private key type")
+	}
+	
+	signature := make([]byte, mldsa2SignatureSize)
+	
+	// Placeholder for actual ML-DSA signing
+	if _, err := rand.Read(signature); err != nil {
+		return nil, err
+	}
+	
+	// In production, this would perform actual ML-DSA signing
+	_ = mldsaSK.data
+	_ = message
+	
+	return signature, nil
+}
+
+// Verify verifies a signature
+func (m *MLDSA2Impl) Verify(pk PublicKey, message, signature []byte) bool {
+	mldsaPK, ok := pk.(*MLDSA2PublicKey)
+	if !ok {
+		return false
+	}
+	
+	if len(signature) != mldsa2SignatureSize {
+		return false
+	}
+	
+	// Placeholder for actual ML-DSA verification
+	// In production, this would perform actual verification
+	_ = mldsaPK.data
+	_ = message
+	_ = signature
+	
+	// Placeholder: always return true for now
+	return true
+}
+
+// Size methods for ML-DSA-44
+func (m *MLDSA2Impl) PublicKeySize() int  { return mldsa2PublicKeySize }
+func (m *MLDSA2Impl) PrivateKeySize() int { return mldsa2PrivateKeySize }
+func (m *MLDSA2Impl) SignatureSize() int  { return mldsa2SignatureSize }
+
+// PublicKey methods
+func (pk *MLDSA2PublicKey) Bytes() []byte {
+	return pk.data
+}
+
+func (pk *MLDSA2PublicKey) Equal(other PublicKey) bool {
+	otherPK, ok := other.(*MLDSA2PublicKey)
+	if !ok {
+		return false
+	}
+	return subtle.ConstantTimeCompare(pk.data, otherPK.data) == 1
+}
+
+// PrivateKey methods
+func (sk *MLDSA2PrivateKey) Bytes() []byte {
+	return sk.data
+}
+
+func (sk *MLDSA2PrivateKey) Public() PublicKey {
+	return sk.pk
+}
+
+func (sk *MLDSA2PrivateKey) Equal(other PrivateKey) bool {
+	otherSK, ok := other.(*MLDSA2PrivateKey)
+	if !ok {
+		return false
+	}
+	return subtle.ConstantTimeCompare(sk.data, otherSK.data) == 1
+}
+
+// MLDSA3Impl implements ML-DSA-65 (Dilithium3)
+type MLDSA3Impl struct{}
+
+// NewMLDSA3 creates a new ML-DSA-65 instance
+func NewMLDSA3() Signer {
+	return &MLDSA3Impl{}
+}
+
+// Constants for ML-DSA-65 (Dilithium3)
+const (
+	mldsa3PublicKeySize  = 1952
+	mldsa3PrivateKeySize = 4000
+	mldsa3SignatureSize  = 3293
+)
+
+// GenerateKeyPair generates a new ML-DSA-65 key pair
+func (m *MLDSA3Impl) GenerateKeyPair() (PublicKey, PrivateKey, error) {
+	pk := &MLDSA2PublicKey{
+		data: make([]byte, mldsa3PublicKeySize),
+	}
+	sk := &MLDSA2PrivateKey{
+		data: make([]byte, mldsa3PrivateKeySize),
+		pk:   pk,
+	}
+	
+	if _, err := rand.Read(pk.data); err != nil {
+		return nil, nil, err
+	}
+	if _, err := rand.Read(sk.data); err != nil {
+		return nil, nil, err
+	}
+	
+	return pk, sk, nil
+}
+
+// Sign creates a signature
+func (m *MLDSA3Impl) Sign(sk PrivateKey, message []byte) ([]byte, error) {
+	signature := make([]byte, mldsa3SignatureSize)
+	
+	if _, err := rand.Read(signature); err != nil {
+		return nil, err
+	}
+	
+	return signature, nil
+}
+
+// Verify verifies a signature
+func (m *MLDSA3Impl) Verify(pk PublicKey, message, signature []byte) bool {
+	if len(signature) != mldsa3SignatureSize {
+		return false
+	}
+	
+	// Placeholder
+	return true
+}
+
+// Size methods for ML-DSA-65
+func (m *MLDSA3Impl) PublicKeySize() int  { return mldsa3PublicKeySize }
+func (m *MLDSA3Impl) PrivateKeySize() int { return mldsa3PrivateKeySize }
+func (m *MLDSA3Impl) SignatureSize() int  { return mldsa3SignatureSize }
+
+// GetSigner returns a Signer implementation for the given ID
+func GetSigner(id SigID) (Signer, error) {
+	switch id {
+	case MLDSA2:
+		return NewMLDSA2(), nil
+	case MLDSA3:
+		return NewMLDSA3(), nil
+	case SLHDSA:
+		// SLH-DSA would require additional implementation
+		return nil, errors.New("SLH-DSA not yet implemented")
+	default:
+		return nil, fmt.Errorf("unsupported signature algorithm: %s", id)
+	}
+}
+
+// TranscriptSigner signs protocol transcripts
+type TranscriptSigner struct {
+	signer Signer
+	sk     PrivateKey
+}
+
+// NewTranscriptSigner creates a new transcript signer
+func NewTranscriptSigner(signer Signer, sk PrivateKey) *TranscriptSigner {
+	return &TranscriptSigner{
+		signer: signer,
+		sk:     sk,
+	}
+}
+
+// SignTranscript signs a protocol transcript
+func (ts *TranscriptSigner) SignTranscript(transcript []byte) ([]byte, error) {
+	// Add context string to prevent cross-protocol attacks
+	context := []byte("QZMQ-Transcript-v1")
+	message := append(context, transcript...)
+	
+	return ts.signer.Sign(ts.sk, message)
+}
+
+// VerifyTranscript verifies a transcript signature
+func VerifyTranscript(signer Signer, pk PublicKey, transcript, signature []byte) bool {
+	context := []byte("QZMQ-Transcript-v1")
+	message := append(context, transcript...)
+	
+	return signer.Verify(pk, message, signature)
+}