.\" $NetBSD: cgd.4,v 1.24 2020/08/17 17:18:02 riastradh 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 16, 2020
.Dt CGD 4
.Os
.Sh NAME
.Nm cgd
.Nd cryptographic disk driver
.Sh SYNOPSIS
.Cd pseudo-device cgd
.Sh DESCRIPTION
The
.Nm
driver, configured with the
.Xr cgdconfig 8
tool, implements a logical disk device by encrypting or decrypting disk
sectors on their way to and from a physical backing disk or partition.
.Ss Security model
As long as you keep the key secret,
.Nm
keeps the content of the disk secret from a
.Em passive
adversary, such as a thief who steals your disk or a border patrol
agent who detains you and takes a snapshot of your laptop's disk while
you are crossing a border.
.Pp
.Nm
.Em does not
detect tampering by an
.Em active
adversary who can modify the content of the backing store, such as a
man-in-the-middle between you and an
.Tn iSCSI
target, or after the border patrol returns your laptop to you.
.Ss Ciphers
The following ciphers are supported:
.Bl -tag -width "abcd"
.It Li "adiantum" (key size: 256 bits)
The Adiantum tweakable wide-block cipher.
The Adiantum tweak for each disk sector is taken to be the
little-endian encoding of the disk sector number.
.Pp
Adiantum provides the best security by encrypting entire disk sectors
at a time (512 bytes), and generally provides the best performance on
machines without CPU support for accelerating
.Tn AES .
.It Li "aes-cbc" (key sizes: 128, 192, or 256 bits)
.Tn AES
in
.Tn CBC
mode.
The
.Tn CBC
initialization vector for each disk sector is chosen to be the
encryption under
.Tn AES
of the little-endian encoding of the disk sector number.
The default key length is 128 bits.
.It Li "aes-xts" (key sizes: 256 or 512 bits)
.Tn AES
in
.Tn XTS
mode.
The
.Tn XTS
tweak for each disk sector is chosen to be the little-endian encoding
of the disk sector number.
.Tn AES-XTS
uses a 256-bit or 512-bit key, composed of a pair of
.Tn AES-128
or
.Tn AES-256
keys.
The default key length is 256, meaning
.Tn AES-128.
.El
.Ss Obsolete Ciphers
The following obsolete ciphers are supported for compatibility with
old disks.
.Pp
.Sy WARNING:
These obsolete ciphers are implemented without timing side channel
protection, so, for example, JavaScript code in a web browser that can
measure the timing of disk activity may be able to recover the secret
key.
These are also based on 64-bit block ciphers and are therefore unsafe
for disks much larger than a gigabyte.
You should not use these except where compatibility with old disks is
necessary.
.Bl -tag -width "abcd"
.It Li "3des-cbc" (key size: 192 bits)
.Tn 3DES
.Po
Triple
.Tn DES
with
.Tn EDE3
.Pc
in
.Tn CBC
mode.
The
.Tn CBC
initialization vector for each disk sector is chosen to be the
encryption under
.Tn 3DES
of the little-endian encoding of the disk sector number.
.Pp
Note: Internally, the
.Sq parity bits
of the 192-bit key are ignored, so there are only 168 bits of key
material, and owing to generic attacks on 64-bit block ciphers and to
meet-in-the-middle attacks on compositions of ciphers as in
.Tn EDE3
the security is much lower than one might expect even for a 168-bit
key.
.It Li "blowfish-cbc" (key sizes: 40, 48, 56, 64, ..., 432, 440, or 448 bits)
Blowfish in
.Tn CBC
mode.
The
.Tn CBC
initialization vector for each disk sector is chosen to be the
encryption under Blowfish of the little-endian encoding of the disk
sector number.
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
A very early version of
.Nm
had a bug in the
.Tn CBC Ns -based
ciphers
.Li "aes-cbc" ,
.Li "3des-cbc" ,
and
.Li "blowfish-cbc" :
the
.Tn CBC
initialization vector was chosen to be the
.Em eight-fold
encryption under the block cipher of the little-endian encoding of the
disk sector number, which has no impact on security but reduces
performance.
For compatibility with such disks, the
.Sq IV method
must be set to
.Li encblkno8 .
Otherwise the
.Sq IV method
should always be
.Li encblkno1 .
The parameter is meaningless for
.Li adiantum
and
.Li aes-xts .
.Sh 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 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.
.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 https://www.usenix.org/event/usenix03/tech/freenix03/full_papers/dowdeswell/dowdeswell.pdf
.Re
.Rs
.%A Paul Crowley
.%A Eric Biggers
.%T Adiantum: length-preserving encryption for entry-level processors
.%I International Association of Cryptologic Research
.%J Transactions on Symmetric Cryptology
.%V 2018
.%N 4
.%P 39-61
.%U https://doi.org/10.13154/tosc.v2018.i4.39-61
.Re
.Rs
.%T FIPS PUB 46-3: Data Encryption Standard (DES)
.%Q United States Department of Commerce
.%I National Institute of Standards and Technology
.%O withdrawn May 19, 2005
.%D October 25, 1999
.%U https://csrc.nist.gov/publications/detail/fips/46/3/archive/1999-10-25
.Re
.Rs
.%T FIPS PUB 197: Advanced Encryption Standard (AES)
.%Q United States Department of Commerce
.%I National Institute of Standards and Technology
.%D November 2001
.%U https://csrc.nist.gov/publications/detail/fips/197/final
.Re
.Rs
.%A Morris Dworkin
.%T Recommendation for Block Cipher Modes of Operation: Methods and Techniques
.%D December 2001
.%Q United States Department of Commerce
.%I National Institute of Standards and Technology
.%O NIST Special Publication 800-38A
.%U https://csrc.nist.gov/publications/detail/sp/800-38a/final
.Re
.Rs
.%A Morris Dworkin
.%T Recommendation for Block Cipher Modes of Operation: the XTS-AES Mode for Confidentiality on Storage Devices
.%D January 2010
.%Q United States Department of Commerce
.%I National Institute of Standards and Technology
.%O NIST Special Publication 800-38E
.%U https://csrc.nist.gov/publications/detail/sp/800-38e/final
.Re
.Rs
.%A Bruce Schneier
.%T The Blowfish Encryption Algorithm
.%O superseded by Twofish, superseded by Threefish
.%U https://www.schneier.com/academic/blowfish
.Re
.Rs
.%A Karthikeyan Bhargavan
.%A Ga\(:etan Leurent
.%T Sweet32: Birthday attacks on 64-bit block ciphers in TLS and OpenVPN
.%U https://sweet32.info
.Re
.Sh HISTORY
The
.Nm
driver was written by Roland C. Dowdeswell for
.Nx .
The
.Nm
driver originally appeared in
.Nx 2.0 .
The
.Li aes-xts
cipher was added in
.Nx 8.0 .
The
.Li adiantum
cipher was added in
.Nx 10.0 .