-
Notifications
You must be signed in to change notification settings - Fork 27
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add APIs to support wrapped keys #50
Comments
Some related internal discussions on the topic: |
An old proposal, which I don't have time to work on right now: ARMmbed/mbed-crypto#364 |
This link above are not working. They are probably to old and no more accessible for the public. |
@cneveux Indeed the |
Wrapping with a device-specific secret keyAn API proposed in Mbed-TLS/mbedtls#7910, enables the import of keys in other formats. As currently proposed, this only covers formats where the key material is in cleartext. However, if we add the equivalent This is sufficient for use cases that do not involve an application choice of algorithm or key-wrapping key. |
Wrapping using a standard algorithm and application-selected key-wrapping keyDefining an API for this use case is more challenging, as there are a lack of standards defining key-wrapping algorithms and formats for the wrapped material. However:
API proposalA simple API design could just implement the wrapping algorithm on data provided by the application. This requires that the application export the key material to the application and then encrypt it, exposing the key material within the application memory. In keeping with the design goals of the Crypto API, I would prefer to define an API that enabled the cleartext key material to be kept within a cryptoprocessor implementation, providing better assurance of the key confidentiality and integrity for application developers. Note that this improvement is a reduction in risk: the application is capable of decrypting the wrapped key as it knows the key and algorithm used to wrap it; but an attacker requires more than application-memory-read capability to disclose the key. Building on the format specifier additions for
Conceptually,
.. except that the cleartext is not visible to the application, and the format might be dictated by the wrapping algorithm. For For For both functions, the format of the key material must be compatible with the algorithm - for example, AES-KW requires cleartext that is An 'unspecified' key format, perhaps |
I now plan to progress this to a draft PR, given interest in finalizing this API for some implementors. Reviewing the proposal, I have a question about the parameter ordering for
Where the wrapping-key, wrap-algorithm, and intermediate-format-specifier are the control/operational inputs. This is the first true 2-key-input functions (compare with key agreement, which takes the peer key as a data buffer) However, this makes it look/read differently to APIs such as Is there a preference for one parameter order over the other? |
Thanks for promoting this PR! Regarding the signature: the parameter ordering of the original proposal above is consistent with the ordering in #149 for
(copied from above) |
Thank you for the feedback @oberon-sk. After some discussion with @gilles-peskine-arm, we think that we want to use the alternate ordering because (a) it treats the key-to-be-wrapped as an input parameter, and (b) it does not have two identically typed parameters next to each other which probably has a higher risk of key mis-ordering in application code. We could also tweak the function names to be a bit more like other cryptographic operations (and less like the key management functions), by using Also, following the development of the formatted key import and export functions, we probably (to be discussed) need to add export format options to key wrapping, and import policy options to key unwrapping. Might we also need the interactive policy construction described in this comment? I don't think we need to be able to wrap the public-key part of a key-pair, so we would not need a wrapping equivalent of So the updated proposed API would be something like:
|
After thinking about the issues discussed in the PR here, I'm thinking about a change of plan for this API. In the process of trying to handle less simple scenarios via small adjustments and generalizations of the proposed API, we end with a hard to use and implement API for the obvious and straight-forward use cases. UnwrappingUnwrapping is easier to consider, and perhaps a higher priority API than wrapping, to support key provisioning scenarios. The two clear use cases with well defined (standardized) behavior are:
For the first use case (1), the only key attributes that can typically be determined from the encrypted key data is the key size - assuming that the plain-text key material is formatted as per the default export format. For this kind of unwrapping API, the caller needs to provide (a) The wrapping key and algorithm used to decrypt/authenticate the key material. This API could be:
For the second use case (2), an algorithm is not required, but the following inputs are needed: This is similar to the currently proposed API, but without an algorithm specified. I propose to call this More discussion is needed to clarify the API for this use case. For some wrapped-key objects, such as OneAsymmetricKey (PrivateKeyInfo) is often wrapped into AuthEnvelopedData in CMS (pkcs#7), the inputs to the authenticated decryption are mixed with other content in the outer structure. It is not obvious how best to handle this for the API... WrappingFor wrapping, the algorithm will always need to be specified, even when using a key-wrapping format such as EncryptedPrivateKeyInfo/pkcs#12, as there are multiple permitted wrapping algorithms. However, it seems that it would be helpful to retain the separation of API for the simple 'wrap the key material in standard AE algorithm' from the 'wrap the key into a standard encrypted key format' use cases. That would lead to:
and However, although this idea can work for EncryptedPrivateKeyInfo, it is not ideal for another common structure. OneAsymmetricKey (PrivateKeyInfo) is often wrapped into AuthEnvelopedData in CMS (pkcs#7) to provide authenticated encryption of the wrapped key. AuthEnvelopedData has the ciphertext, authenticated attributes, and authentication tags in separate fields. However, the application will already have had to process the AuthEnvelopedData object to extract the corresponding RecipientrInfo field, and thus derived/decrypt the KEK to be used to decrypt the OneAsymmetricKey object. AlgorithmsFor the key-wrapping algorithms APIs, I think we need to allocate a new category for 'key-wrapping algorithms' (as done in the current PR), even though these are often forms of AEAD algorithm. This is because, on its own, an AEAD algorithm takes a nonce, and can accept additional data, and outputs the authentication tag as a separate output - for key wrapping in the above API, the algorithm is authenticated-encryption (no AD), any IV is either deterministic, or perhaps random, and all of the output is in a single buffer. Although AEAD algorithms can be used to wrap keys, this requires the additional specification of how to handle these aspects - which suggests that a distinct algorithm identifier for the key-wrapping version of the algorithm. Next stepsIf we split this API between the use cases, then I think we can proceed with the simpler Is this a better approach? |
Are we sure there are no wrapping formats using AD? Unwrap should be a separate policy to decrypt. The fact that I am sending you a blob with a policy, wrapped with a key that I trust can only unwrap into the secure state, means I expect you to honour the policy. The problem case is where the blob contains a partial policy - I think the correct answer is that the caller can always specify extra constraints, but cannot overrule what is in the blob. Is there actually a call for AES-KWP, I note that of the over 7400 CAVP certificates for AES, only 705 include AES-KWP. |
AuthEnvelopedData in CMS can use AEAD - it contains both authenticated-attributes and unauthenticated-attributes fields. But that is a wrapped-key format (use case (2)), not a key-wrapping algorithm. I think as soon as the wrapping algorithm needs to include formatted content that separates key material (that requires encryption and authentication) from key attributes (that only require authentication), this is not a use case (1) scenario. If we extend the API to accept a key id (for encryption of key material) and a buffer of authenticated data, then there is the issue of how that extra data is formatted, and the API no longer binds the data to the key attributes within the key store. To achieve that [important] binding, the encoding the of the authenticated data has to be done within the keystore - which lead back to the
If the key-wrapping key was not imported, is not exportable, and only permits USAGE_UNWRAP; then the caller cannot reproduce the decryption procedure for the encrypted-key blob - and so cannot extract and then import the key material with a different policy. So we should probably deny policy override - or at least permit an implementation to deny it.
Indeed.
I think there are implementations that are using or wanting to make use of AES-KW/KWP. |
We support this approach to splitting off the simple use case and handle further uses cases in a later update/PR. |
Many secure elements and crypto accelerators require the use of wrapped keys and will not accept importing clear-text keys to their key store. The existing
psa_import_key
function could be augmented to support wrapped keys, but that puts the burden of identifying wrapping and associated parameters on the underlying implementation. A new function should be proposed to support wrapped key imports.As there is no standard for key wrapping data formats and associated algorithms, this should be made generic enough to be adaptable to any such key stores.
Same need for exporting wrapped keys.
The text was updated successfully, but these errors were encountered: