pqauth-core

Core cryptographic primitives and JWT utilities for the PQAuth SDK. Provides digital signatures, key generation, hashing, JWKS management, and token blacklisting — all unified behind clean interfaces that cover both classical and post-quantum algorithms.

This module is the foundation that all other PQAuth modules build on. You can also use it standalone if you only need crypto or JWT functionality.

Supported algorithms

Digital signatures (JWT signing)

Algorithm	Type	Standard
HS256, HS384, HS512	HMAC-SHA2	RFC 7518
RS256, RS384, RS512	RSASSA-PKCS1-v1_5	RFC 7518
PS256, PS384, PS512	RSASSA-PSS	RFC 7518
ES256, ES384, ES512	ECDSA (P-256/384/521)	RFC 7518
EdDSA	Ed25519	RFC 8037
ML-DSA-44, ML-DSA-65, ML-DSA-87	CRYSTALS-Dilithium (NIST FIPS 204)	Post-quantum
SLH-DSA-SHA2-128f/s, SLH-DSA-SHA2-192f/s, SLH-DSA-SHA2-256f/s	SPHINCS+ SHA2 (NIST FIPS 205)	Post-quantum
SLH-DSA-SHAKE-128f/s, SLH-DSA-SHAKE-192f/s, SLH-DSA-SHAKE-256f/s	SPHINCS+ SHAKE (NIST FIPS 205)	Post-quantum
Falcon-512-Compressed, Falcon-512-Padded	Falcon-512	Post-quantum
Falcon-1024-Compressed, Falcon-1024-Padded	Falcon-1024	Post-quantum

Hashing

MD5, SHA-1, SHA-224/256/384/512, SHA3-224/256/384/512, SHAKE128, SHAKE256

Installation

go get github.com/PQAuth/pqauth-core

Note: Falcon-512 and Falcon-1024 use CGO (they wrap the Falcon C reference implementation). Your build environment needs gcc and musl-dev (Alpine) or build-essential (Debian/Ubuntu).

Quick start

Generate a key pair and sign a JWT

package main

import (
    "fmt"
    "time"

    "github.com/PQAuth/pqauth-core/cryptography"
    "github.com/PQAuth/pqauth-core/jwt"
)

func main() {
    // Generate an ML-DSA-65 key pair (post-quantum)
    keyGen := cryptography.NewDefaultKeyGenerationUtil()
    keyPair, err := keyGen.GenerateKeyPair(cryptography.ML_DSA_65)
    if err != nil {
        panic(err)
    }

    // Create a JWT helper
    jwtHelper := jwt.NewJWTHelper()

    // Sign a token
    signingKey := &jwt.SigningKey{Key: keyPair.PrivateKey, Algorithm: cryptography.ML_DSA_65}
    token, err := jwtHelper.Sign(jwt.JWTOptions{
        Algorithm: cryptography.ML_DSA_65,
        Payload: jwt.JWTPayload{
            Subject:  "user-123",
            Issuer:   "https://auth.example.com",
            Audience: jwt.ClaimAudience{"https://api.example.com"},
            IssuedAt: jwt.NewNumericDate(time.Now()),
            Expiry:   jwt.NewNumericDate(time.Now().Add(time.Hour)),
        },
    }, signingKey)
    if err != nil {
        panic(err)
    }

    fmt.Println("Token:", token)

    // Verify the token
    verificationKey := &jwt.VerificationKey{Key: keyPair.PublicKey, Algorithm: cryptography.ML_DSA_65}
    result, err := jwtHelper.Validate(token, jwt.ValidationOptions{
        AllowedAlgorithms: []string{cryptography.ML_DSA_65},
        RequiredIssuer:    "https://auth.example.com",
        RequiredAudience:  []string{"https://api.example.com"},
    }, verificationKey)
    if err != nil {
        panic(err)
    }

    fmt.Println("Subject:", result.Subject)
}

Hash a value

hasher := cryptography.NewDefaultHasher()

// SHA3-256
hash, err := hasher.HashSHA3_256([]byte("hello world"))

// SHAKE256 (variable output length)
hash, err = hasher.HashSHAKE256([]byte("hello world"), 32)

JWKS management

// Build a JWKS from existing keys
mgr := jwt.NewJWKSManager()
mgr.AddKey("key-1", &jwt.SigningKey{Key: privateKey, Algorithm: cryptography.ML_DSA_65})

jwksJSON, err := mgr.ToJSON()   // serve at /.well-known/jwks.json

// Load from a remote JWKS
mgr2 := jwt.NewJWKSManager()
err = mgr2.FromJSON(body)
verifyKey, err := mgr2.GetKey("key-1")

Algorithm negotiation

// Server prefers PQ-first, falls back to classical
serverPreference := []string{"ML-DSA-65", "ML-DSA-44", "ES256", "RS256"}
clientSupported  := []string{"RS256", "ES256"}

alg, ok := cryptography.NegotiateAlgorithm(serverPreference, clientSupported)
// alg = "ES256" (best match between server preference and client support)

Packages

Package	Description
cryptography	Digital signatures, key generation, key serialization, hashing, algorithm helpers
jwt	JWT encode/decode/sign/verify/validate, JWKS manager, token blacklist
models	Shared OAuth 2.0 / OIDC data types (User, Client, AccessToken, RefreshToken, DeviceCode, etc.)

Key types

// KeyPair — unified container for any algorithm
type KeyPair struct {
    PrivateKey interface{}
    PublicKey  interface{}
    Algorithm  string
    KeySize    int
}

// JWT — parsed token
type JWT struct {
    Header    JWTHeader
    Payload   JWTPayload
    Signature []byte
    Raw       string
}

// JWTPayload — standard + custom claims
type JWTPayload struct {
    Issuer   string
    Subject  string
    Audience ClaimAudience
    Expiry   *NumericDate
    IssuedAt *NumericDate
    JWTID    string
    Custom   map[string]interface{}
}

Token blacklist

// In-memory blacklist (use a distributed cache for multi-instance deployments)
blacklist := jwt.NewInMemoryTokenBlacklist()

jwtHelper.Validate(token, jwt.ValidationOptions{
    Blacklist: blacklist,
}, verificationKey)

// Revoke a token
blacklist.Blacklist(jti, expiresAt)

Algorithm helpers

cryptography.IsPQCAlgorithm("ML-DSA-65")  // true
cryptography.IsPQCAlgorithm("RS256")       // false

cryptography.FilterPQCAlgorithms([]string{"RS256", "ML-DSA-65", "ES256"})
// returns []string{"ML-DSA-65"}

Related modules

Module	Description
pqauth-auth-svr	OAuth 2.0 Authorization Server
pqauth-resource-svr	Resource server token validation
pqauth-svr-core	Database and cache abstractions
pqauth-client	OAuth 2.0 client SDK

License

MIT