runtime docs: Remove storage from cryptographic mailbox #1795
Conversation
swenson
requested review from
jhand2,
fdamato,
rusty1968,
bluegate010,
mhatrevi and
vsonims
as code owners
|
(Discussion offline: we'll change AES to use the init / update / final flow, so that we can remove CMK from the update / final ones, which reduces some of the confusion around that I think.) |
Mostly. We need to keep a limited amount of storage per AES-256-GCM key to track usage, since these keys can only be used a certain number of times due to their IV problems. For HMAC, we don't specify a key usage on the output MAC, since it has to be imported back into Caliptra to be used as a key, where its usage will have to be specified. We also fix a few other minor issues with the mailbox documentation: Fixes #1753 Fixes #1754 Fixes #1755 Fixes #1756
swenson
force-pushed
the
docs/crypto-mailbox-fixes
branch
from
0ef0012 to
c6b1916
Compare
runtime/README.md
Outdated
| | block offset | 24 | Starting block number | | ||
| | size | 24 | Size (in bytes) of the data stored. | | ||
| | | | Does not have to be a multiple of 16 bytes. | | ||
| The key used to encrypt the CMKs is randomized on reset, which means that CMKS cannot be used between resets. |
runtime/README.md
Outdated
| | size | 24 | Size (in bytes) of the data stored. | | ||
| | | | Does not have to be a multiple of 16 bytes. | | ||
| The key used to encrypt the CMKs is randomized on reset, which means that CMKS cannot be used between resets. | ||
| The iv is a randomized 1-up counter that is incremented for every key created. |
| | ---------- | ----------- | | ||
| | 0 | Reserved | | ||
| | 1 | HMAC | | ||
| | 2 | HKDF | |
There was a problem hiding this comment.
"HMAC-SHA2-384", "HKDF-SHA2-384"?
There was a problem hiding this comment.
We might support multiple sizes for each, though, and I don't know if it is worth having values for each?
runtime/README.md
Outdated
|
|
||
| The IV is the concatenation of `block offset || size`. | ||
| This is necessary for AES-256-GCM in particular to ensure that keys are only used a certain number of times, as per [NIST SP 800-38D, Section 8.3](https://doi.org/10.6028/NIST.SP.800-38D). | ||
| Only AES-256-GCM keys need to be tracked in this table. |
There was a problem hiding this comment.
s/need to be tracked/are tracked/? (Though I'm ok if we just track everything for consistency.)
There was a problem hiding this comment.
I'll add some language to clarify that we might track others, but it is not guaranteed for now. It will depend on the implementation I think.
runtime/README.md
Outdated
| | context size | u32 | | | ||
| | context | u8[...] | | | ||
| | iv | u8[12] | | | ||
| | cipertext size | u32 | MAY be 0 | |
There was a problem hiding this comment.
MAY be 0
We would expect this to always equal the plaintext size from the input args, right? Ditto for other ciphertext/plaintext size return args below.
There was a problem hiding this comment.
Yep. I was probably thinking of the SHA cases, where you have to buffer a whole block, but this should always be equal to the plaintext size. I'll adjust this language.
| | -------------- | -------- | ------------------------------------ | | ||
| | chksum | u32 | | | ||
| | fips_status | u32 | FIPS approved or an error | | ||
| | tag verified | u32 | 1 if tags matched, 0 if they did not | |
There was a problem hiding this comment.
Seems like we should just fail the mailbox command if the tag mis-matched? Or with the tag arg are you anticipating a debugging use-case?
Risk is that someone could forget to check the tag verified field.
There was a problem hiding this comment.
I am anticipating a debug use case. I've seen cases before where something was wrong with the AAD or the tag computation but it is useful to know what the hardware / firmware thought the tag should be.
| | chksum | u32 | | | ||
| | fips_status | u32 | FIPS approved or an error | | ||
| | tag verified | u32 | 1 if tags matched, 0 if they did not | | ||
| | tag | u8[16] | Computed tag | |
There was a problem hiding this comment.
Do we need to return the tag if it was given in the init stage?
There was a problem hiding this comment.
If the tag did not match, it might be useful for debugging to know what the hardware thought the tag should be.
| @@ -1402,14 +1523,15 @@ Command Code: `0x434D_4546` ("CMEF") | |||
| | chksum | u32 | | | |||
| | context size | u32 | size of context | | |||
| | context | u8[...] | This MUST come from the output of the `CM_ECDH_GENERATE` | | |||
| | key usage | u32 | usage tag of the kind of key that will be output | | |||
There was a problem hiding this comment.
Perhaps worth noting here that the key usage must be compatible with a 384-bit key (like, we can't pass AES-256-GCM here).
runtime/README.md
Outdated
| | ---------- | -------- | --------------------------------------- | | ||
| | chksum | u32 | | | ||
| | key usage | u32 | Tag to specify how the data can be used | | ||
| | input size | u32 | | |
There was a problem hiding this comment.
Note that the input size must agree with the key usage?
Mostly.
We need to keep a limited amount of storage per AES-256-GCM key to track usage, since these keys can only be used a certain number of times due to their IV problems. We can keep track of this storage (and remove things from it) using the
CM_STATUS, etc., commands we had previously, though we will have to also keep track that we don't allow deleted CMKs to be used again.We also have some potential issues across resets, since this data is not persistent.
For HMAC, we don't specify a key usage on the output MAC, since it has to be imported back into Caliptra to be used as a key, where its usage will have to be specified.
We also fix a few other minor issues with the mailbox documentation:
Fixes #1753
Fixes #1754
Fixes #1755
Fixes #1756