Commit graph

487 commits

Author SHA1 Message Date
Gilles Peskine
6c12a1e9f2 Add ARIA to the PSA API
Use the encoding from an upcoming version of the specification.

Add as much (or as little) testing as is currently present for Camellia.

Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
2021-09-21 11:59:39 +02:00
Andrew Thoelke
a0f4b595c5
Fixes for PBKDF2 documentation
Fix typos in the PBKDF2 documentation

Correct the constraints on PSA_KEY_USAGE_DERIVE and PSA_KEY_USAGE_VERIFY_DERIVATION, aligning them with the note against psa_key_derivation_input_key(). All key inputs must have the required usage flag to permit output or verification.

Correct the constraints on PSA_KEY_DERIVATION_INPUT_SECRET and PSA_KEY_DERIVATION_INPUT_PASSWORD, aligning them with 4feb611. psa_key_derivation_verify_key() does not require the secret/password input to be a key.

Signed-off-by: Andrew Thoelke <andrew.thoelke@arm.com>
2021-06-24 16:47:14 +01:00
TRodziewicz
10e8cf5fef Remove MD2, MD4, RC4, Blowfish and XTEA
Signed-off-by: TRodziewicz <tomasz.rodziewicz@mobica.com>
2021-06-16 10:34:25 +02:00
Janos Follath
702cf09ae9 PSA PAKE: move the API to crypto_extra.h
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>
2021-06-08 14:48:34 +01:00
Janos Follath
a295918596 PSA PAKE: add input size macros
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>
2021-06-08 14:40:57 +01:00
Janos Follath
79e1c47a54 PSA PAKE: explain implicit key confirmation
Signed-off-by: Janos Follath <janos.follath@arm.com>
2021-06-03 12:37:32 +01:00
Janos Follath
7c59b7a073 Improve psa_pake_set_peer()/user() documentation
Signed-off-by: Janos Follath <janos.follath@arm.com>
2021-06-03 12:37:32 +01:00
Janos Follath
56a4d7a59f Simplify PAKE input/output format documentation
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>
2021-06-03 12:37:32 +01:00
Janos Follath
ead0e4fc7b PSA PAKE: Clarify J-PAKE algorithm documentation
- 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>
2021-06-03 12:37:32 +01:00
Janos Follath
d416838ffd Rename psa_pake_set_password_mhf()
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>
2021-06-03 12:37:32 +01:00
Janos Follath
3ae6696811 Clarify psa_pake_setup() documentation
Signed-off-by: Janos Follath <janos.follath@arm.com>
2021-06-03 12:37:32 +01:00
Janos Follath
19271ea183 PSA PAKE: Clarify documentation of valid states
Signed-off-by: Janos Follath <janos.follath@arm.com>
2021-06-03 12:37:32 +01:00
Janos Follath
9a04aeaff5 PSA PAKE: improve and fix documentation
Signed-off-by: Janos Follath <janos.follath@arm.com>
2021-06-03 12:37:32 +01:00
Janos Follath
7b8910322c PSA PAKE: refine documentation of return values
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>
2021-06-03 12:37:32 +01:00
Janos Follath
e1a080f1f8 Improve psa_pake_set_password_mhf() documentation
Signed-off-by: Janos Follath <janos.follath@arm.com>
2021-06-03 12:37:32 +01:00
Janos Follath
1062a24152 Fix psa_pake_set_password_mhf() parameter list
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>
2021-06-03 12:37:32 +01:00
Janos Follath
14ce06afe2 PSA PAKE: fix documentation
Signed-off-by: Janos Follath <janos.follath@arm.com>
2021-06-03 12:37:32 +01:00
Janos Follath
60fa7c59b2 PSA PAKE: document operation parameters
Signed-off-by: Janos Follath <janos.follath@arm.com>
2021-06-03 12:37:31 +01:00
Janos Follath
b0bcb633ff Link PSA_KEY_TYPE_PASSWORD in the documentation
Signed-off-by: Janos Follath <janos.follath@arm.com>
2021-06-03 12:37:31 +01:00
Janos Follath
fe0c4493f5 Add psa_pake_set_password_mhf()
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>
2021-06-03 12:37:31 +01:00
Janos Follath
56cc9ccc39 PSA PAKE: Align macro names with psa_pake_step_t
Signed-off-by: Janos Follath <janos.follath@arm.com>
2021-06-03 12:37:31 +01:00
Janos Follath
78b9e40662 PSA PAKE: reintroduce psa_pake_primitive_t
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>
2021-06-03 12:37:31 +01:00
Janos Follath
a86c3131a8 PSA PAKE: divide setup into several steps
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>
2021-06-03 12:37:31 +01:00
Janos Follath
beb78d4d41 Rename psa_pake_data_t
"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>
2021-06-03 12:37:31 +01:00
Janos Follath
57cfc407e0 Remove obsolete __DOXYGEN_ONLY__ blocks
__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>
2021-06-03 12:37:31 +01:00
Janos Follath
f53c7af916 PSA PAKE: introduce psa_pake_family_t
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>
2021-06-03 12:37:31 +01:00
Janos Follath
1459aa5656 PSA PAKE: improve documentation
Minor documentation improvement and fixes.

Signed-off-by: Janos Follath <janos.follath@arm.com>
2021-06-03 12:37:31 +01:00
Janos Follath
5b44cfd430 PSA PAKE: remove alg parameter from setup
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>
2021-06-03 12:37:30 +01:00
Janos Follath
cd56ff9c59 PSA PAKE: make cipher suite opaque
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>
2021-06-03 12:37:30 +01:00
Janos Follath
2ba6079d47 PSA: fix wording for implementation defined types
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>
2021-06-03 12:37:30 +01:00
Janos Follath
7ebcbf34f9 Remove psa_pake_get/set_key_share() functions
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>
2021-06-03 12:12:08 +01:00
Janos Follath
fb4203dcff PSA PAKE: Call the scheme algorithm
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>
2021-06-03 12:12:08 +01:00
Janos Follath
ca2c167dcb PSA PAKE: fix doxygen warnings
Signed-off-by: Janos Follath <janos.follath@arm.com>
2021-06-03 12:07:47 +01:00
Janos Follath
7f1e81a98d PSA PAKE: specify key type and usage
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>
2021-06-03 12:07:47 +01:00
Janos Follath
9c6b147d98 PSA PAKE: Add J-PAKE to the interface
Signed-off-by: Janos Follath <janos.follath@arm.com>
2021-06-03 12:07:47 +01:00
Janos Follath
508afeca67 PSA PAKE: Add cipher suite structure
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>
2021-06-03 12:07:47 +01:00
Janos Follath
5e5dcaced3 PSA PAKE: Add function declarations
Add function declarations for the draft version of PSA Crypto API PAKE
interface.

Signed-off-by: Janos Follath <janos.follath@arm.com>
2021-06-03 12:07:47 +01:00
gabor-mezei-arm
12b4f34fff
Fix documentation
Signed-off-by: gabor-mezei-arm <gabor.mezei@arm.com>
2021-05-13 11:18:59 +02:00
gabor-mezei-arm
38cbaf2881
Typo
Signed-off-by: gabor-mezei-arm <gabor.mezei@arm.com>
2021-05-13 11:18:57 +02:00
gabor-mezei-arm
4a21019653 Implement psa_sign_message and psa_verify_message functions
Signed-off-by: gabor-mezei-arm <gabor.mezei@arm.com>
2021-05-13 11:18:49 +02:00
Gilles Peskine
5d1f747d85
Merge pull request #4377 from mpg/psa-pbkdf2-api
PSA API for PBKDF2-HMAC
2021-05-12 18:00:30 +02:00
Manuel Pégourié-Gonnard
4e02f01815 Fix key type that wasn't updated earlier
Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
2021-05-12 10:05:45 +02:00
Manuel Pégourié-Gonnard
2c44daf0bc Add restriction on output_key alg for password hash
Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
2021-05-10 12:53:30 +02:00
Manuel Pégourié-Gonnard
4feb611a49 Lift a restriction on usage of verify_key()
Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
2021-05-07 12:22:21 +02:00
Manuel Pégourié-Gonnard
e88511d7fe Try making one condition more readable
No semantic change intended.

Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
2021-05-07 12:19:03 +02:00
Manuel Pégourié-Gonnard
ece9087b93 Clarify requirement on usage flags
Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
2021-05-05 10:26:29 +02:00
Manuel Pégourié-Gonnard
acfde465f0 Mention USAGE_VERIFY_DERIVATION in input_key()
Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
2021-05-05 09:54:22 +02:00
Manuel Pégourié-Gonnard
2171e421c6 Add new key type PASSWORD_HASH
Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
2021-05-03 10:49:54 +02:00
Manuel Pégourié-Gonnard
88658becd4 Clarify algorithm constraint for verification
Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
2021-05-03 10:28:57 +02:00
Manuel Pégourié-Gonnard
9023cacf15 Merge verification policies together
Signed-off-by: Manuel Pégourié-Gonnard <manuel.pegourie-gonnard@arm.com>
2021-05-03 10:27:27 +02:00