docs/doxygen_index

   1 /**
   2  * @mainpage Cryptsetup API
   3  *
   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.
   6  * For more info about libcryptsetup API versions see
   7  * <a href="http://upstream-tracker.org/versions/libcryptsetup.html">Upstream Tracker</a>.
   8  *
   9  * <OL type="A">
  10  *      <LI>@ref cexamples "Cryptsetup API examples"</LI>
  11  *      <OL type="1">
  12  *              <LI>@ref cluks "crypt_luks_usage" - cryptsetup LUKS device type usage examples</LI>
  13  *                      <UL>
  14  *                              <LI>@ref cinit "crypt_init()"</LI>
  15  *                              <LI>@ref cformat "crypt_format()" - header and payload on mutual device</LI>
  16  *                              <LI>@ref ckeys "Keyslot operations" </LI>
  17  *                              <UL>
  18  *                                      <LI>@ref ckeyslot_vol "crypt_keyslot_add_by_volume_key()"</LI>
  19  *                                      <LI>@ref ckeyslot_pass "crypt_keyslot_add_by_passphrase()"</LI>
  20  *                              </UL>
  21  *                              <LI>@ref cload "crypt_load()"
  22  *                              <LI>@ref cactivate "crypt_activate_by_passphrase()"</LI>
  23  *                              <LI>@ref cactive_pars "crypt_get_active_device()"</LI>
  24  *                              <LI>@ref cinit_by_name "crypt_init_by_name()"</LI>
  25  *                              <LI>@ref cdeactivate "crypt_deactivate()"</LI>
  26  *                              <LI>@ref cluks_ex "crypt_luks_usage.c"</LI>
  27  *                      </UL>
  28  *              <LI>@ref clog "crypt_log_usage" - cryptsetup logging API examples</LI>
  29  *      </OL>
  30  * </OL>
  31  *
  32  * @section cexamples Cryptsetup API examples
  33  *      @section cluks crypt_luks_usage - cryptsetup LUKS device type usage
  34  *              @subsection cinit crypt_init()
  35  *
  36  *                      Every time you need to do something with cryptsetup or dmcrypt device
  37  *                      you need a valid context. The first step to start your work is
  38  *                      @ref crypt_init call. You can call it either with path
  39  *                      to the block device or path to the regular file. If you don't supply the path,
  40  *                      empty context is initialized.
  41  *
  42  *              @subsection cformat crypt_format() - header and payload on mutual device
  43  *
  44  *                      This section covers basic use cases for formatting LUKS devices. Format operation
  45  *                      sets device type in context and in case of LUKS header is written at the beginning
  46  *                      of block device. In the example bellow we use the scenario where LUKS header and data
  47  *                      are both stored on the same device. There's also a possibility to store header and
  48  *                      data separately.
  49  *
  50  *                      <B>Bear in mind</B> that @ref crypt_format() is destructive operation and it
  51  *                      overwrites part of the backing block device.
  52  *
  53  *              @subsection ckeys Keyslot operations examples
  54  *
  55  *                      After successful @ref crypt_format of LUKS device, volume key is not stored
  56  *                      in a persistent way on the device. Keyslot area is an array beyond LUKS header, where
  57  *                      volume key is stored in the encrypted form using user input passphrase. For more info about
  58  *                      LUKS keyslots and how it's actually protected, please look at
  59  *                      <A HREF="https://gitlab.com/cryptsetup/cryptsetup/wikis/Specification">LUKS specification</A>.
  60  *                      There are two basic methods to create a new keyslot:
  61  *
  62  *                      @subsection ckeyslot_vol crypt_keyslot_add_by_volume_key()
  63  *
  64  *                              Creates a new keyslot directly by encrypting volume_key stored in the device
  65  *                              context. Passphrase should be supplied or user is prompted if passphrase param is
  66  *                              NULL.
  67  *
  68  *                      @subsection ckeyslot_pass crypt_keyslot_add_by_passphrase()
  69  *
  70  *                              Creates a new keyslot for the volume key by opening existing active keyslot,
  71  *                              extracting volume key from it and storing it into a new keyslot
  72  *                              protected by a new passphrase
  73  *
  74  *              @subsection cload crypt_load()
  75  *
  76  *                      Function loads header from backing block device into device context.
  77  *
  78  *              @subsection cactivate crypt_activate_by_passphrase()
  79  *
  80  *                      Activates crypt device by user supplied password for keyslot containing the volume_key.
  81  *                      If <I>keyslot</I> parameter is set to <I>CRYPT_ANY_SLOT</I> then all active keyslots
  82  *                      are tried one by one until the volume key is found.
  83  *
  84  *              @subsection cactive_pars crypt_get_active_device()
  85  *
  86  *                      This call returns structure containing runtime attributes of active device.
  87  *
  88  *              @subsection cinit_by_name crypt_init_by_name()
  89  *
  90  *                      In case you need to do operations with active device (device which already
  91  *                      has its corresponding mapping) and you miss valid device context stored in
  92  *                      *crypt_device reference, you should use this call. Function tries to
  93  *                      get path to backing device from DM, initializes context for it and loads LUKS
  94  *                      header.
  95  *
  96  *                      @subsection cdeactivate crypt_deactivate()
  97  *
  98  *                      Deactivates crypt device (removes DM mapping and safely erases volume key from kernel).
  99  *
 100  *              @subsection cluks_ex crypt_luks_usage.c - Complex example
 101  *
 102  *                      To compile and run use following commands in examples directory:
 103  *
 104  * @code
 105  * make
 106  * ./crypt_luks_usage _path_to_[block_device]_file
 107  * @endcode
 108  *
 109  *                      Note that you need to have the cryptsetup library compiled. @include crypt_luks_usage.c
 110  *
 111  *      @section clog crypt_log_usage - cryptsetup logging API example
 112  *
 113  *              Example describes basic use case for cryptsetup logging. To compile and run
 114  *              use following commands in examples directory:
 115  *
 116  * @code
 117  * make
 118  * ./crypt_log_usage
 119  * @endcode
 120  *
 121  *              Note that you need to have the cryptsetup library compiled. @include crypt_log_usage.c
 122  *
 123  *              @example crypt_luks_usage.c
 124  *              @example crypt_log_usage.c
 125  */