crypto

package
v1.5.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 2, 2025 License: LGPL-3.0 Imports: 8 Imported by: 16

README

SAGE Cryptographic Operations

The crypto package provides comprehensive cryptographic key management for SAGE's secure agent communication infrastructure. It offers multi-algorithm support, flexible key storage backends, and blockchain-specific providers for decentralized identity management.

Overview

SAGE requires robust cryptographic operations for agent authentication, message signing, and secure communication. The crypto package abstracts these operations behind clean interfaces, supporting multiple algorithms and storage backends while maintaining security best practices.

Key Benefits
  • Multi-Algorithm Support: Ed25519, Secp256k1 (Ethereum), X25519 (HPKE), RS256
  • Flexible Storage: Memory, file-based, and OS keychain integration via Vault
  • Blockchain Ready: Native Ethereum and Solana provider support
  • Format Agnostic: Import/export keys in JWK and PEM formats
  • Production Secure: File permissions (0600), secure key rotation, hardware-backed storage

Architecture

┌─────────────────────────────────────────────────────────┐
│  SAGE Components (handshake, session, did)              │
│  - Agent authentication                                  │
│  - Message signing                                       │
│  - DID operations                                        │
└────────────────────┬────────────────────────────────────┘
                     │ uses
                     ▼
┌─────────────────────────────────────────────────────────┐
│  crypto.Manager (centralized key management)            │
│  - GenerateKeyPair()                                     │
│  - StoreKeyPair() / LoadKeyPair()                       │
│  - ExportKeyPair() / ImportKeyPair()                    │
└────────────────────┬────────────────────────────────────┘
                     │ manages
          ┌──────────┴──────────┬──────────────────┐
          ▼                     ▼                  ▼
┌──────────────────┐  ┌──────────────────┐  ┌──────────────┐
│ KeyPair          │  │ KeyStorage       │  │ Key Formats  │
│ Interface        │  │ Interface        │  │              │
├──────────────────┤  ├──────────────────┤  ├──────────────┤
│ • Ed25519        │  │ • Memory         │  │ • JWK        │
│ • Secp256k1      │  │ • File           │  │ • PEM        │
│ • X25519         │  │ • Vault (OS)     │  │              │
│ • RS256          │  │                  │  │              │
└──────────────────┘  └──────────────────┘  └──────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────┐
│  Chain Providers (blockchain-specific operations)       │
│  ├─ Ethereum Provider (ECDSA/Secp256k1)                 │
│  └─ Solana Provider (Ed25519)                           │
└─────────────────────────────────────────────────────────┘

Supported Algorithms

Ed25519 (Edwards-curve Digital Signature Algorithm)

Use Cases:

  • DID document signing
  • Agent authentication
  • Solana blockchain operations

Properties:

  • Key Size: 32 bytes (private), 32 bytes (public)
  • Signature Size: 64 bytes
  • Performance: ~40-80 μs signing, ~100-200 μs verification
  • Security: 128-bit security level
  • RFC 9421: Supported (ed25519 algorithm)

Standards:

  • RFC 8032 (EdDSA: Ed25519 and Ed448)
  • RFC 8037 (JWK for CFRG curves)
Secp256k1 (ECDSA with Bitcoin/Ethereum curve)

Use Cases:

  • Ethereum DID registration
  • Ethereum smart contract interaction
  • Blockchain transaction signing

Properties:

  • Key Size: 32 bytes (private), 33 bytes (compressed) or 65 bytes (uncompressed)
  • Signature Size: 64-65 bytes (with recovery ID for Ethereum)
  • Performance: ~60-120 μs signing, ~150-300 μs verification
  • Security: 128-bit security level
  • RFC 9421: Supported (es256k algorithm)

Standards:

  • SEC 2 v2.0 (Secp256k1 curve)
  • EIP-191 (Ethereum Signed Message)
X25519 (Curve25519 for ECDH)

Use Cases:

  • HPKE key agreement (RFC 9180)
  • Secure session establishment
  • Forward secrecy

Properties:

  • Key Size: 32 bytes (private), 32 bytes (public)
  • Performance: ~30-60 μs key generation, ~60-80 μs shared secret derivation
  • Security: 128-bit security level
  • Note: Encryption only, no signing

Standards:

  • RFC 7748 (Curve25519 and Curve448)
  • RFC 9180 (HPKE - Hybrid Public Key Encryption)
RS256 (RSA-SHA256)

Use Cases:

  • Legacy system integration
  • JWT token signing

Properties:

  • Key Size: 2048-4096 bits
  • Performance: Slower than elliptic curve algorithms
  • Security: Depends on key size
  • RFC 9421: Supported (rsa-v1_5-sha256 algorithm)

Note: Ed25519 or Secp256k1 recommended for new implementations.

Core Components

Manager

Centralized cryptographic operations manager:

type Manager struct {
    storage KeyStorage
}

// Core operations
func NewManager() *Manager
func (m *Manager) GenerateKeyPair(keyType KeyType) (KeyPair, error)
func (m *Manager) StoreKeyPair(keyPair KeyPair) error
func (m *Manager) LoadKeyPair(id string) (KeyPair, error)
func (m *Manager) ExportKeyPair(keyPair KeyPair, format KeyFormat) ([]byte, error)
func (m *Manager) ImportKeyPair(data []byte, format KeyFormat) (KeyPair, error)

Features:

  • Pluggable storage backends
  • Multi-algorithm support
  • Format conversion (JWK, PEM)
  • Key lifecycle management
KeyPair Interface

Unified interface for all key types:

type KeyPair interface {
    PublicKey() crypto.PublicKey
    PrivateKey() crypto.PrivateKey
    Type() KeyType
    Sign(message []byte) ([]byte, error)
    Verify(message, signature []byte) error
    ID() string
}

Implementations:

  • Ed25519KeyPair - Edwards curve signing
  • Secp256k1KeyPair - Ethereum-compatible ECDSA
  • X25519KeyPair - ECDH key agreement
  • RSAKeyPair - RSA signing (legacy)
KeyStorage Interface

Pluggable storage backends:

type KeyStorage interface {
    Store(id string, keyPair KeyPair) error
    Load(id string) (KeyPair, error)
    Delete(id string) error
    List() ([]string, error)
}

Available Backends:

1. Memory Storage (Testing)
  • Package: github.com/sage-x-project/sage/pkg/agent/crypto/storage
  • Use Case: Unit tests, temporary keys
  • Persistence: None (RAM only)
import "github.com/sage-x-project/sage/pkg/agent/crypto/storage"

storage := storage.NewMemoryKeyStorage()
2. File Storage (Development)
  • Package: github.com/sage-x-project/sage/pkg/agent/crypto/storage
  • Use Case: Development, local deployments
  • Persistence: Encrypted files with 0600 permissions
  • Location: Configurable directory
import "github.com/sage-x-project/sage/pkg/agent/crypto/storage"

storage := storage.NewFileKeyStorage("/path/to/keys")

Security:

  • Files stored with 0600 permissions (owner read/write only)
  • Keys encrypted at rest
  • Configurable directory location
3. Vault Storage (Production)
  • Package: github.com/sage-x-project/sage/pkg/agent/crypto/vault
  • Use Case: Production deployments
  • Persistence: OS keychain (Keychain on macOS, GNOME Keyring on Linux, Credential Manager on Windows)
  • Hardware: Supports hardware-backed secure enclaves (e.g., Secure Enclave on macOS)
import "github.com/sage-x-project/sage/pkg/agent/crypto/vault"

storage := vault.NewSecureStorage("sage-agent-keys")

Security:

  • Hardware-backed encryption (when available)
  • OS-level access control
  • Tamper-resistant storage
  • Automatic key escrow and recovery
Key Formats
JWK (JSON Web Key) - RFC 7517

Use Cases:

  • Web APIs and JWT tokens
  • Cross-platform key exchange
  • Standard-compliant key storage

Example (Ed25519):

{
  "kty": "OKP",
  "crv": "Ed25519",
  "x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo",
  "d": "nWGxne_9WmC6hEr0kuwsxERJxWl7MmkZcDusAxyuf2A"
}

Example (Secp256k1):

{
  "kty": "EC",
  "crv": "secp256k1",
  "x": "MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
  "y": "4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
  "d": "870MB6gfuTJ4HtUnUvYMyJpr5eUZNP4Bk43bVdj3eAE"
}
PEM (Privacy-Enhanced Mail)

Use Cases:

  • OpenSSL compatibility
  • Traditional Unix systems
  • Certificate infrastructure

Example (Ed25519 Private Key):

-----BEGIN PRIVATE KEY-----
MC4CAQAwBQYDK2VwBCIEINVhsZ3v/VpguoRK9JLsrMREScVpezJpGXA7rAMcrn9g
-----END PRIVATE KEY-----

Example (Ed25519 Public Key):

-----BEGIN PUBLIC KEY-----
MCowBQYDK2VwAyEANVqAYKxCrfVS/7TyWQHOg7hcvPapiMlrwIaaPcHURo=
-----END PUBLIC KEY-----
Chain Providers

Blockchain-specific cryptographic operations:

Ethereum Provider

Package: github.com/sage-x-project/sage/pkg/agent/crypto/chain/ethereum

Features:

  • Secp256k1 key generation
  • Ethereum address derivation (Keccak256 hash)
  • EIP-191 message signing
  • Transaction signing
  • Enhanced provider with gas estimation

Usage:

import "github.com/sage-x-project/sage/pkg/agent/crypto/chain/ethereum"

provider := ethereum.NewProvider()
keyPair, _ := provider.GenerateKeyPair()
address := provider.DeriveAddress(keyPair.PublicKey())
// Result: "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266"
Solana Provider

Package: github.com/sage-x-project/sage/pkg/agent/crypto/chain/solana

Features:

  • Ed25519 key generation
  • Base58 address encoding
  • Transaction signing

Usage:

import "github.com/sage-x-project/sage/pkg/agent/crypto/chain/solana"

provider := solana.NewProvider()
keyPair, _ := provider.GenerateKeyPair()
address := provider.DeriveAddress(keyPair.PublicKey())
// Result: "CuieVDEDtLo7FypA9SbLM9saXFdb1dsshEkyErMqkRQq"

Usage Examples

Basic Key Generation
import "github.com/sage-x-project/sage/pkg/agent/crypto"

// Create manager
manager := crypto.NewManager()

// Generate Ed25519 key pair
ed25519Key, err := manager.GenerateKeyPair(crypto.KeyTypeEd25519)
if err != nil {
    log.Fatal(err)
}

// Generate Secp256k1 key pair (Ethereum)
secp256k1Key, err := manager.GenerateKeyPair(crypto.KeyTypeSecp256k1)
if err != nil {
    log.Fatal(err)
}

// Generate X25519 key pair (HPKE)
import "github.com/sage-x-project/sage/pkg/agent/crypto/keys"
x25519Key, err := keys.GenerateX25519KeyPair()
if err != nil {
    log.Fatal(err)
}
Signing and Verification
import "github.com/sage-x-project/sage/pkg/agent/crypto"

manager := crypto.NewManager()
keyPair, _ := manager.GenerateKeyPair(crypto.KeyTypeEd25519)

// Sign message
message := []byte("Hello, SAGE!")
signature, err := keyPair.Sign(message)
if err != nil {
    log.Fatal(err)
}

log.Printf("Signature: %x", signature)

// Verify signature
err = keyPair.Verify(message, signature)
if err != nil {
    log.Fatal("Signature verification failed:", err)
}

log.Println("Signature verified successfully!")
Key Storage and Loading
import (
    "github.com/sage-x-project/sage/pkg/agent/crypto"
    "github.com/sage-x-project/sage/pkg/agent/crypto/storage"
)

// Create manager with file storage
manager := crypto.NewManager()
fileStorage := storage.NewFileKeyStorage("./keys")
manager.SetStorage(fileStorage)

// Generate and store key
keyPair, _ := manager.GenerateKeyPair(crypto.KeyTypeEd25519)
err := manager.StoreKeyPair(keyPair)
if err != nil {
    log.Fatal(err)
}

log.Printf("Stored key with ID: %s", keyPair.ID())

// Load key
loadedKey, err := manager.LoadKeyPair(keyPair.ID())
if err != nil {
    log.Fatal(err)
}

log.Println("Key loaded successfully!")
Production: Vault Storage
import (
    "github.com/sage-x-project/sage/pkg/agent/crypto"
    "github.com/sage-x-project/sage/pkg/agent/crypto/vault"
)

// Create manager with vault storage (OS keychain)
manager := crypto.NewManager()
vaultStorage := vault.NewSecureStorage("sage-agent-keys")
manager.SetStorage(vaultStorage)

// Generate and securely store key
keyPair, _ := manager.GenerateKeyPair(crypto.KeyTypeSecp256k1)
err := manager.StoreKeyPair(keyPair)
if err != nil {
    log.Fatal(err)
}

// Key is now stored in OS keychain (hardware-backed if available)
log.Println("Key securely stored in OS keychain")
Key Format Conversion
Export to JWK
import "github.com/sage-x-project/sage/pkg/agent/crypto"

manager := crypto.NewManager()
keyPair, _ := manager.GenerateKeyPair(crypto.KeyTypeEd25519)

// Export to JWK
jwkData, err := manager.ExportKeyPair(keyPair, crypto.KeyFormatJWK)
if err != nil {
    log.Fatal(err)
}

log.Printf("JWK:\n%s", string(jwkData))
Export to PEM
import "github.com/sage-x-project/sage/pkg/agent/crypto"

manager := crypto.NewManager()
keyPair, _ := manager.GenerateKeyPair(crypto.KeyTypeSecp256k1)

// Export to PEM
pemData, err := manager.ExportKeyPair(keyPair, crypto.KeyFormatPEM)
if err != nil {
    log.Fatal(err)
}

log.Printf("PEM:\n%s", string(pemData))
Import from JWK
import "github.com/sage-x-project/sage/pkg/agent/crypto"

manager := crypto.NewManager()

jwkData := []byte(`{
  "kty": "OKP",
  "crv": "Ed25519",
  "x": "11qYAYKxCrfVS_7TyWQHOg7hcvPapiMlrwIaaPcHURo",
  "d": "nWGxne_9WmC6hEr0kuwsxERJxWl7MmkZcDusAxyuf2A"
}`)

keyPair, err := manager.ImportKeyPair(jwkData, crypto.KeyFormatJWK)
if err != nil {
    log.Fatal(err)
}

log.Printf("Imported %s key pair", keyPair.Type())
Blockchain Provider Usage
Ethereum
import (
    "github.com/sage-x-project/sage/pkg/agent/crypto/chain/ethereum"
    "github.com/sage-x-project/sage/pkg/agent/did"
)

// Generate Ethereum-compatible key
provider := ethereum.NewProvider()
keyPair, _ := provider.GenerateKeyPair()

// Derive Ethereum address
address := provider.DeriveAddress(keyPair.PublicKey())
log.Printf("Ethereum address: %s", address)

// Generate DID
agentDID := did.GenerateAgentDIDWithAddress(did.ChainEthereum, address)
log.Printf("Agent DID: %s", agentDID)
// Result: "did:sage:ethereum:0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266"

// Sign Ethereum message (EIP-191)
message := []byte("Hello, Ethereum!")
signature, _ := keyPair.Sign(message)
log.Printf("Signature: %x", signature)
Solana
import (
    "github.com/sage-x-project/sage/pkg/agent/crypto/chain/solana"
    "github.com/sage-x-project/sage/pkg/agent/did"
)

// Generate Solana-compatible key
provider := solana.NewProvider()
keyPair, _ := provider.GenerateKeyPair()

// Derive Solana address
address := provider.DeriveAddress(keyPair.PublicKey())
log.Printf("Solana address: %s", address)

// Generate DID
agentDID := did.GenerateAgentDIDWithAddress(did.ChainSolana, address)
log.Printf("Agent DID: %s", agentDID)
// Result: "did:sage:solana:CuieVDEDtLo7FypA9SbLM9saXFdb1dsshEkyErMqkRQq"
Key Rotation
import (
    "github.com/sage-x-project/sage/pkg/agent/crypto"
    "github.com/sage-x-project/sage/pkg/agent/crypto/rotation"
)

manager := crypto.NewManager()

// Create rotator
rotator := rotation.NewKeyRotator(manager)

// Generate initial key
oldKey, _ := manager.GenerateKeyPair(crypto.KeyTypeEd25519)
manager.StoreKeyPair(oldKey)

// Rotate key
newKey, err := rotator.RotateKey(oldKey.ID(), crypto.KeyTypeEd25519)
if err != nil {
    log.Fatal(err)
}

log.Printf("Rotated from %s to %s", oldKey.ID(), newKey.ID())

// Old key is automatically deleted
// New key is stored and ready to use

Directory Structure

pkg/agent/crypto/
├── README.md                    # This file
├── manager.go                   # Crypto manager implementation
├── types.go                     # Core interfaces (KeyPair, KeyStorage, etc.)
├── crypto.go                    # Helper functions and wrappers
├── wrappers.go                  # Convenience wrappers
├── algorithm_registry.go        # Algorithm registration and discovery
│
├── keys/                        # Key implementations
│   ├── algorithms.go            # Algorithm registration (init)
│   ├── constructors.go          # Key pair constructors
│   ├── ed25519.go               # Ed25519 implementation
│   ├── ed25519_test.go          # Ed25519 tests
│   ├── secp256k1.go             # Secp256k1 implementation
│   ├── secp256k1_test.go        # Secp256k1 tests
│   ├── x25519.go                # X25519 implementation
│   ├── x25519_test.go           # X25519 tests
│   ├── rs256.go                 # RSA-SHA256 implementation
│   └── rs256_test.go            # RS256 tests
│
├── storage/                     # Storage backends
│   ├── memory.go                # In-memory storage (testing)
│   ├── memory_test.go           # Memory storage tests
│   ├── file.go                  # File-based storage
│   └── file_test.go             # File storage tests
│
├── vault/                       # Secure storage (OS keychain)
│   ├── secure_storage.go        # Vault implementation
│   └── secure_storage_test.go   # Vault tests
│
├── formats/                     # Key format converters
│   ├── jwk.go                   # JWK import/export
│   ├── jwk_test.go              # JWK tests
│   ├── pem.go                   # PEM import/export
│   └── pem_test.go              # PEM tests
│
├── chain/                       # Blockchain providers
│   ├── types.go                 # Provider interface
│   ├── registry.go              # Provider registry
│   ├── key_mapper.go            # Algorithm to chain mapping
│   ├── ethereum/                # Ethereum provider
│   │   ├── provider.go          # Basic provider
│   │   ├── enhanced_provider.go # Enhanced provider (gas, nonce)
│   │   └── provider_test.go     # Provider tests
│   └── solana/                  # Solana provider
│       ├── provider.go          # Solana provider
│       └── provider_test.go     # Provider tests
│
└── rotation/                    # Key rotation
    ├── rotator.go               # Key rotation logic
    └── rotator_test.go          # Rotation tests

Testing

Unit Tests
# Run all crypto tests
go test ./pkg/agent/crypto/...

# Run with coverage
go test -cover ./pkg/agent/crypto/...

# Run specific algorithm tests
go test ./pkg/agent/crypto/keys -run TestEd25519
go test ./pkg/agent/crypto/keys -run TestSecp256k1
Fuzz Testing
# Run fuzzing (10 seconds)
./tools/scripts/run-fuzz.sh --time 10s --type go

# Run specific fuzzer
go test -fuzz=FuzzSignVerify -fuzztime=1m ./pkg/agent/crypto
Benchmark Tests
# Run crypto benchmarks
go test -bench=. -benchmem ./tools/benchmark -run=^$ -bench="Key|Sign|Verif"

# Expected results:
# - Ed25519 key generation: ~50-100 μs
# - Ed25519 signing: ~40-80 μs
# - Ed25519 verification: ~100-200 μs
# - Secp256k1 key generation: ~100-200 μs
# - Secp256k1 signing: ~60-120 μs
# - Secp256k1 verification: ~150-300 μs

Security Considerations

Key Storage

Development:

  • Use file storage with 0600 permissions
  • Encrypt keys at rest
  • Never commit keys to version control

Production:

  • Use vault storage (OS keychain)
  • Enable hardware-backed encryption
  • Implement key rotation policy
  • Monitor key access logs
Algorithm Selection

For DID Signing:

  • Ed25519 (recommended for new implementations)
  • Secp256k1 (required for Ethereum)
  • RS256 (legacy only, avoid for new systems)

For Key Agreement:

  • X25519 (HPKE, RFC 9180)
  • Never use signing keys for encryption
Best Practices

  1. Key Generation

    • Use cryptographically secure random number generator
    • Never reuse keys across different purposes
    • Generate new keys for each agent

  2. Signature Verification

    • Always verify signatures before trusting messages
    • Check message replay (nonce, timestamp)
    • Validate DID ownership

  3. Key Rotation

    • Rotate keys periodically (e.g., every 90 days)
    • Use atomic rotation to prevent inconsistent states
    • Keep old keys for signature verification during transition

  4. Storage

    • Encrypt keys at rest
    • Use OS keychain for production
    • Limit key access to necessary processes

Performance

Benchmark Results (Apple M1, Go 1.24)
Operation Algorithm Time Memory
Key Generation Ed25519 ~50-100 μs 1-2 KB
Key Generation Secp256k1 ~100-200 μs 2-3 KB
Key Generation X25519 ~30-60 μs 1 KB
Signing Ed25519 ~40-80 μs <1 KB
Signing Secp256k1 ~60-120 μs 1-2 KB
Verification Ed25519 ~100-200 μs <1 KB
Verification Secp256k1 ~150-300 μs 1-2 KB
JWK Export All ~10-20 μs 1-2 KB
PEM Export All ~10-20 μs 1-2 KB
Optimization Tips
  1. Reuse KeyPair objects: Key pair objects can be reused for multiple operations
  2. Cache public keys: Public key parsing/validation is expensive
  3. Batch verification: Verify multiple signatures in parallel
  4. Use X25519 for encryption: Much faster than RSA for key agreement

FAQ

Q: Which algorithm should I use for DID signing?

A: For new implementations, use Ed25519:

  • Faster than Secp256k1
  • Smaller keys and signatures
  • Constant-time operations (side-channel resistant)

Use Secp256k1 only when Ethereum compatibility is required.

Q: Can I use the same key for signing and encryption?

A: No. Use different keys for different purposes:

  • Ed25519/Secp256k1: Signing and verification
  • X25519: Key agreement (HPKE)

Never use signing keys for encryption operations.

Q: How do I securely store keys in production?

A: Use Vault storage with OS keychain:

import "github.com/sage-x-project/sage/pkg/agent/crypto/vault"

vaultStorage := vault.NewSecureStorage("sage-agent-keys")
manager.SetStorage(vaultStorage)

This provides:

  • Hardware-backed encryption (when available)
  • OS-level access control
  • Tamper-resistant storage
Q: How often should I rotate keys?

A: Every 90 days for production agents:

import "github.com/sage-x-project/sage/pkg/agent/crypto/rotation"

rotator := rotation.NewKeyRotator(manager)
newKey, _ := rotator.RotateKey(oldKeyID, crypto.KeyTypeEd25519)

Rotate immediately if:

  • Key compromise suspected
  • Employee departure
  • Security audit recommendation
Q: What's the difference between JWK and PEM?

JWK (JSON Web Key):

  • Modern, JSON-based format
  • Web API friendly
  • Standard for OAuth/JWT
  • Example: {"kty":"OKP","crv":"Ed25519",...}

PEM (Privacy-Enhanced Mail):

  • Traditional, base64-encoded format
  • OpenSSL compatible
  • Unix systems standard
  • Example: -----BEGIN PRIVATE KEY-----

Use JWK for web APIs and PEM for traditional systems.

See Also

References

License

LGPL-3.0 - See LICENSE file for details.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrAlgorithmNotSupported = errors.New("algorithm not supported")
	ErrAlgorithmExists       = errors.New("algorithm already registered")
)

algorithmRegistry stores all registered algorithms

View Source 
var (
	ErrKeyNotFound        = errors.New("key not found")
	ErrInvalidKeyType     = errors.New("invalid key type")
	ErrInvalidKeyFormat   = errors.New("invalid key format")
	ErrKeyExists          = errors.New("key already exists")
	ErrInvalidSignature   = errors.New("invalid signature")
	ErrSignNotSupported   = errors.New("signing not supported")
	ErrVerifyNotSupported = errors.New("verification not supported")
)

Common errors

Functions

func GetRFC9421AlgorithmName 

func GetRFC9421AlgorithmName(keyType KeyType) (string, error)

GetRFC9421AlgorithmName returns the RFC 9421 algorithm name for a key type

func IsAlgorithmSupported 

func IsAlgorithmSupported(keyType KeyType) bool

IsAlgorithmSupported checks if an algorithm is registered

func ListRFC9421SupportedAlgorithms 

func ListRFC9421SupportedAlgorithms() []string

ListRFC9421SupportedAlgorithms returns a list of RFC 9421 algorithm names

func RegisterAlgorithm 

func RegisterAlgorithm(info AlgorithmInfo) error

RegisterAlgorithm registers a new algorithm in the registry This should be called during package initialization

func SetFormatConstructors 

func SetFormatConstructors(jwkExp, pemExp func() KeyExporter, jwkImp, pemImp func() KeyImporter)

SetFormatConstructors sets the format constructor functions

func SetKeyGenerators 

func SetKeyGenerators(ed25519Gen, secp256k1Gen, p256Gen func() (KeyPair, error))

SetKeyGenerators sets the key generation functions

func SetStorageConstructors 

func SetStorageConstructors(memoryStorage func() KeyStorage)

SetStorageConstructors sets the storage constructor functions

func SupportsKeyGeneration 

func SupportsKeyGeneration(keyType KeyType) bool

SupportsKeyGeneration checks if an algorithm supports key generation

func SupportsRFC9421 

func SupportsRFC9421(keyType KeyType) bool

SupportsRFC9421 checks if an algorithm supports RFC 9421

func SupportsSignature 

func SupportsSignature(keyType KeyType) bool

SupportsSignature checks if an algorithm supports digital signatures

func ValidateAlgorithmForPublicKey 

func ValidateAlgorithmForPublicKey(publicKey interface{}, algorithm string) error

ValidateAlgorithmForPublicKey validates that an RFC 9421 algorithm is compatible with a public key Returns nil if valid, error otherwise

Types

type AlgorithmInfo 

type AlgorithmInfo struct {
	// KeyType is the internal key type identifier
	KeyType KeyType

	// Name is the human-readable name of the algorithm
	Name string

	// Description provides details about the algorithm
	Description string

	// RFC9421Algorithm is the algorithm name used in RFC 9421 HTTP Message Signatures
	// Empty string if the algorithm doesn't support RFC 9421
	RFC9421Algorithm string

	// SupportsRFC9421 indicates if this algorithm can be used for RFC 9421 signatures
	SupportsRFC9421 bool

	// SupportsKeyGeneration indicates if the system can generate keys for this algorithm
	SupportsKeyGeneration bool

	// SupportsSignature indicates if this algorithm supports digital signatures
	SupportsSignature bool

	// SupportsEncryption indicates if this algorithm supports encryption
	SupportsEncryption bool
}

AlgorithmInfo contains metadata about a cryptographic algorithm

func GetAlgorithmInfo 

func GetAlgorithmInfo(keyType KeyType) (*AlgorithmInfo, error)

GetAlgorithmInfo returns information about a registered algorithm

func ListSupportedAlgorithms 

func ListSupportedAlgorithms() []AlgorithmInfo

ListSupportedAlgorithms returns a list of all supported algorithms

type KeyExporter 

type KeyExporter interface {
	// Export exports the key pair in the specified format
	Export(keyPair KeyPair, format KeyFormat) ([]byte, error)

	// ExportPublic exports only the public key
	ExportPublic(keyPair KeyPair, format KeyFormat) ([]byte, error)
}

KeyExporter handles key export operations

func NewJWKExporter 

func NewJWKExporter() KeyExporter

NewJWKExporter creates a new JWK exporter

func NewPEMExporter 

func NewPEMExporter() KeyExporter

NewPEMExporter creates a new PEM exporter

type KeyFormat 

type KeyFormat string

KeyFormat represents the format for key export/import 

const (
	KeyFormatJWK KeyFormat = "JWK"
	KeyFormatPEM KeyFormat = "PEM"
)

type KeyImporter 

type KeyImporter interface {
	// Import imports a key pair from the specified format
	Import(data []byte, format KeyFormat) (KeyPair, error)

	// ImportPublic imports only a public key
	ImportPublic(data []byte, format KeyFormat) (crypto.PublicKey, error)
}

KeyImporter handles key import operations

func NewJWKImporter 

func NewJWKImporter() KeyImporter

NewJWKImporter creates a new JWK importer

func NewPEMImporter 

func NewPEMImporter() KeyImporter

NewPEMImporter creates a new PEM importer

type KeyManager 

type KeyManager interface {
	// GenerateKeyPair generates a new key pair
	GenerateKeyPair(keyType KeyType) (KeyPair, error)

	// GetExporter returns the key exporter
	GetExporter() KeyExporter

	// GetImporter returns the key importer
	GetImporter() KeyImporter

	// GetStorage returns the key storage
	GetStorage() KeyStorage

	// GetRotator returns the key rotator
	GetRotator() KeyRotator
}

KeyManager is the main interface for key management

type KeyPair 

type KeyPair interface {
	// PublicKey returns the public key
	PublicKey() crypto.PublicKey

	// PrivateKey returns the private key
	PrivateKey() crypto.PrivateKey

	// Type returns the key type
	Type() KeyType

	// Sign signs the given message
	Sign(message []byte) ([]byte, error)

	// Verify verifies the signature
	Verify(message, signature []byte) error

	// ID returns a unique identifier for this key pair
	ID() string
}

KeyPair represents a cryptographic key pair

func GenerateEd25519KeyPair 

func GenerateEd25519KeyPair() (KeyPair, error)

GenerateEd25519KeyPair is an alias for NewEd25519KeyPair

func GenerateP256KeyPair added in v1.3.1 

func GenerateP256KeyPair() (KeyPair, error)

GenerateP256KeyPair is an alias for NewP256KeyPair

func GenerateSecp256k1KeyPair 

func GenerateSecp256k1KeyPair() (KeyPair, error)

GenerateSecp256k1KeyPair is an alias for NewSecp256k1KeyPair

func NewEd25519KeyPair 

func NewEd25519KeyPair() (KeyPair, error)

NewEd25519KeyPair generates a new Ed25519 key pair

func NewP256KeyPair added in v1.3.1 

func NewP256KeyPair() (KeyPair, error)

NewP256KeyPair generates a new P-256 key pair

func NewSecp256k1KeyPair 

func NewSecp256k1KeyPair() (KeyPair, error)

NewSecp256k1KeyPair generates a new Secp256k1 key pair

type KeyRotationConfig 

type KeyRotationConfig struct {
	// RotationInterval is the time between rotations
	RotationInterval time.Duration

	// MaxKeyAge is the maximum age for a key
	MaxKeyAge time.Duration

	// KeepOldKeys determines if old keys should be kept
	KeepOldKeys bool
}

KeyRotationConfig represents configuration for key rotation

type KeyRotationEvent 

type KeyRotationEvent struct {
	Timestamp time.Time
	OldKeyID  string
	NewKeyID  string
	Reason    string
}

KeyRotationEvent represents a key rotation event

type KeyRotator 

type KeyRotator interface {
	// Rotate rotates the key for the given ID
	Rotate(id string) (KeyPair, error)

	// SetRotationConfig sets the rotation configuration
	SetRotationConfig(config KeyRotationConfig)

	// GetRotationHistory returns the rotation history for a key
	GetRotationHistory(id string) ([]KeyRotationEvent, error)
}

KeyRotator handles key rotation operations

type KeyStorage 

type KeyStorage interface {
	// Store stores a key pair with the given ID
	Store(id string, keyPair KeyPair) error

	// Load loads a key pair by ID
	Load(id string) (KeyPair, error)

	// Delete removes a key pair by ID
	Delete(id string) error

	// List returns all stored key IDs
	List() ([]string, error)

	// Exists checks if a key exists
	Exists(id string) bool
}

KeyStorage provides secure storage for keys

func NewMemoryKeyStorage 

func NewMemoryKeyStorage() KeyStorage

NewMemoryKeyStorage creates a new memory key storage

type KeyType 

type KeyType string

KeyType represents the type of cryptographic key 

const (
	KeyTypeEd25519   KeyType = "Ed25519"
	KeyTypeSecp256k1 KeyType = "Secp256k1"
	KeyTypeP256      KeyType = "P256" // NIST P-256 (secp256r1, prime256v1)
	KeyTypeX25519    KeyType = "X25519"
	KeyTypeRSA       KeyType = "RSA256"
)

func GetKeyTypeFromPublicKey 

func GetKeyTypeFromPublicKey(publicKey interface{}) (KeyType, error)

GetKeyTypeFromPublicKey maps a Go crypto.PublicKey to our KeyType This is used for algorithm validation in signature verification

func GetKeyTypeFromRFC9421Algorithm 

func GetKeyTypeFromRFC9421Algorithm(rfc9421Algorithm string) (KeyType, error)

GetKeyTypeFromRFC9421Algorithm returns the key type for an RFC 9421 algorithm name

type Manager 

type Manager struct {
	// contains filtered or unexported fields
}

Manager provides centralized management of cryptographic operations

func NewManager 

func NewManager() *Manager

NewManager creates a new crypto manager

func (*Manager) DeleteKeyPair 

func (m *Manager) DeleteKeyPair(id string) error

DeleteKeyPair deletes a key pair by ID

func (*Manager) ExportKeyPair 

func (m *Manager) ExportKeyPair(keyPair KeyPair, format KeyFormat) ([]byte, error)

ExportKeyPair exports a key pair in the specified format

func (*Manager) GenerateKeyPair 

func (m *Manager) GenerateKeyPair(keyType KeyType) (KeyPair, error)

GenerateKeyPair generates a new key pair of the specified type

func (*Manager) ImportKeyPair 

func (m *Manager) ImportKeyPair(data []byte, format KeyFormat) (KeyPair, error)

ImportKeyPair imports a key pair from the specified format

func (*Manager) ListKeyPairs 

func (m *Manager) ListKeyPairs() ([]string, error)

ListKeyPairs lists all stored key pair IDs

func (*Manager) LoadKeyPair 

func (m *Manager) LoadKeyPair(id string) (KeyPair, error)

LoadKeyPair loads a key pair by ID

func (*Manager) SetStorage 

func (m *Manager) SetStorage(storage KeyStorage)

SetStorage sets the key storage backend

func (*Manager) StoreKeyPair 

func (m *Manager) StoreKeyPair(keyPair KeyPair) error

StoreKeyPair stores a key pair

Source Files

View all Source files

Directories

Path Synopsis
ethereum
solana

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.