At this point this is a proposed PAKE interface for the PSA Crypto API
and not part of the official standard. Place the interface in
crypto_extra.h to make this clear.
Signed-off-by: Janos Follath <janos.follath@arm.com>
The caller is likely to receive the inputs on the wire, and having a
known size for which they can confidently reject longer inputs would be
helpful in cases where the application can't just use the input in
place.
Signed-off-by: Janos Follath <janos.follath@arm.com>
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>
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>
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>
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>
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>
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>
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>
