luks

README

Pure Go library for LUKS volume management

luks.go is a pure-Go library that helps to deal with LUKS-encrypted volumes.

Currently, this library is focusing on the read-only path i.e. unlocking a partition without doing any modifications to LUKS metadata header.

Here is an example that demonstrates the API usage:

dev, err := luks.Open("/dev/sda1")
if err != nil {
  // handle error
}
defer dev.Close()

// set LUKS flags before unlocking the volume
if err := dev.FlagsAdd(luks.FlagAllowDiscards); err != nil {
    log.Print(err)
}

// UnsealVolume+SetupMapper is equivalent of `cryptsetup open /dev/sda1 volumename`
volume, err = dev.UnsealVolume(/* slot */ 0, []byte("password"))
if err == luks.ErrPassphraseDoesNotMatch {
    log.Printf("The password is incorrect")
} else if err != nil {
    log.Print(err)
} else {
    err := volume.SetupMapper("volumename")
    // at this point system should have a file `/dev/mapper/volumename`.
}

// equivalent of `cryptsetup close volumename`
if err := luks.Lock("volumename"); err != nil {
    log.Print(err)
}

License

See LICENSE.

Documentation

Index

• Constants
• Variables
• func Lock(name string) error
• type Device
  • func Open(path string) (Device, error)
• type Token
• type Volume
  • func (v *Volume) SetupMapper(name string) error

Constants

const (
	FlagAllowDiscards       string = "allow-discards"
	FlagSameCPUCrypt        string = "same-cpu-crypt"
	FlagSubmitFromCryptCPUs string = "submit-from-crypt-cpus"
	FlagNoReadWorkqueue     string = "no-read-workqueue"  // supported at Linux 5.9 or newer
	FlagNoWriteWorkqueue    string = "no-write-workqueue" // supported at Linux 5.9 or newer
)

List of options handled by luks.go API. These names correspond to LUKSv2 persistent flags names (see persistent_flags[] array).

Variables

var ErrPassphraseDoesNotMatch = fmt.Errorf("Passphrase does not match")

ErrPassphraseDoesNotMatch is an error that indicates provided passphrase does not match

Functions

func Lock

func Lock(name string) error

Lock closes device mapper partition with the given name

Types

type Device

type Device interface {
	io.Closer
	// Version returns version of LUKS disk
	Version() int
	// Path returns block device path
	Path() string
	// UUID returns UUID of the LUKS partition
	UUID() string
	// Slots returns list of all active slots for this device sorted by priority
	Slots() []int
	// Tokens returns list of available tokens (metadata) for slots
	Tokens() ([]Token, error)
	// FlagsGet get the list of LUKS flags (options) used during unlocking
	FlagsGet() []string
	// FlagsAdd adds LUKS flags used for the upcoming unlocking
	// Note that this method does not update LUKS v2 persistent flags
	FlagsAdd(flags ...string) error
	// FlagsClear clears flags
	// Note that this method does not update LUKS v2 persistent flags
	FlagsClear()

	// UnsealVolume recovers slot password and then populates Volume structure that contains information needed to
	// create a mapper device
	UnsealVolume(keyslot int, passphrase []byte) (*Volume, error)

	// Unlock is a shortcut for
	// “`go
	//   volume, err := dev.UnsealVolume(keyslot, passphrase)
	//   volume.SetupMapper(dmName)
	// “`
	Unlock(keyslot int, passphrase []byte, dmName string) error
	// UnlockAny iterates over all available slots and tries to unlock them until succeeds
	UnlockAny(passphrase []byte, dmName string) error
}

Device represents LUKS partition data

func Open

func Open(path string) (Device, error)

Open reads LUKS headers from the given partition and returns LUKS device object. This function internally handles LUKS v1 and v2 partitions metadata.

type Token

type Token struct {
	ID    int
	Slots []int
	// Type of the token e.g. "clevis", "systemd-fido2"
	Type    string
	Payload []byte
}

Token represents LUKS token metadata information

type Volume

type Volume struct {
	BackingDevice string
	Flags         []string // luks-named flags
	UUID          string

	LuksType          string
	StorageEncryption string
	StorageIvTweak    uint64
	StorageSectorSize uint64
	StorageOffset     uint64 // offset of underlying storage in bytes
	StorageSize       uint64 // length of underlying device in bytes, zero means that size should be calculated using `diskSize` function
	// contains filtered or unexported fields
}

Volume represents information provided by an unsealed (i.e. with recovered password) LUKS slot

func (*Volume) SetupMapper

func (v *Volume) SetupMapper(name string) error

SetupMapper creates a device mapper for the given LUKS volume