Make input/output format documentation easier to find:
- Add direct reference to the steps from the input/output functions
- Move the format description directly to the step constants
Signed-off-by: Janos Follath <janos.follath@arm.com>
- Transformed setup description to a more explicit pseudocode based
approach.
- Explained implicit vs explicit key confirmation
Signed-off-by: Janos Follath <janos.follath@arm.com>
This step is not necessarily a memory-hard function. Memory-hard
functions are the best of the breed at the moment, but that's due to
current hardware designs, and CPU-hard-but-not-memory-hard functions
like PBKDF2 are acceptable as well. We're using “key stretching” as the
generic term for such functions.
Signed-off-by: Janos Follath <janos.follath@arm.com>
The key derivation operation passed to psa_pake_set_password_mhf() might
enter an error state before the function returns. If this happens, the
user needs to know about it so that they can properly abort it.
Signed-off-by: Janos Follath <janos.follath@arm.com>
The type of the key derivation operation was incorrect.
Also neither the PAKE nor key_derivation algorithm knows how many bytes
to transfer at this stage.
There is no optimal or recommended size, PAKEs don't mandate it either
(with the exception of OPAQUE, but that uses it internally and won't be
using this interface).
Adding an input length parameter to allow the application to control how
many bytes the PAKE takes from the key derivation.
Signed-off-by: Janos Follath <janos.follath@arm.com>
Using memory hard functions with PAKEs is the more secure option. It
should be as convenient and efficient to use as less secure options, but
so far it required creating an additional temporary key object.
With psa_pake_set_password_mhf() this eliminates the need for this.
Similarly we could add a convenience function to supply the password
directly from character strings, but that would make the less secure
option more convenient again and therfore we are not doing it now.
Signed-off-by: Janos Follath <janos.follath@arm.com>
PAKE constructions that have multiple key shares will always consume and
produce the key shares in numerical order. So using PSA_PAKE_DATA_XXX_X
would demand step-sequence validation, and provides no functional
utility over having only PSA_PAKE_DATA_XXX.
Signed-off-by: Janos Follath <janos.follath@arm.com>
If PSA_PAKE_OUTPUT_SIZE takes cipher_suite as a parameter and it is a
structure it can't be a compile-time constant anymore.
Reintroducing psa_pake_primitive_t, because it can be constructed as an
integral type and holds enough information to allow PSA_PAKE_OUTPUT_SIZE
calculating accurate estimates on the output size in compile time.
Signed-off-by: Janos Follath <janos.follath@arm.com>
There are too many parameters to the setup function. This makes it hard
to figure out how to call the function and read code that calls the
function. This also opens the suspicion that there's yet another
parameter that we're missing.
Signed-off-by: Janos Follath <janos.follath@arm.com>
"Data" is too vague, renaming it to psa_pake_step_t. It is still
somewhat vague, but at least consistent with the naming used in key
derivation.
Signed-off-by: Janos Follath <janos.follath@arm.com>
__DOXYGEN_ONLY__ blocks were only used to typeset the PSA specification
back when it was extracted from Mbed TLS headers. They are no longer
used and should be removed.
The PSA Crypto Driver API is still under development and might be
extracted from Mbed TLS headers, leaving them there for now.
Signed-off-by: Janos Follath <janos.follath@arm.com>
It is the size of something that has no a priori reason to consist of 8
bits. This should be psa_pake_family_t, both for documentation (and
possibly static analysis) and in case 8 bits turn out not to be enough.
Signed-off-by: Janos Follath <janos.follath@arm.com>
Identifier value was not consistent with PSA conventions (last byte is
reserved for hash algorithms or used in algorithms parametrized by
a hash).
Signed-off-by: Janos Follath <janos.follath@arm.com>
The cipher suite now defines the algorithm itself as well. Passing the
algorithm separately is redundant and error prone.
Signed-off-by: Janos Follath <janos.follath@arm.com>
Making the cipher suite struct internal made a number of types and
macros in the interface unused.
Signed-off-by: Janos Follath <janos.follath@arm.com>
Hiding the structure of the cipher suite implementation allows for
greater flexibility.
To preserve maximum flexibility, the constructor is replaced by
individual setter/getter functions.
Convenience macros and or functions can be added later.
Signed-off-by: Janos Follath <janos.follath@arm.com>
In the key types API, PSA Crypto uses ECC to denote Elliptic curve
cryptography and DH to denote Finite Field Diffie-Hellman.
Change PSA_PAKE_PRIMITIVE_TYPE_XXX macros to be aligned.
Signed-off-by: Janos Follath <janos.follath@arm.com>
The macro PSA_PAKE_KEY_SHARE_SIZE has been removed, we need to remove
references to it from the documentation as well.
Signed-off-by: Janos Follath <janos.follath@arm.com>
There were remnants of the PSA specification wording in the
documentation that can be confusing in Mbed TLS.
We need to make it clear what the consequences of being implementation
defined are in Mbed TLS.
Signed-off-by: Janos Follath <janos.follath@arm.com>
The main purpose of psa_pake_get_key_share() is to provide a more
straightforward and convenient call flow for regular PAKEs. Most PAKEs
have a single key share and need a flow like this:
op=PSA_PAKE_OPERATION_INIT;
psa_pake_setup();
psa_pake_get_key_share();
psa_pake_set_key_share();
psa_pake_get_implicit_key();
Adding psa_pake_get/set_key_share() functions cuts out the
psa_pake_data_t constants from the users vision, hiding complexity that
exists only for unrelated PAKEs that aren't relevant for the user.
This comes with the cost of the two additional API functions that we need
to maintain.
Since the current stream of work focuses on enabling J-PAKE, there are
no benefits to these functions for now.
Once algorithms that can benefit from this simplification are added,
adding back these functions can be reconsidered.
Signed-off-by: Janos Follath <janos.follath@arm.com>
The documentation is calling PAKEs protocols but it has an
psa_algorithm_t identifier. To align the terminology, the documentation
should call them algorithms as well.
Signed-off-by: Janos Follath <janos.follath@arm.com>
Fix the typo in the macro definition and more specific parameter names
allow for future scripts to check validity of arguments.
Signed-off-by: Janos Follath <janos.follath@arm.com>
The PSA_KEY_TYPE_PASSWORD key type to which this documentation change
refers to is not yet present in the code and will be introduced by a
parallel line of work.
Signed-off-by: Janos Follath <janos.follath@arm.com>
PAKE protocols make use of a range of cryptographic schemes and
primitives. Standards allow for several options to use for each of them.
They call the combination of specific algorithms cipher suites,
configurations or options.
Cipher suites are represented by a separate data type for several
reasons:
1. To allow for individual PAKE protocols to provide pre-defined cipher
suites.
2. To organise cipher suites into a unit that can be handled separately
from the operation context. The PAKE operation flow is already
complex, will be even more so when key confirmation is added.
Handling them separately should reduce the surface of the interface
the application developer needs to pay attention at any given time.
Signed-off-by: Janos Follath <janos.follath@arm.com>
In most of the PAKEs the primitives are prime order groups, but some of
them might need the ring structure or just are using completely different
algebraic structures (eg. SRP or PQC schemes).
Signed-off-by: Janos Follath <janos.follath@arm.com>
Add comment to the effect that we cannot really check nonce size as the
GCM spec allows almost arbitrarily large nonces. As a result of this,
change the operation nonce over to an allocated buffer to avoid overflow
situations.
Signed-off-by: Paul Elliott <paul.elliott@arm.com>
Split to data required for internal implementation and data required for
driver implementation with data left over for the PSA layer.
Signed-off-by: Paul Elliott <paul.elliott@arm.com>
Move CCM to update all data at update step, as final step can only
output at most a block length, so outputting all data at this step
significantly breaks the tests. Had to add unpleasant workaround for the
validate stage, but this is the only way I can do things without
breaking CCM Alt implementations.
Signed-off-by: Paul Elliott <paul.elliott@arm.com>
For the time being CCM and GCM are not entirely implemented correctly
due to issues with their underlying implentations, which would be
difficult to fix in 2.x, and thus require all the AD and data to be
passed in in one go.
Signed-off-by: Paul Elliott <paul.elliott@arm.com>
Multipart AEAD operation struct has to be public as it's allocated by
the caller, so to save duplication of code, switch oneshot AEAD over to
using the multipart operation struct.
Signed-off-by: Paul Elliott <paul.elliott@arm.com>
It makes sense to do the length checking in the core rather than expect
each driver to deal with it themselves. This puts the onus on the core to
dictate which algorithm/key combinations are valid before calling a driver.
Additionally, this commit also updates the psa_mac_sign_finish function
to better deal with output buffer sanitation, as per the review comments
on #4247.
Signed-off-by: Steven Cooreman <steven.cooreman@silabs.com>
This means there is no longer a need to have an internal HMAC API, so
it is being removed in this commit as well.
Signed-off-by: Steven Cooreman <steven.cooreman@silabs.com>
Prefix with 'mbedtls_psa' as per the other types which implement some
sort of algorithm in software.
Signed-off-by: Steven Cooreman <steven.cooreman@silabs.com>
The purpose of key_set was to guard the operation structure from being
used for update/finish before a key was set. Now that the implementation
fully adheres to the PSA API, that function is covered by the `alg`
variable instead. It's set to the algorithm in use when a key is set, and
is zero when the operation is reset/invalid.
Signed-off-by: Steven Cooreman <steven.cooreman@silabs.com>
Apparently it was at some point assumed that there would be
support for MAC algorithms with IV, but that hasn't been
implemented yet. Until that time, these context structure
members are superfluous and can be removed.
Signed-off-by: Steven Cooreman <steven.cooreman@silabs.com>
Typedef'ed structures are suffixed _t
Also updated the initialiser macro with content that actually
matches the structure's content.
Signed-off-by: Steven Cooreman <steven.cooreman@silabs.com>
Since HMAC moved into its own compilation unit, the internal API needed
to be documented and finalized. This means no more reaching deep into
the operation structure from within the PSA Crypto core. This will make
future refactoring work easier, since internal HMAC is now opaque to the
core.
Signed-off-by: Steven Cooreman <steven.cooreman@silabs.com>
Modeled after the include chain of the primitive operation contexts.
Also moved the HMAC context structure to the builtin composites file,
since that is where it conceptually belongs. This is a preparatory
step for implementing driver dispatch of MAC multipart operations.
Signed-off-by: Steven Cooreman <steven.cooreman@silabs.com>
This was probably included by mistake, because the file itself is part
of the inclusion chain starting with crypto.h.
Signed-off-by: Steven Cooreman <steven.cooreman@silabs.com>
This is a preparatory step in order to be able to organize the include
chain from crypto_struct in such a way that the MAC operation structure
for the PSA 'software' driver can make use of the hash operation structure.
Conceptually:
* Primitives:
* Hash
* Cipher
* Composites:
* AEAD (can use cipher)
* MAC (can use cipher and/or hash)
Signed-off-by: Steven Cooreman <steven.cooreman@silabs.com>
This algorithm is used for example by the Thread 1.1.1 specification,
which is not public but can be obtained free of charge at
https://www.threadgroup.org/ThreadSpec
Here it doesn't really make sense to define a parametrised family, as
this really seems to be the only use of PBKDF2 with a CMAC-based PRF (or
with any PRF other than HMAC with SHA1 or SHA2, for that matter).
Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
Might make the implementer's life a bit simpler, and is not a big
constraint on applications.
Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
No change of behaviour, encoding or naming intended in this commit: just
describe the same behaviour, but in a way that's hopefully clearer and
more complete.
Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
Note on naming: previously considered input_numeric but then thought the
other two input function are "input <name>" not "input <adjective>" so
decided to follow that pattern. input_int would be shorter but sounds
too much like the C type, which could be confusing as that's not the
type of the parameter; IMO "integer" avoids that problem.
Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
For the numeric values, I followed the apparent existing convention:
- first byte is 01 for secret inputs, 02 for non-secret inputs
- then second by is just incremented for each new input type
The documentation references a function that will be introduced in the
next commit.
Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
The documentation references functions that will be introduced in later
commits, but hopefully from the naming it's already clear what those
function will do.
Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
Question to reviewers: regarding the numeric values, I'm not sure I've
incremented the right byte/nibble. Should this be 0x1201, 0x1202
instead, or something else? Is there a convention I should be aware of?
Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
Specifically allow the driver to override the persistency level of a
builtin key in cases where the driver is persistency-aware.
Signed-off-by: Steven Cooreman <steven.cooreman@silabs.com>
Due to repeated calls to PSA_AEAD_NONCE_LENGTH, which in turn calls
PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG several times, some macros updated
in this PR expanded to over 6000 characters, more than the 4095 that ISO
C99 compilers are guaranteed to support.
Signed-off-by: Bence Szépkúti <bence.szepkuti@arm.com>
Instead of the full attributes struct, it now only takes/returns what it
actually needs to.
Signed-off-by: Steven Cooreman <steven.cooreman@silabs.com>
According to the design in psa-driver-interface.md. Compiles without
issue in test_psa_crypto_drivers.
Signed-off-by: Steven Cooreman <steven.cooreman@silabs.com>
Where a change was necessary, the new documentation was copied from the
PSA Crypto API spec exactly, with the exception of PSA_AEAD_TAG_LENGTH,
which needed some adjustment.
Signed-off-by: Bence Szépkúti <bence.szepkuti@arm.com>
Fix expected error code when importing a persistent key or
registering a key with an invalid key identifier:
PSA_ERROR_INVALID_ARGUMENT instead of PSA_ERROR_INVALID_HANDLE.
Signed-off-by: Ronald Cron <ronald.cron@arm.com>
Implementers and users would have to refer to the RFC for the detailed
specification of the algorithm anyway.
Keep a mention of the curves and hashes involved for avoidance of doubt.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
The coordinates are over $F_{2^{255}-19}$, so by the general
definition of the bit size associated with the curve in the
specification, the value for size attribute of keys is 255.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
The size attribute of a key is expressed in bits, so use bits in the
documentation. (The documentation of psa_export_key() describes the
export format, so it counts in bytes.)
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
Call it “SHAKE256-512”, just like SHA3-512 has 512 bits of output.
SHAKE256-64 looks like it's 64 bits of output, but this is 64 bytes.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
Define algorithms for PureEdDSA and for HashEdDSA, the EdDSA variants
defined by RFC 8032.
The encoding for HashEdDSA needs to encode the hash algorithm so that
the hash can be calculated by passing PSA_ALG_SIGN_GET_HASH(sig_alg)
to psa_hash_compute() or psa_hash_setup(). As a consequence,
Ed25519ph (using SHA-512) and Ed448ph (using SHAKE256) need to have
different algorithm encodings (the key is enough to tell them apart,
but it is not known while hashing). Another consequence is that the
API needs to recognize the Ed448 prehash (64 bytes of SHAKE256 output)
as a hash algorithm.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
Add an elliptic curve family for the twisted Edwards curves
Edwards25519 and Edwards448 ("Goldilocks"). As with Montgomery curves,
since these are the only two curves in common use, the family has a
generic name.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
Remove cipher_generate_iv driver entry point as there
is no known use case to delegate this to a driver.
Signed-off-by: Ronald Cron <ronald.cron@arm.com>
Move members that are of no use to the PSA crypto core
to the Mbed TLS implementation specific operation context.
Signed-off-by: Ronald Cron <ronald.cron@arm.com>
For cipher multi-part operations, dispatch based on
the driver identifier even in the case of the
Mbed TLS software implementation (viewed as a driver).
Also use the driver identifier to check that an
cipher operation context is active or not.
This aligns the way hash and cipher multi-part
operations are dispatched.
Signed-off-by: Ronald Cron <ronald.cron@arm.com>
Add missing PSA_WANT_CCM/GCM/CMAC. This completes
the set of PSA_WANT config options given the
current support of PSA crypto in Mbed TLS.
Signed-off-by: Ronald Cron <ronald.cron@arm.com>
When these names were changed, the definition got misaligned with the
rest of the fields. Fix this alignment.
Signed-off-by: David Brown <david.brown@linaro.org>
The hash driver entry points (and consequentially the hash driver core)
are now always compiled on when PSA_CRYPTO_DRIVER_TEST is turned on.
Signed-off-by: Steven Cooreman <steven.cooreman@silabs.com>
Drivers (both built-in and external) need to declare their context
structures in a way such that they are accessible by the
to-be-autogenerated crypto_driver_contexts.h file. That file lives in
include/psa, which means all builtin driver context structure
declarations also need to live in include/psa.
Signed-off-by: Steven Cooreman <steven.cooreman@silabs.com>
psa_aead_generate_nonce() could generate a nonce of up to 13 bytes,
depending on the inputs to psa_aead_set_lengths().
Signed-off-by: Bence Szépkúti <bence.szepkuti@arm.com>
An earlier commit fixes the names of the PSA_WANT_ECC_ macros. Update
the crypto_config.h file to match these new names.
Signed-off-by: David Brown <david.brown@linaro.org>
Removes a broken doxygen link to a macro that is now internal and
cannot be seen from the public API anymore.
Signed-off-by: Chris Jones <christopher.jones@arm.com>
Apparently there's a goal to make the PSA Crypto core free from
dynamic memory allocations. Therefore, all driver context structures
need to be known at compile time in order for the core to know their
final size.
This change defines & implements for hashing operations how the context
structures get defined.
Signed-off-by: Steven Cooreman <steven.cooreman@silabs.com>
