internal

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 14, 2025 License: MIT Imports: 28 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	AeadTypeGcm               = &AeadType{"AES-GCM-256", HkdfInfoGcmContent, sizeIvAesGcm, sizeKeyAesGcm}
	AeadTypeSiv               = &AeadType{"AES-SIV-512", HkdfInfoSivContent, sizeIvAesSiv, sizeKeyAesSiv}
	AeadTypeXChaCha20Poly1305 = &AeadType{"XChaCha20-Poly1305", HkdfInfoXChaChaPoly1305Content, sizeIvXChaCha20_Poly1305, sizeKeyXChaChaPoly1305Content}
)
View Source 
var (
	ErrInvalidFS    = errors.New("not a gocryptfs directory")
	ErrBadPassword  = errors.New("wrong password")
	ErrDirNotEmpty  = errors.New("directory not empty")
	ErrMustBeAesSiv = errors.New("reverse mode fs must use aead type siv")
	ErrNotDirectory = errors.New("not a directory")
)
View Source 
var (
	ErrBadDirIv           = errors.New("diriv size is not 16")
	ErrBadKeySize         = errors.New("master key size is not 32")
	ErrUnsupportedVersion = errors.New("unsupported gocryptfs version")
	ErrUnknownAeadBackend = errors.New("cannot determine aead backend from featureflags")
)

Functions

func CreateFS added in v0.2.0 

func CreateFS(base any, aeadType *AeadType, log2n int, password, masterkey []byte, reverse bool) ([]byte, error)

log2n parameter should be >= 10 for security; 16 is recommended; gocryptfs max is 28.

"masterkey" can be nil, or an AeadTypeGcm key (32 bytes).

Returns the master key, print it to user once and wipe it.

func Passwd added in v0.2.0 

func Passwd(base any, oldpass, newpass, masterkey []byte) ([]byte, error)

Change password and/or masterkey of a gocryptfs.

"masterkey" can be nil, or an AeadTypeGcm key (32 bytes).

Be cautious supplying "masterkey", as changing master key doesn't require "oldpass", and a bad master key risks breaking a fs irreversibly.

Automatically identifies reverse mode fs.

Returns the master key, print it to user once and wipe it.

func ReadPassword 

func ReadPassword(fd int) []byte

func ValidBase added in v0.2.0 

func ValidBase(base any) bool

Types

type AeadType added in v0.2.0 

type AeadType struct {
	Name     string
	HkdfInfo HkdfInfo
	SizeIv   int
	SizeKey  int
}

Aead types

ref: gocryptfs/internal/cryptocore/cryptocore.go

func (AeadType) String added in v0.2.0 

func (a AeadType) String() string

type Conf added in v0.2.0 

type Conf struct {
	ScryptObject ScryptObject // not embedded for json.Unmarshal
	FeatureFlags []string
	Creator      string
	EncryptedKey string
	Version      int
}

Same structure as gocryptfs.conf

func ReadConf added in v0.2.0 

func ReadConf(base any) (conf *Conf, reverse bool, err error)

Try to read configuration from base FS.

func (*Conf) GetAeadBackend added in v0.2.0 

func (c *Conf) GetAeadBackend() (*AeadType, error)

Get AEAD backend from feature flags in conf.

func (*Conf) GetKey added in v0.2.0 

func (c *Conf) GetKey(password []byte) ([]byte, error)

Decrypt the master key.

func (*Conf) Parse added in v0.2.0 

func (c *Conf) Parse(data []byte) error

Parse config from gocryptfs.conf data (raw json).

func (*Conf) SetKey added in v0.2.0 

func (c *Conf) SetKey(password, masterkey []byte) ([]byte, error)

Sets master key as EncryptedKey encrypted with password.

If masterkey is nil, a random one is used. If not, it should be size of AeadTypeGcm key (32 bytes).

Returns the plain master key on success. Wipe it after printing it to user once.

func (*Conf) Write added in v0.2.0 

func (c *Conf) Write(base any, reverse bool) error

Write gocryptfs.conf (or reverse conf) to base FS.

type EncryptedFile added in v0.2.0 

type EncryptedFile struct {
	// contains filtered or unexported fields
}

A virtual file, for reading underlying cleartext content.

Implements fs.File, io.ReaderAt, io.Seeker, io.Writer, io.WriterAt, and ReadDir, Truncate functions.

func (*EncryptedFile) Close added in v0.2.0 

func (e *EncryptedFile) Close() error

Write modified block to disk (if any), close the underlying file.

func (*EncryptedFile) Flush added in v0.2.0 

func (e *EncryptedFile) Flush() (int, error)

Write current block encrypted to disk (if modified).

func (*EncryptedFile) Read added in v0.2.0 

func (e *EncryptedFile) Read(buf []byte) (int, error)

Read the underlying plaintext data.

For concurrency, use [encryptedFile.ReadAt] with bufsize and seek boundry 4096.

func (*EncryptedFile) ReadAt added in v0.2.0 

func (e *EncryptedFile) ReadAt(buf []byte, at int64) (int, error)

Concurrency safe. Useful for zip, 9p, and more packages.

func (*EncryptedFile) ReadDir added in v0.2.0 

func (e *EncryptedFile) ReadDir(n int) ([]fs.DirEntry, error)

Similar to [(*os.File).ReadDir], useful for [http.FS] etc.

func (*EncryptedFile) Seek added in v0.2.0 

func (e *EncryptedFile) Seek(o int64, w int) (int64, error)

func (*EncryptedFile) Stat added in v0.2.0 

func (e *EncryptedFile) Stat() (fs.FileInfo, error)

func (*EncryptedFile) Truncate added in v0.2.0 

func (e *EncryptedFile) Truncate(n int64) error

n < size: Preserves part of the last chunk.

n > size: Extends zero bytes to n.

func (*EncryptedFile) Write added in v0.2.0 

func (e *EncryptedFile) Write(buf []byte) (int, error)

Read and Write should only be used synchronously.

For concurrency, use [ReadAt] and [WriteAt].

func (*EncryptedFile) WriteAt added in v0.2.0 

func (e *EncryptedFile) WriteAt(buf []byte, at int64) (int, error)

Identical to Seek, Write, then Flush, guarded by a mutex.

Dev note: unlike [ReadAt], keeping a local block buffer is still unsafe for [WriteAt], as writes to the same block have race condition.

type FS 

type FS struct {
	// Wrapper for underlying FS.
	FS duckfs.FS
	// contains filtered or unexported fields
}

Implements fs.FS, fs.ReadDirFS and fs.StatFS.

Plus io.Closer for wiping master key in memory.

func NewFS 

func NewFS(base any, password []byte, masterkey []byte) (*FS, error)

New FS. May return ErrBadPassword or other errors.

Optionally pass masterkey, in this case password is ignored. After that, wipe masterkey manually.

func (*FS) Chmod added in v0.2.0 

func (f *FS) Chmod(name string, mode fs.FileMode) error

Change file mode.

func (*FS) Close 

func (f *FS) Close() error

In case the underlying FS has clean-up functions.

func (*FS) Create added in v0.2.0 

func (f *FS) Create(name string) (fs.File, error)

Create a file and return it opened read-write.

func (*FS) EncryptName added in v0.2.0 

func (f *FS) EncryptName(name string) (string, error)

Plain filename to encrypted filename.

Make sure to path.Clean the input.

func (*FS) Mkdir added in v0.2.0 

func (f *FS) Mkdir(name string, perm fs.FileMode) error

Create a directory, and generate a diriv under it.

Use perm 0o755 if unsure.

func (*FS) MkdirAll added in v0.2.0 

func (f *FS) MkdirAll(name string, perm fs.FileMode) error

Create directories if they are not yet created.

Use perm 0o755 if unsure.

func (*FS) Open 

func (f *FS) Open(name string) (fs.File, error)

Opens a file readonly.

func (*FS) OpenFile added in v0.2.0 

func (f *FS) OpenFile(name string, flag int, perm fs.FileMode) (fs.File, error)

Similar to os.OpenFile or os.Root.OpenFile. (But not identical!)

Files opened implements io.Writer, io.WriterAt, and other writing functions, if "base" FS implements duckfs.OpenFile or duckfs.OpenFileFS.

In most cases, you want to use FS.Open or FS.Create instead.

Use perm 0o644 if unsure.

func (*FS) ReadDir 

func (f *FS) ReadDir(name string) ([]fs.DirEntry, error)

func (*FS) Remove added in v0.2.0 

func (f *FS) Remove(name string) error

Remove a file or empty directory.

From an outer perspective, an "empty" directory contains exactly one file: gocryptfs.diriv, this function removes it in such case, to remove this directory.

func (*FS) Rename added in v0.2.0 

func (f *FS) Rename(oldname, newname string) error

Rename ("move") a file or directory.

func (*FS) Stat 

func (f *FS) Stat(name string) (fs.FileInfo, error)

func (*FS) Truncate added in v0.2.0 

func (f *FS) Truncate(name string, size int64) error

Truncate the file if it exists. Truncates the plaintext data to "size".

An encrypted file on disk is bigger than the corresponding plaintext file. For an empty file, both are 0 bytes.

type HkdfInfo added in v0.2.0 

type HkdfInfo string
const (
	HkdfInfoEmeNames               HkdfInfo = "EME filename encryption"
	HkdfInfoGcmContent             HkdfInfo = "AES-GCM file content encryption"
	HkdfInfoSivContent             HkdfInfo = "AES-SIV file content encryption"
	HkdfInfoXChaChaPoly1305Content HkdfInfo = "XChaCha20-Poly1305 file content encryption"
)

Info strings for hkdf.Key.

ref: gocryptfs/internal/cryptocore/hkdf.go

type Purpose added in v0.2.0 

type Purpose string
const (
	PurposeDirIV     Purpose = "DIRIV"
	PurposeFileID    Purpose = "FILEID"
	PurposeSymlinkIV Purpose = "SYMLINKIV"
	PurposeBlock0IV  Purpose = "BLOCK0IV"
)

Purpose strings for deterministic iv.

ref: gocryptfs/internal/pathiv/pathiv.go

type ScryptObject added in v0.2.0 

type ScryptObject struct {
	Salt            string
	N, R, P, KeyLen int
}

func (*ScryptObject) Derive added in v0.2.0 

func (s *ScryptObject) Derive(password []byte) ([]byte, error)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.