path: root/static/netbsd/man4/cgd.4 3.html

<table class="head">
  <tr>
    <td class="head-ltitle">CGD(4)</td>
    <td class="head-vol">Device Drivers Manual</td>
    <td class="head-rtitle">CGD(4)</td>
  </tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">cgd</code> &#x2014;
    <span class="Nd">cryptographic disk driver</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="Cd">pseudo-device cgd</code></p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The <code class="Nm">cgd</code> driver, configured with the
    <a class="Xr">cgdconfig(8)</a> tool, implements a logical disk device by
    encrypting or decrypting disk sectors on their way to and from a physical
    backing disk or partition.</p>
<section class="Ss">
<h2 class="Ss" id="Security_model"><a class="permalink" href="#Security_model">Security
  model</a></h2>
<p class="Pp">As long as you keep the key secret, <code class="Nm">cgd</code>
    keeps the content of the disk secret from a
    <a class="permalink" href="#passive"><i class="Em" id="passive">passive</i></a>
    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.</p>
<p class="Pp" id="does"><code class="Nm">cgd</code>
    <a class="permalink" href="#does"><i class="Em">does not</i></a> detect
    tampering by an
    <a class="permalink" href="#active"><i class="Em" id="active">active</i></a>
    adversary who can modify the content of the backing store, such as a
    man-in-the-middle between you and an iSCSI target, or after the border
    patrol returns your laptop to you.</p>
</section>
<section class="Ss">
<h2 class="Ss" id="Ciphers"><a class="permalink" href="#Ciphers">Ciphers</a></h2>
<p class="Pp">The following ciphers are supported:</p>
<dl class="Bl-tag">
  <dt id="adiantum"><a class="permalink" href="#adiantum"><code class="Li">adiantum
    (key size: 256 bits)</code></a></dt>
  <dd>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.
    <p class="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 AES.</p>
  </dd>
  <dt id="aes-cbc"><a class="permalink" href="#aes-cbc"><code class="Li">aes-cbc
    (key sizes: 128, 192, or 256 bits)</code></a></dt>
  <dd>AES in CBC mode. The CBC initialization vector for each disk sector is
      chosen to be the encryption under AES of the little-endian encoding of the
      disk sector number. The default key length is 128 bits. CBC mode is
      expected to provide marginally better theoretical security than XTS
    mode.</dd>
  <dt id="aes-xts"><a class="permalink" href="#aes-xts"><code class="Li">aes-xts
    (key sizes: 256 or 512 bits)</code></a></dt>
  <dd>AES in XTS mode. The XTS tweak for each disk sector is chosen to be the
      little-endian encoding of the disk sector number. AES-XTS uses a 256-bit
      or 512-bit key, composed of a pair of AES-128 or AES-256 keys. The default
      key length is 256, meaning AES-128. XTS mode is expected to provide
      marginally better theoretical performance than CBC mode.</dd>
</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="Obsolete_Ciphers"><a class="permalink" href="#Obsolete_Ciphers">Obsolete
  Ciphers</a></h2>
<p class="Pp">The following obsolete ciphers are supported for compatibility
    with old disks.</p>
<p class="Pp" id="WARNING:"><a class="permalink" href="#WARNING:"><b class="Sy">WARNING:</b></a>
    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.</p>
<dl class="Bl-tag">
  <dt id="3des-cbc"><a class="permalink" href="#3des-cbc"><code class="Li">3des-cbc
    (key size: 192 bits)</code></a></dt>
  <dd>3DES (Triple DES with EDE3) in CBC mode. The CBC initialization vector for
      each disk sector is chosen to be the encryption under 3DES of the
      little-endian encoding of the disk sector number.
    <p class="Pp">Note: Internally, the &#x2018;parity bits&#x2019; 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 EDE3 the
        security is much lower than one might expect even for a 168-bit key.</p>
  </dd>
  <dt id="blowfish-cbc"><a class="permalink" href="#blowfish-cbc"><code class="Li">blowfish-cbc
    (key sizes: 40, 48, 56, 64, ..., 432, 440, or 448 bits)</code></a></dt>
  <dd>Blowfish in CBC mode. The 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.</dd>
</dl>
</section>
<section class="Ss">
<h2 class="Ss" id="IV_Methods"><a class="permalink" href="#IV_Methods">IV
  Methods</a></h2>
<p class="Pp">A very early version of <code class="Nm">cgd</code> had a bug in
    the CBC-based ciphers <code class="Li">aes-cbc</code>,
    <code class="Li">3des-cbc</code>, and <code class="Li">blowfish-cbc</code>:
    the CBC initialization vector was chosen to be the
    <a class="permalink" href="#eight-fold"><i class="Em" id="eight-fold">eight-fold</i></a>
    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 &#x2018;IV method&#x2019; must be set to
    <code class="Li">encblkno8</code>. Otherwise the &#x2018;IV method&#x2019;
    should always be <code class="Li">encblkno1</code>. The parameter is
    meaningless for <code class="Li">adiantum</code> and
    <code class="Li">aes-xts</code>.</p>
</section>
</section>
<section class="Sh">
<h1 class="Sh" id="IOCTLS"><a class="permalink" href="#IOCTLS">IOCTLS</a></h1>
<p class="Pp">A <code class="Nm">cgd</code> responds to all of the standard disk
    <a class="Xr">ioctl(2)</a> calls defined in <a class="Xr">sd(4)</a>, and
    also defines the following:</p>
<dl class="Bl-tag">
  <dt id="CGDIOCSET"><a class="permalink" href="#CGDIOCSET"><code class="Dv">CGDIOCSET</code></a></dt>
  <dd>Configure the <code class="Nm">cgd</code>. This <a class="Xr">ioctl(2)</a>
      sets up the encryption parameters and points the
      <code class="Nm">cgd</code> at the underlying disk.</dd>
  <dt id="CGDIOCCLR"><a class="permalink" href="#CGDIOCCLR"><code class="Dv">CGDIOCCLR</code></a></dt>
  <dd>Unconfigure the <code class="Nm">cgd</code>.</dd>
  <dt id="CGDIOCGET"><a class="permalink" href="#CGDIOCGET"><code class="Dv">CGDIOCGET</code></a></dt>
  <dd>Get info about the <code class="Nm">cgd</code>.</dd>
</dl>
<p class="Pp">These <a class="Xr">ioctl(2)</a>'s and their associated data
    structures are defined in
    <code class="In">&lt;<a class="In">dev/cgdvar.h</a>&gt;</code> header.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="WARNINGS"><a class="permalink" href="#WARNINGS">WARNINGS</a></h1>
<p class="Pp">It goes without saying that if you forget the passphrase that you
    used to configure a <code class="Nm">cgd</code>, then you have irrevocably
    lost all of the data on the disk. Please ensure that you are using an
    appropriate backup strategy.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1>
<dl class="Bl-tag">
  <dt>/dev/{,r}cgd*</dt>
  <dd><code class="Nm">cgd</code> device special files.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
  ALSO</a></h1>
<p class="Pp"><a class="Xr">config(1)</a>, <a class="Xr">ioctl(2)</a>,
    <a class="Xr">sd(4)</a>, <a class="Xr">cgdconfig(8)</a>,
    <a class="Xr">MAKEDEV(8)</a></p>
<p class="Pp"><cite class="Rs"><span class="RsA">Roland C. Dowdeswell</span> and
    <span class="RsA">John Ioannidis</span>, <span class="RsT">The CryptoGraphic
    Disk Driver</span>, <i class="RsB">Proceedings of the FREENIX Track: 2003
    USENIX Annual Technical Conference</i>, <i class="RsI">USENIX
    Association</i>,
    <a class="RsU" href="https://www.usenix.org/event/usenix03/tech/freenix03/full_papers/dowdeswell/dowdeswell.pdf">https://www.usenix.org/event/usenix03/tech/freenix03/full_papers/dowdeswell/dowdeswell.pdf</a>,
    <span class="RsP">179-186</span>, <span class="RsD">June 9-14,
    2003</span>.</cite></p>
<p class="Pp"><cite class="Rs"><span class="RsA">Paul Crowley</span> and
    <span class="RsA">Eric Biggers</span>, <span class="RsT">Adiantum:
    length-preserving encryption for entry-level processors</span>,
    <i class="RsI">International Association of Cryptologic Research</i>,
    <i class="RsJ">Transactions on Symmetric Cryptology</i>,
    <span class="RsN">4</span>, <span class="RsV">2018</span>,
    <a class="RsU" href="https://doi.org/10.13154/tosc.v2018.i4.39-61">https://doi.org/10.13154/tosc.v2018.i4.39-61</a>,
    <span class="RsP">39-61</span>.</cite></p>
<p class="Pp"><cite class="Rs"><span class="RsT">FIPS PUB 46-3: Data Encryption
    Standard (DES)</span>, <i class="RsI">National Institute of Standards and
    Technology</i>,
    <a class="RsU" href="https://csrc.nist.gov/publications/detail/fips/46/3/archive/1999-10-25">https://csrc.nist.gov/publications/detail/fips/46/3/archive/1999-10-25</a>,
    <span class="RsQ">United States Department of Commerce</span>,
    <span class="RsD">October 25, 1999</span>, <span class="RsO">withdrawn May
    19, 2005</span>.</cite></p>
<p class="Pp"><cite class="Rs"><span class="RsT">FIPS PUB 197: Advanced
    Encryption Standard (AES)</span>, <i class="RsI">National Institute of
    Standards and Technology</i>,
    <a class="RsU" href="https://csrc.nist.gov/publications/detail/fips/197/final">https://csrc.nist.gov/publications/detail/fips/197/final</a>,
    <span class="RsQ">United States Department of Commerce</span>,
    <span class="RsD">November 2001</span>.</cite></p>
<p class="Pp"><cite class="Rs"><span class="RsA">Morris Dworkin</span>,
    <span class="RsT">Recommendation for Block Cipher Modes of Operation:
    Methods and Techniques</span>, <i class="RsI">National Institute of
    Standards and Technology</i>,
    <a class="RsU" href="https://csrc.nist.gov/publications/detail/sp/800-38a/final">https://csrc.nist.gov/publications/detail/sp/800-38a/final</a>,
    <span class="RsQ">United States Department of Commerce</span>,
    <span class="RsD">December 2001</span>, <span class="RsO">NIST Special
    Publication 800-38A</span>.</cite></p>
<p class="Pp"><cite class="Rs"><span class="RsA">Morris Dworkin</span>,
    <span class="RsT">Recommendation for Block Cipher Modes of Operation: the
    XTS-AES Mode for Confidentiality on Storage Devices</span>,
    <i class="RsI">National Institute of Standards and Technology</i>,
    <a class="RsU" href="https://csrc.nist.gov/publications/detail/sp/800-38e/final">https://csrc.nist.gov/publications/detail/sp/800-38e/final</a>,
    <span class="RsQ">United States Department of Commerce</span>,
    <span class="RsD">January 2010</span>, <span class="RsO">NIST Special
    Publication 800-38E</span>.</cite></p>
<p class="Pp"><cite class="Rs"><span class="RsA">Bruce Schneier</span>,
    <span class="RsT">The Blowfish Encryption Algorithm</span>,
    <a class="RsU" href="https://www.schneier.com/academic/blowfish">https://www.schneier.com/academic/blowfish</a>,
    <span class="RsO">superseded by Twofish, superseded by
    Threefish</span>.</cite></p>
<p class="Pp"><cite class="Rs"><span class="RsA">Karthikeyan Bhargavan</span>
    and <span class="RsA">Ga&#x00EB;tan Leurent</span>,
    <span class="RsT">Sweet32: Birthday attacks on 64-bit block ciphers in TLS
    and OpenVPN</span>,
    <a class="RsU" href="https://sweet32.info">https://sweet32.info</a>.</cite></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">The <code class="Nm">cgd</code> driver was written by Roland C.
    Dowdeswell for <span class="Ux">NetBSD</span>. The
    <code class="Nm">cgd</code> driver originally appeared in
    <span class="Ux">NetBSD 2.0</span>. The <code class="Li">aes-xts</code>
    cipher was added in <span class="Ux">NetBSD 8.0</span>. The
    <code class="Li">adiantum</code> cipher was added in <span class="Ux">NetBSD
    10.0</span>.</p>
</section>
</div>
<table class="foot">
  <tr>
    <td class="foot-date">September 27, 2024</td>
    <td class="foot-os">NetBSD 10.1</td>
  </tr>
</table>