"Fossies" - the Fresh Open Source Software Archive

Member "cryptsetup-2.4.3/docs/doxygen_index.h" (24 Jul 2021, 5261 Bytes) of package /linux/misc/cryptsetup-2.4.3.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "doxygen_index.h" see the Fossies "Dox" file reference documentation.

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