Documentation
¶
Overview ¶
decryptor.go: Chunked streaming decryption logic for go-fileencrypt
encryptor.go: Chunked streaming encryption logic for go-fileencrypt
format.go: File format constants and algorithm ID support for go-fileencrypt
key.go: Key derivation and management for go-fileencrypt
options.go: Configuration options for go-fileencrypt
Index ¶
- Constants
- Variables
- func CalculateChecksum(path string) ([]byte, error)
- func CalculateChecksumHex(path string) (string, error)
- func DeriveKeyArgon2(password, salt []byte, time, memory uint32, threads uint8, keyLen uint32) ([]byte, error)
- func DeriveKeyPBKDF2(password, salt []byte, iterations, keyLen int) ([]byte, error)
- func GenerateSalt(size int) ([]byte, error)
- func SanitizeError(err error) error
- func VerifyChecksum(path string, sum []byte) (bool, error)
- func VerifyChecksumHex(path string, hexSum string) (bool, error)
- func WrapError(context string, err error) error
- type Algorithm
- type Config
- type Decryptor
- type EncryptionError
- type Encryptor
- type Option
Constants ¶
const ( // MagicBytes is the file signature "GFE" (Go File Encrypt). MagicBytes = "GFE" // Version is the current file format version (1). Version = 1 // NonceSize is the size of the nonce for AES-GCM. NonceSize = 12 // HeaderSize is the total size of the file header. // File format: [3 bytes magic][1 byte version][12 bytes nonce][8 bytes file size][chunks...] HeaderSize = len(MagicBytes) + 1 + NonceSize + 8 // MaxChunkSize is the maximum size for a single chunk of data. MaxChunkSize = 10 * 1024 * 1024 )
const ( // DefaultPBKDF2Iterations is the default iteration count for PBKDF2 DefaultPBKDF2Iterations = 600000 // OWASP recommendation (2023) // MinPBKDF2Iterations is the minimum safe iteration count MinPBKDF2Iterations = 210000 // OWASP minimum // DefaultSaltSize is the default salt size in bytes DefaultSaltSize = 32 // DefaultKeySize is the default derived key size (32 bytes for AES-256) DefaultKeySize = 32 // DefaultArgon2Time is the number of iterations (time cost) DefaultArgon2Time = 3 // DefaultArgon2Memory is the memory cost in KiB (64 MB) DefaultArgon2Memory = 64 * 1024 // DefaultArgon2Threads is the parallelism factor DefaultArgon2Threads = 4 // MinArgon2Memory is the minimum memory cost (19 MB per OWASP minimum) MinArgon2Memory = 19 * 1024 )
const ( MinChunkSize = 1 // Minimum valid chunk size // DefaultChunkSize is the default chunk size used by the library // for streaming operations. It is intentionally smaller than // `MaxChunkSize` (format limit) so the library uses sensible // default buffering without reaching the format's absolute max. DefaultChunkSize = 1 * 1024 * 1024 // 1MB default chunk size )
Variables ¶
var ( ErrInvalidKey = fmt.Errorf("invalid key") ErrInvalidNonce = fmt.Errorf("invalid nonce") ErrChunkSize = fmt.Errorf("invalid chunk size") ErrChecksum = fmt.Errorf("checksum mismatch") ErrContextCanceled = fmt.Errorf("context canceled") )
Error types for file encryption
Functions ¶
func CalculateChecksum ¶
CalculateChecksum computes the SHA-256 checksum of a file.
func CalculateChecksumHex ¶
CalculateChecksumHex computes the SHA-256 checksum of a file and returns it as hex string.
func DeriveKeyArgon2 ¶
func DeriveKeyArgon2(password, salt []byte, time, memory uint32, threads uint8, keyLen uint32) ([]byte, error)
DeriveKeyArgon2 derives a key from a password using Argon2id. Argon2id is the recommended password hashing algorithm as of 2023 (winner of Password Hashing Competition). It provides better resistance to GPU/ASIC attacks compared to PBKDF2.
Parameters:
- password: The password bytes (will not be modified)
- salt: The salt bytes (must be at least 16 bytes, recommended 32 bytes)
- time: Time cost (number of iterations), minimum 1, recommended 3+
- memory: Memory cost in KiB (minimum 19456 = 19 MB, recommended 65536 = 64 MB)
- threads: Parallelism factor (recommended: number of CPU cores, typically 4)
- keyLen: Length of the derived key in bytes (typically 32 for AES-256)
OWASP 2023 Recommendations:
- Interactive logins: memory=64MB, time=3, threads=4
- Background operations: memory=256MB, time=4, threads=4
- Minimum acceptable: memory=19MB, time=2, threads=1
Example:
salt, _ := GenerateSalt(DefaultSaltSize)
key, err := DeriveKeyArgon2(
[]byte("password"),
salt,
DefaultArgon2Time, // 3 iterations
DefaultArgon2Memory, // 64 MB
DefaultArgon2Threads, // 4 threads
DefaultKeySize, // 32 bytes
)
if err != nil {
return err
}
defer secure.Zero(key)
func DeriveKeyPBKDF2 ¶
DeriveKeyPBKDF2 derives a key from a password using PBKDF2-HMAC-SHA256. Returns the derived key. The caller must securely zero the key after use.
Parameters:
- password: The password bytes (will not be modified)
- salt: The salt bytes (must be at least 16 bytes, recommended 32 bytes)
- iterations: Number of iterations (must be >= MinPBKDF2Iterations)
- keyLen: Length of the derived key in bytes (typically 32 for AES-256)
Example:
salt := make([]byte, DefaultSaltSize)
if _, err := rand.Read(salt); err != nil {
return err
}
key, err := DeriveKeyPBKDF2([]byte("password"), salt, DefaultPBKDF2Iterations, DefaultKeySize)
if err != nil {
return err
}
defer secure.Zero(key)
func GenerateSalt ¶
GenerateSalt generates a cryptographically secure random salt.
func SanitizeError ¶ added in v0.1.4
SanitizeError removes sensitive details for external consumption
func VerifyChecksum ¶
VerifyChecksum checks if the file matches the given checksum
func VerifyChecksumHex ¶
VerifyChecksumHex checks if the file matches the given hex-encoded checksum
Types ¶
type Algorithm ¶
type Algorithm uint8
Algorithm represents a cryptographic algorithm
const ( // AlgorithmAESGCM is AES-256-GCM (default, currently supported) AlgorithmAESGCM Algorithm = 1 // AlgorithmChaCha20Poly1305 is ChaCha20-Poly1305 (reserved for future) AlgorithmChaCha20Poly1305 Algorithm = 2 // AlgorithmMLKEMHybrid is ML-KEM hybrid post-quantum (reserved for future) AlgorithmMLKEMHybrid Algorithm = 3 )
func (Algorithm) IsSupported ¶
IsSupported returns true if the algorithm is currently implemented
type Decryptor ¶
type Decryptor struct {
// contains filtered or unexported fields
}
Decryptor handles chunked decryption of files and streams.
func (*Decryptor) DecryptFile ¶
DecryptFile performs chunked decryption of a file.
type EncryptionError ¶ added in v0.1.4
type EncryptionError struct {
Op string // Operation: "encrypt", "decrypt", "generate_key", etc.
Path string // File path being operated on
ChunkNum int // Chunk number if applicable (-1 if not chunked operation)
Err error // Underlying error
}
EncryptionError represents an encryption/decryption error with context
func NewEncryptionError ¶ added in v0.1.4
func NewEncryptionError(op, path string, chunkNum int, err error) *EncryptionError
NewEncryptionError creates a new EncryptionError
func (*EncryptionError) Error ¶ added in v0.1.4
func (e *EncryptionError) Error() string
func (*EncryptionError) Unwrap ¶ added in v0.1.4
func (e *EncryptionError) Unwrap() error
type Encryptor ¶
type Encryptor struct {
// contains filtered or unexported fields
}
Encryptor handles chunked encryption of files and streams.
func (*Encryptor) Destroy ¶
func (e *Encryptor) Destroy()
Destroy zeroes key material and unlocks memory
func (*Encryptor) EncryptFile ¶
EncryptFile performs chunked encryption of a file.
type Option ¶
type Option func(*Config)
Option defines functional options for encryption/decryption (chunk size, progress, checksum, algorithm, etc.)
func WithAlgorithm ¶
WithAlgorithm sets the encryption algorithm (default: AES-256-GCM). Currently only AlgorithmAESGCM is supported; others return an error.
func WithChecksum ¶
WithChecksum enables checksum calculation/verification.
func WithChunkSize ¶
WithChunkSize sets the chunk size for streaming operations.
func WithProgress ¶
WithProgress sets a progress callback (called at every 20% interval).
The callback receives a fraction between 0.0 and 1.0 (inclusive), where 0.0 means no progress and 1.0 means complete. Examples and documentation should use fractional progress (not percentages).
Source Files