misc/keyslot_checker/README

   1 Purpose
   2 =======
   3
   4 chk_luks_keyslots is a tool that searches the keyslot area of a
   5 LUKS container for positions where entropy is low and hence
   6 there is a high probability of damage from overwrites of parts
   7 of the key-slot with data such as a RAID superblock or a partition
   8 table.
   9
  10
  11 Installation
  12 ============
  13
  14 1. Install the version of cryptsetup the tool came with.
  15 2. Compile with "make"
  16
  17 Manual compile can be done with
  18    gcc -lm -lcryptsetup chk_luks_keyslots.c -o chk_luks_keyslots
  19
  20 Usage
  21 =====
  22
  23 Call chk_luks_keyslots without arguments for an option summary.
  24
  25
  26 Example of a good keyslot area with keys 0 and 2 in use:
  27 --------------------------------------------------------
  28
  29 root> ./chk_luks_keyslots /dev/loop0
  30
  31 parameters (commandline and LUKS header):
  32   sector size: 512
  33   threshold:   0.900000
  34
  35 - processing keyslot 0:  start: 0x001000   end: 0x020400
  36 - processing keyslot 1:  keyslot not in use
  37 - processing keyslot 2:  start: 0x041000   end: 0x060400
  38 - processing keyslot 3:  keyslot not in use
  39 - processing keyslot 4:  keyslot not in use
  40 - processing keyslot 5:  keyslot not in use
  41 - processing keyslot 6:  keyslot not in use
  42 - processing keyslot 7:  keyslot not in use
  43
  44
  45 Same example of a fault in slot 2 at offset 0x50000:
  46 ----------------------------------------------------
  47
  48 root>./chk_luks_keyslots /dev/loop2
  49
  50 parameters (commandline and LUKS header):
  51   sector size: 512
  52   threshold:   0.900000
  53
  54 - processing keyslot 0:  start: 0x001000   end: 0x020400
  55 - processing keyslot 1:  keyslot not in use
  56 - processing keyslot 2:  start: 0x041000   end: 0x060400
  57   low entropy at: 0x050000    entropy: 0.549165
  58 - processing keyslot 3:  keyslot not in use
  59 - processing keyslot 4:  keyslot not in use
  60 - processing keyslot 5:  keyslot not in use
  61 - processing keyslot 6:  keyslot not in use
  62 - processing keyslot 7:  keyslot not in use
  63
  64
  65 Same as last, but verbose:
  66 --------------------------
  67 root>./chk_luks_keyslots  -v /dev/loop2
  68
  69 parameters (commandline and LUKS header):
  70   sector size: 512
  71   threshold:   0.900000
  72
  73 - processing keyslot 0:  start: 0x001000   end: 0x020400
  74 - processing keyslot 1:  keyslot not in use
  75 - processing keyslot 2:  start: 0x041000   end: 0x060400
  76   low entropy at: 0x050000    entropy: 0.549165
  77   Binary dump:
  78   0x050000  54 68 69 73 20 69 73 20  61 20 74 65 73 74 2D 73  This is a test-s
  79   0x050010  65 63 74 6F 72 20 66 6F  72 20 63 68 6B 5F 6C 75  ector for chk_lu
  80   0x050020  6B 73 5F 6B 65 79 73 6C  6F 74 73 20 74 68 65 20  ks_keyslots the
  81   0x050030  71 75 69 63 6B 20 62 72  6F 77 6E 20 66 6F 78 20  quick brown fox
  82   0x050040  6A 75 6D 70 73 20 6F 76  65 72 20 74 68 65 20 6C  jumps over the l
  83   0x050050  61 7A 79 20 64 6F 67 20  74 68 65 20 71 75 69 63  azy dog the quic
  84   0x050060  6B 20 62 72 6F 77 6E 20  66 6F 78 20 6A 75 6D 70  k brown fox jump
  85   0x050070  73 20 6F 76 65 72 20 74  68 65 20 6C 61 7A 79 20  s over the lazy
  86   0x050080  64 6F 67 20 74 68 65 20  71 75 69 63 6B 20 62 72  dog the quick br
  87   0x050090  6F 77 6E 20 66 6F 78 20  6A 75 6D 70 73 20 6F 76  own fox jumps ov
  88   0x0500a0  65 72 20 74 68 65 20 6C  61 7A 79 20 64 6F 67 20  er the lazy dog
  89   0x0500b0  74 68 65 20 71 75 69 63  6B 20 62 72 6F 77 6E 20  the quick brown
  90   0x0500c0  66 6F 78 20 6A 75 6D 70  73 20 6F 76 65 72 20 74  fox jumps over t
  91   0x0500d0  68 65 20 6C 61 7A 79 20  64 6F 67 20 74 68 65 20  he lazy dog the
  92   0x0500e0  71 75 69 63 6B 20 62 72  6F 77 6E 20 66 6F 78 20  quick brown fox
  93   0x0500f0  6A 75 6D 70 73 20 6F 76  65 72 20 74 68 65 20 6C  jumps over the l
  94   0x050100  61 7A 79 20 64 6F 67 20  74 68 65 20 71 75 69 63  azy dog the quic
  95   0x050110  6B 20 62 72 6F 77 6E 20  66 6F 78 20 6A 75 6D 70  k brown fox jump
  96   0x050120  73 20 6F 76 65 72 20 74  68 65 20 6C 61 7A 79 20  s over the lazy
  97   0x050130  64 6F 67 20 74 68 65 20  71 75 69 63 6B 20 62 72  dog the quick br
  98   0x050140  6F 77 6E 20 66 6F 78 20  6A 75 6D 70 73 20 6F 76  own fox jumps ov
  99   0x050150  65 72 20 74 68 65 20 6C  61 7A 79 20 64 6F 67 20  er the lazy dog
 100   0x050160  74 68 65 20 71 75 69 63  6B 20 62 72 6F 77 6E 20  the quick brown
 101   0x050170  66 6F 78 20 6A 75 6D 70  73 20 6F 76 65 72 20 74  fox jumps over t
 102   0x050180  68 65 20 6C 61 7A 79 20  64 6F 67 20 74 68 65 20  he lazy dog the
 103   0x050190  71 75 69 63 6B 20 62 72  6F 77 6E 20 66 6F 78 20  quick brown fox
 104   0x0501a0  6A 75 6D 70 73 20 6F 76  65 72 20 74 68 65 20 6C  jumps over the l
 105   0x0501b0  61 7A 79 20 64 6F 67 20  74 68 65 20 71 75 69 63  azy dog the quic
 106   0x0501c0  6B 20 62 72 6F 77 6E 20  66 6F 78 20 6A 75 6D 70  k brown fox jump
 107   0x0501d0  73 20 6F 76 65 72 20 74  68 65 20 6C 61 7A 79 20  s over the lazy
 108   0x0501e0  64 6F 67 20 74 68 65 20  71 75 69 63 6B 20 62 72  dog the quick br
 109   0x0501f0  6F 77 6E 20 66 6F 78 20  6A 75 6D 70 73 20 6F 76  own fox jumps ov
 110
 111 - processing keyslot 3:  keyslot not in use
 112 - processing keyslot 4:  keyslot not in use
 113 - processing keyslot 5:  keyslot not in use
 114 - processing keyslot 6:  keyslot not in use
 115 - processing keyslot 7:  keyslot not in use
 116
 117 ----
 118 Copyright (C) 2012, Arno Wagner <arno@wagner.name>
 119 This file is free documentation; the author gives
 120 unlimited permission to copy, distribute and modify it.