Skip site navigation (1)Skip section navigation (2)
Date:      Sun, 10 Jun 2012 10:13:40 +0200
From:      Pawel Jakub Dawidek <pjd@FreeBSD.org>
To:        "John W. O'Brien" <john@saltant.com>
Cc:        freebsd-geom@freebsd.org
Subject:   Re: Scope and purpose of each kind geli key
Message-ID:  <20120610081337.GL1379@garage.freebsd.pl>
In-Reply-To: <4FD3B8D5.7030906@saltant.com>
References:  <4FD3B8D5.7030906@saltant.com>

next in thread | previous in thread | raw e-mail | index | archive | help

--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--



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20120610081337.GL1379>