[src/trunk]: src/share/man/man4 A [much needed] document describing cgd.

[elric <elric%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/0d33accd00da
branches:  trunk
changeset: 537695:0d33accd00da
user:      elric <elric%NetBSD.org@localhost>
date:      Fri Oct 04 18:57:35 2002 +0000

description:
A [much needed] document describing cgd.

diffstat:

 share/man/man4/cgd.4 |  135 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 135 insertions(+), 0 deletions(-)

diffs (139 lines):

diff -r 3580352fb318 -r 0d33accd00da share/man/man4/cgd.4
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man4/cgd.4      Fri Oct 04 18:57:35 2002 +0000
@@ -0,0 +1,135 @@
+.\" $NetBSD: cgd.4,v 1.1 2002/10/04 18:57:35 elric Exp $
+.\"
+.\" Copyright (c) 2002, The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Roland C. Dowdeswell.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"        This product includes software developed by the NetBSD
+.\"        Foundation, Inc. and its contributors.
+.\" 4. Neither the name of The NetBSD Foundation nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd September 23, 2002
+.Dt CGD 4
+.Os
+.Sh NAME
+.Nm cgd
+.Nd cryptographic disk driver
+.Sh SYNOPSIS
+.Cd "pseudo-device cgd" Op Ar count
+.Sh DESCRIPTION
+The
+.Nm
+driver provides the capability of encrypting blocks on their way
+to and from a disk or partition.
+.Pp
+In order to compile support for the
+.Nm
+into your kernel, you must add the driver to your kernel configuration
+file.  To do this, add a line similar to:
+.Bd -unfilled -offset indent
+pseudo-device   cgd     4       # cryptographic disk devices
+.Ed
+.Pp
+The count argument defines how many
+.Nm Ns 's
+may be configured at a time.
+.Ss Encryption Algorithms
+Currently the following cryptographic algorithms are supported:
+.Bl -tag -width indentxxxxxxx
+.It aes-cbc
+AES in CBC mode.  AES uses a 128 bit blocksize and can accept keys of
+length 128, 192 or 256.  The default key length is 256.
+.It 3des-cbc
+Triple DES in CBC mode.  Triple DES uses a 64 bit blocksize and is
+performed in EDE3 mode with a 168 bit key.  The key passed to the kernel
+is 192 bits but the parity bits are ignored.
+.It blowfish-cbc
+Blowfish in CBC mode.  Blowfish uses a 64 bit blocksize and can accept
+keys of length 128.
+.El
+.Ss IV Methods
+Currently, the only IV Method supported is
+.Ar encblkno
+(Encrypted Block Number.)  This method encrypts the block number of the
+physical disk block with the cipher and key provided and uses that as the
+IV for CBC mode.  This method should ensure that each block has a different
+IV and that the IV is reasonably unpredictable.
+.Ss IOCTLS
+A
+.Nm
+responds to all of the standard disk
+.Xr ioctl 2
+calls defined in
+.Xr sd 4 ,
+and also defines the following:
+.Bl -tag -width CGDIOCSET
+.It CGDIOCSET
+configure the
+.Nm "" .
+This
+.Xr ioctl 2
+sets up the encryption parameters and points the
+.Nm
+at the underlying disk.
+.It CGDIOCCLR
+unconfigures the
+.Nm "" .
+.El
+.Pp
+These
+.Xr ioctl 2 Ns 's
+and their associated data structures are defined in
+.Pa /usr/include/dev/cgdvar.h .
+.Sh WARNINGS
+It goes without saying that if you forget the passphrase that you used
+to configure a
+.Nm "" ,
+then you have irrevocably lost all of the data on the disk.  Please ensure
+that you are using an appropriate backup strategy.
+.Sh FILES
+.Bl -tag -width indentxxxxxxxxxxx
+.It /dev/{,r}cgd*
+.Nm
+device special files.
+.El
+.Sh SEE ALSO
+.Xr ioctl 2 ,
+.Xr sd 4 ,
+.Xr MAKEDEV 8 ,
+.Xr cgdconfig 8 ,
+.Xr config 8
+.Sh HISTORY
+The
+.Nm
+driver was written by Roland C. Dowdeswell for
+.Nx .
+The
+.Nm
+driver originally appeared in
+.Nx 1.7 .