README
¶
Crypto Module
The crypto module provides cryptographic utilities for the Service Layer.
Overview
This module provides secure cryptographic operations including:
- Hashing (SHA-256, RIPEMD-160)
- Key derivation (HKDF)
- Encryption/Decryption (AES-GCM)
- Digital signatures (ECDSA P-256)
- Neo N3 address utilities
Functions
Hashing
// SHA-256 hash
hash := crypto.Hash256(data)
// RIPEMD-160 hash (for Neo addresses)
hash160 := crypto.Hash160(data)
Key Derivation
// Derive a key using HKDF
derivedKey := crypto.DeriveKey(masterKey, salt, info, keyLength)
Encryption
// AES-GCM encryption
ciphertext, err := crypto.Encrypt(key, plaintext)
// AES-GCM decryption
plaintext, err := crypto.Decrypt(key, ciphertext)
Random Generation
// Generate cryptographically secure random bytes
randomBytes, err := crypto.GenerateRandomBytes(32)
Neo N3 Utilities
// Convert public key to Neo script hash
scriptHash := crypto.PublicKeyToScriptHash(publicKey)
// Convert script hash to Neo address
address := crypto.ScriptHashToAddress(scriptHash)
Memory Safety
// Securely zero memory (for sensitive data)
crypto.ZeroBytes(sensitiveData)
Security Considerations
- Key Material: All key material should be zeroed after use
- Random Generation: Uses
crypto/randfor secure randomness - Encryption: AES-256-GCM with random nonces
- Key Derivation: HKDF with SHA-256
Usage Example
package main
import (
"github.com/R3E-Network/service_layer/infrastructure/crypto"
)
func main() {
// Generate a random key
key, _ := crypto.GenerateRandomBytes(32)
defer crypto.ZeroBytes(key)
// Encrypt sensitive data
plaintext := []byte("sensitive data")
ciphertext, _ := crypto.Encrypt(key, plaintext)
// Decrypt
decrypted, _ := crypto.Decrypt(key, ciphertext)
// Hash data
hash := crypto.Hash256(decrypted)
}
Testing
go test ./infrastructure/crypto/... -v
Current test coverage: 71.9%
Documentation
¶
Overview ¶
Package crypto provides cryptographic operations for the service layer.
Index ¶
- func Decrypt(key, ciphertext []byte) ([]byte, error)
- func DecryptEnvelope(masterKey, subject []byte, info string, ciphertext []byte) ([]byte, error)
- func DeriveKey(masterKey, salt []byte, info string, keyLen int) ([]byte, error)
- func Encrypt(key, plaintext []byte) ([]byte, error)
- func EncryptEnvelope(masterKey, subject []byte, info string, plaintext []byte) ([]byte, error)
- func GenerateRandomBytes(n int) ([]byte, error)
- func HMACSign(key, data []byte) []byte
- func HMACVerify(key, data, signature []byte) bool
- func Hash160(data []byte) []byte
- func Hash256(data []byte) []byte
- func PublicKeyFromBytes(data []byte) (*ecdsa.PublicKey, error)
- func PublicKeyToAddress(publicKey *ecdsa.PublicKey) string
- func PublicKeyToBytes(pub *ecdsa.PublicKey) []byte
- func PublicKeyToScriptHash(publicKey []byte) []byte
- func ScriptHashToAddress(scriptHash []byte) string
- func Sign(privateKey *ecdsa.PrivateKey, data []byte) ([]byte, error)
- func Verify(publicKey *ecdsa.PublicKey, data, signature []byte) bool
- func ZeroBytes(b []byte)
- type KeyPair
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func DecryptEnvelope ¶
DecryptEnvelope decrypts ciphertext previously produced by EncryptEnvelope.
func DeriveKey ¶
DeriveKey derives a key using HKDF-SHA256.
UPGRADE SAFETY: This function is designed to produce identical keys across enclave upgrades (MRENCLAVE changes). Key derivation depends ONLY on:
- masterKey: Injected by MarbleRun Coordinator (manifest-defined, stable)
- salt: Business identifier like accountID (application-defined, stable)
- info: Service context string (code constant, stable)
This function intentionally does NOT use:
- MRENCLAVE or MRSIGNER (enclave identity)
- SGX sealing keys (tied to enclave measurement)
- Any enclave report fields
As long as the manifest secrets remain unchanged, derived keys will be identical regardless of enclave version, enabling seamless upgrades.
func EncryptEnvelope ¶
EncryptEnvelope encrypts plaintext using a key derived from masterKey + subject + info. The output is ASCII-safe (`v1:` + base64url(nonce|ciphertext)).
func GenerateRandomBytes ¶
GenerateRandomBytes generates cryptographically secure random bytes.
func HMACVerify ¶
HMACVerify verifies an HMAC-SHA256 signature.
func PublicKeyFromBytes ¶
PublicKeyFromBytes parses a compressed or uncompressed public key.
func PublicKeyToAddress ¶
PublicKeyToAddress converts a public key to a Neo N3 address.
func PublicKeyToBytes ¶
PublicKeyToBytes converts a public key to compressed format (33 bytes).
func PublicKeyToScriptHash ¶
PublicKeyToScriptHash converts a public key to a Neo N3 script hash.
func ScriptHashToAddress ¶
ScriptHashToAddress converts a script hash to a Neo N3 address.
func Sign ¶
func Sign(privateKey *ecdsa.PrivateKey, data []byte) ([]byte, error)
Sign signs data using ECDSA.
Types ¶
type KeyPair ¶
type KeyPair struct {
PrivateKey *ecdsa.PrivateKey
PublicKey *ecdsa.PublicKey
}
KeyPair represents an ECDSA key pair.
func GenerateKeyPair ¶
GenerateKeyPair generates a new ECDSA key pair using P-256 (secp256r1).
Source Files