nametransform

Documentation

Overview

Package nametransform encrypts and decrypts filenames.

Index

• Constants
• func DeleteLongNameAt(dirfd int, hashName string) error
• func Dir(path string) string
• func IsLongContent(cName string) bool
• func IsValidName(name string) error
• func NameType(cName string) int
• func ReadLongNameAt(dirfd int, cName string) (string, error)
• func RemoveLongNameSuffix(cName string) string
• func WriteDirIVAt(dirfd int) error
• type NameTransform
  • func New(e *eme.EMECipher, longNames bool, longNameMax uint8, raw64 bool, ...) *NameTransform
  • func (n *NameTransform) B64DecodeString(s string) ([]byte, error)
  • func (n *NameTransform) B64EncodeToString(src []byte) string
  • func (n *NameTransform) DecryptName(cipherName string, iv []byte) (string, error)
  • func (n *NameTransform) DecryptXattrName(cipherName string) (plainName string, err error)
  • func (be *NameTransform) EncryptAndHashBadName(name string, iv []byte, dirfd int) (cName string, err error)
  • func (be *NameTransform) EncryptAndHashName(name string, iv []byte) (string, error)
  • func (n *NameTransform) EncryptName(plainName string, iv []byte) (cipherName64 string, err error)
  • func (n *NameTransform) EncryptXattrName(plainName string) (cipherName64 string, err error)
  • func (n *NameTransform) GetLongNameMax() int
  • func (n *NameTransform) HashLongName(name string) string
  • func (n *NameTransform) HaveBadnamePatterns() bool
  • func (n *NameTransform) ReadDirIVAt(dirfd int) (iv []byte, err error)
  • func (n *NameTransform) WriteLongNameAt(dirfd int, hashName string, plainName string) (err error)

Constants

const (
	// DirIVLen is identical to AES block size
	DirIVLen = 16
	// DirIVFilename is the filename used to store directory IV.
	// Exported because we have to ignore this name in directory listing.
	DirIVFilename = "gocryptfs.diriv"
)

const (
	// LongNameContent is the file that stores the file content.
	// Example: gocryptfs.longname.URrM8kgxTKYMgCk4hKk7RO9Lcfr30XQof4L_5bD9Iro=
	LongNameContent = iota
	// LongNameFilename is the file that stores the full encrypted filename.
	// Example: gocryptfs.longname.URrM8kgxTKYMgCk4hKk7RO9Lcfr30XQof4L_5bD9Iro=.name
	LongNameFilename = iota
	// LongNameNone is used when the file does not have a long name.
	// Example: i1bpTaVLZq7sRNA9mL_2Ig==
	LongNameNone = iota
)

Values returned by IsLongName

const (
	// BadnameSuffix is appended to filenames in plaintext view if a corrupt
	// ciphername is shown due to a matching `-badname` pattern
	BadnameSuffix = " GOCRYPTFS_BAD_NAME"
)

const (
	// LongNameSuffix is the suffix used for files with long names.
	// Files with long names are stored in two files:
	// gocryptfs.longname.[sha256]       <--- File content, prefix = gocryptfs.longname.
	// gocryptfs.longname.[sha256].name  <--- File name, suffix = .name
	LongNameSuffix = ".name"
)

const (
	// Like ext4, we allow at most 255 bytes for a file name.
	NameMax = 255
)

Functions

func DeleteLongNameAt

func DeleteLongNameAt(dirfd int, hashName string) error

DeleteLongName deletes "hashName.name" in the directory opened at "dirfd".

This function is symlink-safe through the use of Unlinkat().

func Dir

func Dir(path string) string

Dir is like filepath.Dir but returns "" instead of ".".

func IsLongContent

func IsLongContent(cName string) bool

IsLongContent returns true if "cName" is the content store of a long name file (looks like "gocryptfs.longname.sha256").

This function does not do any I/O.

func IsValidName

func IsValidName(name string) error

IsValidName checks if `name` is a valid name for a normal file (does not contain null bytes or "/" etc...).

func NameType

func NameType(cName string) int

NameType - detect if cName is gocryptfs.longname.sha256 ........ LongNameContent (content of a long name file) gocryptfs.longname.sha256.name .... LongNameFilename (full file name of a long name file) else ................................ LongNameNone (normal file)

This function does not do any I/O.

func ReadLongNameAt

func ReadLongNameAt(dirfd int, cName string) (string, error)

ReadLongName - read cName + ".name" from the directory opened as dirfd.

Symlink-safe through Openat().

func RemoveLongNameSuffix

func RemoveLongNameSuffix(cName string) string

RemoveLongNameSuffix removes the ".name" suffix from cName, returning the corresponding content file name. No check is made if cName actually is a LongNameFilename.

func WriteDirIVAt

func WriteDirIVAt(dirfd int) error

WriteDirIVAt - create a new gocryptfs.diriv file in the directory opened at "dirfd". On error we try to delete the incomplete file. This function is exported because it is used from fusefrontend, main, and also the automated tests.

Types

type NameTransform

type NameTransform struct {

	// B64 = either base64.URLEncoding or base64.RawURLEncoding, depending
	// on the Raw64 feature flag
	B64 *base64.Encoding
	// contains filtered or unexported fields
}

NameTransform is used to transform filenames.

func New

func New(e *eme.EMECipher, longNames bool, longNameMax uint8, raw64 bool, badname []string, deterministicNames bool) *NameTransform

New returns a new NameTransform instance.

If `longNames` is set, names longer than `longNameMax` are hashed to `gocryptfs.longname.[sha256]`. Pass `longNameMax = 0` to use the default value (255).

func (*NameTransform) B64DecodeString

func (n *NameTransform) B64DecodeString(s string) ([]byte, error)

B64DecodeString decodes a Base64-encoded string

func (*NameTransform) B64EncodeToString

func (n *NameTransform) B64EncodeToString(src []byte) string

B64EncodeToString returns a Base64-encoded string

func (*NameTransform) DecryptName

func (n *NameTransform) DecryptName(cipherName string, iv []byte) (string, error)

DecryptName calls decryptName to try and decrypt a base64-encoded encrypted filename "cipherName", and failing that checks if it can be bypassed

func (*NameTransform) DecryptXattrName

func (n *NameTransform) DecryptXattrName(cipherName string) (plainName string, err error)

DecryptXattrName calls decryptName to try and decrypt a base64-encoded encrypted filename "cipherName", and failing that checks if it can be bypassed

func (*NameTransform) EncryptAndHashBadName

func (be *NameTransform) EncryptAndHashBadName(name string, iv []byte, dirfd int) (cName string, err error)

EncryptAndHashBadName tries to find the "name" substring, which (encrypted and hashed) leads to an unique existing file Returns ENOENT if cipher file does not exist or is not unique

func (*NameTransform) EncryptAndHashName

func (be *NameTransform) EncryptAndHashName(name string, iv []byte) (string, error)

EncryptAndHashName encrypts "name" and hashes it to a longname if it is too long. Returns ENAMETOOLONG if "name" is longer than 255 bytes.

func (*NameTransform) EncryptName

func (n *NameTransform) EncryptName(plainName string, iv []byte) (cipherName64 string, err error)

EncryptName encrypts a file name "plainName" and returns a base64-encoded "cipherName64", encrypted using EME (https://github.com/rfjakob/eme).

plainName is checked for null bytes, slashes etc. and such names are rejected with an error.

This function is exported because in some cases, fusefrontend needs access to the full (not hashed) name if longname is used.

func (*NameTransform) EncryptXattrName

func (n *NameTransform) EncryptXattrName(plainName string) (cipherName64 string, err error)

EncryptXattrName encrypts an extended attribute (xattr) name. xattr names are encrypted like file names, but with a fixed IV, and fewer naming restriction.

func (*NameTransform) GetLongNameMax

func (n *NameTransform) GetLongNameMax() int

GetLongNameMax will return curent `longNameMax`. File name longer than this should be hashed.

func (*NameTransform) HashLongName

func (n *NameTransform) HashLongName(name string) string

HashLongName - take the hash of a long string "name" and return "gocryptfs.longname.sha256"

This function does not do any I/O.

func (*NameTransform) HaveBadnamePatterns

func (n *NameTransform) HaveBadnamePatterns() bool

HaveBadnamePatterns returns true if `-badname` patterns were provided

func (*NameTransform) ReadDirIVAt

func (n *NameTransform) ReadDirIVAt(dirfd int) (iv []byte, err error)

ReadDirIVAt reads "gocryptfs.diriv" from the directory that is opened as "dirfd". Using the dirfd makes it immune to concurrent renames of the directory. Retries on EINTR. If deterministicNames is set it returns an all-zero slice.

func (*NameTransform) WriteLongNameAt

func (n *NameTransform) WriteLongNameAt(dirfd int, hashName string, plainName string) (err error)

WriteLongName encrypts plainName and writes it into "hashName.name". For the convenience of the caller, plainName may also be a path and will be Base()named internally.

This function is symlink-safe through the use of Openat().