token_mgmt

Name

token_mgmt - create and manage security tokens for disk encryption.

Synopsis

token_mgmt COMMAND [PARAMS...]

Description

token_mgmt can be used to create and manage physical security tokens holding keys for disk encryption using cryptsetup. Any block device can be used as a token (external disk, memory card, USB flash drive...).

The keys are stored encrypted and a decryption key is kept on the computer. Decryption of disks encrypted using a key generated by token_mgmt can only be done with a valid token and the associated decryption key.

token_mgmt runs as a boot service. It checks all known block devices for a valid token and decrypt the disks if a token is found. Additionnal configuration provided on the token (profile made up of one or more overlays) can also be applied.

Commands

create - Create token
disable - Disable a token
list - List tokens
load - Load a token
getkey - Read a disk key from a token
status - Print status
log - Print log

Create token

create [-n NAME] [-p PROFILE] [-P] [-w] [-f] DEVICE

Create a new token.

If no valid token exists, new disk keys are generated. Otherwise, a valid token needs to be loaded and the keys are extracted from the token.

-n - Name
-p - Add profile to the token.
-P - Create partition.
-w - Wipe the device before writing the token.
-f - Do not request confirmation (with -p and -w).

Disable token

disable [-f] TOKEN

Disable a token. This cannot be undone.

-f - Do not request confirmation.

List tokens

list [-a]

List active tokens.

-a - List all tokens.

Load a token

load [-l]

Load the token (decrypt disks and activate custom configuration).

-l - Load only (don't mount the overlays or decrypt the disks).

Read a disk key

getkey DISK

Print the key for the disk to the standard output. The key is retrieved from the currently loaded token.

Print status

status

Print the systemd status for the service.

Print log

log [-a]

Print the systemd log for the service (since boot).

-a - Print all logs

Configuration

/etc/token_mgmt/config

General configuration

DISKS - List of encrypted disks
MAILTO - User to receive notifications of unauthorized boots.
BACKUP - Remote directory for rsync backup of the keys in the format USER@HOST:PATH
PICTURE - Picture to be displayed in case of unauthorized access. The path is relative to the configuration directory.

/etc/token_mgmt/profiles/*

A profile is a custom configuration that is loaded on top of the system configuration when the token is loaded. A token contains a profile made of multiple overlays.

/etc/token_mgmt/overlays/*

Overlays are configuration units that can be included in profiles.

Getting started

Create the first token

token_mgmt create none
Load the token

token_mgmt load -l
Retrieve the disk keys to encrypt the disks

ENCRYPTION_COMMAND --key-file <( token_mgmt getkey UDISK )
Create additional tokens for safety.

Tokens

A token is a gzipped tar archive written at offset 512 of a block device. This is intented to put it after the MBR of a partitioned USB flash drive or memory stick. Writting a token on a partition will damage the filesystem.

The tar archive contains the following files:

ID - A UUID identifying the token.
key.enc - 256 bytes random key encrypted using a 4096 bits RSA key stored on the computer. Used to encrypt other *.enc files.
profile.enc - Additional configuration.
*.enc - 4096 bytes random keys for disk encryption (one for each device specified in the configuration).

Profiles

A token can include a profile (stored as an encrypted tar archive) which includes one or more overlays (configuration units) and a script executed after the token has been loaded (post-load.sh).

The overlays are tar archives inside the overlays/ directory of the profile or one of its subdirectories. When a token is loaded, all overlays in the profile are unpacked in a ramfs filesystem and mounted using overlayfs. The lower directory is specified by the path of the overlay. For example, overlays/etc/systemd/system/getty@tty1.service.d.tar will be mounted over /etc/systemd/system/getty@tty1.service.d.

/etc/token_mgmt/overlays/ and /etc/token_mgmt/profiles/ contain the templates for the overlays and profiles. To create a new overlay, simply create a new directory containing any file you wish (for example: /etc/token_mgmt/overlays/my-overlay/). The archive will be created on the fly when creating a new token. To include this overlay in a profile, create a dead symbolic link to the (not yet existing) archive (for example: /etc/token_mgmt/overlays/my-overlay.tar).

Warning

CAREFUL! IF YOU LOSE ALL ACTIVE TOKENS OR THEIR ASSOCIATED KEYS, THE DISK KEYS ARE LOST FOREVER!

MAKE SURE YOU KEEP SEVERAL VALID TOKENS IN A SAFE AND SECURE PLACE AND KEEP A BACKUP OF THE TOKEN DECRYPTION KEYS AS WELL (BY USING THE BUILT-IN BACKUP FUNCTIONALITY OR ANY OTHER BACKUP TOOL).

polletfa / token_mgmt