luks2

package
v0.0.9 Latest Latest
Warning

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

 Go to latest Published: Nov 11, 2022 License: GPL-3.0 Imports: 24 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// AnySlot tells AddKey to automatically choose an appropriate slot
	// as opposed to hard coding one.
	AnySlot = -1

	// AnyId tells ImportToken to automatically choose an appropriate token
	// ID as opposed to hard coding one.
	AnyId = -1
)

Variables

View Source 
var (
	// ErrMissingCryptsetupFeature is returned from some functions that make
	// use of the system's cryptsetup binary, if that binary is missing some
	// required features.
	ErrMissingCryptsetupFeature = errors.New("cannot perform the requested operation because a required feature is missing from cryptsetup")
)

Functions

func Activate 

func Activate(volumeName, sourceDevicePath string, key []byte) error

Activate unlocks the LUKS device at sourceDevicePath using systemd-cryptsetup and creates a device mapping with the supplied volumeName. The device is unlocked using the supplied key.

func AddKey 

func AddKey(devicePath string, existingKey, key []byte, options *AddKeyOptions) error

AddKey adds the supplied key in to a new keyslot for specified LUKS2 container. In order to do this, an existing key must be provided. The KDF for the new keyslot will be configured to use argon2i with the supplied benchmark time. The key will be added to the supplied slot.

If options is not supplied, the default KDF benchmark time is used and the command will automatically choose an appropriate slot.

func Deactivate 

func Deactivate(volumeName string) error

Deactivate detaches the LUKS volume with the supplied name.

func Format 

func Format(devicePath, label string, key []byte, opts *FormatOptions) error

Format will initialize a LUKS2 container with the specified options and set the primary key to the supplied key. The label for the new container will be set to the supplied label. This can only be called on a device that is not mapped.

The container will be configured to encrypt data with AES-256 and XTS block cipher mode. The KDF for the primary keyslot will be configured to use argon2i with the supplied benchmark time.

WARNING: This function is destructive. Calling this on an existing LUKS2 container will make the data contained inside of it irretrievable.

func ImportToken 

func ImportToken(devicePath string, token Token, options *ImportTokenOptions) error

ImportToken imports the supplied token in to the JSON metadata area of the specified LUKS2 container. This requires FeatureTokenImport. If the Replace field of options is set, then FeatureTokenReplace is required.

func KillSlot 

func KillSlot(devicePath string, slot int, key []byte) error

KillSlot erases the keyslot with the supplied slot number from the specified LUKS2 container. Note that a valid key for a remaining keyslot must be supplied, in order to prevent the last keyslot from being erased.

func RegisterTokenDecoder 

func RegisterTokenDecoder(typ TokenType, decoder TokenDecoder)

RegisterTokenDecoder registers a custom decoder for the specified token type, in order for external packages to be able to create type-specific token structures as opposed to relying on GenericToken.

func RemoveToken 

func RemoveToken(devicePath string, id int) error

RemoveToken removes the token with the supplied ID from the JSON metadata area of the specified LUKS2 container.

func SetSlotPriority 

func SetSlotPriority(devicePath string, slot int, priority SlotPriority) error

SetSlotPriority sets the priority of the keyslot with the supplied slot number on the specified LUKS2 container.

Types

type AF 

type AF struct {
	Type    AFType
	Stripes int  // Number of stripes
	Hash    Hash // Hash algorith.
}

AF correspnds to an af object in the JSON metadata of a LUKS2 volume, and details the anti-forensic splitter parameters for a keyslot.

type AFType 

type AFType string

AFType corresponds to an anti-forensic splitter algorithm. 

const (
	AFTypeLUKS1 AFType = "luks1"
)

type AddKeyOptions 

type AddKeyOptions struct {
	// KDFOptions describes the KDF options for the new key slot.
	KDFOptions KDFOptions

	// Slot is the keyslot to use. Note that the default value is slot 0. In
	// order to automatically choose a slot, use AnySlot.
	Slot int
}

AddKeyOptions provides the options for adding a key to a LUKS2 volume

type Area 

type Area struct {
	Type       AreaType
	Offset     uint64 // Offset from the device start to the beginning of this area, in bytes
	Size       uint64 // Size of this area in bytes
	Encryption string // Encryption algorithm used for this area in dm-crypt notation
	KeySize    int    // The size of the encryption key for this area, in bytes
}

Area corresponds to an area object in the JSON metadata of a LUKS2 volume, and details the parameters for the storage area in the binary keyslots area for a keyslot.

func (*Area) UnmarshalJSON 

func (a *Area) UnmarshalJSON(data []byte) error

type AreaType 

type AreaType string

AreaType corresponds to the type of a storage area in the binary keyslots area. 

const (
	AreaTypeRaw AreaType = "raw"
)

type Config 

type Config struct {
	JSONSize     uint64   // Size of the JSON area, in bytes
	KeyslotsSize uint64   // Size of the keyslots area, in bytes
	Flags        []string // Optional flags
	Requirements []string // Optional required features
}

Config corresponds to a config object in the JSON metadata of a LUKS2 volume.

func (*Config) UnmarshalJSON 

func (c *Config) UnmarshalJSON(data []byte) error

type Digest 

type Digest struct {
	Type       KDFType // Digest type
	Keyslots   []int   // The keyslots assigned to this digest
	Segments   []int   // The segments assigned to this digest
	Salt       []byte  // Salt for this digest
	Digest     []byte  // The actual digest
	Hash       Hash    // Hash algorithm (pbkdf2 only)
	Iterations int     // The number of iterations (pbkdf2 only)
}

Digest corresponds to a digest object in the JSON metadata area of a LUKS2 volume, and provides a way to verify that a key decrypted from a keyslot is correct. It also links keyslots to their corresponding segments.

func (*Digest) UnmarshalJSON 

func (d *Digest) UnmarshalJSON(data []byte) error

type Features 

type Features int

Features indicates the set of features supported by this package, determined by the features of the system's cryptsetup binary. 

const (
	// FeatureHeaderSizeSetting indicates that the header size settings can be
	// specified when using the Format API. This was introduced to cryptsetup by:
	// https://gitlab.com/cryptsetup/cryptsetup/-/commit/ec07927b55fa83f8a3980ea7b0cc0dd8032927f0
	FeatureHeaderSizeSetting Features = 1 << iota

	// FeatureTokenImport indicates that ImportToken can be used. Token imports were
	// introduced to cryptsetup by
	// https://gitlab.com/cryptsetup/cryptsetup/-/commit/cc27088df92b669df7649217c4a64dc72f21987a
	FeatureTokenImport

	// FeatureTokenReplace indicates that tokens can be atomically replaced with
	// ImportToken (yet to be implemented). This was introduced to cryptsetup by:
	// https://gitlab.com/cryptsetup/cryptsetup/-/commit/98cd52c8d7bddf5b4c1ff775158a48bbb522acb2
	FeatureTokenReplace
)

func DetectCryptsetupFeatures 

func DetectCryptsetupFeatures() Features

DetectCryptsetupFeatures returns the features supported by the cryptsetup binary on this system.

type FormatOptions 

type FormatOptions struct {
	// MetadataKiBSize sets the size of the metadata area in KiB.
	// This size includes the 4KiB fixed-size binary header, with
	// the remaining space for the JSON area. Set to zero to use
	// the cryptsetup default. Must be any power of 2 between
	// 16KiB and 4MiB.
	MetadataKiBSize int

	// KeyslotsAreaKiBSize sets the size of the binary keyslots
	// area in KiB. Set to zero to use the cryptsetup default.
	// Must be a multiple of 4KiB.
	KeyslotsAreaKiBSize int

	// KDFOptions describes the KDF options for the initial
	// key slot.
	KDFOptions KDFOptions
}

FormatOptions provide the options for formatting a new LUKS2 volume.

type GenericToken 

type GenericToken struct {
	TokenType     TokenType              // Token type ("luks2-" prefixed types are reserved for cryptsetup)
	TokenKeyslots []int                  // Keyslots assigned to this token
	Params        map[string]interface{} // Type-specific parameters for this token
}

GenericToken corresponds to a token that doesn't have a more type-specific representation.

func (*GenericToken) Keyslots 

func (t *GenericToken) Keyslots() []int

func (*GenericToken) MarshalJSON 

func (t *GenericToken) MarshalJSON() ([]byte, error)

func (*GenericToken) Type 

func (t *GenericToken) Type() TokenType

func (*GenericToken) UnmarshalJSON 

func (t *GenericToken) UnmarshalJSON(data []byte) error

type Hash 

type Hash string

Hash corresponds to a cryptpgraphic digest algorithm. 

const (
	HashSHA1   Hash = "sha1"
	HashSHA224 Hash = "sha224"
	HashSHA256 Hash = "sha256"
	HashSHA384 Hash = "sha384"
	HashSHA512 Hash = "sha512"
)

func (Hash) GetHash 

func (h Hash) GetHash() crypto.Hash

type HeaderInfo 

type HeaderInfo struct {
	HeaderSize uint64   // The total size of the binary header and JSON metadata in bytes
	Label      string   // The label
	Metadata   Metadata // JSON metadata
}

HeaderInfo corresponds to the header (binary header and JSON metadata) for a LUKS2 volume.

func ReadHeader 

func ReadHeader(path string, lockMode LockMode) (*HeaderInfo, error)

ReadHeader will decode the LUKS header at the specified path. The path can either be a block device or file containing a LUKS2 volume with an integral header, or it can be a detached header file. Data is interpreted in accordance with the LUKS2 On-Disk Format specification (https://gitlab.com/cryptsetup/LUKS2-docs/blob/master/luks2_doc_wip.pdf).

This function will verify the checksum of both the primary and secondary headers if found, and will return the decoded form of one of the headers according to the following rules:

  • If both headers have valid checksums and the same sequence ID, return the primary header.
  • If both headers have valid checksums but different sequence IDs, return the newest header.
  • If only one header has a valid checksum, return that header.

libcryptsetup performs some additional validation of the JSON metadata from both the primary and secondary headers, and rejects a header if the JSON metadata isn't correctly formed. We don't duplicate that logic here - we assume that anything that modifies the LUKS2 headers (which should only be libcryptsetup) will write well-formed JSON metadata. Corruption of the JSON metadata outside of modifications by libcryptsetup will be detected by the checksum verification.

Note that this function does not attempt recovery of either header in the event that one of the headers is not valid - we leave this to libcryptsetup, which happens automatically on any cryptsetup or systemd-cryptsetup invocation. This package does not directly perform any modifications to the header.

This function requires an advisory shared lock on the LUKS container associated with the specified path. If the mode parameter is LockModeBlocking, this function will block until the lock can be obtained. If the mode parameter is LockModeNonBlocking, a wrapped syscall.Errno error with the value of syscall.EWOULDBLOCK will be returned if the lock can not be obtained.

type ImportTokenOptions 

type ImportTokenOptions struct {
	// Id is the token ID to use. Note that the default value is slot 0. In
	// order to automatically choose an ID, use AnyId.
	Id int

	// Replace will overwrite an existing token at the specified slot.
	Replace bool
}

ImportTokenOptions provides the options for importing a JSON token into a LUKS2 header.

type Integrity 

type Integrity struct {
	Type              string // Integirty type in dm-crypt notation
	JournalEncryption string
	JournalIntegrity  string
}

Integrity corresponds to an integrity object in the JSON metadata of a LUKS2 volume, and details the data integrity parameters for a segment.

type JsonNumber 

type JsonNumber string

JsonNumber represents a JSON number literal. It is similar to json.Number but supports uint64 and int literals as required by the LUKS2 specification.

func (JsonNumber) Int 

func (n JsonNumber) Int() (int, error)

func (JsonNumber) Uint64 

func (n JsonNumber) Uint64() (uint64, error)

type KDF 

type KDF struct {
	Type       KDFType // KDF type (pbkdf2, argon2i or argon2id)
	Salt       []byte  // Salt for the KDF
	Hash       Hash    // Hash algorithm (pbkdf2 only)
	Iterations int     // Number of iterations (pbkdf2 only)
	Time       int     // Number of iterations (argon2 only)
	Memory     int     // Memory cost in kB (argon2 only)
	CPUs       int     // Number of threads (argon2 only)
}

KDF corresponds to a kdf object in the JSON metadata of a LUKS2 volume, and details the KDF parameters for a keyslot.

type KDFOptions 

type KDFOptions struct {
	// TargetDuration specifies the target time for benchmarking of the
	// time and memory cost parameters. If it is zero then the cryptsetup
	// default is used. If ForceIterations is not zero then this is ignored.
	TargetDuration time.Duration

	// MemoryKiB specifies the maximum memory cost in KiB when ForceIterations
	// is zero, or the actual memory cost in KiB when ForceIterations is not zero.
	// If this is set to zero, then the cryptsetup default is used.
	MemoryKiB int

	// ForceIterations specifies the time cost. If set to zero, the time
	// and memory cost are determined by benchmarking the algorithm based on
	// the specified TargetDuration. Set to a non-zero number to force the
	// time cost to the value of this field, and the memory cost to the value
	// of MemoryKiB, disabling benchmarking.
	ForceIterations int

	// Parallel sets the maximum number of parallel threads. Cryptsetup may
	// choose a lower value based on its own maximum and the number of available
	// CPU cores.
	Parallel int
}

KDFOptions specifies parameters for the Argon2 KDF.

type KDFType 

type KDFType string

KDFType corresponds to a key derivation function. 

const (
	KDFTypePBKDF2   KDFType = "pbkdf2"
	KDFTypeArgon2i  KDFType = "argon2i"
	KDFTypeArgon2id KDFType = "argon2id"
)

type Keyslot 

type Keyslot struct {
	Type     KeyslotType
	KeySize  int          // The size of the key protected by this keyslot, in bytes
	Area     *Area        // The allocated area in the keyslots area
	KDF      *KDF         // The KDF parameters used for this keyslot
	AF       *AF          // The anti-forensic splitter parameters used for this keyslot
	Priority SlotPriority // Priority of this keyslot (0:ignore, 1:normal, 2:high)
}

Keyslot corresponds to a keyslot object in the JSON metadata of a LUKS2 volume, and contains information about a stored protected key.

func (*Keyslot) UnmarshalJSON 

func (s *Keyslot) UnmarshalJSON(data []byte) error

type KeyslotType 

type KeyslotType string

KeyslotType corresponds to the type of a keyslot. 

const (
	KeyslotTypeLUKS2 KeyslotType = "luks2"
)

type LockMode 

type LockMode int

LockMode defines the locking mode for ReadHeader. 

const (
	LockModeBlocking LockMode = iota
	LockModeNonBlocking
)

type Metadata 

type Metadata struct {
	Keyslots map[int]*Keyslot // Keyslot objects
	Segments map[int]*Segment // Segment objects
	Digests  map[int]*Digest  // Digest objects
	Tokens   map[int]Token    // Token objects
	Config   Config           // Config object
}

Metadata corresponds to the top level object in the JSON metadata area of a LUKS2 volume.

func (*Metadata) UnmarshalJSON 

func (m *Metadata) UnmarshalJSON(data []byte) error

type Segment 

type Segment struct {
	Type        string
	Offset      uint64     // Offset from the device start to the beginning of this segment, in bytes
	Size        uint64     // Size of this segment, in bytes (only if DynamicSize is false)
	DynamicSize bool       // The size is the size of the underlying device
	IVTweak     uint64     // The starting offset of the IV tweak
	Encryption  string     // The encryption algorithm for this segment in dm-crypt notation
	SectorSize  int        // The sector size for this segment, in bytes
	Integrity   *Integrity // Data integrity parameters for this segment (optional)
	Flags       []string   // Additional options for this segment
}

Segment corresponds to a segment object in the JSON metadata of a LUKS2 volume, and details an encrypted area on disk.

func (*Segment) UnmarshalJSON 

func (s *Segment) UnmarshalJSON(data []byte) error

type SlotPriority 

type SlotPriority int

SlotPriority represents the priority of a keyslot. 

const (
	// SlotPriorityIgnore means that cryptsetup will not use the associated
	// keyslot unless it is specified explicitly.
	SlotPriorityIgnore SlotPriority = iota

	// SlotPriorityNormal is the default keyslot priority.
	SlotPriorityNormal

	// SlotPriorityHigh means that cryptsetup will try the associated keyslot
	// before it tries any keyslots with a priority of SlotPriorityNormal.
	SlotPriorityHigh
)

func (SlotPriority) String 

func (p SlotPriority) String() string

type Token 

type Token interface {
	Type() TokenType // Token type ("luks2-" prefixed types are reserved for cryptsetup)
	Keyslots() []int // Keyslots assigned to this token
}

Token corresponds to a token object in the JSON metadata of a LUKS2 volume. It describes how to retrieve a passphrase or key for a keyslot. Tokens decoded by ReadHeader will be represented by a type-specific implementation if a TokenDecoder is registered for it, or GenericToken.

type TokenDecoder 

type TokenDecoder func([]byte) (Token, error)

TokenDecoder provides a mechanism for an external package to decode custom token types.

type TokenType 

type TokenType string
const (
	TokenTypeKeyring TokenType = "luks2-keyring"
)

Source Files

View all Source files

Directories

Path Synopsis

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.