Documentation
¶
Overview ¶
SPDX-License-Identifier: Apache-2.0 Copyright (c) 2024-2026 Quad4.io
SPDX-License-Identifier: Apache-2.0 Copyright (c) 2024-2026 Quad4.io
SPDX-License-Identifier: Apache-2.0 Copyright (c) 2024-2026 Quad4.io
Package cryptography is the single integration point for cryptographic primitives used across Reticulum-Go. Application and library code should call the exported functions here (or types derived from them) rather than importing lower-level packages such as crypto/ed25519 or curve25519 directly, so algorithms and test doubles can be changed in one place.
Extension model:
- CryptoProvider defines the full surface; [stdlibProvider] is the default.
- SetProvider installs a replacement (for tests or future algorithms); SetProvider(nil) restores the default.
- ActiveProvider returns the current implementation.
On-wire formats (key sizes, packet layouts, hash truncation) are defined elsewhere and assume the default provider’s behavior. Replacing the provider without updating those formats will break interoperability; treat provider swaps as coordinated protocol changes unless you control all peers.
Hardware signing (HSM, PKCS#11, cloud KMS) can integrate via Ed25519Signer: use NewSoftwareEd25519Signer for in-memory seeds, or NewEd25519SignerFromCryptoSigner to wrap a standard crypto.Signer that performs Ed25519. Identity wiring is in package identity (git.quad4.io/Networks/Reticulum-Go/pkg/identity.NewIdentityWithSigner).
SPDX-License-Identifier: Apache-2.0 Copyright (c) 2024-2026 Quad4.io
SPDX-License-Identifier: Apache-2.0 Copyright (c) 2024-2026 Quad4.io
SPDX-License-Identifier: Apache-2.0 Copyright (c) 2024-2026 Quad4.io
SPDX-License-Identifier: Apache-2.0 Copyright (c) 2024-2026 Quad4.io
SPDX-License-Identifier: Apache-2.0 Copyright (c) 2024-2026 Quad4.io
SPDX-License-Identifier: Apache-2.0 Copyright (c) 2024-2026 Quad4.io
SPDX-License-Identifier: Apache-2.0 Copyright (c) 2024-2026 Quad4.io
SPDX-License-Identifier: Apache-2.0 Copyright (c) 2024-2026 Quad4.io
SPDX-License-Identifier: Apache-2.0 Copyright (c) 2024-2026 Quad4.io
Index ¶
- Constants
- func ComputeHMAC(key, message []byte) []byte
- func DecryptAES256CBC(key, ciphertext []byte) ([]byte, error)
- func DeriveIdentityKeyMaterial(sharedSecret, salt, context []byte) ([]byte, error)
- func DeriveKey(secret, salt, info []byte, length int) ([]byte, error)
- func DeriveSharedSecret(privateKey, peerPublicKey []byte) ([]byte, error)
- func EncryptAES256CBC(key, plaintext []byte) ([]byte, error)
- func ExpandEncryptWithHMACKeyMaterial(key32 []byte) (hmacKey, aesKey []byte, err error)
- func GenerateAES256Key() ([]byte, error)
- func GenerateHMACKey(size int) ([]byte, error)
- func GenerateKeyPair() (privateKey, publicKey []byte, err error)
- func GenerateSigningKeyPair() (ed25519.PublicKey, ed25519.PrivateKey, error)
- func GetBasepoint() []byte
- func Hash(data []byte) []byte
- func PublicKeyFromPrivate(privateKey []byte) ([]byte, error)
- func RemovePKCS7Padding(plaintext []byte) ([]byte, error)
- func SetProvider(p CryptoProvider)
- func Sign(privateKey ed25519.PrivateKey, message []byte) []byte
- func ValidateHMAC(key, message, messageHMAC []byte) bool
- func Verify(publicKey ed25519.PublicKey, message, signature []byte) bool
- type CryptoProvider
- type Ed25519Signer
Constants ¶
const ( SHA256Size = 32 AES256KeySize = 32 // IdentityKeyMaterialSize is the HKDF output for identity encrypt/decrypt (HMAC key + AES key). IdentityKeyMaterialSize = SHA256Size + AES256KeySize )
const Ed25519SignatureSize = ed25519.SignatureSize
Ed25519SignatureSize is the byte length of an Ed25519 signature.
Variables ¶
This section is empty.
Functions ¶
func ComputeHMAC ¶
ComputeHMAC returns HMAC-SHA256(key, message).
func DecryptAES256CBC ¶
DecryptAES256CBC decrypts data using AES-256 in CBC mode. It assumes the IV is prepended to the ciphertext.
func DeriveIdentityKeyMaterial ¶ added in v0.9.0
DeriveIdentityKeyMaterial derives 64 bytes of key material for identity-layer encryption using the active CryptoProvider.
func DeriveKey ¶
DeriveKey performs HKDF-SHA256 expansion (non-RFC 5869 extract; matches legacy use).
func DeriveSharedSecret ¶
DeriveSharedSecret performs an X25519 scalar multiplication.
func EncryptAES256CBC ¶
EncryptAES256CBC encrypts data using AES-256 in CBC mode. The IV is prepended to the ciphertext.
func ExpandEncryptWithHMACKeyMaterial ¶ added in v0.9.0
ExpandEncryptWithHMACKeyMaterial derives 32-byte HMAC and 32-byte AES keys from a 32-byte input using HKDF-SHA256 (RFC 5869).
func GenerateAES256Key ¶
func GenerateHMACKey ¶
func GenerateKeyPair ¶
GenerateKeyPair creates a random X25519 key pair.
func GenerateSigningKeyPair ¶
func GenerateSigningKeyPair() (ed25519.PublicKey, ed25519.PrivateKey, error)
GenerateSigningKeyPair creates a random Ed25519 key pair.
func GetBasepoint ¶
func GetBasepoint() []byte
GetBasepoint returns the standard Curve25519 basepoint.
func PublicKeyFromPrivate ¶ added in v0.9.0
PublicKeyFromPrivate derives the X25519 public key from a private key.
func RemovePKCS7Padding ¶ added in v0.9.0
RemovePKCS7Padding validates and removes PKCS#7 padding without early exit on the first mismatched byte (reduces padding-oracle surface when used after MAC verify).
func SetProvider ¶ added in v0.9.0
func SetProvider(p CryptoProvider)
SetProvider replaces the global crypto implementation. Passing nil restores the default stdlib-backed provider.
func Sign ¶
func Sign(privateKey ed25519.PrivateKey, message []byte) []byte
Sign signs message with privateKey.
func ValidateHMAC ¶
ValidateHMAC performs a constant-time comparison of the MAC.
Types ¶
type CryptoProvider ¶ added in v0.9.0
type CryptoProvider interface {
GenerateKeyPair() (privateKey, publicKey []byte, err error)
PublicKeyFromPrivate(privateKey []byte) ([]byte, error)
GetBasepoint() []byte
GenerateSigningKeyPair() (ed25519.PublicKey, ed25519.PrivateKey, error)
Sign(privateKey ed25519.PrivateKey, message []byte) []byte
Verify(publicKey ed25519.PublicKey, message, signature []byte) bool
EncryptAES256CBC(key, plaintext []byte) ([]byte, error)
DecryptAES256CBC(key, ciphertext []byte) ([]byte, error)
ComputeHMAC(key, message []byte) []byte
ValidateHMAC(key, message, messageHMAC []byte) bool
Hash(data []byte) []byte
DeriveKey(secret, salt, info []byte, length int) ([]byte, error)
ExpandEncryptWithHMACKeyMaterial(key32 []byte) (hmacKey, aesKey []byte, err error)
DeriveIdentityKeyMaterial(sharedSecret, salt, context []byte) ([]byte, error)
}
CryptoProvider abstracts the cryptographic primitives used by Reticulum. The default implementation matches the on-wire protocol (X25519, Ed25519, AES-256-CBC, HMAC-SHA256, HKDF-SHA256). Call SetProvider to substitute implementations for testing or future algorithm agility; callers must preserve wire compatibility unless all peers are upgraded together.
func ActiveProvider ¶ added in v0.9.0
func ActiveProvider() CryptoProvider
ActiveProvider returns the current CryptoProvider (for tests or advanced use).
type Ed25519Signer ¶ added in v0.9.0
type Ed25519Signer interface {
Sign(message []byte) ([]byte, error)
Ed25519PublicKey() ed25519.PublicKey
}
Ed25519Signer signs Reticulum identity material with Ed25519. Use a software implementation from seed (NewSoftwareEd25519Signer) or wrap an HSM-backed crypto.Signer with NewEd25519SignerFromCryptoSigner. The public key must be the 32-byte Ed25519 key used in identity announcements.
func NewEd25519SignerFromCryptoSigner ¶ added in v0.9.0
func NewEd25519SignerFromCryptoSigner(s crypto.Signer) (Ed25519Signer, error)
NewEd25519SignerFromCryptoSigner wraps an Ed25519 crypto.Signer, such as PKCS#11 or a hardware key exposed via the standard library interface.
func NewSoftwareEd25519Signer ¶ added in v0.9.0
func NewSoftwareEd25519Signer(seed []byte) (Ed25519Signer, error)
NewSoftwareEd25519Signer returns a signer that uses an in-memory Ed25519 seed (same semantics as identity file bytes 32:64).
Source Files