pqc-binary-format 2.0.2

// Package pqcbinaryformat provides pure Go implementation of PQC Binary Format v1.0
//
// This package implements the PQC Binary Format specification for post-quantum
// cryptographic data encapsulation. It provides constant-time parsing and
// serialization of encrypted data with support for 47 cryptographic algorithms
// including HQC, ML-KEM, ML-DSA, and SLH-DSA NIST FIPS standards.
//
// Example usage:
//
//	// Create a new format
//	format := &PqcBinaryFormat{
//		Version:     1,
//		AlgorithmID: AlgorithmHybrid,
//		Metadata:    []byte(`{"key":"value"}`),
//		Data:        encryptedData,
//	}
//	binary, err := format.Serialize()
//
//	// Parse existing format
//	format, err := Parse(binaryData)
//	fmt.Printf("Algorithm: %s\n", format.AlgorithmName())
package pqcbinaryformat

import (
	"bytes"
	"crypto/sha256"
	"encoding/binary"
	"errors"
	"fmt"
)

// Magic bytes identifying PQC Binary Format
var MagicBytes = []byte{0x50, 0x51, 0x43, 0x01} // "PQC\x01"

// Version constants
const (
	Version1 byte = 0x01
)

// Algorithm IDs - Core Algorithms
const (
	AlgorithmClassical         uint16 = 0x0050
	AlgorithmPasswordClassical uint16 = 0x0051
	AlgorithmHybrid            uint16 = 0x0100
	AlgorithmPostQuantum       uint16 = 0x0200
	AlgorithmMlKem1024         uint16 = 0x0202
	AlgorithmMultiAlgorithm    uint16 = 0x0201
)

// Algorithm IDs - Multi-KEM Series
const (
	AlgorithmMultiKem       uint16 = 0x0203
	AlgorithmMultiKemTriple uint16 = 0x0204
	AlgorithmQuadLayer      uint16 = 0x0205
)

// Algorithm IDs - Advanced Stacks
const (
	AlgorithmLatticeCodeHybrid uint16 = 0x0206
	AlgorithmPq3Stack          uint16 = 0x0207
)

// Algorithm IDs - Max Secure Series
const (
	AlgorithmMaxSecureLightweight      uint16 = 0x0300
	AlgorithmMaxSecurePurePQ           uint16 = 0x0301
	AlgorithmMaxSecureHybrid           uint16 = 0x0302
	AlgorithmMaxSecureStateless        uint16 = 0x0303
	AlgorithmMaxSecureCryptoAgile      uint16 = 0x0304
	AlgorithmMaxSecurePQCZK            uint16 = 0x0305
	AlgorithmMaxSecureHybridTransition uint16 = 0x0306
)

// Algorithm IDs - FN-DSA Signature Series
const (
	AlgorithmFnDsa512Compact      uint16 = 0x0400
	AlgorithmFnDsa1024Security    uint16 = 0x0401
	AlgorithmFnDsaFPHardened      uint16 = 0x0402
	AlgorithmFnDsaDualSignature   uint16 = 0x0403
	AlgorithmFnDsaTransition      uint16 = 0x0404
	AlgorithmFnDsaZK              uint16 = 0x0405
	AlgorithmFnDsaZKStack         uint16 = 0x0406
	AlgorithmFnDsaTransitionStack uint16 = 0x0407
)

// Algorithm IDs - Experimental Series
const (
	AlgorithmQuantumLatticeFusion      uint16 = 0x0500
	AlgorithmPostZKHomomorphic         uint16 = 0x0501
	AlgorithmQuantumResistantConsensus uint16 = 0x0502
	AlgorithmEntropyOrchestrated       uint16 = 0x0503
	AlgorithmLatticeCodeHybridFn       uint16 = 0x0504
	AlgorithmAISynthesizedCryptoAgile  uint16 = 0x0505
	AlgorithmExperimental              uint16 = 0x0506
)

// Algorithm IDs - HQC Code-Based Series (NIST 2025 Backup KEM)
const (
	AlgorithmHqc128 uint16 = 0x0600
	AlgorithmHqc192 uint16 = 0x0601
	AlgorithmHqc256 uint16 = 0x0602
)

// Algorithm IDs - NIST ML-KEM Variants (FIPS 203)
const (
	AlgorithmMlKem512 uint16 = 0x0700
	AlgorithmMlKem768 uint16 = 0x0701
)

// Algorithm IDs - NIST ML-DSA Variants (FIPS 204)
const (
	AlgorithmMlDsa44 uint16 = 0x0800
	AlgorithmMlDsa65 uint16 = 0x0801
	AlgorithmMlDsa87 uint16 = 0x0802
)

// Algorithm IDs - NIST SLH-DSA Variants (FIPS 205)
const (
	AlgorithmSlhDsaSha2_128s uint16 = 0x0900
	AlgorithmSlhDsaSha2_128f uint16 = 0x0901
	AlgorithmSlhDsaSha2_192s uint16 = 0x0902
	AlgorithmSlhDsaSha2_192f uint16 = 0x0903
	AlgorithmSlhDsaSha2_256s uint16 = 0x0904
	AlgorithmSlhDsaSha2_256f uint16 = 0x0905
)

// Algorithm name mappings
var algorithmNames = map[uint16]string{
	AlgorithmClassical:                 "Classical",
	AlgorithmPasswordClassical:         "Password-Classical",
	AlgorithmHybrid:                    "Hybrid",
	AlgorithmPostQuantum:               "Post-Quantum",
	AlgorithmMlKem1024:                 "ML-KEM-1024",
	AlgorithmMultiAlgorithm:            "Multi-Algorithm",
	AlgorithmMultiKem:                  "Multi-KEM Dual Layer",
	AlgorithmMultiKemTriple:            "Multi-KEM Triple Layer",
	AlgorithmQuadLayer:                 "Quad-Layer",
	AlgorithmLatticeCodeHybrid:         "Lattice-Code Hybrid",
	AlgorithmPq3Stack:                  "PQ3-Stack",
	AlgorithmMaxSecureLightweight:      "Max Secure: PQ Lightweight",
	AlgorithmMaxSecurePurePQ:           "Max Secure: Pure PQ",
	AlgorithmMaxSecureHybrid:           "Max Secure: Hybrid",
	AlgorithmMaxSecureStateless:        "Max Secure: Stateless",
	AlgorithmMaxSecureCryptoAgile:      "Max Secure: Crypto-Agile",
	AlgorithmMaxSecurePQCZK:            "Max Secure: PQC + ZK",
	AlgorithmMaxSecureHybridTransition: "Max Secure: Hybrid Transition",
	AlgorithmFnDsa512Compact:           "FN-DSA 512: Compact",
	AlgorithmFnDsa1024Security:         "FN-DSA 1024: High-Security",
	AlgorithmFnDsaFPHardened:           "FN-DSA: Floating-Point Hardened",
	AlgorithmFnDsaDualSignature:        "FN-DSA: Dual Signature",
	AlgorithmFnDsaTransition:           "FN-DSA: Transition Stack",
	AlgorithmFnDsaZK:                   "FN-DSA + ZK Stack",
	AlgorithmFnDsaZKStack:              "FN-DSA + ZK Stack Enhanced",
	AlgorithmFnDsaTransitionStack:      "FN-DSA: Transition Stack Enhanced",
	AlgorithmQuantumLatticeFusion:      "Quantum-Inspired Lattice Fusion",
	AlgorithmPostZKHomomorphic:         "Post-ZK Homomorphic",
	AlgorithmQuantumResistantConsensus: "Quantum-Resistant Consensus",
	AlgorithmEntropyOrchestrated:       "Entropy-Orchestrated",
	AlgorithmLatticeCodeHybridFn:       "Lattice-Code Hybrid FN",
	AlgorithmAISynthesizedCryptoAgile:  "AI-Synthesized Crypto-Agile",
	AlgorithmExperimental:              "Experimental Engine",
	AlgorithmHqc128:                    "HQC-128",
	AlgorithmHqc192:                    "HQC-192",
	AlgorithmHqc256:                    "HQC-256",
	AlgorithmMlKem512:                  "ML-KEM-512",
	AlgorithmMlKem768:                  "ML-KEM-768",
	AlgorithmMlDsa44:                   "ML-DSA-44",
	AlgorithmMlDsa65:                   "ML-DSA-65",
	AlgorithmMlDsa87:                   "ML-DSA-87",
	AlgorithmSlhDsaSha2_128s:           "SLH-DSA-SHA2-128s",
	AlgorithmSlhDsaSha2_128f:           "SLH-DSA-SHA2-128f",
	AlgorithmSlhDsaSha2_192s:           "SLH-DSA-SHA2-192s",
	AlgorithmSlhDsaSha2_192f:           "SLH-DSA-SHA2-192f",
	AlgorithmSlhDsaSha2_256s:           "SLH-DSA-SHA2-256s",
	AlgorithmSlhDsaSha2_256f:           "SLH-DSA-SHA2-256f",
}

// Errors
var (
	ErrInvalidMagic    = errors.New("invalid magic bytes")
	ErrInvalidVersion  = errors.New("invalid version")
	ErrInvalidChecksum = errors.New("invalid checksum")
	ErrInvalidLength   = errors.New("invalid data length")
	ErrBufferTooSmall  = errors.New("buffer too small")
)

// PqcBinaryFormat represents a PQC Binary Format structure
type PqcBinaryFormat struct {
	// Magic bytes (always "PQC\x01")
	Magic []byte

	// Version (currently 0x01)
	Version byte

	// Algorithm identifier (16-bit)
	AlgorithmID uint16

	// Feature flags (reserved, MUST be 0x00 in version 0x01)
	Flags byte

	// Metadata length (32-bit)
	MetadataLen uint32

	// Data length (64-bit)
	DataLen uint64

	// Algorithm-specific metadata
	Metadata []byte

	// Encrypted payload
	Data []byte

	// SHA-256 checksum (32 bytes)
	Checksum [32]byte
}

// New creates a new PqcBinaryFormat with the given parameters
func New(algorithmID uint16, metadata, data []byte) *PqcBinaryFormat {
	format := &PqcBinaryFormat{
		Magic:       make([]byte, 4),
		Version:     Version1,
		AlgorithmID: algorithmID,
		Flags:       0,
		MetadataLen: uint32(len(metadata)),
		DataLen:     uint64(len(data)),
		Metadata:    metadata,
		Data:        data,
	}
	copy(format.Magic, MagicBytes)
	return format
}

// Parse parses a PQC Binary Format from bytes
func Parse(data []byte) (*PqcBinaryFormat, error) {
	if len(data) < 52 { // Minimum size: 4 + 1 + 2 + 1 + 4 + 8 + 32 = 52 bytes
		return nil, ErrBufferTooSmall
	}

	format := &PqcBinaryFormat{}
	offset := 0

	// Parse magic bytes
	format.Magic = data[offset : offset+4]
	if !bytes.Equal(format.Magic, MagicBytes) {
		return nil, ErrInvalidMagic
	}
	offset += 4

	// Parse version
	format.Version = data[offset]
	if format.Version != Version1 {
		return nil, ErrInvalidVersion
	}
	offset += 1

	// Parse algorithm ID (little-endian)
	format.AlgorithmID = binary.LittleEndian.Uint16(data[offset : offset+2])
	offset += 2

	// Parse flags
	format.Flags = data[offset]
	offset += 1

	// Parse metadata length (little-endian)
	format.MetadataLen = binary.LittleEndian.Uint32(data[offset : offset+4])
	offset += 4

	// Parse metadata
	if int(format.MetadataLen) > len(data)-offset-32 {
		return nil, ErrInvalidLength
	}
	if format.MetadataLen > 0 {
		format.Metadata = data[offset : offset+int(format.MetadataLen)]
		offset += int(format.MetadataLen)
	}

	// Parse data length (little-endian)
	format.DataLen = binary.LittleEndian.Uint64(data[offset : offset+8])
	offset += 8

	// Validate total length
	totalLen := 52 + int(format.MetadataLen) + int(format.DataLen)
	if len(data) != totalLen {
		return nil, ErrInvalidLength
	}

	// Parse data (metadata was already consumed before the data length field)
	if format.DataLen > 0 {
		format.Data = data[offset : offset+int(format.DataLen)]
		offset += int(format.DataLen)
	}

	// Parse checksum
	copy(format.Checksum[:], data[offset:offset+32])
	offset += 32

	// Verify checksum
	if !format.VerifyChecksum() {
		return nil, ErrInvalidChecksum
	}

	return format, nil
}

// Serialize serializes the format to bytes with checksum
func (f *PqcBinaryFormat) Serialize() ([]byte, error) {
	// Calculate total size
	totalSize := 52 + len(f.Metadata) + len(f.Data)
	buf := make([]byte, totalSize)
	offset := 0

	// Write magic bytes
	copy(buf[offset:], MagicBytes)
	offset += 4

	// Write version
	buf[offset] = f.Version
	offset += 1

	// Write algorithm ID (little-endian)
	binary.LittleEndian.PutUint16(buf[offset:], f.AlgorithmID)
	offset += 2

	// Write flags
	buf[offset] = f.Flags
	offset += 1

	// Write metadata length (little-endian)
	binary.LittleEndian.PutUint32(buf[offset:], uint32(len(f.Metadata)))
	offset += 4

	// Write metadata
	if len(f.Metadata) > 0 {
		copy(buf[offset:], f.Metadata)
		offset += len(f.Metadata)
	}

	// Write data length (little-endian)
	binary.LittleEndian.PutUint64(buf[offset:], uint64(len(f.Data)))
	offset += 8

	// Write data
	if len(f.Data) > 0 {
		copy(buf[offset:], f.Data)
		offset += len(f.Data)
	}

	// Calculate checksum (everything except the checksum field itself)
	checksumData := buf[:offset]
	checksum := sha256.Sum256(checksumData)
	copy(buf[offset:], checksum[:])

	// Store checksum in struct
	f.Checksum = checksum

	return buf, nil
}

// VerifyChecksum verifies the SHA-256 checksum
func (f *PqcBinaryFormat) VerifyChecksum() bool {
	// Reconstruct the data that was checksummed
	buf := new(bytes.Buffer)

	// Write all fields except checksum, in spec order (little-endian)
	buf.Write(f.Magic)
	buf.WriteByte(f.Version)

	algID := make([]byte, 2)
	binary.LittleEndian.PutUint16(algID, f.AlgorithmID)
	buf.Write(algID)

	buf.WriteByte(f.Flags)

	metaLen := make([]byte, 4)
	binary.LittleEndian.PutUint32(metaLen, uint32(len(f.Metadata)))
	buf.Write(metaLen)

	buf.Write(f.Metadata)

	dataLen := make([]byte, 8)
	binary.LittleEndian.PutUint64(dataLen, uint64(len(f.Data)))
	buf.Write(dataLen)

	buf.Write(f.Data)

	// Calculate checksum
	calculated := sha256.Sum256(buf.Bytes())

	// Constant-time comparison
	return bytes.Equal(calculated[:], f.Checksum[:])
}

// AlgorithmName returns the human-readable algorithm name
func (f *PqcBinaryFormat) AlgorithmName() string {
	if name, ok := algorithmNames[f.AlgorithmID]; ok {
		return name
	}
	return fmt.Sprintf("Unknown-0x%04X", f.AlgorithmID)
}

// IsQuantumResistant returns true if the algorithm is quantum-resistant
func (f *PqcBinaryFormat) IsQuantumResistant() bool {
	// Classical algorithms are not quantum-resistant
	if f.AlgorithmID == AlgorithmClassical || f.AlgorithmID == AlgorithmPasswordClassical {
		return false
	}
	// All other algorithms in the spec are quantum-resistant or hybrid
	return true
}

// Size returns the total size of the serialized format in bytes
func (f *PqcBinaryFormat) Size() int {
	return 52 + len(f.Metadata) + len(f.Data)
}

// String returns a string representation of the format
func (f *PqcBinaryFormat) String() string {
	return fmt.Sprintf("PqcBinaryFormat{Version: %d, Algorithm: %s (0x%04X), MetadataLen: %d, DataLen: %d}",
		f.Version, f.AlgorithmName(), f.AlgorithmID, len(f.Metadata), len(f.Data))
}