cryptsetup  2.0.6
About: cryptsetup is a utility used to conveniently setup disk encryption based on the dm-crypt kernel module. These include plain dm-crypt volumes, LUKS volumes, loop-AES and TrueCrypt compatible format.
  Fossies Dox: cryptsetup-2.0.6.tar.xz  ("inofficial" and yet experimental doxygen-generated source code documentation)  

Cryptsetup API

The documentation covers public parts of cryptsetup API. In the following sections you'll find the examples that describe some features of cryptsetup API. For more info about libcryptsetup API versions see API Tracker.

  1. Cryptsetup API examples
    1. crypt_luks_usage - cryptsetup LUKS device type usage examples
    2. crypt_log_usage - cryptsetup logging API examples

Cryptsetup API examples

crypt_luks_usage - cryptsetup LUKS device type usage

crypt_init()

Every time you need to do something with cryptsetup or dmcrypt device you need a valid context. The first step to start your work is crypt_init call. You can call it either with path to the block device or path to the regular file. If you don't supply the path, empty context is initialized.

crypt_format() - header and payload on mutual device

This section covers basic use cases for formatting LUKS devices. Format operation sets device type in context and in case of LUKS header is written at the beginning of block device. In the example below we use the scenario where LUKS header and data are both stored on the same device. There's also a possibility to store header and data separately.

Bear in mind that crypt_format() is destructive operation and it overwrites part of the backing block device.

Keyslot operations examples

After successful crypt_format of LUKS device, volume key is not stored in a persistent way on the device. Keyslot area is an array beyond LUKS header, where volume key is stored in the encrypted form using user input passphrase. For more info about LUKS keyslots and how it's actually protected, please look at LUKS specification. There are two basic methods to create a new keyslot:

crypt_keyslot_add_by_volume_key()

Creates a new keyslot directly by encrypting volume_key stored in the device context. Passphrase should be supplied or user is prompted if passphrase param is NULL.

crypt_keyslot_add_by_passphrase()

Creates a new keyslot for the volume key by opening existing active keyslot, extracting volume key from it and storing it into a new keyslot protected by a new passphrase

crypt_load()

Function loads header from backing block device into device context.

crypt_activate_by_passphrase()

Activates crypt device by user supplied password for keyslot containing the volume_key. If keyslot parameter is set to CRYPT_ANY_SLOT then all active keyslots are tried one by one until the volume key is found.

crypt_get_active_device()

This call returns structure containing runtime attributes of active device.

crypt_init_by_name()

In case you need to do operations with active device (device which already has its corresponding mapping) and you miss valid device context stored in *crypt_device reference, you should use this call. Function tries to get path to backing device from DM, initializes context for it and loads LUKS header.

crypt_deactivate()

Deactivates crypt device (removes DM mapping and safely erases volume key from kernel).

crypt_luks_usage.c - Complex example

To compile and run use following commands in examples directory:

make
./crypt_luks_usage _path_to_[block_device]_file

Note that you need to have the cryptsetup library compiled.

crypt_log_usage - cryptsetup logging API example

Example describes basic use case for cryptsetup logging. To compile and run use following commands in examples directory:

make
./crypt_log_usage

Note that you need to have the cryptsetup library compiled.