From owner-freebsd-geom@FreeBSD.ORG Sun Jun 10 08:15:38 2012 Return-Path: Delivered-To: freebsd-geom@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id DE8F3106566B for ; Sun, 10 Jun 2012 08:15:38 +0000 (UTC) (envelope-from pawel@dawidek.net) Received: from mail.dawidek.net (60.wheelsystems.com [83.12.187.60]) by mx1.freebsd.org (Postfix) with ESMTP id 2403F8FC0A for ; Sun, 10 Jun 2012 08:15:38 +0000 (UTC) Received: from localhost (89-73-195-149.dynamic.chello.pl [89.73.195.149]) by mail.dawidek.net (Postfix) with ESMTPSA id A932F8D0; Sun, 10 Jun 2012 10:15:36 +0200 (CEST) Date: Sun, 10 Jun 2012 10:13:40 +0200 From: Pawel Jakub Dawidek To: "John W. O'Brien" Message-ID: <20120610081337.GL1379@garage.freebsd.pl> References: <4FD3B8D5.7030906@saltant.com> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha1; protocol="application/pgp-signature"; boundary="UUMz/kfoogzZ9WLZ" Content-Disposition: inline In-Reply-To: <4FD3B8D5.7030906@saltant.com> X-OS: FreeBSD 10.0-CURRENT amd64 User-Agent: Mutt/1.5.21 (2010-09-15) Cc: freebsd-geom@freebsd.org Subject: Re: Scope and purpose of each kind geli key X-BeenThere: freebsd-geom@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: GEOM-specific discussions and implementations List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 10 Jun 2012 08:15:38 -0000 --UUMz/kfoogzZ9WLZ Content-Type: text/plain; charset=us-ascii Content-Disposition: inline Content-Transfer-Encoding: quoted-printable On Sat, Jun 09, 2012 at 04:57:57PM -0400, John W. O'Brien wrote: > I recently started using geli and found it necessary to read a bunch > of source code to supplement the manpages and Handbook sections. In > particular, there are several different kinds of keys (and sources of > key material), but they are not clearly differentiated in the docs. Of > course, one need not understand the entire geli architecture and > theory of operation in order to use it, but a bit more context would > make things easier. >=20 > So, the purpose of this inquiry is twofold: first, to sanity check > what I think I learned from my studies; second, to find out if others > would find it useful for me to take a swipe at integrating this > information into the docs. I think this is great you decided to document it and I'll do my best to help. I'd also like to see such description to be available easly and I'd be happy to add it to GELI manual page or create dedicated manual page with detailed documentation how it works. > Master Key > - ---------- >=20 > There is exactly one Master Key per provider, and it never changes for > the life of the provider. It is generated in userland upon init (or > onetime) and the user can select the key length (-l). The Master Key is always 1024 bits long (128 bytes). We split it into two parts. First part (first 64 bytes) is called IV Key and is used for IV generations when encryption algorithm is used in CBC mode. The IV Key is _not_ used when encryption algorithm is used in XTS mode. For CBC mode IV is generated by calculating SHA256 from IV Key concatenated with eight bytes that consist byte offset of the block we are encrypting. For XTS mode we use raw byte offset of the block. The second part of the Master Key (next 64 bytes) is used directly or indirectly (depending on the configuration) for data encryption and optionally for data authentication. It is called Data Key. There are three cases here: 1. Single encryption key, no authentication (single encryption key was used in older GELI versions). In this case the Data Key is used directly to encrypt all the data. IV is generated as described above. 2. Single encryption key with authentication. In this case encryption key and authentication key are calculated with: Encryption-Key =3D HMAC_SHA512(Data-Key, 0x10) Authentication-Key =3D HMAC_SHA512(Data-Key, 0x11) The Encryption-Key is used to encrypt all the data. IV is calculated as described above. 3. Multiple encryption keys. If authentication is enabled, the Authentication-Key is calculated as described in point 2. When multiple keys are used, Encryption Key is calculated with: Encryption-Key =3D HMAC_SHA512(Data-Key, "ekey"+keyno) Where keyno is eight bytes array that contains key number. Key number is incremented every 2^20 sectors of the GELI provider. XXX: This is how it should work, but while looking at the code now I realized that not the Data Key, but IV Key was used to generate Encryption Keys. For XTS mode this is totally fine, as the IV Key was unused anyway. For CBC mode this should also be fine, as IV Key is not used the same way for IV generation and for Encryption Keys generation. But I'll correct that still. > Up to two, encrypted copies of the Master Key can be stored in the > provider metadata. Each copy is encrypted with a Key Encrypting Key > derived from a User Key. >=20 >=20 > Storage Key > - ----------- >=20 > The Storage Key(s) are deterministically derived by the kernel and > cached in memory during operation. Each is generated from the Master > Key and is based on the block offset. The total number of Storage Keys > used by a given provider depends on the size of the provider; one > Storage Key per 2^20 blocks. A block's offset is used as an > Initialization Vector (IV) when encrypting or decrypting its data with > the applicable Storage Key. >=20 >=20 > User Key > - -------- >=20 > Upon init, attach, setkey, and resume, the user provides a User Key > comprised of one or more User Key components; files (-k, -K), a > passphrase, or stored passphrases (-j, -J). All components are > processed in userland to generate a Key Encrypting Key which is used > to access one of the two, encrypted Master Key copies stored in the > provider metadata. It would probably be worth noting that passphrase (either entered by hand or provided with -j/-J options) is strengthened with PKCS#2 PBKDF2 function based on SHA512 algorithm. > Key Encrypting Key > - ------------------ >=20 > Each Key Encrypting Key is generated from a User Key and used to > encrypt a copy of the Master Key on init or setkey, and to decrypt a > copy of the Master Key on attach, setkey, or resume. >=20 >=20 > For my sake and the sake of future mailing list archaeologists, are > there any errors or significant ambiguities in my description? Once > I've addressed any problems, would this, or something like it, be a > welcome addition to the manpage and/or the Handbook? If so, is the > level sufficient, or would more detail about salt, hashes, and so > forth be appropriate? This is very welcome. And more details are even more welcome:) Thanks! --=20 Pawel Jakub Dawidek http://www.wheelsystems.com FreeBSD committer http://www.FreeBSD.org Am I Evil? Yes, I Am! http://tupytaj.pl --UUMz/kfoogzZ9WLZ Content-Type: application/pgp-signature -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.19 (FreeBSD) iEYEARECAAYFAk/UVzEACgkQForvXbEpPzRUcwCg8kn/cRnB7KrEXoHQHT4B8uOf kX8AnRUzz1Eexph292SRcwgduIJjkPrc =MURF -----END PGP SIGNATURE----- --UUMz/kfoogzZ9WLZ--