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.FlagNoReadWorkqueue, luks.FlagNoWriteWorkqueue); 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 ¶
const ( FlagAllowDiscards string = "allow-discards" FlagSameCPUCrypt string = "same-cpu-crypt" FlagSubmitFromCryptCPUs string = "submit-from-crypt-cpus" FlagNoReadWorkqueue string = "no-read-workqueue" FlagNoWriteWorkqueue string = "no-write-workqueue" )
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 ¶
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
type ReadVolume ¶
type ReadVolume struct {
// contains filtered or unexported fields
}
func OpenReadVolume ¶
func OpenReadVolume(v *Volume) (r *ReadVolume, err error)
OpenReadVolume opens the volume without using dm. Reads decrypt the data.
func (*ReadVolume) Close ¶
func (r *ReadVolume) Close() error
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 {
// contains filtered or unexported fields
}
Volume represents information provided by an unsealed (i.e. with recovered password) LUKS slot
func (*Volume) MapperReady ¶
MapperReady waits for the mapped device to be created. This is a temporary workaround until devmapper does this. Use when the mapped device is not created immediately upon `SetupMapper` return.
func (*Volume) SetupMapper ¶
SetupMapper creates a device mapper for the given LUKS volume
Source Files
Directories