Commit graph

409 commits

Author SHA1 Message Date
Gilles Peskine eff4942202
Merge pull request #268 from ARMmbed/psa-error_tampering_detected
Rename PSA_ERROR_TAMPERING_DETECTED to PSA_ERROR_CORRUPTION_DETECTED
2019-05-17 11:06:09 +02:00
Gilles Peskine 35ef36b62f Rename psa_generate_random_key back to psa_generate_key
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)
2019-05-17 10:56:57 +02:00
Gilles Peskine c93b80c350 Rename *KEYPAIR* to *KEY_PAIR*
Be consistent with PUBLIC_KEY.

perl -i -pe 's/KEYPAIR/KEY_PAIR/g' $(git ls-files)
2019-05-17 10:56:57 +02:00
Gilles Peskine 4b3eb69271 Rename PSA_ERROR_TAMPERING_DETECTED to ..._CORRUPTION_DETECTED
“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)
2019-05-16 21:35:18 +02:00
Gilles Peskine 27a983d93c Grammar fix 2019-05-16 19:51:11 +02:00
Gilles Peskine 20a77aeac7 RSA key generation: require e=65537 2019-05-16 19:51:10 +02:00
Gilles Peskine a130219ac0 Move remaining text about DSA out of the specification 2019-05-16 19:51:10 +02:00
Gilles Peskine e38ab1ac4f Move DSA definitions out of the specification
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.
2019-05-16 19:51:10 +02:00
Gilles Peskine dcaefae849 Parametrize Diffie-Hellman keys by a group identifier
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.
2019-05-16 19:51:10 +02:00
Gilles Peskine 24f10f85e2 Remove domain parameters from the official API
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.
2019-05-16 19:27:05 +02:00
Gilles Peskine 58fe9e8afe Correct the description of psa_raw_key_agreement
There was some copypasta from the KA+KDF function's description.
2019-05-16 18:55:25 +02:00
Gilles Peskine be697d8324 Shorten the name of psa_key_agreement_raw_shared_secret
There is less of a risk of confusion with the KA+KDF function now.
2019-05-16 18:55:25 +02:00
Gilles Peskine 1cb9a08d6a Reorder key derivation functions in the header file
Present key derivation functions in a more logical order,
corresponding roughly to the order in which an application would call
them.
2019-05-16 18:55:25 +02:00
Gilles Peskine cf7292e257 Wrap and reindent some lines
After renaming several identifiers, re-wrap and re-indent some lines
to make the code prettier.
2019-05-16 18:55:25 +02:00
Gilles Peskine 35675b6b26 Terminology: say "key derivation operation", not "generator"
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.
2019-05-16 18:55:25 +02:00
Gilles Peskine cbe6650394 Rename generator-related internal identifiers
perl -pe 's/crypto_generator/key_derivation/gi' $(git ls-files)
    perl -pe 's/_generator/_key_derivation/gi' $(git ls-files)
2019-05-16 18:55:25 +02:00
Gilles Peskine 03410b5c5f Rename PSA_KDF_STEP_xxx -> PSA_KEY_DERIVATION_INPUT_xxx
More consistent with the new function names.
2019-05-16 18:55:25 +02:00
Gilles Peskine a99d3fbd05 Rename generator functions to psa_key_derivation_xxx
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)
2019-05-16 18:55:21 +02:00
Jaeden Amero d35249e66f
Merge pull request #109 from gilles-peskine-arm/psa-key_attributes-set_persistent
Individual setters for persistent key attributes
2019-05-16 17:28:53 +01:00
Jaeden Amero 99e8d26a75
Merge pull request #104 from gilles-peskine-arm/psa-global_key_id
Make key ids global and define their range
2019-05-16 17:11:59 +01:00
Gilles Peskine f1b7694768 Minor documentation improvements 2019-05-16 16:10:59 +02:00
Gilles Peskine 280948a32b Fix copypasta in the documentation of PSA_KEY_ID_xxx_{MIN,MAX} 2019-05-16 15:27:14 +02:00
Jaeden Amero 16ab39102e
Merge pull request #102 from gilles-peskine-arm/psa-aead_multipart-delay
Multipart AEAD buffer output sizes
2019-05-16 13:34:21 +01:00
Jaeden Amero 76be7f9c70
Merge pull request #108 from gilles-peskine-arm/psa-copy_key-policy
Add policy usage flag to copy a key
2019-05-16 12:08:13 +01:00
Jaeden Amero 826e326d2e
Merge pull request #107 from gilles-peskine-arm/psa-curve_size_macro
PSA: EC curve size macro
2019-05-16 11:59:41 +01:00
Gilles Peskine 6c9514427b New macro to get the bit size of an elliptic curve 2019-05-16 00:16:46 +02:00
Gilles Peskine 73676cbc50 Put handle parameter last: psa_import_key
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.
2019-05-15 23:16:07 +02:00
Gilles Peskine 806051f17e Update an obsolete use of psa_import_key in documentation
psa_import_key now takes an attribute structure, not a type.
2019-05-15 23:15:49 +02:00
Gilles Peskine 98dd779eb5 Put handle parameter last: psa_generate_derived_key
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.
2019-05-15 20:15:31 +02:00
Gilles Peskine 9de5eb0a2f Remove psa_make_key_persistent 2019-05-15 19:14:05 +02:00
Gilles Peskine dc8219a10d Replace psa_make_key_persistent by id/lifetime setters
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.
2019-05-15 19:14:05 +02:00
Gilles Peskine 80b39ae753 Remove obsolete use of key policy structure in API text 2019-05-15 19:14:05 +02:00
Gilles Peskine f9fbc38e66 Declare key id 0 as invalid
In keeping with other integral types, declare 0 to be an invalid key
identifier.

Documented, implemented and tested.
2019-05-15 18:42:09 +02:00
Gilles Peskine d6a8f5f1b5 Improve description of PSA_KEY_USAGE_COPY
Be more clear about when EXPORT is also required.
2019-05-14 16:25:50 +02:00
Gilles Peskine ac99e32b79 Documentation improvements 2019-05-14 16:11:07 +02:00
Gilles Peskine 36d477de44 Fix copypasta in PSA_AEAD_DECRYPT_OUTPUT_SIZE 2019-05-14 16:11:07 +02:00
Gilles Peskine 248010caa0 Fix calculation in PSA_AEAD_UPDATE_OUTPUT_SIZE 2019-05-14 16:11:07 +02:00
Gilles Peskine 8e0206aa26 New usage flag PSA_KEY_USAGE_COPY
Document the new flag and allow its use.
2019-05-14 14:24:28 +02:00
Gilles Peskine 4318dfc8ec psa_export_key, psa_export_public_key: document the EXPORT flag 2019-05-14 14:23:32 +02:00
Jaeden Amero 1fe90fab30
Merge pull request #101 from gilles-peskine-arm/psa-key_attributes-verify_attributes
Check unused attributes in import and copy
2019-05-13 11:48:40 +01:00
Gilles Peskine 4a231b8d3b Break up key identifiers into user, vendor and reserved ranges
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).
2019-05-06 18:56:14 +02:00
Gilles Peskine 225010fdf7 Remove lifetime parameter from psa_open_key
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.
2019-05-06 18:52:22 +02:00
Gilles Peskine f02aec90dc Allow AEAD update output to be delayed
Do not require finish() to have empty output for any algorithm. Some
hardware does not support immediate stream processing.
2019-05-06 15:59:44 +02:00
Gilles Peskine 3e79c8ecfd Declare ChaCha20 cipher and AEAD
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).
2019-05-06 15:59:44 +02:00
Gilles Peskine 49dd8d8cec Add size macros for multipart AEAD
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().
2019-05-06 15:59:16 +02:00
Gilles Peskine 5211efb317 Add output parameter for 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.
2019-05-06 15:56:05 +02:00
Gilles Peskine bdc27860c2 Reorder macros for clarity
Group PSA_AEAD_DECRYPT_OUTPUT_SIZE with PSA_AEAD_ENCRYPT_OUTPUT_SIZE.
2019-05-06 15:45:16 +02:00
Gilles Peskine 679693ee49 Algorithm encoding: add flag bit PSA_ALG_AEAD_FROM_BLOCK_FLAG
Make it easy to distinguish generic constructions on top of block
ciphers, such as CCM or GCM, from specialized algorithms such as
Chacha20-Poly1305.
2019-05-06 15:10:16 +02:00
Gilles Peskine 4ce2a9dcbf Check unused attributes in import and copy
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.
2019-05-03 16:57:15 +02:00
Adrian L. Shaw 5a5a79ae2a Rename psa_generate_key() and psa_generator_import_key() 2019-05-03 15:44:28 +01:00