Scope and purpose of each kind geli key

Hello freebsd-geom <at> ,

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.

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.

Master Key
----------

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

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.

Storage Key
-----------

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.

User Key
--------

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.

Key Encrypting Key
------------------

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.

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?

I will solicit editorial input in the event that this is going to see
the light of day as a patch attached to a PR.

Regards,
John