Now that transparent drivers have an "import_key" entry point, the key
creation interfaces for transparent drivers and opaque drivers are
very similar. Unify the sections that describe their behavior,
including key validation and key size determination.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
When importing a transparent key, the key needs to be not only
validated, but also possibly converted, if it is not already in the
canonical representation. So change the validate_key entry point to an
import_key entry point.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
When importing a key, the code that parses the input needs to
determine the key size ("bits" attribute). This is specific to import
since other key creation methods require the caller to supply a size.
Therefore, add an extra output parameter `bits` to the "import_key"
entry point for opaque drivers. Likewise, add a `bits` output
parameter to the "validate_key" entry point for transparent drivers.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
With PSA crypto v1.0.0, a volatile key identifier may
contain a owner identifier but no file is associated
to it. Thus rename the type psa_key_file_id_t to
mbedtls_svc_key_id_t to avoid a direct link with a
file when a key identifier involves an owner
identifier.
The new type name is prefixed by mbedtls to highlight
that the type is specific to Mbed TLS implementation
and not defined in the PSA Cryptography API
specification.
The svc in the type name stands for service as this
is the key identifier type from the point of view of
the service providing the Cryptography services.
The service can be completely provided by the present
library or partially in case of a multi-client service.
As a consequence rename as well:
. MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER to
MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER
. PSA_KEY_ID_INIT to MBEDTLS_SVC_KEY_ID_INIT
. PSA_KEY_FILE_GET_KEY_ID to MBEDTLS_SVC_KEY_ID_GET_KEY_ID
. psa_key_file_id_make to mbedtls_svc_key_id_make
Signed-off-by: Ronald Cron <ronald.cron@arm.com>
Proposed specification for conditional inclusion of cryptographic
mechanism through the PSA API in Mbed TLS.
The inclusion of a mechanism is based on a declaration of boolean
symbols by the application. There is a symbol for each key type or
parametrized key type constructor, and for each algorithm or
parametrized algorithm constructor.
This is work in progress, presented for a first design discussion.
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>
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>
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>
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>
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>
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>
Locations aren't in the official PSA API specification yet (they've
only be made public in Mbed TLS). Until version 1.0.1 of the API
specification is out, this document needs to explain locations.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
Rather than have some functions take the in-memory copy of the
persistent data as argument, allow all of them to access the
persistent data, including modifying it.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
Opaque drivers only have a destroy function if the key is stored in
the secure element.
Expand on how key creation works. Provide more explanations of
allocate_key in drivers for secure elements with storage. Discuss key
destruction as well.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
