Moov's mission is to give developers an easy way to create and integrate bank processing into their own software products. Our open source projects are each focused on solving a single responsibility in financial services and designed around performance, scalability, and ease of use.
cryptfs implements Go's io/fs.FS interface for interacting with the local filesystem to transparently encrypt/decrypt files. This is useful as a library because it offers applications a well tested routine for keeping data protected.
cryptfs is included in multiple open-source projects Moov offers and is used in production environments. Please star the project if you are interested in its progress. If you find any bugs or desire additional encryption/encoding algorithms we would appreciate an issue or pull request. Thanks!
Cryptfs supports AES and GPG for encryption and Base64 (Standard Raw) encoding. Currently cryptfs is usable as a Go library in your applications. This needs to be initialized prior to reading or writing any files.
The original []byte-based API encrypts and decrypts data entirely in memory.
AES Cryptor
key := []byte("1234567812345678") // insecure key
fsys, err := cryptfs.FromCryptor(cryptfs.NewAESCryptor(key))
if err != nil {
// do something
}
fsys.SetCoder(cryptfs.Base64()) // optional, default is the raw bytesGPG Cryptor
fsys, err := cryptfs.FromCryptor(cryptfs.NewGPGCryptorFile(publicKeyPath, privateKeyPath, password))
if err != nil {
// handle error
}
fsys.SetCoder(cryptfs.Base64()) // optional, default is the raw bytesOnce initialized you can perform open/read and write operations.
Open
file, err := fsys.Open(path)
if err != nil {
// handle error
}ReadFile
plaintext, err := fsys.ReadFile(path)
if err != nil {
// handle error
}WriteFile
err := fsys.WriteFile(path, data, 0600)
if err != nil {
// handle error
}The github.com/moov-io/cryptfs/stream sub-package provides streaming encryption that works in fixed-size chunks (default 64KB), keeping memory usage bounded regardless of file size. This is ideal for use with cloud storage (e.g. gocloud.dev/blob) or any io.Writer/io.Reader pipeline.
The streaming format (CRFS) uses AES-GCM with per-file data keys, chunked encryption, and optional gzip compression. When using Vault, this enables envelope encryption — Vault generates and wraps data keys, and all data encryption happens locally. The master key never leaves Vault.
AES streaming
import "github.com/moov-io/cryptfs/stream"
key := []byte("1234567812345678")
kp := stream.NewStaticKeyProvider(key)
// Encrypt
var buf bytes.Buffer
w, err := stream.NewWriter(&buf, kp, stream.WithCompression()) // compression is optional
if err != nil {
// handle error
}
if _, err := io.Copy(w, sourceReader); err != nil {
// handle error
}
if err := w.Close(); err != nil {
// handle error
}
// Decrypt
r, err := stream.NewReader(bytes.NewReader(buf.Bytes()), kp)
if err != nil {
// handle error
}
plaintext, err := io.ReadAll(r)
if err != nil {
// handle error
}
if err := r.Close(); err != nil {
// handle error
}Vault envelope encryption
Each call to stream.NewWriter generates a fresh data key via Vault Transit — the plaintext key encrypts locally, and only the wrapped key is stored in the file header.
import (
"github.com/moov-io/cryptfs"
"github.com/moov-io/cryptfs/stream"
)
// Set up Vault key provider
kp, err := cryptfs.NewVaultKeyProvider(vaultConf)
if err != nil {
// handle error
}
// Write — generates a Vault data key, encrypts locally
w, err := stream.NewWriter(destination, kp)
if err != nil {
// handle error
}
if _, err := io.Copy(w, sourceReader); err != nil {
// handle error
}
if err := w.Close(); err != nil {
// handle error
}
// Read — unwraps the data key via Vault, decrypts locally
r, err := stream.NewReader(source, kp)
if err != nil {
// handle error
}
plaintext, err := io.ReadAll(r)
if err != nil {
// handle error
}
if err := r.Close(); err != nil {
// handle error
}Streaming write to a cloud bucket
func (bs *bucketStorage) Save(ctx context.Context, path string, file fs.File) (retErr error) {
bw, err := bs.bucket.NewWriter(ctx, path, nil)
if err != nil {
return err
}
defer func() {
if err := bw.Close(); retErr == nil {
retErr = err
}
}()
ew, err := stream.NewWriter(bw, bs.keyProvider)
if err != nil {
return err
}
defer func() {
if err := ew.Close(); retErr == nil {
retErr = err
}
}()
_, err = io.Copy(ew, file)
return err
}Streaming read from a cloud bucket
func (bs *bucketStorage) Read(ctx context.Context, path string) (io.ReadCloser, error) {
br, err := bs.bucket.NewReader(ctx, path, nil)
if err != nil {
return nil, err
}
dr, err := stream.NewReader(br, bs.keyProvider)
if err != nil {
br.Close()
return nil, err
}
return dr, nil // Close() closes both dr and the underlying bucket reader
}Moov offers a command line tool for using this library as well. It's handy for operational debugging and testing.
| channel | info |
|---|---|
| Twitter @moov | You can follow Moov.io's Twitter feed to get updates on our project(s). You can also tweet us questions or just share blogs or stories. |
| GitHub Issue | If you are able to reproduce a problem please open a GitHub Issue under the specific project that caused the error. |
| moov-io slack | Join our slack channel to have an interactive discussion about the development of the project. |
- 64-bit Linux (Ubuntu, Debian), macOS, and Windows
Yes please! Please review our Contributing guide and Code of Conduct to get started! Checkout our issues for first time contributors for something to help out with.
This project uses Go Modules and Go v1.18 or newer. See Golang's install instructions for help setting up Go. You can download the source code and we offer tagged and released versions as well. We highly recommend you use a tagged release for production.
Apache License 2.0 - See LICENSE for details.