GoPKI

Production-ready Go library for PKI operations with type-safe cryptography through Go generics. Full X.509, PKCS#7/CMS, PKCS#12, SSH, and JOSE (JWT/JWS/JWE/JWK) support with 80.3% test coverage across 900+ tests.

✨ Why GoPKI?

🔒 Type-Safe Cryptography: Go generics eliminate any/interface{} types for compile-time safety
🛡️ Security-First: Enforced minimum key sizes, secure file permissions, memory-safe APIs
📜 Standards Compliant: Full RFC compliance (X.509, CMS, PKCS#7, PKCS#12, SSH)
🤝 Battle-Tested: 95%+ OpenSSL compatibility, 100% OpenSSH compatibility
⚡ Production Ready: 80.3% test coverage, comprehensive CI/CD, semantic versioning

📦 Installation

go get github.com/jasoet/gopki

Requirements: Go 1.24.5+

🤖 AI Agent Instructions

If you're an AI assistant working on this codebase, start here:

📖 Comprehensive AI Navigation Guide

For complete AI agent guidance, read:

docs/AI_NAVIGATION.md - Comprehensive navigation guide for AI assistants

This README provides a quick reference. For detailed navigation paths, common bug patterns, module interaction patterns, and troubleshooting guides, see the AI Navigation document.

Quick Navigation by Task

Task	Read First	Read Next	Key Files
Key Generation/Management	`keypair/README.md`	`docs/ALGORITHMS.md`	`keypair/keypair.go`, `keypair/algo/*.go`
Encryption Features	`encryption/README.md`	`docs/ENCRYPTION_GUIDE.md`	`encryption/envelope/`, `encryption/asymmetric/`
Digital Signatures	`signing/README.md`	`docs/OPENSSL_COMPAT.md`	`signing/signer.go`, `signing/formats/`
Certificate Operations	`cert/README.md`	Certificate examples	`cert/cert.go`, `cert/ca.go`
PKCS#12 Files	`pkcs12/README.md`	Module tests	`pkcs12/pkcs12.go`
JOSE (JWT/JWS/JWE/JWK)	`jose/README.md`	JOSE modules	`jose/jwt/`, `jose/jws/`, `jose/jwe/`, `jose/jwk/`
OpenSSL Compatibility	`docs/OPENSSL_COMPAT.md`	`compatibility/` tests	`compatibility/helpers.go`
Testing	`Taskfile.yml`	Module-specific tests	`*_test.go` files

Understanding the Architecture

Step 1: Core Concepts

Read docs/ARCHITECTURE.md - System design and module relationships
Review CLAUDE.md - Detailed development guidelines and patterns
Check module dependency diagram below

Step 2: Type System

GoPKI uses Go generics extensively for type safety
Key type constraints defined in keypair/keypair.go:50-150
All modules follow these type patterns - review them first

Step 3: Format Support

PEM, DER, SSH, PKCS#12 formats all supported
Format conversion logic in format/ package
See module-specific READMEs for conversion patterns

Common Modification Patterns

Adding New Algorithm Support:

Read existing algorithm implementation in relevant algo/ directory
Check test patterns in *_algo_test.go
Verify compatibility test requirements in compatibility/
Update format conversion functions
Add to documentation and examples

Fixing Bugs:

Start with tests - Read *_test.go files first to understand expected behavior
Check recent changes: git log --oneline -10 <file>
Review error handling patterns in similar functions
Run specific tests: task test:specific -- TestName
Verify compatibility: task test:compatibility

Adding OpenSSL Compatibility:

Read docs/OPENSSL_COMPAT.md for current status
Review compatibility/helpers.go for OpenSSL integration patterns
Add test in appropriate compatibility/*/ directory
Update docs/COMPATIBILITY_REPORT.md with findings

Code Reading Order for New AI Agents

First Session (Core Understanding):

1. README.md (this file) - Project overview
2. CLAUDE.md - Development guidelines
3. docs/ARCHITECTURE.md - System design
4. keypair/README.md - Foundation module
5. encryption/README.md - Most complex module

For Specific Features:

Certificate Operations:
  cert/README.md → cert/cert.go → cert/ca.go → examples/certificates/

Encryption:
  encryption/README.md → encryption/envelope/envelope.go →
  encryption/asymmetric/*.go → compatibility/encryption/

Signing:
  signing/README.md → signing/signer.go → signing/formats/pkcs7.go →
  examples/signing/

Key Files Map

Core Type Definitions:

keypair/keypair.go:50-150 - Generic type constraints (START HERE)
encryption/types.go - Encryption types
signing/types.go - Signature types
cert/types.go - Certificate types

Main Implementations:

keypair/manager.go - Key pair management
encryption/envelope/envelope.go:150-450 - Envelope encryption
signing/signer.go:100-300 - Document signing
cert/ca.go:75-250 - Certificate authority operations

Testing Infrastructure:

compatibility/helpers.go - OpenSSL integration utilities
*_test.go - Unit tests (80.3% coverage)
examples/*/main.go - Integration examples

Project Conventions

Type Safety:

No any/interface{} in core APIs (exceptions: metadata maps only)
Use generic constraints from keypair/keypair.go
Compile-time type checking enforced

Security:

Minimum RSA key size: 2048 bits (enforced)
File permissions: 0600 (private keys), 0700 (directories)
No raw key material exposure in APIs

Error Handling:

All functions return explicit errors (no panics)
Errors wrapped with context: fmt.Errorf("context: %w", err)

Testing:

Run tests before changes: task test
Run specific tests: task test:specific -- TestName
Check coverage: task test:coverage
Verify compatibility: task test:compatibility

Getting Help

Documentation:

docs/AI_NAVIGATION.md - Comprehensive AI navigation guide ⭐
Module-specific READMEs for detailed API docs
docs/ directory for conceptual guides (ARCHITECTURE, ALGORITHMS, OPENSSL_COMPAT)
examples/ directory for working code
docs/COMPATIBILITY_REPORT.md for OpenSSL interoperability

Code Exploration:

Use task docs:serve to browse godoc locally (http://localhost:6060)
Check test files for usage examples
Review git history for context: git log -p <file>

When Stuck:

Understanding type system → Read keypair/keypair.go:50-150 first
Envelope encryption issues → See encryption/README.md AI Quick Start
OpenSSL compatibility → Read docs/OPENSSL_COMPAT.md
Module relationships → Read docs/ARCHITECTURE.md
Algorithm selection → Read docs/ALGORITHMS.md

Critical Resources for AI Agents:

docs/AI_NAVIGATION.md - Navigation paths, bug patterns, troubleshooting
keypair/README.md - Foundation module with complete file map
encryption/README.md - Most complex module, detailed structure
docs/ARCHITECTURE.md - System design and data flows
docs/OPENSSL_COMPAT.md - OpenSSL integration patterns

🏗️ Architecture

GoPKI is structured as six core modules with strong type relationships:

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   keypair/      │◄───┤     cert/        │◄───┤   signing/      │
│ Core Key Mgmt   │    │ X.509 Certs      │    │ Digital Sigs    │
│ (75.3% coverage)│    │ (74.3% coverage) │    │ (79.8% coverage)│
└─────────────────┘    └──────────────────┘    └─────────────────┘
         ▲                        ▲                       ▲
         │                        │                       │
         └────────┬───────────────┴───────────────────────┘
                  ▼                ▼                      ▼
         ┌─────────────────┐    ┌──────────────────┐   ┌─────────────────┐
         │  encryption/    │    │    pkcs12/       │   │     jose/       │
         │ Data Encryption │    │ PKCS#12 Files    │   │  JWT/JWS/JWE/JWK│
         │ (89.1% coverage)│    │ (79.1% coverage) │   │ (79.6% coverage)│
         └─────────────────┘    └──────────────────┘   └─────────────────┘

Module Documentation:

keypair/README.md - Foundation: Type-safe key generation and management
cert/README.md - X.509 certificates, CA operations, certificate chains
signing/README.md - Digital signatures, PKCS#7/CMS formats
encryption/README.md - Multi-algorithm encryption, envelope encryption
pkcs12/README.md - PKCS#12 file management and certificate bundling
jose/README.md - JOSE support: JWT, JWS, JWE, JWK for JSON-based security

Detailed Architecture: See docs/ARCHITECTURE.md for complete system design

🚀 Quick Start

Generate Key Pairs

import (
    "crypto/rsa"
    "github.com/jasoet/gopki/keypair"
    "github.com/jasoet/gopki/keypair/algo"
)

// Generate RSA key pair with Manager (recommended)
manager, _ := keypair.Generate[algo.KeySize, *algo.RSAKeyPair, *rsa.PrivateKey, *rsa.PublicKey](algo.KeySize2048)

// Save with secure permissions (0600 for private, 0644 for public)
manager.SaveToPEM("private.pem", "public.pem")

// Convert to different formats
privateSSH, publicSSH, _ := manager.ToSSH("user@host", "")
privateDER, publicDER, _ := manager.ToDER()

See keypair/README.md for complete key management documentation

Create Certificates

import (
    "crypto/x509/pkix"
    "time"
    "github.com/jasoet/gopki/cert"
    "github.com/jasoet/gopki/keypair/algo"
)

// Generate key pair
keyPair, _ := algo.GenerateRSAKeyPair(algo.KeySize2048)

// Create self-signed certificate
certificate, _ := cert.CreateSelfSignedCertificate(keyPair, cert.CertificateRequest{
    Subject: pkix.Name{CommonName: "example.com"},
    DNSNames: []string{"example.com", "www.example.com"},
    ValidFor: 365 * 24 * time.Hour,
})

See cert/README.md for CA operations and certificate chains

Sign Documents

import (
    "github.com/jasoet/gopki/signing"
)

// Sign document with key pair and certificate
document := []byte("Important contract")
signature, _ := signing.SignDocument(document, keyPair, certificate)

// Verify signature
_ = signing.VerifySignature(document, signature, signing.DefaultVerifyOptions())

See signing/README.md for PKCS#7/CMS signatures and advanced options

Encrypt Data

import (
    "github.com/jasoet/gopki/encryption"
)

// Encrypt for certificate recipient
encrypted, _ := encryption.EncryptForCertificate(
    []byte("Secret message"),
    certificate.Certificate,
    encryption.DefaultEncryptOptions(),
)

// Decrypt with private key
decrypted, _ := encryption.DecryptWithKeyPair(encrypted, keyPair)

See encryption/README.md for envelope encryption and multi-recipient support

📚 Examples

Comprehensive examples with complete documentation:

# Install Task runner
go install github.com/go-task/task/v3/cmd/task@latest

# Run all examples
task examples:run

# Run specific examples
task examples:keypair      # Key generation and format conversion
task examples:certificates # CA hierarchies and certificate chains
task examples:signing      # Document signing with multiple algorithms
task examples:encryption   # Data encryption with various methods

Example Documentation:

examples/keypair/doc.md - Key management examples
examples/certificates/doc.md - Certificate examples
examples/signing/doc.md - Signing examples
examples/encryption/doc.md - Encryption examples
examples/pkcs12/doc.md - PKCS#12 bundle examples

🔢 Algorithm Support

Algorithm	Key Sizes	Key Agreement	Signing	Encryption	Certificate
RSA	2048/3072/4096	❌	✅	✅	✅
ECDSA	P-224/256/384/521	✅ (ECDH)	✅	✅	✅
Ed25519	256-bit	✅ (X25519)	✅	✅ (key-pair only)	⚠️

Format Support: PEM, DER, SSH, PKCS#12 (all algorithms)

See docs/ALGORITHMS.md for detailed algorithm guide and decision trees

🛡️ Security Features

Cryptographic Security:

✅ Enforced minimum key sizes (RSA ≥2048 bits)
✅ Secure random sources (crypto/rand.Reader only)
✅ Authenticated encryption (AES-GCM)
✅ Timing attack resistant (Ed25519)

File System Security:

✅ Secure permissions (0600 for private keys, 0700 for directories)
✅ Atomic file operations
✅ Secure temporary file cleanup

Memory Security:

✅ Type-safe APIs with generic constraints
✅ No raw cryptographic material exposure
✅ Defensive copying of sensitive parameters

🧪 Testing

Test Coverage: 80.3% across 844+ tests

# Run comprehensive test suite
task test              # Full suite with race detection
task test:coverage     # Generate HTML coverage report
task test:compatibility # OpenSSL/OpenSSH compatibility tests

# Code quality
task lint:full         # Comprehensive linting
task lint:security     # Security-focused linting (gosec)
task format:check      # Verify code formatting

Module Coverage:

encryption/ 89.1% (highest)
keypair/algo/ 87.8%
signing/ 79.8%
pkcs12/ 79.1%
cert/ 74.3%
keypair/ 75.3%

🤝 Compatibility

OpenSSL Compatibility: 95%+

✅ Certificate management (100%)
✅ Digital signatures (95% - Ed25519 PKCS#7 has expected limitations)
✅ Key agreement (100% - ECDH, X25519)
⚠️ RSA-OAEP encryption (parameter differences)

OpenSSH Compatibility: 100%

✅ SSH key format validation (all algorithms)
✅ SSH fingerprint generation
✅ authorized_keys format support

Compatibility Report: See docs/COMPATIBILITY_REPORT.md for detailed interoperability testing results

OpenSSL Integration Guide: See docs/OPENSSL_COMPAT.md for integration patterns

📖 Standards Compliance

RFC 5652 - Cryptographic Message Syntax (CMS)
RFC 5280 - X.509 Public Key Infrastructure
RFC 3447 - PKCS #1: RSA Cryptography
RFC 7748 - Elliptic Curves (Ed25519, X25519)
RFC 5208 - PKCS #8: Private-Key Information
PKCS #7 - Cryptographic Message Syntax
PKCS #12 - Personal Information Exchange
OpenSSH - SSH public/private key formats
RFC 7515 - JSON Web Signature (JWS)
RFC 7516 - JSON Web Encryption (JWE)
RFC 7517 - JSON Web Key (JWK)
RFC 7518 - JSON Web Algorithms (JWA)
RFC 7519 - JSON Web Token (JWT)
RFC 8037 - CFRG Elliptic Curve Algorithms for JOSE

💻 Development

Using Taskfile (Recommended):

task setup             # Initialize project
task test              # Run tests
task format            # Format code
task lint:full         # Comprehensive linting
task examples:run      # Run all examples
task clean             # Clean build artifacts

Manual Commands:

go test ./... -race -coverprofile=coverage.out
go build ./...
go fmt ./...
go vet ./...

Development Guide: See CLAUDE.md for comprehensive development documentation

🔗 Dependencies

Minimal, carefully selected dependencies:

go.mozilla.org/pkcs7 v0.9.0 - Battle-tested CMS/PKCS#7
golang.org/x/crypto v0.42.0 - Extended cryptographic primitives
software.sslmate.com/src/go-pkcs12 v0.6.0 - Standards-compliant PKCS#12

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

Mozilla for the excellent PKCS#7 library
Go Team for outstanding cryptographic standard library
Community for feedback and contributions

📞 Support

Documentation: Module-specific READMEs, examples, and guides
Issues: GitHub Issues
Questions: Use GitHub Issues for questions and feature requests

Made with ❤️ in Go | Type-Safe Cryptography for Production

Name		Name	Last commit message	Last commit date
Latest commit History 199 Commits
.github/workflows		.github/workflows
bao		bao
cert		cert
compatibility		compatibility
docs/plans		docs/plans
encryption		encryption
examples		examples
internal/crypto		internal/crypto
jose		jose
keypair		keypair
pkcs12		pkcs12
signing		signing
.gitignore		.gitignore
.golangci.yml		.golangci.yml
.releaserc.json		.releaserc.json
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
Taskfile.yml		Taskfile.yml
go.mod		go.mod
go.sum		go.sum
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

GoPKI

✨ Why GoPKI?

📦 Installation

🤖 AI Agent Instructions

📖 Comprehensive AI Navigation Guide

Quick Navigation by Task

Understanding the Architecture

Common Modification Patterns

Code Reading Order for New AI Agents

Key Files Map

Project Conventions

Getting Help

🏗️ Architecture

🚀 Quick Start

Generate Key Pairs

Create Certificates

Sign Documents

Encrypt Data

📚 Examples

🔢 Algorithm Support

🛡️ Security Features

🧪 Testing

🤝 Compatibility

📖 Standards Compliance

💻 Development

🔗 Dependencies

📄 License

🙏 Acknowledgments

📞 Support

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 34

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages