debian/grml-crypt.8

   1 .\"                                      Hey, EMACS: -*- nroff -*-
   2 .\" First parameter, NAME, should be all caps
   3 .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
   4 .\" other parameters are allowed: see man(7), man(1)
   5 .TH GRML-CRYPT 8 "AUG 9, 2005"
   6 .\" Please adjust this date whenever revising the manpage.
   7 .\"
   8 .\" Some roff macros, for reference:
   9 .\" .nh        disable hyphenation
  10 .\" .hy        enable hyphenation
  11 .\" .ad l      left justify
  12 .\" .ad b      justify to both left and right margins
  13 .\" .nf        disable filling
  14 .\" .fi        enable filling
  15 .\" .br        insert line break
  16 .\" .sp <n>    insert n+1 empty lines
  17 .\" for manpage-specific macros, see man(7)
  18 .SH NAME
  19 grml-crypt \- Wrapper arround cryptsetup/losetup/mkfs/mount
  20 .SH SYNOPSIS
  21 .B grml-crypt
  22 .RI [OPTIONS] " action " <device/file> " [mountpoint]
  23 .br
  24 .SH DESCRIPTION
  25 This manual page documents briefly the
  26 .B grml-crypt program
  27 .PP
  28 .\" TeX users may be more comfortable with the \fB<whatever>\fP and
  29 .\" \fI<whatever>\fP escape sequences to invode bold face and italics,
  30 .\" respectively.
  31 \fBgrml-crypt\fP is a program that
  32 provides an easy wrapper arround cryptsetup, mkfs, losetup and mount.
  33 You could create a loopback mountet crypted filesystem with only one command, but grml-crypt works for normal devices also.
  34 .SH ACTIONS
  35 .TP
  36 .B format <device/file> [mountpoint]
  37 This command "formats" a device/file.
  38 If the second parameter is not a blockdevice grml-crupt assumes that it should operate in file modus. If the file does not allready exist it will be created with the given size.
  39 The first 2MB of a device (luks header) are initialised with /dev/urandom, the other space is initialised with the given initialisation. If grml-crypt is in file modus the first 2MB of the loop file are also initialised with /dev/urandom except where the file allready exist (with -f vor overwriting).
  40 Commands: [losetup], dd, cryptsetup luksFormat, cryptsetup luksOpen, [dd], mkfs, [mount]
  41 .TP
  42 .B start <device/file> <mountpoint>
  43 This command starts a encrypted device/file and mounts it to the given mountpoint.
  44 Commands: [losetup], cryptsetup luksOpen, mount
  45 .TP
  46 .B stop <mountpoint>
  47 This command stops a encrypted filesystem mountet at mountpoint.
  48 Even the loopdevice gets destroyed with this command.
  49 Commands: mount, dmsetup info, cryptsetup status, umount, cryptsetup luksClose, [losetup -d]
  50 .SH OPTIONS
  51 These program follow the long option style without dashes and
  52 short options starting with one dash (`-').
  53 A summary of options is included below.
  54 .TP
  55 .B \-h, help
  56 Show summary of options.
  57 .TP
  58 .B \-v
  59 Show what is going on (more v => more output).
  60 .TP
  61 .B \-s (in MB, default=10)
  62 Give the size of loopfilesystem grml-crypt should create.
  63 .TP
  64 .B \-t (default=vfat)
  65 Give the type of the filesystem grml-crypt should create.
  66 /sbin/mkfs.<your choosen filesystem> should exist.
  67 .TP
  68 .B \-r
  69 Read-only mode. The device mapping AND the mountpoint will be made read-only.
  70 In format mode only the mountpoint could be made read-only.
  71 .TP
  72 .B \-z
  73 Insecure initialisation mode
  74 .TP
  75 .B \-o
  76 Optimized initialisation mode
  77 .TP
  78 .B \-y
  79 Verifies the password by asking for it twice during creation.
  80 .TP
  81 .B \-f
  82 Force overwriting and/or disable confirmation dialog.
  83 If the second parameter to format is an existing file and force is given, then the file will be used for the encrypted loop filesystem. ATTENTION: the file should be bigger than 2MB for LUKS only + the constraints from the filesystems itself (eg. xfs needs a minimum of 4096 blocks).
  84 .TP
  85 .B \-m
  86 Additional arguments passed through to mount. Could be like '-o noatime'.
  87 .SH CRYPTSETUP FORMAT OPTIONS
  88 .TP
  89 .B \-S (in bits, default=128)
  90 Cipher size used for the encryption. Usually 128, 192 or 256 (but higher maybe also possible)
  91 .TP
  92 .B \-C (default=aes-cbc-essiv:sha256)
  93 Cipher mode, should be aes-plain for pre-2.6.10. Look at /proc/crypto for other ciphers.
  94 .TP
  95 .B \-I (in seconds, default=1)
  96 The number of seconds to spend with PBKDF2 password processing. This time is comsumed for every key operation (format, start).
  97 .TP
  98 .B \-A (default="")
  99 Additional arguments to cryptsetup luksFormat.
 100 .SH INITIALISATION MODES
 101 .TP
 102 .B Default/Secure mode (no -o or -z given)
 103 This mode is the default. It should be quite secure.
 104 The device/file gets initialised with /dev/urandom. Except with an allready existing file and -f, where NO initialisation will be done (all other modes behave as usual).
 105 .TP
 106 .B Optimized secure mode (-o)
 107 In this mode only the first 2MB of the device/file are initialised with /dev/urandom.
 108 The encryption will be initialised and then the whole encrypted device is filled with /dev/zero.
 109 .TP
 110 .B Insecure mode (-z)
 111 In this mode only the first 2MB of the device/file are initialised with /dev/urandom.
 112 .SH EXAMPLES
 113 .TP
 114 .B grml-crypt -t xfs -o format /dev/hda4 /mnt/tmp
 115 Formats /dev/hda4 with xfs and apply optimized initialisation rules and mount it to /mnt/tmp
 116 .TP
 117 .B grml-crypt -t ext2 -z format /home/user/test.img /mnt/tmp
 118 Creates /home/user/test.img with 10MB and apply only insecure initialisation rules. Create an ext2 filesystem on it and mount it to /mnt/tmp.
 119 .TP
 120 .B grml-crypt -f -S 256 -C aes-plain -I 2 -A "--verify-passphrase" -m '-o noatime' -vvv format img /mnt/tmp
 121 Reuses the image img with no initialisation. The encryption is established with aes-plain with 256 bit keysize and an iteration time of 2 seconds. Cryptsetup is advised to verify the password by asking for it twice. Mount it to /mnt/tmp with '-o noatime'. And print what is going on (-vvv).
 122 .SH ENCRYPT AN USBSTICK
 123 .TP
 124 .B grml-crypt -t ext2 -z format /dev/external1
 125 This command formats your usbstick which hopely is at /dev/external1 (please verify!!) with ext2 and nearly no initialisation.
 126 You could als give the format action a mountpoint. In this case your crypto-partition gets also mounted on this mountpoint.
 127 .TP
 128 .B grml-crypt start /dev/external1 /mnt/tmp
 129 This command asks you for the right passphrase for your crypto-partition and tries to mount it to /mnt/tmp.
 130 .TP
 131 .B grml-crypt stop /mnt/tmp
 132 This command removes your crypto-partition cleanly out of the system (umount, cryptsetup luksClose, [losetup -d]).
 133 .SH ENCRYPTED LOOPFILESYSTEM ON USBSTICK
 134 .TP
 135 .B mount /mnt/external1
 136 To mount your usb-stick on /mnt/external1 (please verify!!).
 137 .TP
 138 .B grml-crypt -o -t vfat -s 50 /mnt/external1/secure.img /mnt/tmp
 139 This command creates a 50MB big file, encrypted with the default options and with vfat (also known as fat32). The optimized initialisation mode will be used for this file (without -o this could take REALLY LONG).
 140 This command _also_ starts your cryptofile and mounts it on /mnt/tmp
 141 .TP
 142 .B grml-crypt stop /mnt/tmp
 143 This command removes your crypto-partition cleanly out of the system (umount, cryptsetup luksClose, [losetup -d]).
 144 .TP
 145 .B umount /mnt/external1
 146 Guess what ;)?
 147 .SH SEE ALSO
 148 .BR cryptsetup (8)
 149 .SH AUTHOR
 150 grml-crypt was written by Michael Gebetsroither <gebi@grml.org>.
 151 .PP
 152 This manual page was written by Michael Gebetsroither <gebi@grml.org>.