2 * @mainpage Cryptsetup API
4 * The documentation covers public parts of cryptsetup API. In the following sections you'll find
5 * the examples that describe some features of cryptsetup API.
8 * <LI>@ref cexamples "Cryptsetup API examples"</LI>
10 * <LI>@ref cluks "crypt_luks_usage" - cryptsetup LUKS device type usage examples</LI>
12 * <LI>@ref cinit "crypt_init()"</LI>
13 * <LI>@ref cformat "crypt_format()" - header and payload on mutual device</LI>
14 * <LI>@ref ckeys "Keyslot operations" </LI>
16 * <LI>@ref ckeyslot_vol "crypt_keyslot_add_by_volume_key()"</LI>
17 * <LI>@ref ckeyslot_pass "crypt_keyslot_add_by_passphrase()"</LI>
19 * <LI>@ref cload "crypt_load()"
20 * <LI>@ref cactivate "crypt_activate_by_passphrase()"</LI>
21 * <LI>@ref cactive_pars "crypt_get_active_device()"</LI>
22 * <LI>@ref cinit_by_name "crypt_init_by_name()"</LI>
23 * <LI>@ref cdeactivate "crypt_deactivate()"</LI>
24 * <LI>@ref cluks_ex "crypt_luks_usage.c"</LI>
26 * <LI>@ref clog "crypt_log_usage" - cryptsetup logging API examples</LI>
30 * @section cexamples Cryptsetup API examples
31 * @section cluks crypt_luks_usage - cryptsetup LUKS device type usage
32 * @subsection cinit crypt_init()
34 * Every time you need to do something with cryptsetup or dmcrypt device
35 * you need a valid context. The first step to start your work is
36 * @ref crypt_init call. You can call it either with path
37 * to the block device or path to the regular file. If you don't supply the path,
38 * empty context is initialized.
40 * @subsection cformat crypt_format() - header and payload on mutual device
42 * This section covers basic use cases for formatting LUKS devices. Format operation
43 * sets device type in context and in case of LUKS header is written at the beginning
44 * of block device. In the example bellow we use the scenario where LUKS header and data
45 * are both stored on the same device. There's also a possibility to store header and
48 * <B>Bear in mind</B> that @ref crypt_format() is destructive operation and it
49 * overwrites part of the backing block device.
51 * @subsection ckeys Keyslot operations examples
53 * After successful @ref crypt_format of LUKS device, volume key is not stored
54 * in a persistent way on the device. Keyslot area is an array beyond LUKS header, where
55 * volume key is stored in the encrypted form using user input passphrase. For more info about
56 * LUKS keyslots and how it's actually protected, please look at
57 * <A HREF="http://code.google.com/p/cryptsetup/wiki/Specification">LUKS specification</A>.
58 * There are two basic methods to create a new keyslot:
60 * @subsection ckeyslot_vol crypt_keyslot_add_by_volume_key()
62 * Creates a new keyslot directly by encrypting volume_key stored in the device
63 * context. Passphrase should be supplied or user is prompted if passphrase param is
66 * @subsection ckeyslot_pass crypt_keyslot_add_by_passphrase()
68 * Creates a new keyslot for the volume key by opening existing active keyslot,
69 * extracting volume key from it and storing it into a new keyslot
70 * protected by a new passphrase
72 * @subsection cload crypt_load()
74 * Function loads header from backing block device into device context.
76 * @subsection cactivate crypt_activate_by_passphrase()
78 * Activates crypt device by user supplied password for keyslot containing the volume_key.
79 * If <I>keyslot</I> parameter is set to <I>CRYPT_ANY_SLOT</I> then all active keyslots
80 * are tried one by one until the volume key is found.
82 * @subsection cactive_pars crypt_get_active_device()
84 * This call returns structure containing runtime attributes of active device.
86 * @subsection cinit_by_name crypt_init_by_name()
88 * In case you need to do operations with active device (device which already
89 * has its corresponding mapping) and you miss valid device context stored in
90 * *crypt_device reference, you should use this call. Function tries to
91 * get path to backing device from DM, initializes context for it and loads LUKS
94 * @subsection cdeactivate crypt_deactivate()
96 * Deactivates crypt device (removes DM mapping and safely erases volume key from kernel).
98 * @subsection cluks_ex crypt_luks_usage.c - Complex example
100 * To compile and run use following commands in examples directory:
104 * ./crypt_luks_usage _path_to_[block_device]_file
107 * Note that you need to have the cryptsetup library compiled. @include crypt_luks_usage.c
109 * @section clog crypt_log_usage - cryptsetup logging API example
111 * Example describes basic use case for cryptsetup logging. To compile and run
112 * use following commands in examples directory:
119 * Note that you need to have the cryptsetup library compiled. @include crypt_log_usage.c
121 * @example crypt_luks_usage.c
122 * @example crypt_log_usage.c