diff options
Diffstat (limited to 'static/netbsd/man4/cgd.4')
| -rw-r--r-- | static/netbsd/man4/cgd.4 | 324 |
1 files changed, 324 insertions, 0 deletions
diff --git a/static/netbsd/man4/cgd.4 b/static/netbsd/man4/cgd.4 new file mode 100644 index 00000000..31217d19 --- /dev/null +++ b/static/netbsd/man4/cgd.4 @@ -0,0 +1,324 @@ +.\" $NetBSD: cgd.4,v 1.25 2024/09/27 12:49:41 nia 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 September 27, 2024 +.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. +.Tn CBC +mode is expected to provide marginally better theoretical security than +.Tn XTS +mode. +.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. +.Tn XTS +mode is expected to provide marginally better theoretical performance than +.Tn CBC +mode. +.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 . |