PSA unified driver specification: minor updates #3542
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Clarify some sentences. There is no change in intended meaning. Fix typos. Change British spelling to American spelling. Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
Add the mention of key_derivation_output_key in the section about the key derivation entry point family. Rename "derive_key" to "key_derivation_output_key". At this point, there's no reason to deviate from the naming convention. Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
Add the rationale which I'd accidentally omitted. No intended meaning change. Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
gilles-peskine-arm
added
needs-review
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
|
|
||
| [Req.plugins] It is possible to combine multiple drivers from different providers into the same implementation, without any prior arrangement other than choosing certain names and values from disjoint namespaces. | ||
|
|
||
| [Req.compile] It is possible to compile the code of each driver and of the core separately, and link them together. A small amount of glue code may need to be compiled once the list of drivers is available. | ||
|
|
||
| [Req.types] Support drivers for the following types of hardware: accelerators that operate on keys in cleartext; cryptoprocessors that can wrap keys with a built-in keys but not store user keys; and cryptoprocessors that store key material. | ||
|
|
||
| [Req.portable] The interface between drivers and the core does not involve any platform-specific consideration. Driver calls are simple C functions. Interactions between driver code and hardware happen inside the driver (and in fact a driver need not involve any hardware at all). | ||
| [Req.portable] The interface between drivers and the core does not involve any platform-specific consideration. Driver calls are simple C function calls. Interactions between driver code and hardware happen only inside the driver (and in fact a driver need not involve any hardware at all). |
There was a problem hiding this comment.
For the beginning of the second sentence I suggested rather "Interactions with platform-specific hardware happen only ... " as "Interactions between driver code and hardware happen only inside the driver" sounds a bit strange as the driver code is part of the driver thus yes it is "inside the driver" ...
| * `"algorithms"` (optional, list of strings). Each element is an [algorithm specification](#algorithm-specifications). If specified, the core will invoke this capability of the driver only when performing one of the specified algorithms. If omitted, the core will invoke this capability for all applicable algorithms. | ||
| * `"key_types"` (optional, list of strings). Each element is a [key type specification](#key-type-specifications). If specified, the core will invoke this capability of the driver only for operations involving a key with one of the specified key types. If omitted, the core will invoke this capability of the driver for all applicable key types. | ||
| * `"key_sizes"` (optional, list of integers). If specified, the core will invoke this capability of the driver only for operations involving a key with one of the specified key sizes. If omitted, the core will invoke this capability of the driver for all applicable key sizes. Key sizes are expressed in bits. | ||
| * `"names"` (optional, object). A mapping from entry point names described by the `"functions"` property, to the name of the C function in the driver that implements the corresponding function. If a function is not listed here, name of the driver function that implements it is the driver's prefix followed by an underscore (`_`) followed by the function name. If this property is omitted, it is equivalent to an empty object (so each entry point *suffix* is implemented by a function called *prefix*`_`*suffix*). | ||
| * `"fallback"` (optional for transparent drivers, not permitted for opaque drivers, boolean). If present and true, the driver may return `PSA_ERROR_NOT_SUPPORTED`, in which case the core should call another driver or use built-in code to perform this operation. If absent or false, the core should not include built-in code to perform this particular cryptographic mechanism. See the section “[Fallback](#fallback)” for more information. | ||
| * `"fallback"` (optional for transparent drivers, not permitted for opaque drivers, boolean). If present and true, the driver may return `PSA_ERROR_NOT_SUPPORTED`, in which case the core should call another driver or use built-in code to perform this operation. If absent or false, the driver is expected to fully support the mechanisms described by this capabilit. See the section “[Fallback](#fallback)” for more information. |
Inferring entry points from algorithms is nice in that it makes capability specifications shorter and less redundant, but that's not really important. It also makes capabilities more fragile: if the core starts supporting new mechanisms based on the same algorithm (for example, adding hash-and-sign when only sign-the-hash existed before), a driver only supporting the old mechanisms would fail at build time. So make entry points mandatory. This has the benefit of making the semantics of capabilities easier to describe. Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
The existing description of the syntax of capabilities also describes the semantics of each property, but the semantics of the capability as a whole is not immediately clear. Add a subsection that explains precisely when a capability is applicable. Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
It's ok if they map to the same function names and an error otherwise. It's an error to have multiple opaque drivers for the same location. If multiple transparent drivers apply, which one applies is unspecified. Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
There is little point in leaving the order in which drivers are considered unspecified. This gives flexibility to the implementation for a process that is generally performed at build time, not in a constrained environment. Having a well-defined order is especially useful with fallback. Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
I'd intended this all along but never made it explicit. Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
danh-arm
suggested changes
Aug 13, 2020
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
danh-arm
approved these changes
Aug 20, 2020
| #### Multiple transparent drivers | ||
|
|
||
| When multiple transparent drivers implement the same mechanism, which one is called? The first one? The last one? Unspecified? Or is this an error (excluding capabilities with fallback enabled)? | ||
|
|
||
| The current choice is that the first one is used, which allows having a preference order on drivers, but may mask integration errors. |
There was a problem hiding this comment.
...but may mask integration errors.
The implementation could emit a warning to mitigate this.
|
I don't intend to squash commits: why would I? It would make it harder to understand the history, it would disrupt the link between the review and the history, and it would have no benefit. History is supposed to be useful, not pretty. |
|
This has one approval. It's only documentation, and that documentation is marked as a work in progress, so I'm going ahead and merging. Feedback on the whole document is still welcome, just open an issue or discuss on the mailing list. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
These are minor updates following @ronald-cron-arm's feedback in #3493.
These are mostly editorial changes. The semantic changes are:
"functions"JSON property to"entry_points".derive_keyentry point tokey_derivation_output_key."entry_points"property is now mandatory in capabilities.