cryptsetup

README

Table of Contents

• 1. Install
• 2. Hacking

The go-cryptsetup package is designed to provide golang bindings to the cryptsetup library. The cryptsetup library is what provides access to encrypted hard drives on the linux kernel and provides some of the best encryption for protecting a hard drive from an attacker with physical access to the device (and not enough time for a full firmware hack plus arranging for the unsuspecting user to enter their password).

Install

This project can be easily installed with just

go get -u github.com/kcolford/go-cryptsetup

Hacking

The project is maintained on Github. Pull requests will gladly be accepted.

Please remember to run go generate to rebuild the generated source code. The generated files are committed to the repository as per the recommendations of the Go documentation.

Documentation

Overview

Cryptsetup is designed to facilitate using linux's full disk encryption.

Some distributions may require you to install the relevent development libraries. Arch Linux includes all the necessary libraries by default, although it does not include libcryptsetup.a, the static version of the library. A modified PKGBUILD can be found in the contrib/ directory that should fix this (it's a relatively fast build time on an intel celeron).

Index

• Constants
• func Dir() string
• type CryptError
  • func (e CryptError) Error() string
• type CryptParameter
• type Device
  • func NewDevice(name string) (d *Device, err error)
  • func (d *Device) Activate(name string, pass []byte) error
  • func (d *Device) AddKey(pass []byte, newpass []byte) error
  • func (d *Device) Benchmark(iv_size uint64, buffer_size uint64, pp Params) (enc float64, dec float64, err error)
  • func (d *Device) BenchmarkKdf(hash string, pass, salt []byte) (iter uint64, err error)
  • func (d *Device) Close()
  • func (d *Device) Deactivate(name string) error
  • func (d *Device) DelKey(pass []byte) (err error)
  • func (d *Device) Format(key []byte, p CryptParameter) error
  • func (d *Device) Load(p CryptParameter) error
  • func (d *Device) Name() string
  • func (d *Device) Params() (pp Params)
  • func (d *Device) SetDataDevice(name string) error
  • func (d *Device) SetIterationTime(t time.Duration)
  • func (d *Device) SetUuid(uuid string) error
  • func (d *Device) Uuid() string
• type LuksParams
  • func (p LuksParams) CMode() (t string, pp Params, out unsafe.Pointer, free func())
• type Params
• type PlainParams
  • func (p PlainParams) CMode() (t string, pp Params, out unsafe.Pointer, free func())

Examples

• Device.Benchmark
• Device.BenchmarkKdf

Constants

const (
	DefaultCipher = "aes"
	DefaultMode   = "xts-plain64"
	DefaultHash   = "sha256"
)

Default cipher settings designed to maximize the security of one's data.

Functions

func Dir

func Dir() string

Dir returns the directory were the decrypted devices are placed.

Types

type CryptError

type CryptError struct {
	Messages []string
	Errno    error
}

CryptError is an error produced by libcryptsetup.

func (CryptError) Error

func (e CryptError) Error() string

type CryptParameter

type CryptParameter interface {
	CMode() (string, Params, unsafe.Pointer, func())
}

type Device

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

Device is a handle on the crypto device. It corresponds to a `struct crypt_device*` in libcryptsetup

func NewDevice

func NewDevice(name string) (d *Device, err error)

NewDevice creates a new device based on the name of a file/block device to encrypt. It is the caller's responsibility to ensure that `Close` gets called on the device (or a copy of the device).

func (*Device) Activate

func (d *Device) Activate(name string, pass []byte) error

Activate sets up the encrypted volume as name under the directory specified by Dir().

func (*Device) AddKey

func (d *Device) AddKey(pass []byte, newpass []byte) error

AddKey adds a new password, newpass, to the block device, first unlocking it with pass.

func (*Device) Benchmark

func (d *Device) Benchmark(iv_size uint64, buffer_size uint64, pp Params) (enc float64, dec float64, err error)

Benchmark runs the library's internal benchmarking code on the underlying block device with the given parameters. It returns the number of MiB encrypted and decrypted per-second.

Example

d, err := NewDevice("/dev/sda")
if err != nil {
	panic(err)
}
defer d.Close()

enc, dec, err := d.Benchmark(128, 4096, Params{})
if err != nil {
	panic(err)
}
fmt.Printf("Encryption time: %f MiB/s\n", enc)
fmt.Printf("Decryption time: %f MiB/s\n", dec)

func (*Device) BenchmarkKdf

func (d *Device) BenchmarkKdf(hash string, pass, salt []byte) (iter uint64, err error)

BenchmarkKdf runs the the library's internal benchmark code for the Key Deriviation Function. It returns the number hashes performed in one second on the password with the given salt.

The number of hashes indicates the difficulty of bruteforcing the password; higher is more difficult to crack.

Example

d, err := NewDevice("/dev/sda")
if err != nil {
	panic(err)
}
defer d.Close()

iter, err := d.BenchmarkKdf("", []byte("my password"), []byte("secure salt"))
if err != nil {
	panic(err)
}
fmt.Printf("Kdf iterations per second: %d\n", iter)

func (*Device) Close

func (d *Device) Close()

Close closes a Device and frees the associated context and resources.

func (*Device) Deactivate

func (d *Device) Deactivate(name string) error

Deactivate removes the active device-mapper mapping from the kernel. This also removes sensitive data from memory.

func (*Device) DelKey

func (d *Device) DelKey(pass []byte) (err error)

DelKey removes the password specified by pass from the device, effectively making it impossible to decrypt the device with that password any more. Note that this is not guaranteed to work on SSDs and flash memory because the wear leveling technology used in those devices makes it impossible to ensure complete erasure of the data in a specific sector.

func (*Device) Format

func (d *Device) Format(key []byte, p CryptParameter) error

Format formats the block device

func (*Device) Load

func (d *Device) Load(p CryptParameter) error

Load loads the device header into the device context.

func (*Device) Name

func (d *Device) Name() string

Name returns the name of the underlying device. This is the same as the argument passed to NewDevice.

func (*Device) Params

func (d *Device) Params() (pp Params)

Params returns a Params object with the cryptographic parameters used by the device.

func (*Device) SetDataDevice

func (d *Device) SetDataDevice(name string) error

SetDataDevice specifies a device to use in detached header mode.

func (*Device) SetIterationTime

func (d *Device) SetIterationTime(t time.Duration)

SetIterationTime sets how log it should take to construct a key from a password. The default is about 1 second.

func (*Device) SetUuid

func (d *Device) SetUuid(uuid string) error

SetUuid sets the uuid of the device

func (*Device) Uuid

func (d *Device) Uuid() string

Uuid returns the UUID of the device.

type LuksParams

type LuksParams struct {
	Params
	Hash          string  // hash used in LUKS header
	DataAlignment uint64  // data alignment (in sectors)
	DataDevice    *string // detached encrypted data device or ""
}

LuksParams is the set of parameters used for defining operations on LUKS based encrypted devices.

func (LuksParams) CMode

func (p LuksParams) CMode() (t string, pp Params, out unsafe.Pointer, free func())

type Params

type Params struct {
	Cipher        string
	Mode          string
	VolumeKeySize uint64
}

Params consists of common parameters used by the various cryptographic backends.

type PlainParams

type PlainParams struct {
	Params
	Hash   string // password hash function
	Offset uint64 // offset (in sectors)
	Skip   uint64 // IV offset / initialization sector
	Size   uint64 // size of mapped device or 0
}

PlainParams is the set of parameters used for performing plain headerless encryption of a block device. Using this, the device is indistinguishable from truly random data.

While this can be useful for deniable encryption, it is not perfect as an adversary who may suspect such deniable encryption is in use whenever they see "truly random data" can use various interrogation techniques to force the password out of a user. Cases when it may be useful include: when ordered by a judge to provide a password for a drive, one can claim that there is no password and the drive is full of random data, in this case it is impossible to "prove" (as in beyond any reasonable doubt) that a user is in fact keeping a password from authorities.

I am not a lawyer and the laws in your jurisdiction may be different. Do not take any of this as professional legal advice.

func (PlainParams) CMode

func (p PlainParams) CMode() (t string, pp Params, out unsafe.Pointer, free func())