cryptsetup

Documentation

Overview

Package cryptsetup provides a wrapper around libcryptsetup. The package is used to manage encrypted disks for Constellation.

Since libcryptsetup is not thread safe, this package uses a global lock to prevent concurrent use. There should only be one instance using this package per process.

Copyright (c) Edgeless Systems GmbH

SPDX-License-Identifier: AGPL-3.0-only

Index

• Constants
• type CryptSetup
  • func New() *CryptSetup
  • func (c *CryptSetup) ActivateByPassphrase(deviceName string, keyslot int, passphrase string, flags int) error
  • func (c *CryptSetup) ActivateByVolumeKey(deviceName, volumeKey string, volumeKeySize, flags int) error
  • func (c *CryptSetup) ConstellationStateDiskTokenIsInitialized() bool
  • func (c *CryptSetup) Deactivate(deviceName string) error
  • func (c *CryptSetup) Format(integrity bool) error
  • func (c *CryptSetup) Free()
  • func (c *CryptSetup) GetDeviceName() string
  • func (c *CryptSetup) GetUUID() (string, error)
  • func (c *CryptSetup) Init(devicePath string) (free func(), err error)
  • func (c *CryptSetup) InitByName(name string) (free func(), err error)
  • func (c *CryptSetup) KeyslotAddByVolumeKey(keyslot int, volumeKey string, passphrase string) error
  • func (c *CryptSetup) KeyslotChangeByPassphrase(currentKeyslot, newKeyslot int, currentPassphrase, newPassphrase string) error
  • func (c *CryptSetup) LoadLUKS2() error
  • func (c *CryptSetup) Resize(name string, newSize uint64) error
  • func (c *CryptSetup) SetConstellationStateDiskToken(diskIsInitialized bool) error
  • func (c *CryptSetup) TokenJSONGet(token int) (string, error)
  • func (c *CryptSetup) TokenJSONSet(token int, json string) (int, error)
  • func (c *CryptSetup) Wipe(name string, blockWipeSize int, flags int, ...) (err error)

Constants

const (
	// ConstellationStateDiskTokenID is the ID of Constellation's state disk token.
	ConstellationStateDiskTokenID = 0
	// SetDiskInitialized is a flag to set the Constellation state disk token to initialized.
	SetDiskInitialized = true
	// SetDiskNotInitialized is a flag to set the Constellation state disk token to not initialized.
	SetDiskNotInitialized = false

	// FormatIntegrity is a flag to enable dm-integrity for a crypt device when formatting.
	FormatIntegrity = true
	// FormatNoIntegrity is a flag to disable dm-integrity for a crypt device when formatting.
	FormatNoIntegrity = false
)

const (
	// ReadWriteQueueBypass is a flag to disable the write and read workqueues for a crypt device.
	ReadWriteQueueBypass = C.CRYPT_ACTIVATE_NO_WRITE_WORKQUEUE | C.CRYPT_ACTIVATE_NO_READ_WORKQUEUE
)

Types

type CryptSetup

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

CryptSetup manages encrypted devices.

func New

func New() *CryptSetup

New creates a new CryptSetup. Before first use, call Init() or InitByName() to open a crypt device.

func (*CryptSetup) ActivateByPassphrase

func (c *CryptSetup) ActivateByPassphrase(deviceName string, keyslot int, passphrase string, flags int) error

ActivateByPassphrase actives a crypt device using a passphrase.

func (*CryptSetup) ActivateByVolumeKey

func (c *CryptSetup) ActivateByVolumeKey(deviceName, volumeKey string, volumeKeySize, flags int) error

ActivateByVolumeKey activates a crypt device using a volume key. Set volumeKey to empty string to use the internal key.

func (*CryptSetup) ConstellationStateDiskTokenIsInitialized

func (c *CryptSetup) ConstellationStateDiskTokenIsInitialized() bool

ConstellationStateDiskTokenIsInitialized returns true if the Constellation state disk token is set to initialized.

func (*CryptSetup) Deactivate

func (c *CryptSetup) Deactivate(deviceName string) error

Deactivate deactivates a crypt device, removing the mapped device.

func (*CryptSetup) Format

func (c *CryptSetup) Format(integrity bool) error

Format formats a disk as a LUKS2 crypt device. Optionally set integrity to true to enable dm-integrity for the device.

func (*CryptSetup) Free

func (c *CryptSetup) Free()

Free frees resources from a previously opened crypt device.

func (*CryptSetup) GetDeviceName

func (c *CryptSetup) GetDeviceName() string

GetDeviceName gets the path to the underlying device.

func (*CryptSetup) GetUUID

func (c *CryptSetup) GetUUID() (string, error)

GetUUID gets the device's LUKS2 UUID. The UUID is returned in lowercase.

func (*CryptSetup) Init

func (c *CryptSetup) Init(devicePath string) (free func(), err error)

Init opens a crypt device by device path.

func (*CryptSetup) InitByName

func (c *CryptSetup) InitByName(name string) (free func(), err error)

InitByName opens an active crypt device using its mapped name.

func (*CryptSetup) KeyslotAddByVolumeKey

func (c *CryptSetup) KeyslotAddByVolumeKey(keyslot int, volumeKey string, passphrase string) error

KeyslotAddByVolumeKey adds a key slot to a device, allowing later activations using the chosen passphrase. Set volumeKey to empty string to use the internal key.

func (*CryptSetup) KeyslotChangeByPassphrase

func (c *CryptSetup) KeyslotChangeByPassphrase(currentKeyslot, newKeyslot int, currentPassphrase, newPassphrase string) error

KeyslotChangeByPassphrase changes the passphrase for a keyslot.

func (*CryptSetup) LoadLUKS2

func (c *CryptSetup) LoadLUKS2() error

LoadLUKS2 loads the device as LUKS2 crypt device.

func (*CryptSetup) Resize

func (c *CryptSetup) Resize(name string, newSize uint64) error

Resize resizes a device to the given size. name must be equal to the mapped device name. Set newSize to 0 to use the maximum available size.

func (*CryptSetup) SetConstellationStateDiskToken

func (c *CryptSetup) SetConstellationStateDiskToken(diskIsInitialized bool) error

SetConstellationStateDiskToken sets the Constellation state disk token.

func (*CryptSetup) TokenJSONGet

func (c *CryptSetup) TokenJSONGet(token int) (string, error)

TokenJSONGet gets the JSON data for a token.

func (*CryptSetup) TokenJSONSet

func (c *CryptSetup) TokenJSONSet(token int, json string) (int, error)

TokenJSONSet sets the JSON data for a token. The JSON data must be a valid LUKS2 token. Required fields are:

• type [string] the token type (tokens with luks2- prefix are reserved)
• keyslots [array] the array of keyslot objects names that are assigned to the token

Returns the allocated token ID on success.

func (*CryptSetup) Wipe

func (c *CryptSetup) Wipe(
	name string, blockWipeSize int, flags int, logCallback func(size, offset uint64), logFrequency time.Duration,
) (err error)

Wipe overwrites the device with zeros to initialize integrity checksums.