Educational Project: Post-Quantum Safe Utility Cryptography created with Agentic AI
gopq is an educational project to demonstrate:
Overview
gopq provides reusable Go functions for PQC algorithms; ML-DSA for signing, and ML-KEM for encryption.
Note: gopq is for demonstration and educational purposes only. Do not use in production.
The implementation uses the Cloudflare CIRCL library.
Installation
go get github.com/cloudflare/circl@latest
Clone or vendor this repository as needed:
git clone https://github.com/justincranford/gopq.git
ML-DSA (ML-DSA-87) Example
import "gopq/pq"
// Generate a random ML-DSA keypair
mldsaKey, err := pq.GenerateMLDSAKeyPair()
if err != nil {
// handle error
}
// Deterministic keypair (from seed)
var seed [48]byte // 48 is the seed size for ML-DSA-87
detDSAKey, err := pq.DeriveMLDSAKeyPair(&seed)
// Sign a message
message := []byte("hello world")
signature, err := pq.MLDSASign(mldsaKey.PrivateKey, message)
if err != nil {
// handle error
}
// Verify a signature
valid, err := pq.MLDSAVerify(mldsaKey.PublicKey, message, signature)
if err != nil {
// handle error
}
if !valid {
// signature invalid
}ML-KEM (Kyber KEM) Example
import "github.com/cloudflare/circl/kem/kyber/kyber1024"
import "gopq/pq"
// Generate a random Kyber1024 KEM keypair
mlkemKey, err := pq.GenerateMLKEMKeyPair()
if err != nil {
// handle error
}
// Serialize and deserialize keys
pubBytes, _ := pq.MarshalPublicKey(mlkemKey.PublicKey)
privBytes, _ := pq.MarshalPrivateKey(mlkemKey.PrivateKey)
pub, _ := pq.UnmarshalPublicKey(pubBytes)
priv, _ := pq.UnmarshalPrivateKey(privBytes)
// Encapsulate a shared secret
ciphertext, sharedSecret, err := pq.MLKEMEncapsulate(pub)
// Decapsulate the shared secret
recoveredSecret, err := pq.MLKEMDecapsulate(priv, ciphertext)
// Deterministic keypair (for KATs)
seed := make([]byte, kyber1024.Scheme().SeedSize())
detKey, err := pq.GenerateDeterministicMLKEMKeyPair(seed)
// Deterministic encapsulation (for KATs)
encSeed := make([]byte, kyber1024.Scheme().EncapsulationSeedSize())
ct, shared, err := pq.MLKEMEncapsulateDeterministic(detKey.PublicKey, encSeed)Testing
Run all tests and benchmarks:
go test -v -bench=. ./pq
Documentation
To generate and view GoDoc documentation locally:
- Install the godoc tool (if not already installed):
go install golang.org/x/tools/cmd/godoc@latest - Start the documentation server:
godoc -http=:6060 - Open the documentation link http://localhost:6060/pkg/gopq/pq in your browser.
start http://localhost:6060/pkg/gopq/pq/
Security Notes
- This library is for demonstration and educational use only.
- For production, use vetted libraries and follow NIST and FIPS 140-3 guidance.
- Never log or expose private keys or shared secrets in production.
Overview
This project was developed using an Agentic AI workflow, leveraging:
- VS Code
- GitHub Copilot
- Custom instruction and prompt files
Settings
The main configuration file is .vscode/settings.json.
It specifies the instruction and prompt files to use.
Instruction Files
All instruction files are in the .github/instructions/ directory.
AI
Development
- commit-instructions.md
- coding-instructions.md
- go-instructions.md
- security-instructions.md
- doc-instructions.md
- project-instructions.md
Testing
Instruction files ensure that all human contributors and AI personas follow the same standards.
Design intent for the instruction files is to be generic and reusable for my other R&D projects. The main exception is project-instructions file, which contains project-specific context.
Prompt Files
All prompt files are in the .github/prompts/ directory.
Prompt files are personas for AI Agents to adopt more focused context when performing tasks. See Additional Details.
Additional Details
Instruction files define standards and rules that apply to both human contributors and AI agents.
When a human contributor interacts with Agentic AI:
- Using Copilot Chat, the AI agent follows all instructions in a general context (no specific persona).
- Using a Persona Prompt, the AI agent follows all instructions, but adopts the perspective and goals of the selected persona.
AI effectiveness can increase when given more specific and narrow context.
For example, you can get good but mixed results using Copilot Chat. Switching to a persona (e.g., Dev, QA, PM) can narrow the context, and help AI give you the better expertise and results you were expecting.