share/man/man4/cgd.4

   1 .\" $NetBSD: cgd.4,v 1.11 2008/09/12 16:51:55 christos Exp $
   2 .\"
   3 .\" Copyright (c) 2002, 2003 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Roland C. Dowdeswell.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd September 12, 2008
  31 .Dt CGD 4
  32 .Os
  33 .Sh NAME
  34 .Nm cgd
  35 .Nd cryptographic disk driver
  36 .Sh SYNOPSIS
  37 .Cd "pseudo-device cgd" Op Ar count
  38 .Sh DESCRIPTION
  39 The
  40 .Nm
  41 driver provides the capability of encrypting blocks on their way
  42 to and from a disk or partition.
  43 .Pp
  44 In order to compile support for the
  45 .Nm
  46 into your kernel, you must add the driver to your kernel configuration
  47 file.
  48 To do this, add a line similar to:
  49 .Bd -unfilled -offset indent
  50 pseudo-device   cgd     4       # cryptographic disk driver
  51 .Ed
  52 .Pp
  53 The count argument defines how many
  54 .Nm Ns 's
  55 may be configured at a time.
  56 .Ss Encryption Algorithms
  57 Currently the following cryptographic algorithms are supported:
  58 .Bl -tag -width indentxxxxxxx
  59 .It aes-cbc
  60 AES in CBC mode.
  61 AES uses a 128 bit blocksize and can accept keys of
  62 length 128, 192, or 256.
  63 The default key length is 128.
  64 .It 3des-cbc
  65 Triple DES in CBC mode.
  66 Triple DES uses a 64 bit blocksize and is
  67 performed in EDE3 mode with a 168 bit key.
  68 The key passed to the kernel
  69 is 192 bits but the parity bits are ignored.
  70 .It blowfish-cbc
  71 Blowfish in CBC mode.
  72 Blowfish uses a 64 bit blocksize and can accept keys between 40 and
  73 448 bits in multiples of 8.
  74 It is strongly encouraged that keys be at least 128 bits long.
  75 There are no performance advantages of using shorter keys.
  76 The default key length is 128 bits.
  77 .El
  78 .Ss IV Methods
  79 Currently, the following IV Methods are supported:
  80 .Bl -tag -width encblkno1
  81 .It encblkno1
  82 This method  encrypts the block number of the physical disk block once with
  83 the cipher and key provided and uses the result as the IV for CBC mode.
  84 This method should ensure that each block has a different IV and that the IV
  85 is reasonably unpredictable.
  86 This is the default method used by
  87 .Xr cgdconfig 8
  88 when configuring new
  89 .Nm Ns 's .
  90 .It encblkno8
  91 This is the original IV method used by
  92 .Nm
  93 and provided for backward compatibility.
  94 It repeatedly encrypts the block number of the physical disk block
  95 eight times and uses the result as the IV for CBC mode.
  96 This method should ensure that each block has a different IV and that the IV
  97 is reasonably unpredictable.
  98 The eightfold encryption was not intended and causes a notable
  99 performance loss with little (if any) increase in security over a
 100 single encryption.
 101 .El
 102 .Ss IOCTLS
 103 A
 104 .Nm
 105 responds to all of the standard disk
 106 .Xr ioctl 2
 107 calls defined in
 108 .Xr sd 4 ,
 109 and also defines the following:
 110 .Bl -tag -width CGDIOCSET
 111 .It CGDIOCSET
 112 configure the
 113 .Nm .
 114 This
 115 .Xr ioctl 2
 116 sets up the encryption parameters and points the
 117 .Nm
 118 at the underlying disk.
 119 .It CGDIOCCLR
 120 unconfigures the
 121 .Nm .
 122 .El
 123 .Pp
 124 These
 125 .Xr ioctl 2 Ns 's
 126 and their associated data structures are defined in
 127 .Pa /usr/include/dev/cgdvar.h .
 128 .Sh WARNINGS
 129 It goes without saying that if you forget the passphrase that you used
 130 to configure a
 131 .Nm ,
 132 then you have irrevocably lost all of the data on the disk.
 133 Please ensure that you are using an appropriate backup strategy.
 134 .Sh FILES
 135 .Bl -tag -width indentxxxxxxxxxxx
 136 .It /dev/{,r}cgd*
 137 .Nm
 138 device special files.
 139 .El
 140 .Sh SEE ALSO
 141 .Xr config 1 ,
 142 .Xr ioctl 2 ,
 143 .Xr sd 4 ,
 144 .Xr MAKEDEV 8 ,
 145 .Xr cgdconfig 8
 146 .Sh HISTORY
 147 The
 148 .Nm
 149 driver was written by Roland C. Dowdeswell for
 150 .Nx .
 151 The
 152 .Nm
 153 driver originally appeared in
 154 .Nx 2.0 .