gofilecrypto

go-file-crypto

Zero-dependency file encryption for Go, compatible with @time-file/browser-file-crypto.

Language:

• English (this file)
• Korean: README.ko.md

Features

• Browser-compatible wire format (0x01, 0x02, 0x11, 0x12)
• AES-256-GCM
• PBKDF2-SHA256 (100,000 iterations)
• Password mode + keyfile mode
• Streaming encryption/decryption for large files
• Auto-detect decryption for standard + streaming payloads
• Keyfile generation/parsing/hash utilities
• Custom profile support (salt/iv/tag/chunk/markers)
• No external crypto dependency (Go stdlib only, Go 1.24+)

Why

time-file ecosystem already has browser-native encryption.
This module gives the same data format in Go so encrypted files can move between:

• browser -> go (decrypt)
• go -> browser (decrypt)

without conversion or migration code.

Requirements

• Go 1.24+
  • Uses standard library crypto/pbkdf2.

Install

go get github.com/Time-File/go-file-crypto

Quick Start

package main

import (
	"fmt"

	filecrypto "github.com/Time-File/go-file-crypto"
)

func main() {
	plain := []byte("hello-go-file-crypto")

	enc, err := filecrypto.Encrypt(plain, filecrypto.EncryptOptions{
		Password: "secret-password",
	})
	if err != nil {
		panic(err)
	}

	dec, err := filecrypto.Decrypt(enc, filecrypto.DecryptOptions{
		Password: "secret-password",
	})
	if err != nil {
		panic(err)
	}

	fmt.Println(string(dec))
}

API

Standard Encryption

encrypted, err := filecrypto.Encrypt(data, filecrypto.EncryptOptions{
	Password: "secret", // OR KeyData: "<base64>"
})

Standard Decryption (Auto-detect marker)

plain, err := filecrypto.Decrypt(encrypted, filecrypto.DecryptOptions{
	Password: "secret", // OR KeyData: "<base64>"
})

Auto Encryption

encrypted, err := filecrypto.EncryptAuto(data, filecrypto.AutoEncryptOptions{
	Password:      "secret",
	AutoStreaming: true, // stream when size > threshold
	// StreamingThreshold default: 100MB
})

Streaming (Reader/Writer)

err := filecrypto.EncryptReader(src, dst, filecrypto.StreamEncryptOptions{
	Password:  "secret", // OR KeyData
	ChunkSize: 64 * 1024,
})

err = filecrypto.DecryptReader(srcEnc, dstPlain, filecrypto.StreamDecryptOptions{
	Password: "secret", // OR KeyData
})

File Helpers

// Writes streaming format (0x11 or 0x12)
err := filecrypto.EncryptFileStream("plain.bin", "encrypted.bin", filecrypto.StreamEncryptOptions{
	Password: "secret",
})

// Auto-detects standard/streaming marker and decrypts
err = filecrypto.DecryptFile("encrypted.bin", "decrypted.bin", filecrypto.DecryptOptions{
	Password: "secret",
})

Keyfile Utilities

kf, err := filecrypto.GenerateKeyFile()
hash, err := filecrypto.ComputeKeyFileHash(kf.Key)

Detection Utilities

t := filecrypto.DetectEncryptionType(data, filecrypto.Profile{})
ok := filecrypto.IsEncryptedData(data, filecrypto.Profile{})

Error Handling

Primary error codes:

• PASSWORD_REQUIRED
• KEYFILE_REQUIRED
• INVALID_PASSWORD
• INVALID_KEYFILE
• INVALID_ENCRYPTED_DATA
• UNSUPPORTED_FORMAT
• ENCRYPTION_FAILED
• DECRYPTION_FAILED

Example:

plain, err := filecrypto.Decrypt(encrypted, filecrypto.DecryptOptions{Password: "wrong"})
if err != nil && filecrypto.IsCryptoErrorCode(err, filecrypto.ErrInvalidPassword) {
	// wrong password
}
_ = plain

Browser Compatibility

This module is intentionally compatible with @time-file/browser-file-crypto format.

• Standard password:
  • [0x01] + [salt:16] + [iv:12] + [ciphertext||tag]
• Standard keyfile:
  • [0x02] + [iv:12] + [ciphertext||tag]
• Stream password:
  • [0x11] + [version] + [chunkSize LE] + [salt] + [baseIV] + [chunks...]
• Stream keyfile:
  • [0x12] + [version] + [chunkSize LE] + [baseIV] + [chunks...]

Detailed spec:

• docs/compatibility.md
• docs/api.md
• docs/testing.md

timefile-cli Integration

timefile-cli can now encrypt files locally before upload using this module.

timefile upload secret.zip --crypto-password "my-pass"
timefile upload secret.zip --crypto-keyfile ./mykey.tfkey

Testing

This repository includes:

• deterministic unit tests
• stream corruption/error-path tests
• browser WebCrypto vector interoperability tests

Run:

go test ./...
go vet ./...

License

MIT. See LICENSE.