.\" $NetBSD: cgd.4,v 1.22 2018/08/31 18:20:10 sevan Exp $
.\"
.\" Copyright (c) 2002, 2003 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.
.\"
.\" 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 August 31, 2018
.Dt CGD 4
.Os
.Sh NAME
.Nm cgd
.Nd cryptographic disk driver
.Sh SYNOPSIS
.Cd pseudo-device cgd
.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     # cryptographic disk driver
.Ed
.Pp
The
.Nm
devices are allocated as needed.
.Ss Encryption Algorithms
Currently the following cryptographic algorithms are supported:
.Bl -tag -width indentxxxxxxx
.It Ic aes-cbc
.Tn AES
in
.Tn CBC
mode.
.Tn AES
uses a 128 bit blocksize and can accept keys of length 128, 192, or 256.
The default key length is 128.
.It Ic aes-xts
.Tn AES
in
.Tn XTS
mode.
.Tn AES-XTS
uses a 128 bit blocksize and can accept keys of length 256 or 512.
Note that an
.Tn AES-XTS
key consists of two
.Tn AES
keys of equal size.
The second key is used solely to encrypt the block number of the physical
disk block.
The default key length is 256.
.It Ic 3des-cbc
Triple
.Tn DES
in
.Tn CBC
mode.
Triple
.Tn DES
uses a 64 bit blocksize and is performed in
.Tn EDE3
mode with a 168 bit key.
The key passed to the kernel is 192 bits but the parity bits are ignored.
.It Ic blowfish-cbc
Blowfish in
.Tn CBC
mode.
Blowfish uses a 64 bit blocksize and can accept keys between 40 and
448 bits in multiples of 8.
It is strongly encouraged that keys be at least 128 bits long.
There are no performance advantages of using shorter keys.
The default key length is 128 bits.
.El
.Ss IV Methods
Currently, the following
.Tn IV
Methods are supported:
.Bl -tag -width encblkno1
.It Ic encblkno1
This method  encrypts the block number of the physical disk block once with
the cipher and key provided and uses the result as the
.Tn IV
for
.Tn CBC
mode.
This method should ensure that each block has a different
.Tn IV
and that the
.Tn IV
is reasonably unpredictable.
This is the default method used by
.Xr cgdconfig 8
when configuring a new
.Nm .
.It Ic encblkno8
This is the original
.Tn IV
method used by
.Nm
and provided for backward compatibility.
It repeatedly encrypts the block number of the physical disk block
eight times and uses the result as the
.Tn IV
for
.Tn CBC
mode.
This method should ensure that each block has a different
.Tn IV
and that the
.Tn IV
is reasonably unpredictable.
The eightfold encryption was not intended and causes a notable
performance loss with little (if any) increase in security over a
single encryption.
.El
.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 -offset indent
.It Dv CGDIOCSET
Configure the
.Nm .
This
.Xr ioctl 2
sets up the encryption parameters and points the
.Nm
at the underlying disk.
.It Dv CGDIOCCLR
Unconfigure the
.Nm .
.It Dv CGDIOCGET
Get info about the
.Nm .
.El
.Pp
These
.Xr ioctl 2 Ns 's
and their associated data structures are defined in
.In dev/cgdvar.h
header.
.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.
.Pp
A
.Nm
device doesn't authenticate data and thus it can't guarantee integrity
of the encrypted data.
In particular, if the plaintext is known to an adversary, it is
possible to change every second block on a disk encrypted in the
.Tn CBC
mode to plaintext blocks of their choice.
The
.Tn XTS
mode isn't vulnerable to this particular attack but a lack of
integrity should be taken into account when evaluating security risks.
.Sh FILES
.Bl -tag -width indentxxxxxxxxxxx
.It /dev/{,r}cgd*
.Nm
device special files.
.El
.Sh SEE ALSO
.Xr config 1 ,
.Xr ioctl 2 ,
.Xr sd 4 ,
.Xr cgdconfig 8 ,
.Xr MAKEDEV 8
.Rs
.%A Roland C. Dowdeswell
.%A John Ioannidis
.%T The CryptoGraphic Disk Driver
.%I USENIX Association
.%B Proceedings of the FREENIX Track: 2003 USENIX Annual Technical Conference
.%P 179-186
.%D June 9-14, 2003
.%U http://www.usenix.org/event/usenix03/tech/freenix03/full_papers/dowdeswell/dowdeswell.pdf
.Re
.Sh HISTORY
The
.Nm
driver was written by Roland C. Dowdeswell for
.Nx .
The
.Nm
driver originally appeared in
.Nx 2.0 .