The methods to import and generate a key in a secure element drivers
were written for an earlier version of the application-side interface.
Now that there is a psa_key_attributes_t structure that combines all
key metadata including its lifetime (location), type, size, policy and
extra type-specific data (domain parameters), pass that to drivers
instead of separate arguments for each piece of metadata. This makes
the interface less cluttered.
Update parameter names and descriptions to follow general conventions.
Document the public-key output on key generation more precisely.
Explain that it is optional in a driver, and when a driver would
implement it. Declare that it is optional in the core, too (which
means that a crypto core might not support drivers for secure elements
that do need this feature).
Update the implementation and the tests accordingly.
Register an existing key in a secure element.
Minimal implementation that doesn't call any driver method and just
lets the application declare whatever it wants.
Pass the key creation method (import/generate/derive/copy) to the
driver methods to allocate or validate a slot number. This allows
drivers to enforce policies such as "this key slot can only be used
for keys generated inside the secure element".
Test the behavior of the getter/setter functions.
Test that psa_get_key_slot_number() reports a slot number for a key in
a secure element, and doesn't report a slot number for a key that is
not in a secure element.
Test that psa_get_key_slot_number() reports the correct slot number
for a key in a secure element.
Add a slot_number field to psa_key_attributes_t and getter/setter
functions. Since slot numbers can have the value 0, indicate the
presence of the field via a separate flag.
In psa_get_key_attributes(), report the slot number if the key is in a
secure element.
When creating a key, for now, applications cannot choose a slot
number. A subsequent commit will add this capability in the secure
element HAL.
Add infrastructure for internal, external and dual-use flags, with a
compile-time check (if static_assert is available) to ensure that the
same numerical value doesn't get declared for two different purposes
in crypto_struct.h (external or dual-use) and
psa_crypto_core.h (internal).
Conflict resolution:
* `scripts/config.pl`:
Take the exclusion of `MBEDTLS_PSA_CRYPTO_SE_C` from the API branch.
Take the removal of `MBEDTLS_PSA_CRYPTO_STORAGE_ITS_C` (obsolete) from
the development branch.
* `tests/scripts/all.sh`:
Multiple instances of factoring a sequence of `config.pl` calls into
a mere `config.pl baremetal` in the development branch, and a change in
the composition of `baremetal` in the API branch. In each case, take the
version from development.
* `tests/suites/test_suite_psa_crypto_slot_management.function`:
A function became non-static in development and disappeared in the API
branch. Keep the version from the API branch. Functions need to be
non-static if they're defined but unused in some configurations,
which is not the case for any function in this file at the moment.
* `tests/suites/test_suite_psa_crypto.function`:
Consecutive changes in the two branches, reconciled.
65528 bits is more than any reasonable key until we start supporting
post-quantum cryptography.
This limit is chosen to allow bit-sizes to be stored in 16 bits, with
65535 left to indicate an invalid value. It's a whole number of bytes,
which facilitates some calculations, in particular allowing a key of
exactly PSA_CRYPTO_MAX_STORAGE_SIZE to be created but not one bit
more.
As a resource usage limit, this is arguably too large, but that's out
of scope of the current commit.
Test that key import, generation and derivation reject overly large
sizes.
Move the "core attributes" to a substructure of psa_key_attribute_t.
The motivation is to be able to use the new structure
psa_core_key_attributes_t internally.
Add a parameter to the key import method of a secure element driver to
make it report the key size in bits. This is necessary (otherwise the
core has no idea what the bit-size is), and making import report it is
easier than adding a separate method (for other key creation methods,
this information is an input, not an output).
Most driver methods are not allowed to modify the persistent data, so
the driver context structure contains a const pointer to it. Pass a
non-const pointer to the persstent data to the driver methods that
need it: init, allocate, destroy.
Pass the driver context to all driver methods except the ones that
operate on an already-setup operation context.
Rename `p_context` arguments to `op_context` to avoid confusion
between contexts.
This slightly increases storage requirements, but works in more use
cases. In particular, it allows drivers to treat choose slot numbers
with a monotonic counter that is incremented each time a key is
created, without worrying about overflow in practice.
Instead of having one giant table containing all possible methods,
represent a driver's method table as a structure containing pointers
to substructures. This way a driver that doesn't implement a certain
class of operations can use NULL for this class as a whole instead of
storing NULL for each method.
Technically we could have reused the old one for the new API, but then
we had to set an extra field during setup. The new version works when
all the fields that haven't been set explicitely are zero-initialised.
This change affects the psa_key_derivation_s structure. With the buffer
removed from the union, it is empty if MBEDTLS_MD_C is not defined.
We can avoid undefined behaviour by adding a new dummy field that is
always present or make the whole union conditional on MBEDTLS_MD_C.
In this latter case the initialiser macro has to depend on MBEDTLS_MD_C
as well. Furthermore the first structure would be either
psa_hkdf_key_derivation_t or psa_tls12_prf_key_derivation_t both of
which are very deep and would make the initialisation macro difficult
to maintain, therefore we go with the first option.
We want to make the PRF context structure depend on this flag, but
crypto_extra.h is included after crypto_struct.h and having the
option at its original place would not affect crypto_struct.h.
Add the compile time option PSA_PRE_1_0_KEY_DERIVATION. If this is not
turned on, then the function `psa_key_derivation()` is removed.
Most of the tests regarding key derivation haven't been adapted to the
new API yet and some of them have only been adapted partially. When this
new option is turned off, the tests using the old API and test cases
using the old API of partially adapted tests are skipped.
The sole purpose of this option is to make the transition to the new API
smoother. Once the transition is complete it can and should be removed
along with the old API and its implementation.
From the implementation point of view does not make much difference to
constrain the input order.
We constrain it because, this way the code is easier to review, the data
flow easier to understand and the implementations in general are easier
to validate.
Relative include paths should be avoided. The build system will
determine where to pull in includes from. Specifically, `#include
"../mbedtls/config.h"` shouldn't be used. Use `#include
"mbedtls/config.h` instead, so that the submodule-building makefiles can
change which directory to use to get mbedtls include files from.
Fixes#141
Remove the key creation functions from before the attribute-based API,
i.e. the key creation functions that worked by allocating a slot, then
setting metadata through the handle and finally creating key material.
Don't use "safe buffer size", because this it's somewhat misleading to
make it about safety: a buffer size that's too small will lead to a
runtime error, not to undefined behavior.
Convert the description of PSA_ALG_TLS12_PRF and
PSA_ALG_TLS12_PSK_TO_MS to the key derivation API that takes one input
at a time rather than the old {secret,salt,label} interface.
Define a new input category "seed".
PSA_KEY_ATTRIBUTES_INIT and psa_key_attributes_init weren't declared
in the API document, only defined in our implementation, but they are
referenced in the API document.
generate_key is a more classical name. The longer name was only
introduced to avoid confusion with getting a key from a generator,
which is key derivation, but we no longer use the generator
terminology so this reason no longer applies.
perl -i -pe 's/psa_generate_random_key/psa_generate_key/g' $(git ls-files)
“Tampering detected” was misleading because in the real world it can
also arise due to a software bug. “Corruption detected” is neutral and
more precisely reflects what can trigger the error.
perl -i -pe 's/PSA_ERROR_TAMPERING_DETECTED/PSA_ERROR_CORRUPTION_DETECTED/gi' $(git ls-files)
Move DSA-related key types and algorithms to the
implementation-specific header file. Not that we actually implement
DSA, but with domain parameters, we should be able to.
Parametrize finite-field Diffie-Hellman key types with a DH group
identifier, in the same way elliptic curve keys are parametrized with
an EC curve identifier.
Define the DH groups from the TLS registry (these are the groups from
RFC 7919).
Replicate the macro definitions and the metadata tests from elliptic
curve identifiers to DH group identifiers.
Define PSA_DH_GROUP_CUSTOM as an implementation-specific extension for
which domain parameters are used to specify the group.
Move psa_get_key_domain_parameters() and
psa_set_key_domain_parameters() out of the official API and declare
them to be implementation-specific extensions.
Expand the documentation of psa_set_key_domain_parameters() a bit to
explain how domain parameters are used.
Remove all mentions of domain parameters from the documentation of API
functions. This leaves DH and DSA effectively unusable.
Generators are mostly about key derivation (currently: only about key
derivation). "Generator" is not a commonly used term in cryptography.
So favor "derivation" as terminology.
This commit updates the function descriptions.
Generators are mostly about key derivation (currently: only about key
derivation). "Generator" is not a commonly used term in cryptography.
So favor "derivation" as terminology. Call a generator a key
derivation operation structure, since it behaves like other multipart
operation structures. Furthermore, the function names are not fully
consistent.
In this commit, I rename the functions to consistently have the prefix
"psa_key_derivation_". I used the following command:
perl -i -pe '%t = (
psa_crypto_generator_t => "psa_key_derivation_operation_t",
psa_crypto_generator_init => "psa_key_derivation_init",
psa_key_derivation_setup => "psa_key_derivation_setup",
psa_key_derivation_input_key => "psa_key_derivation_input_key",
psa_key_derivation_input_bytes => "psa_key_derivation_input_bytes",
psa_key_agreement => "psa_key_derivation_key_agreement",
psa_set_generator_capacity => "psa_key_derivation_set_capacity",
psa_get_generator_capacity => "psa_key_derivation_get_capacity",
psa_generator_read => "psa_key_derivation_output_bytes",
psa_generate_derived_key => "psa_key_derivation_output_key",
psa_generator_abort => "psa_key_derivation_abort",
PSA_CRYPTO_GENERATOR_INIT => "PSA_KEY_DERIVATION_OPERATION_INIT",
PSA_GENERATOR_UNBRIDLED_CAPACITY => "PSA_KEY_DERIVATION_UNLIMITED_CAPACITY",
); s/\b(@{[join("|", keys %t)]})\b/$t{$1}/ge' $(git ls-files)
In psa_import_key, change the order of parameters to pass
the pointer where the newly created handle will be stored last.
This is consistent with most other library functions that put inputs
before outputs.
In psa_generate_derived_key, change the order of parameters to pass
the pointer where the newly created handle will be stored last.
This is consistent with most other library functions that put inputs
before outputs.
Use individual setters for the id and lifetime fields of an attribute
structure, like the other attributes.
This commit updates the specification and adds an implementation of
the new setters.
Define a range of key identifiers for use by the application
(0..2^30-1), a range for use by implementations (2^30..2^31), and a
range that is reserved for future use (2^31..2^32-1).
Change the scope of key identifiers to be global, rather than
per lifetime. As a result, you now need to specify the lifetime of a
key only when creating it.
Declare algorithms for ChaCha20 and ChaCha20-Poly1305, and a
corresponding (common) key type.
Don't declare Poly1305 as a separate algorithm because it's a one-time
authenticator, not a MAC, so the API isn't suitable for it (no way to
use a nonce).
New macros PSA_AEAD_UPDATE_OUTPUT_SIZE, PSA_AEAD_FINISH_OUTPUT_SIZE
and PSA_AEAD_VERIFY_OUTPUT_SIZE to determine the output buffer sizes
for psa_aead_update(), psa_aead_finish() and psa_aead_verify().
Like psa_aead_finish(), psa_aead_verify() needs to produce output from
the last partial block of input if psa_aead_update() cannot produce
output byte by byte.
In psa_import_key and psa_copy_key, some information comes from the
key data (input buffer or source key) rather than from the attributes:
key size for import, key size and type and domain parameters for copy.
If an unused attribute is nonzero in the attribute structure, check
that it matches the correct value. This protects against application
errors.
There was a guarantee that psa_get_key_attributes() does not require a
subsequent psa_reset_key_attributes() to free resources as long as the
key was created with attributes having this property. This requirement
was hard to pin down because if a key is created with default
parameters, there are cases where it is difficult to ensure that the
domain parameters will be reported without allocating memory. So
remove this guarantee. Now the only case psa_reset_key_attributes() is
not required is if the attribute structure has only been modified with
certain specific setters.
Read extra data from the domain parameters in the attribute structure
instead of taking an argument on the function call.
Implement this for RSA key generation, where the public exponent can
be set as a domain parameter.
Add tests that generate RSA keys with various public exponents.
Change psa_get_domain_parameters() and psa_set_domain_parameters() to
access a psa_key_attributes_t structure rather than a key handle.
In psa_get_key_attributes(), treat the RSA public exponent as a domain
parameter and read it out. This is in preparation for removing the
`extra` parameter of psa_generate_key() and setting the RSA public
exponent for key generation via domain parameters.
In this commit, the default public exponent 65537 is not treated
specially, which allows us to verify that test code that should be
calling psa_reset_key_attributes() after retrieving the attributes of
an RSA key is doing so properly (if it wasn't, there would be a memory
leak), even if the test data happens to use an RSA key with the
default public exponent.
Instead of passing a separate parameter for the key size to
psa_generate_key and psa_generator_import_key, set it through the
attributes, like the key type and other metadata.
Types and functions that are not used in the attribute-based key
creation API are now implementation-specific extensions, kept around
until we finish transitioning to the new API.
Implement attribute querying.
Test attribute getters and setters. Use psa_get_key_attributes instead
of the deprecated functions psa_get_key_policy or
psa_get_key_information in most tests.
Implement the new, attribute-based psa_import_key and some basic
functions to access psa_key_attributes_t. Replace
psa_import_key_to_handle by psa_import_key in a few test functions.
This commit does not handle persistence attributes yet.
This commit starts a migration to a new interface for key creation.
Today, the application allocates a handle, then fills its metadata,
and finally injects key material. The new interface fills metadata
into a temporary structure, and a handle is allocated at the same time
it gets filled with both metadata and key material.
This commit was obtained by moving the declaration of the old-style
functions to crypto_extra.h and renaming them with the to_handle
suffix, adding declarations for the new-style functions in crypto.h
under their new name, and running
perl -i -pe 's/\bpsa_(import|copy|generator_import|generate)_key\b/$&_to_handle/g' library/*.c tests/suites/*.function programs/psa/*.c
perl -i -pe 's/\bpsa_get_key_lifetime\b/$&_from_handle/g' library/*.c tests/suites/*.function programs/psa/*.c
Many functions that are specific to the old interface, and which will
not remain under the same name with the new interface, are still in
crypto.h for now.
All functional tests should still pass. The documentation may have
some broken links.
This gives a little more room to encode key agreement algorithms,
while keeping enough space for key derivation algorithms.
This doesn't affect any of the already-defined algorithms.
Merge the Mbed Crypto development branch a little after
mbedcrypto-1.0.0 into the PSA Crypto API 1.0 beta branch a little
after beta 2.
Summary of merge conflicts:
* Some features (psa_copy_key, public key format without
SubjectPublicKeyInfo wrapping) went into both sides, but with a few
improvements on the implementation side. For those, take the
implementation side.
* The key derivation API changed considerably on the API side. This
merge commit generally goes with the updated API except in the tests
where it keeps some aspects of the implementation.
Due to the divergence between the two branches on key derivation and
key agreement, test_suite_psa_crypto does not compile. This will be
resolved in subsequent commits.
MBEDTLS_PSA_HAS_ITS_IO is not really useful since it doesn't actually
enable anything except the entropy seed file support, which only
requires the ITS interface and not a native implemetation. Remove it.
For DH, ECC (Weierstrass curves) and DSA, specify that the re-drawing
method is the one defined by NIST as
"key-pair generation by testing candidates", and describe it
unambiguously.
Also specify DES explicitly.
psa_generator_import_key() was only specified for "symmetric keys",
and there were some mistakes in the specification. Rewrite the
specification and extend it to other key types.
* For most private key types, specify that the function draws a byte
string repeatedly until the byte string is suitable.
* For DES, despite being a symmetric key type, re-drawing is
necessary.
* For Montgomery curves, despite being asymmetric, no re-drawing is
necessary.
* Specify the behavior for every standard key type other than RSA.
An implementation doesn't have to support all key types, but if it
does, it's better to have a standard.
crypto_extra.h has a dependency on platform_util.h for
MBEDTLS_DEPRECATED_NUMERIC_CONSTANT. Make the dependency explicit by
including platform_util.h. Although in most use cases the header should
already be included by something else, it doesn't hurt to include it
again and helps to clarify dependencies.
When building for the PSA crypto service (defined(PSA_CRYPTO_SECURE)),
define psa_key_owner_id_t as int32_t, which is how a PSA platform
encodes partition identity. Note that this only takes effect when the
build option MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER is active.
Support this configuration in the ITS backend.
Declare the owner as psa_key_owner_id_t, of which an implementation
must be provided separately.
Make this a configuration option
MBEDTLS_PSA_CRYPTO_KEY_FILE_ID_ENCODES_OWNER, to make the conditional
compilation flow easier to follow. Declare it in config.h to
pacify check_names.sh.
Support for a specific implementation of psa_key_owner_id_t in storage
backends will come in a subsequent commit.
Differentiate between _key identifiers_, which are always `uint32_t`,
and _key file identifiers_, which are platform-dependent. Normally,
the two are the same.
In `psa/crypto_platform.h`, define `psa_app_key_id_t` (which is always
32 bits, the standard key identifier type) and
`psa_key_file_id_t` (which will be different in some service builds).
A subsequent commit will introduce a platform where the two are different.
It would make sense for the function declarations in `psa/crypto.h` to
use `psa_key_file_id_t`. However this file is currently part of the
PSA Crypto API specification, so it must stick to the standard type
`psa_key_id_t`. Hence, as long as the specification and Mbed Crypto
are not separate, use the implementation-specific file
`psa/crypto_platform.h` to define `psa_key_id_t` as `psa_key_file_id_t`.
In the library, systematically use `psa_key_file_id_t`.
perl -i -pe 's/psa_key_id_t/psa_key_file_id_t/g' library/*.[hc]
PSA spec now defines more generic PSA storage types instead of the ITS
specific ones. This is necessary in order to integrate with
the newer implementation of PSA ITS landing in Mbed OS soon.
Changes include the following:
- psa_status_t replaces psa_its_status_t
- psa_storage_info_t replaces psa_its_info_t
- psa_storage_uid_t replaces psa_its_uid_t
The macro PSA_HASH_FINAL_SIZE no longer exists and all instances of it
should be replaced by PSA_HASH_SIZE. Replace all remaining instances of
PSA_HASH_FINAL_SIZE with PSA_HASH_SIZE.
Remove front matter from our EC key format, to make it just the contents
of an ECPoint as defined by SEC1 section 2.3.3.
As a consequence of the simplification, remove the restriction on not
being able to use an ECDH key with ECDSA. There is no longer any OID
specified when importing a key, so we can't reject importing of an ECDH
key for the purpose of ECDSA based on the OID.
Remove pkcs-1 and rsaEncryption front matter from RSA public keys. Move
code that was shared between RSA and other key types (like EC keys) to
be used only with non-RSA keys.
New function psa_copy_key().
Conflicts:
* library/psa_crypto.c: trivial conflicts due to consecutive changes.
* tests/suites/test_suite_psa_crypto.data: the same code
was added on both sides, but with a conflict resolution on one side.
* tests/suites/test_suite_psa_crypto_metadata.function: the same code
was added on both sides, but with a conflict resolution on one side.
You can use PSA_ALG_ANY_HASH to build the algorithm value for a
hash-and-sign algorithm in a policy. Then the policy allows usage with
this hash-and-sign family with any hash.
Test that PSA_ALG_ANY_HASH-based policies allow a specific hash, but
not a different hash-and-sign family. Test that PSA_ALG_ANY_HASH is
not valid for operations, only in policies.
Test for a subclass of public-key algorithm: those that perform
full-domain hashing, i.e. algorithms that can be broken down as
sign(key, hash(message)).
Remove the type and bits arguments to psa_allocate_key() and
psa_create_key(). They can be useful if the implementation wants to
know exactly how much space to allocate for the slot, but many
implementations (including ours) don't care, and it's possible to work
around their lack by deferring size-dependent actions to the time when
the key material is created. They are a burden to applications and
make the API more complex, and the benefits aren't worth it.
Change the API and adapt the implementation, the units test and the
sample code accordingly.
Change the key derivation API to take inputs in multiple steps,
instead of a single one-site-fits-poorly function.
Conflicts:
* include/psa/crypto.h: merge independent changes in the documentation
of psa_key_agreement (public_key from the work on public key formats
vs general description and other parameters in the work on key derivation).
* tests/suites/test_suite_psa_crypto.data: update the key agreement
tests from the work on key derivation to the format from the work on
public key formats.
* tests/suites/test_suite_psa_crypto_metadata.function: reconcile the
addition of unrelated ALG_IS_xxx macros
Get rid of "key selection" algorithms (of which there was only one:
raw key selection).
Encode key agreement by combining a raw key agreement with a KDF,
rather than passing the KDF as an argument of a key agreement macro.
The normal way is to pass the shared secret to a key derivation.
Having an ad hoc function will allow us to simplify the possible
behaviors of key agreement and get rid of "key selection" algorithms
which are a hard-to-understand invention of this API.
It isn't a good fit. It's overly complex for what the API can do now,
which is Diffie-Hellman. Consider it again later for more complex use
cases such as authenticated key exchanges.
Use separate step types for a KDF secret and for the private key in a
key agreement.
Determine which key type is allowed from the step type, independently
of the KDF.
Forbid raw inputs for certain steps. They definitely should be
forbidden for asymmetric keys, which are structured. Also forbid them
for KDF secrets: the secrets are supposed to be keys, even if they're
unstructured.
Add the ability to specify Diffie-Hellman key exchange keys. Specify the
import/export format as well, even though importing and exporting isn't
implemented yet.
Remove front matter and DSS parameters from our DSA key formats, both
keypair and public key, to make it just a representation of the integer
private key, `x`, or the public key, `y`, respectively.
DSA and static DH need extra domain parameters. Instead of passing these
in with the keys themselves, add get and set functions to set and
retrieve this information about keys.
Remove front matter from our EC key format, to make it just the contents
of an ECPoint as defined by SEC1 section 2.3.3.
As a consequence of the simplification, remove the restriction on not
being able to use an ECDH key with ECDSA. There is no longer any OID
specified when importing a key, so we can't reject importing of an ECDH
key for the purpose of ECDSA based on the OID.
You can use PSA_ALG_ANY_HASH to build the algorithm value for a
hash-and-sign algorithm in a policy. Then the policy allows usage with
this hash-and-sign family with any hash.
Test that PSA_ALG_ANY_HASH-based policies allow a specific hash, but
not a different hash-and-sign family. Test that PSA_ALG_ANY_HASH is
not valid for operations, only in policies.
Finish changing "start" to "set up".
Correct the way to set an IV for decryption: it's set_iv(), not
update().
When decrypting, the IV is given, not random.
Test for a subclass of public-key algorithm: those that perform
full-domain hashing, i.e. algorithms that can be broken down as
sign(key, hash(message)).
Remove pkcs-1 and rsaEncryption front matter from RSA public keys. Move
code that was shared between RSA and other key types (like EC keys) to
be used only with non-RSA keys.
Copy the nice and clear documentation from psa_export_key() as to what
implementations are allowed to do regarding key export formats, as the
same applies to public keys.
hash_setup and mac_setup used to be called hash_start and mac_start,
but we've now converged on _setup as names. Finish making the
terminology in the documentation consistent.
We've added documentation for how context objects for multi-part
operations must be initialized consistently for key policy, hash,
cipher, and MAC. Update the generator documentation to be consistent
with how we've documented the other operations.
Add new initializers for cipher operation objects and use them in our
tests and library code. Prefer using the macro initializers due to their
straightforwardness.
The struct psa_cipher_operation_s is built with a
mbedtls_cipher_context_t. The shape of mbedtls_cipher_context_t and an
initializer that works with Clang 5.0 and its
-Wmissing-field-initializers varies based on the configuration of the
library. Instead of making multiple initializers based on a maze of
ifdefs for all combinations of MBEDTLS_CIPHER_MODE_WITH_PADDING,
MBEDTLS_CMAC_C, and MBEDTLS_USE_PSA_CRYPTO, add a dummy variable to
psa_cipher_operation_s's union that encloses mbedtls_cipher_context_t.
This allows us to initialize the dummy with a Clang-approved initializer
and have it properly initialize the entire object.
Add new initializers for MAC operation objects and use them in our tests
and library code. Prefer using the macro initializers due to their
straightforwardness.
Add new initializers for hash operation objects and use them in our
tests and library code. Prefer using the macro initializers due to their
straightforwardness.
Add new initializers for key policies and use them in our docs, example
programs, tests, and library code. Prefer using the macro initializers
due to their straightforwardness.
Split crypto_driver.h into 4:
* crypto_driver_common.h for common definitions, not meant to be
included directly by driver code.
* crypto_accel_driver.h for drivers that work with transparent
key material.
* crypto_se_driver.h for drivers that work with opaque key
material.
* crypto_entropy_driver.h for drivers of entropy sources.
There is no code change in this commit, I only moved some code around.
Now that the type definitions that are useful for driver are in a
separate header file from the application interface function
declarations, include that header file in crypto_driver.h.
Some parts of the library, and crypto drivers, need to see key types,
algorithms, policies, etc. but not API functions. Move portable
integral types and macros to build and analyze values of these types
to a separate headers crypto_types.h and crypto_values.h.
No functional changes, code was only moved from crypto.h to the new headers.
Define psa_status_t to int32_t unconditionally. There's no reason to
refer to psa_error_t here: psa_error_t is int32_t if it's present. We
would only need a conditional definition if psa_defs.h and
psa_crypto.h used the same type name.
Keep the conditional definition of PSA_SUCCESS. Although the C
preprocessor allows a duplicate definition for a macro, it has to be
the exact same token sequence, not merely an equivalent way to build
the same value.
Some of the documentation is obsolete in its reference to key slots
when it should discuss key handles. This may require a further pass,
possibly with some reorganization of error codes.
Update the documentation of functions that modify key slots (key
material creation and psa_set_key_policy()) to discuss how they affect
storage.
This commit marks the beginning of the removal of support for direct
access to key slots. From this commit on, programs that use
psa_key_slot_t will no longer compile.
Subsequent commits will remove the now-unused legacy support in
psa_crypto.c.
Replace `psa_key_slot_t key` by `psa_key_handle_t` in function
declarations.
This is a transition period during which handles are key slot numbers
and the whole library can still be used by accessing a key slot number
without allocating a handle.
Allow use of persistent keys, including configuring them, importing and
exporting them, and destroying them.
When getting a slot using psa_get_key_slot, there are 3 scenarios that
can occur if the keys lifetime is persistent:
1. Key type is PSA_KEY_TYPE_NONE, no persistent storage entry:
- The key slot is treated as a standard empty key slot
2. Key type is PSA_KEY_TYPE_NONE, persistent storage entry exists:
- Attempt to load the key from persistent storage
3. Key type is not PSA_KEY_TYPE_NONE:
- As checking persistent storage on every use of the key could
be expensive, the persistent key is assumed to be saved in
persistent storage, the in-memory key is continued to be used.
Add missing checks for defined(MBEDTLS_MD_C) around types and
functions that require it (HMAC, HKDF, TLS12_PRF).
Add missing checks for defined(MBEDTLS_ECDSA_DETERMINISTIC) around
code that calls mbedtls_ecdsa_sign_det().
Add missing checks for defined(MBEDTLS_ECDH_C) around ECDH-specific
functions.
This commit adds KDF algorithm identifiers `PSA_ALG_TLS12_PRF(HASH)`
to the PSA crypto API. They represent the key derivation functions
used by TLS 1.2 for the PreMasterSecret->MasterSecret and
MasterSecret->KeyBlock conversions.
Use m for the bit size of the field order, not q which is
traditionally the field order.
Correct and clarify the private key representation format as has been
done for the private key and ECDH shared secret formats.
The endianness actually depends on the curve type.
Correct the terminology around "curve size" and "order of the curve".
I tried to find a formulation that is comprehensible to programmers
who do not know the underlying mathematics, but nonetheless correct
and precise.
Use similar terminology in other places that were using "order of the
curve" to describe the bit size associated with the curve.
psa_key_derivation requires the caller to specify a maximum capacity.
This commit adds a special value that indicates that the maximum
capacity should be the maximum supported by the algorithm. This is
currently meant only for selection algorithms used on the shared
secret produced by a key agreement.
A key selection algorithm is similar to a key derivation algorithm in
that it takes a secret input and produces a secret output stream.
However, unlike key derivation algorithms, there is no expectation
that the input cannot be reconstructed from the output. Key selection
algorithms are exclusively meant to be used on the output of a key
agreement algorithm to select chunks of the shared secret.
Change the import/export format of private elliptic curve keys from
RFC 5915 to the raw secret value. This commit updates the format
specification and the import code, but not the export code.
Add extern "C" wrappers around type and function declarations to enable C++
interoperability of the driver header. This is done so that the driver
functions and types can be used or implmented by C++ code.
Convert PSA Crypto driver model structs to typedefs so that the `struct`
name doesn't need to be used and for consistent style with other PSA
structures.
The file crypto_driver.h was not using the header guard style as other PSA
Crypto header files. Remove the `__` prefix and suffix. Use C-style
comments for the end-of-guard comment.
The driver model's "encrypt or decrypt" type, encrypt_or_decrypt_t, is
publicly exposed and needs to have a `psa_` prefix in order to properly
communicate that it is part of the PSA driver model.
The `pcd_` prefix is ambiguous and does not make it clear that the types
and symbols are standardized by PSA. Replace `pcd_` with a prefix that can
be shared with all PSA drivers, `psa_drv_`.
"Driver APIs" can be interpreted to mean APIs used when you want to write a
driver, not the set of functions you implement to make a driver. See
https://www.kernel.org/doc/html/latest/driver-api/index.html "The kernel
offers a wide variety of interfaces to support the development of device
drivers."
As such, we are renaming "Driver API" to "Driver Model" and updating our
work so far to reflect this change.
Add comments noting that the maximum length of a MAC must fit in
PSA_ALG_MAC_TRUNCATION_MASK. Add a unit test that verifies that the
maximum MAC size fits.
None of the currently defined MAC algorithms have a MAC size that
depends on the key size, so the key_bits parameter is unused. The
key_type parameter may be unused on an implementation where there is
no block cipher MAC. Declare the key_type and key_bits parameters as
used so that callers who define a variable just for this don't risk
getting "unused variable" warnings.
The macro was used under the name PSA_ALG_IS_BLOCK_CIPHER_MAC but
defined as PSA_ALG_IS_CIPHER_MAC. That wouldn't have worked if we used
this macro (we currently don't but it may become useful).
TLS now defines named curves in the "TLS Supported Groups registry",
but we're using the encoding only for elliptic curves, so don't
include values that aren't named curve.
While we're at it, upgrade the reference to the shiny new RFC 8422.
OFB and CFB are streaming modes. XTS is a not a cipher mode but it
doesn't use a separate padding step. This leaves only CBC as a block
cipher mode that needs a padding step.
Since CBC is the only mode that uses a separate padding step, and is
likely to remain the only mode in the future, encode the padding mode
directly in the algorithm constant, rather than building up an
algorithm value from a chaining mode and a padding mode. This greatly
simplifies the interface as well as some parts of the implementation.
There were only 5 categories (now 4). Reduce the category mask from 7
bits to 3.
Combine unformatted, not-necessarily-uniform keys (HMAC, derivation)
with raw data.
Reintroduce a KEY_TYPE_IS_UNSTRUCTURED macro (which used to exist
under the name KEY_TYPE_IS_RAW_DATA macro) for key types that don't
have any structure, including both should-be-uniform keys (such as
block cipher and stream cipher keys) and not-necessarily-uniform
keys (such as HMAC keys and secrets for key derivation).
These structs are using bitfields of length one, which can only represent 0 and -1 for signed ints.
Changing these to unsigned int lets them represent 0 and 1, which is what we want.
MBEDTLS_PK_WRITE_C only requires either MBEDTLS_RSA_C or MBEDTLS_ECP_C to be defined.
Added wrappers to handle the cases where only one has been defined.
Moved mbedtls_pk_init to be within the ifdefs, so it's only called if appropriate.
* Broken link #PSA_ALG_SHA_256
* Duplicate group name "generators"
* Missing documentation in psa_generate_key_extra_rsa due to bad magic
comment marker
New key type PSA_KEY_TYPE_DERIVE. New usage flag PSA_KEY_USAGE_DERIVE.
New function psa_key_derivation.
No key derivation algorithm is implemented yet. The code may not
compile with -Wunused.
Write some unit test code for psa_key_derivation. Most of it cannot be
used yet due to the lack of a key derivation algorithm.
Add an API for byte generators: psa_crypto_generator_t,
PSA_CRYPTO_GENERATOR_INIT, psa_crypto_generator_init,
psa_get_generator_capacity, psa_generator_read,
psa_generator_import_key, psa_generator_abort.
This commit does not yet implement any generator algorithm, it only
provides the framework. This code may not compile with -Wunused.
This is the most common mode and the only mode that Mbed TLS functions
fully supports (mbedtls_rsa_rsassa_pss_verify_ext can verify
signatures with a different salt length).
Explicitly state that calling abort is safe after initializing to
zero.
Explicitly state that calling abort on an inactive operation is safe,
and replace "active" by "initialized" in the description of the
parameter.
Get rid of the recommendation for implementers to try to handle
uninitialized structures safely. It's good advice in principle but
cannot be achieved in a robust way and the wording was confusing.
No common signature algorithm uses a salt (RSA-PKCS#1v1.5, RSA-PSS,
DSA, ECDSA, EdDSA). We don't even take an IV for MAC whereas MAC
algorithms with IV are uncommon but heard of. So remove the salt
parameter from psa_asymmetric_sign and psa_asymmetric_verify.
Make function names for multipart operations more consistent (cipher
edition).
Rename symmetric cipher multipart operation functions so that they all
start with psa_cipher_:
* psa_encrypt_setup -> psa_cipher_encrypt_setup
* psa_decrypt_setup -> psa_cipher_decrypt_setup
* psa_encrypt_set_iv -> psa_cipher_set_iv
* psa_encrypt_generate_iv -> psa_cipher_generate_iv
Make function names for multipart operations more consistent (MAC
setup edition).
Split psa_mac_setup into two functions psa_mac_sign_setup and
psa_mac_verify_setup. These functions behave identically except that
they require different usage flags on the key. The goal of the split
is to enforce the key policy during setup rather than at the end of
the operation (which was a bit of a hack).
In psa_mac_sign_finish and psa_mac_verify_finish, if the operation is
of the wrong type, abort the operation before returning BAD_STATE.
This requires defining a maximum RSA key size, since the RSA key size
is the signature size. Enforce the maximum RSA key size when importing
or generating a key.
Macros such as PSA_HASH_SIZE whose definitions can be the same
everywhere except in implementations that support non-standard
algorithms remain in crypto.h, at least for the time being.
This header will contain macros that calculate buffer sizes, whose
semantics are standardized but whose definitions are
implementation-specific because they depend on the available algorithms
and on some permitted buffer size tolerances.
Move size macros from crypto_struct.h to crypto_sizes.h, because these
definitions need to be available both in the frontend and in the
backend, whereas structures have different contents.
Change the representation of an ECDSA signature from the ASN.1 DER
encoding used in TLS and X.509, to the concatenation of r and s
in big-endian order with a fixed size. A fixed size helps memory and
buffer management and this representation is generally easier to use
for anything that doesn't require the ASN.1 representation. This is
the same representation as PKCS#11 (Cryptoki) except that PKCS#11
allows r and s to be truncated (both to the same length), which
complicates the implementation and negates the advantage of a
fixed-size representation.
* Distinguish randomized ECDSA from deterministic ECDSA.
* Deterministic ECDSA needs to be parametrized by a hash.
* Randomized ECDSA only uses the hash for the initial hash step,
but add ECDSA(hash) algorithms anyway so that all the signature
algorithms encode the initial hashing step.
* Add brief documentation for the ECDSA signature mechanisms.
* Also define DSA signature mechanisms while I'm at it. There were
already key types for DSA.
* PSS needs to be parametrized by a hash.
* Don't use `_MGF1` in the names of macros for OAEP and PSS. No one
ever uses anything else.
* Add brief documentation for the RSA signature mechanisms.
Doxygen interprets `\param` as starting documentation for a new param, or
to extend a previously started `\param` documentation when the same
reference is used. The intention here was to reference the function
parameter, not extend the previous documentation. Use `\p` to refer to
function parameters.
It isn't used to define other macros and it doesn't seem that useful
for users. Remove it, we can reintroduce it if needed.
Define a similar function key_type_is_raw_bytes in the implementation
with a clear semantics: it's a key that's represented as a struct
raw_data.
When calling psa_generate_key, pass the size of the parameters buffer
explicitly. This makes calls more verbose but less error-prone. This
also has the benefit that in an implementation with separation, the
frontend knows how many bytes to send to the backend without needing
to know about each key type.
Instead of rolling our own list of elliptic curve identifiers, use one
from somewhere. Pick TLS because it's the right size (16 bits) and
it's as good as any.
Conflicts:
library/psa_crypto.c
tests/suites/test_suite_psa_crypto.data
tests/suites/test_suite_psa_crypto.function
All the conflicts are concurrent additions where the order doesn't
matter. I put the code from feature-psa (key policy) before the code
from PR #13 (key lifetime).
psa_get_key_lifetime() behavior changed regarding empty slots, now
it return the lifetime of and empty slots. Documentation in header
file updated accordingly.
Conflict resolution:
* `tests/suites/test_suite_psa_crypto.data`: in the new tests from PR #14,
rename `PSA_ALG_RSA_PKCS1V15_RAW` to `PSA_ALG_RSA_PKCS1V15_SIGN_RAW` as
was done in PR #15 in the other branch.
