sbin/gbde/gbde.8

   1 .\"
   2 .\" Copyright (c) 2002 Poul-Henning Kamp
   3 .\" Copyright (c) 2002 Networks Associates Technology, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This software was developed for the FreeBSD Project by Poul-Henning Kamp
   7 .\" and NAI Labs, the Security Research Division of Network Associates, Inc.
   8 .\" under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the
   9 .\" DARPA CHATS research program.
  10 .\"
  11 .\" Redistribution and use in source and binary forms, with or without
  12 .\" modification, are permitted provided that the following conditions
  13 .\" are met:
  14 .\" 1. Redistributions of source code must retain the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer.
  16 .\" 2. Redistributions in binary form must reproduce the above copyright
  17 .\"    notice, this list of conditions and the following disclaimer in the
  18 .\"    documentation and/or other materials provided with the distribution.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\" $FreeBSD$
  33 .\"
  34 .Dd October 1, 2013
  35 .Dt GBDE 8
  36 .Os
  37 .Sh NAME
  38 .Nm gbde
  39 .Nd operation and management utility for Geom Based Disk Encryption
  40 .Sh SYNOPSIS
  41 .Nm
  42 .Cm attach
  43 .Ar destination
  44 .Op Fl k Ar keyfile
  45 .Op Fl l Ar lockfile
  46 .Op Fl p Ar pass-phrase
  47 .Nm
  48 .Cm detach
  49 .Ar destination
  50 .Nm
  51 .Cm init
  52 .Ar destination
  53 .Op Fl i
  54 .Op Fl f Ar filename
  55 .Op Fl K Ar new-keyfile
  56 .Op Fl L Ar new-lockfile
  57 .Op Fl P Ar new-pass-phrase
  58 .Nm
  59 .Cm setkey
  60 .Ar destination
  61 .Op Fl n Ar key
  62 .Op Fl k Ar keyfile
  63 .Op Fl l Ar lockfile
  64 .Op Fl p Ar pass-phrase
  65 .Op Fl K Ar new-keyfile
  66 .Op Fl L Ar new-lockfile
  67 .Op Fl P Ar new-pass-phrase
  68 .Nm
  69 .Cm nuke
  70 .Ar destination
  71 .Op Fl n Ar key
  72 .Op Fl k Ar keyfile
  73 .Op Fl l Ar lockfile
  74 .Op Fl p Ar pass-phrase
  75 .Nm
  76 .Cm destroy
  77 .Ar destination
  78 .Op Fl k Ar keyfile
  79 .Op Fl l Ar lockfile
  80 .Op Fl p Ar pass-phrase
  81 .Sh DESCRIPTION
  82 .Bf -symbolic
  83 NOTICE:
  84 Please be aware that this code has not yet received much review
  85 and analysis by qualified cryptographers and therefore should be considered
  86 a slightly suspect experimental facility.
  87 .Pp
  88 We cannot at this point guarantee that the on-disk format will not change
  89 in response to reviews or bug-fixes, so potential users are advised to
  90 be prepared that
  91 .Xr dump 8 Ns / Ns
  92 .Xr restore 8
  93 based migrations may be called for in the future.
  94 .Ef
  95 .Pp
  96 The
  97 .Nm
  98 utility is the only official operation and management interface for the
  99 .Xr gbde 4
 100 .Tn GEOM
 101 based disk encryption kernel facility.
 102 The interaction between the
 103 .Nm
 104 utility and the kernel part is not a published interface.
 105 .Pp
 106 The operational aspect consists of two subcommands:
 107 one to open and attach
 108 a device to the in-kernel cryptographic
 109 .Nm
 110 module
 111 .Pq Cm attach ,
 112 and one to close and detach a device
 113 .Pq Cm detach .
 114 .Pp
 115 The management part allows initialization of the master key and lock sectors
 116 on a device
 117 .Pq Cm init ,
 118 initialization and replacement of pass-phrases
 119 .Pq Cm setkey ,
 120 and key invalidation
 121 .Pq Cm nuke
 122 and blackening
 123 .Pq Cm destroy
 124 functions.
 125 .Pp
 126 The
 127 .Fl l Ar lockfile
 128 argument is used to supply the lock selector data.
 129 If no
 130 .Fl l
 131 option is specified, the first sector is used for this purpose.
 132 .Pp
 133 The
 134 .Fl L Ar new-lockfile
 135 argument
 136 specifies the lock selector file for the key
 137 initialized with the
 138 .Cm init
 139 subcommand
 140 or modified with the
 141 .Cm setkey
 142 subcommand.
 143 .Pp
 144 The
 145 .Fl n Ar key
 146 argument can be used to specify to which of the four keys
 147 the operation applies.
 148 A value of 1 to 4 selects the specified key, a value of 0 (the default)
 149 means
 150 .Dq "this key"
 151 (i.e., the key used to gain access to the device)
 152 and a value of \-1 means
 153 .Dq "all keys" .
 154 .Pp
 155 The
 156 .Fl f Ar filename
 157 specifies an optional parameter file for use under initialization.
 158 .Pp
 159 Alternatively, the
 160 .Fl i
 161 option toggles an interactive mode where a template file with descriptions
 162 of the parameters can be interactively edited.
 163 .Pp
 164 The
 165 .Fl p Ar pass-phrase
 166 argument
 167 specifies the pass-phrase used for opening the device.
 168 If not specified, the controlling terminal will be used to prompt the user
 169 for the pass-phrase.
 170 Be aware that using this option may expose the pass-phrase to other
 171 users who happen to run
 172 .Xr ps 1
 173 or similar while the command is running.
 174 .Pp
 175 The
 176 .Fl P Ar new-pass-phrase
 177 argument
 178 can be used to specify the new pass-phrase to the
 179 .Cm init
 180 and
 181 .Cm setkey
 182 subcommands.
 183 If not specified, the user is prompted for the new pass-phrase on the
 184 controlling terminal.
 185 Be aware that using this option may expose the pass-phrase to other
 186 users who happen to run
 187 .Xr ps 1
 188 or similar while the command is running.
 189 .Pp
 190 The
 191 .Fl k Ar keyfile
 192 argument specifies a key file to be used in combination with the
 193 pass-phrase (whether the pass-phrase is specified on the command line
 194 or entered from the terminal) for opening the device.
 195 The device will only be opened if the contents of the key file and the
 196 pass-phrase are both correct.
 197 .Pp
 198 The
 199 .Fl K Ar new-keyfile
 200 argument can be used to specify a new key file to the
 201 .Cm init
 202 and
 203 .Cm setkey
 204 subcommands.
 205 If not specified, no key file will be used (even if one was previously
 206 used).
 207 .Sh EXAMPLES
 208 To initialize a device, using default parameters:
 209 .Pp
 210 .Dl "gbde init /dev/ada0s1f -L /etc/ada0s1f.lock"
 211 .Pp
 212 To attach an encrypted device:
 213 .Pp
 214 .Dl "gbde attach ada0s1f -l /etc/ada0s1f.lock"
 215 .Pp
 216 The encrypted device has the suffix
 217 .Pa .bde
 218 so a typical
 219 command to create and mount a file system would be:
 220 .Pp
 221 .Dl "newfs /dev/ada0s1f.bde"
 222 .Dl "mount /dev/ada0s1f.bde /secret"
 223 .Pp
 224 To detach an encrypted device:
 225 .Pp
 226 .Dl "gbde detach ada0s1f"
 227 .Pp
 228 Please notice that detaching an encrypted device corresponds to
 229 physically removing it, do not forget to unmount the file system first.
 230 .Pp
 231 To initialize the second key using a detached lockfile and a trivial
 232 pass-phrase:
 233 .Pp
 234 .Dl "gbde setkey ada0s1f -n 2 -P foo -L key2.lockfile"
 235 .Pp
 236 To destroy all copies of the masterkey:
 237 .Pp
 238 .Dl "gbde destroy ada0s1f -n -1"
 239 .Sh SEE ALSO
 240 .Xr gbde 4 ,
 241 .Xr geom 4
 242 .Sh HISTORY
 243 This software was developed for the
 244 .Fx
 245 Project by
 246 .An "Poul-Henning Kamp"
 247 and NAI Labs, the Security Research Division of Network Associates, Inc.\&
 248 under DARPA/SPAWAR contract N66001-01-C-8035
 249 .Pq Dq CBOSS ,
 250 as part of the
 251 DARPA CHATS research program.
 252 .Sh AUTHORS
 253 .An "Poul-Henning Kamp" Aq phk@FreeBSD.org
 254 .Sh BUGS
 255 The cryptographic algorithms and the overall design have not been
 256 attacked mercilessly for over 10 years by a gang of cryptoanalysts.