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 .\" 3. The names of the authors may not be used to endorse or promote
  20 .\"    products derived from this software without specific prior written
  21 .\"    permission.
  22 .\"
  23 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  26 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  33 .\" SUCH DAMAGE.
  34 .\"
  35 .\" $FreeBSD$
  36 .\"
  37 .Dd October 19, 2002
  38 .Os
  39 .Dt gbde 8
  40 .Sh NAME
  41 .Nm gbde
  42 .Nd Operation and management utility for Geom Based Disk Encryption.
  43 .Sh SYNOPSIS
  44 .Nm
  45 .Cm attach
  46 .Ar destination
  47 .Op Fl l Ar lockfile
  48 .Op Fl p Ar pass-phrase
  49 .Nm
  50 .Cm detach
  51 .Ar destination
  52 .Nm
  53 .Cm init
  54 .Ar destination
  55 .Op Fl i
  56 .Op Fl f Ar filename
  57 .Op Fl L Ar lockfile
  58 .Op Fl P Ar pass-phrase
  59 .Nm
  60 .Cm setkey
  61 .Ar destination
  62 .Op Fl n Ar key
  63 .Op Fl l Ar lockfile
  64 .Op Fl p Ar pass-phrase
  65 .Op Fl L Ar new-lockfile
  66 .Op Fl P Ar new-pass-phrase
  67 .Nm
  68 .Cm destroy
  69 .Ar destination
  70 .Op Fl n Ar key
  71 .Op Fl l Ar lockfile
  72 .Op Fl L Ar lockfile
  73 .Sh DESCRIPTION
  74 The
  75 .Nm
  76 program is the only official operation and management interface for the
  77 .Xr gbde 4
  78 GEOM based disk encryption kernel facility.
  79 The interaction between the
  80 .Nm
  81 program and the kernel part is not a published interface.
  82 .Pp
  83 The operational aspect consists of two subcommands:
  84 one to open and attach
  85 a device to the in-kernel cryptographic gbde module,
  86 and one to close and detach a device.
  87 .Pp
  88 The management part allows initialization of the master key and lock sectors
  89 on a device, initialization and replacement of pass-phrases and
  90 key invalidation and blackening functions.
  91 .Pp
  92 The
  93 .Fl l Ar lockfile
  94 argument is used to supply the lock selector data.
  95 If no
  96 .Fl l
  97 option is specified, the first sector is used for this purpose.
  98 .Pp
  99 The
 100 .Fl L Ar new-lockfile
 101 argument
 102 specifies the lock selector file for the key modified with the
 103 .Ar setkey subcommand.
 104 .Pp
 105 The
 106 .Fl n Ar key
 107 argument can be used to specify which of the four keys
 108 to which the operation applies.
 109 A value of 1 to 4 selects the specified key, a value of 0 (the default)
 110 means
 111 .Dq "this key"
 112 (i.e., the key used to gain access to the device)
 113 and a value of -1 means
 114 .Dq "all keys" .
 115 .Pp
 116 The
 117 .Fl f Ar filename
 118 specifies an optional parameter file for use under initialization.
 119 .Pp
 120 Alternatively, the
 121 .Fl i
 122 option toggles an interactive mode where a template file with descriptions
 123 of the parameters can be interactively edited.
 124 .Pp
 125 The
 126 .Fl p Ar pass-phrase
 127 argument
 128 specifies the pass-phrase used to opening the device.
 129 If not specified, the controlling terminal will be used to prompt the user
 130 for the pass-phrase.
 131 .Pp
 132 The
 133 .Fl P Ar new-pass-phrase
 134 argument
 135 can be used to specify the new pass-phrase to the
 136 .Cm setkey
 137 subcommand.
 138 If not specified, the user is prompted for the new pass-phrase on the
 139 controlling terminal.
 140 .Sh EXAMPLES
 141 To initialize a device, using default parameters:
 142 .Dl # gbde init /dev/ad0s1f -l /etc/ad0s1f.lock
 143 .Pp
 144 To attach an encrypted device:
 145 .Dl # gbde attach ad0s1f -l /etc/ad0s1f.lock
 146 .Pp
 147 To detach an encrypted device:
 148 .Dl # gbde detach ad0s1f
 149 .Pp
 150 To initialize the second key using a detached lockfile and a trivial
 151 pass-phrase:
 152 .Dl # gbde setkey ad0s1f -n 2 -P foo -L key2.lockfile
 153 .Pp
 154 To destroy all copies of the masterkey:
 155 .Dl # gbde destroy ad0s1f -n -1
 156 .Sh SEE ALSO
 157 .Xr gbde 4 ,
 158 .Xr geom 4 .
 159 .Rs
 160 .%A Poul-Henning Kamp
 161 .%T "Making sure data is lost: Spook-strength encryption of on-disk data"
 162 .%R "Refereed paper, NORDU2003 conference"
 163 .Re
 164 .Sh HISTORY
 165 This software was developed for the FreeBSD Project by Poul-Henning Kamp
 166 and NAI Labs, the Security Research Division of Network Associates, Inc.
 167 under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the
 168 DARPA CHATS research program.
 169 .Sh AUTHORS
 170 .An "Poul-Henning Kamp" Aq phk@FreeBSD.org