How is the root key obtained in the various seal/unseal mechanisms?

[thgoebel]

I'm trying to understand how the root key is derived/obtained/stored/used, and the key hierarchy in general. The documentation is somewhat conflicting and thus confusing.

Specifically:

1. In the Shamir case: is the root key directly split into/assembled from key shares?
   a. This is what some of the docs seem to say.
2. Or is the root key encrypted by an intermediate "unseal key"? And that unseal key is Shamir-shared?
   a. This is what some of the docs seems to say. I could trace this to this commit/this PR. But I'm still confused to what extend this is still up-to-date.
3. The encryption keys in the keyring: they are stored (encrypted under the root key) on physical storage, and are (once decrypted) visible in memory?
4. When using auto-unseal with an HSM/KMS: The HSM/KMS stores the root key? And the encrypted encryption key is sent to the HSM/KMS, which decrypts it using the root key, and sends it back to OpenBao? This would be in line of using the name bao-root-key-aes in the seal stanza docs.
5. Or is the HSM/KMS storing an "unseal key" (as effectively a single key share)? And the encrypted root key is sent to the HSM/KMS, which decrypts it with the unseal key, and returns it to OpenBao, which then locally uses the decrypted root key to decrypt the encryption key(s)? As insinuated here. But then the naming bao-root-key-aes (as above) don't make sense.

Thanks in advance! :)

P.S.: I'm happy to contribute to the docs and clarify this, once I understand what is actually implemented, and what the docs should say.

References

• https://openbao.org/docs/internals/architecture/
• https://openbao.org/docs/concepts/seal/
• https://openbao.org/docs/internals/rotation/

[cipherboy]

#1021 should be the most clear explanation. We're working on #1170 first, but the hierarchy should be consistent.

Key material hierarchy is consistent between the Shamir's and Auto-Unseal mechanisms since (before) the fork point.

[cipherboy]

@thgoebel Realized I missed 3.

I believe, from memory, root keys get purged from memory and only barrier keyring remains. There's a copy of the root key encrypted with the barrier keyring so that you can always rotate the barrier keyring (encrypting new items) if necessary.

1/2/4/5 should all be addressed in those docs. I think we had planned to wait for the parallel unseal implementation to land to clarify this, though I'm not against taking PRs earlier (since, parallel unseal will likely be delayed a release to v2.5.x series).