Commit graph

3556 commits

Author SHA1 Message Date
Gilles Peskine dddda81fbc mbedtls_ctr_drbg_set_entropy_len() only matters when reseeding
The documentation of CTR_DRBG erroneously claimed that
mbedtls_ctr_drbg_set_entropy_len() had an impact on the initial
seeding. This is in fact not the case: mbedtls_ctr_drbg_seed() forces
the initial seeding to grab MBEDTLS_CTR_DRBG_ENTROPY_LEN bytes of
entropy. Fix the documentation and rewrite the discussion of the
entropy length and the security strength accordingly.
2019-10-04 18:33:59 +02:00
Gilles Peskine 7e27936767 Add a note about CTR_DRBG security strength to config.h 2019-10-04 11:16:31 +02:00
Gilles Peskine 1540e5bd04 Move MBEDTLS_CTR_DRBG_USE_128_BIT_KEY to the correct section
It's an on/off feature, so it should be listed in version_features.
2019-10-04 11:16:24 +02:00
Gilles Peskine d0c64c856d CTR_DRBG: more consistent formatting and wording
In particular, don't use #MBEDTLS_xxx on macros that are undefined in
some configurations, since this would be typeset with a literal '#'.
2019-10-04 11:12:04 +02:00
Gilles Peskine 2884ba3720 CTR_DRBG: Improve the explanation of security strength
Separate the cases that achieve a 128-bit strength and the cases that
achieve a 256-bit strength.
2019-10-04 11:09:03 +02:00
Gilles Peskine 017778e9d8 CTR_DRBG: make it easier to understand the security strength
Explain how MBEDTLS_CTR_DRBG_ENTROPY_LEN is set next to the security
strength statement, rather than giving a partial explanation (current
setting only) in the documentation of MBEDTLS_CTR_DRBG_ENTROPY_LEN.
2019-10-04 11:09:03 +02:00
Gilles Peskine 5d9fd07938 HMAC_DRBG: note that the initial seeding grabs entropy for the nonce 2019-10-04 11:09:03 +02:00
Gilles Peskine 217b8159da Use standard terminology to describe the personalization string
NIST and many other sources call it a "personalization string", and
certainly not "device-specific identifiers" which is actually somewhat
misleading since this is just one of many things that might go into a
personalization string.
2019-10-04 11:09:03 +02:00
Gilles Peskine 2d8f069472 Do note that xxx_drbg_random functions reseed with PR enabled 2019-10-04 11:09:03 +02:00
Gilles Peskine 10f16ac74a Consistently use \c NULL and \c 0 2019-10-04 11:09:03 +02:00
Gilles Peskine 3457b5e05e HMAC_DRBG: improve the documentation of the entropy length 2019-10-04 11:09:03 +02:00
Gilles Peskine 74efcd2b71 HMAC_DRBG documentation improvements clarifications
Improve the formatting and writing of the documentation based on what
had been done for CTR_DRBG.

Document the maximum size and nullability of some buffer parameters.
2019-10-04 11:09:03 +02:00
Gilles Peskine ec51dd12fa More CTR_DRBG documentation improvements and clarifications 2019-10-04 11:09:03 +02:00
Gilles Peskine 6fdf0b3a47 CTR_DRBG: improve the discussion of entropy length vs strength 2019-10-04 11:09:02 +02:00
Gilles Peskine 223deea86b CTR_DRBG: Document the security strength and SP 800-90A compliance
Document that a derivation function is used.

Document the security strength of the DRBG depending on the
compile-time configuration and how it is set up. In particular,
document how the nonce specified in SP 800-90A is set.

Mention how to link the ctr_drbg module with the entropy module.
2019-10-04 11:09:02 +02:00
Gilles Peskine 944bc587e8 CTR_DRBG: Document the maximum size of some parameters 2019-10-04 11:09:02 +02:00
Gilles Peskine 08875d441e CTR_DRBG documentation clarifications
* State explicit whether several numbers are in bits or bytes.
* Clarify whether buffer pointer parameters can be NULL.
* Explain the value of constants that are dependent on the configuration.
2019-10-02 19:16:09 +02:00
Gilles Peskine a990c49caf
Merge pull request #269 from adrianlshaw/version
Add PSA API versioning
2019-09-30 15:59:21 +02:00
Gilles Peskine 178c9aa966 Key derivation: forbid output_key without input_key
If none of the inputs to a key derivation is a
PSA_KEY_DERIVATION_INPUT_SECRET passed with
psa_key_derivation_input_key(), forbid
psa_key_derivation_output_key(). It usually doesn't make sense to
derive a key object if the secret isn't itself a proper key.
2019-09-24 18:39:03 +02:00
Gilles Peskine 7ebd4dcf57 Key derivation: allow both keys and direct inputs (function doc)
Update the documentation of psa_key_derivation_input_key() and
psa_key_derivation_input_bytes() now that the key/buffer distinction
is not mandatory.
2019-09-24 18:39:03 +02:00
Gilles Peskine 224b0d656a Key derivation: allow both keys and direct inputs
Allow a direct input as the SECRET input step in a key derivation, in
addition to allowing DERIVE keys. This makes it easier for
applications to run a key derivation where the "secret" input is
obtained from somewhere else. This makes it possible for the "secret"
input to be empty (keys cannot be empty), which some protocols do (for
example the IV derivation in EAP-TLS).

Conversely, allow a RAW_DATA key as the INFO/LABEL/SALT/SEED input to a key
derivation, in addition to allowing direct inputs. This doesn't
improve security, but removes a step when a personalization parameter
is stored in the key store, and allows this personalization parameter
to remain opaque.

Add test cases that explore step/key-type-and-keyhood combinations.
2019-09-24 18:39:03 +02:00
Andrew Thoelke dd49cf984b Include vendor-defined algorithm macros
Fixes ARMmbed/psa-crypto#264
2019-09-24 13:11:49 +01:00
Gilles Peskine 38b7c5edeb
Merge pull request #260 from athoelke/at-operations
Update multipart operation documentation
2019-09-20 18:44:44 +02:00
Gilles Peskine c893235ea1
Merge pull request #115 from gilles-peskine-arm/psa-error-compatibility_aliases
Improve how generate_psa_constants handles compatibility aliases
2019-09-19 16:20:08 +02:00
Adrian L. Shaw 429fff487a Remove whitespace 2019-09-19 14:03:49 +01:00
Adrian L. Shaw d89338ac47 Add API versioning 2019-09-19 13:32:57 +01:00
Gilles Peskine a291413a1e
Merge pull request #257 from gilles-peskine-arm/psa-remove_zero_length_keys
Forbid zero-length keys
2019-09-19 13:07:41 +02:00
Andrew Thoelke 51514f57e9 Resolve inconsistent descipriton of operation state after exhausting a key derivation operation 2019-09-18 17:50:01 +01:00
Andrew Thoelke 4104afb770 Clarify valid state descriptions 2019-09-18 17:47:25 +01:00
Andrew Thoelke beb97ba066 Update documentation for multipart key derivation operations 2019-09-13 15:35:18 +01:00
Andrew Thoelke 414415a457 Update documentation for multipart aead operations 2019-09-13 15:35:18 +01:00
Andrew Thoelke db6f44f875 Update documentation for multipart cipher operations 2019-09-13 15:35:17 +01:00
Andrew Thoelke 9f208cc8c2 Update documentation for multipart mac operations 2019-09-13 15:35:17 +01:00
Andrew Thoelke 272ba1dd96 Update documentation for multipart hash operations 2019-09-13 15:35:17 +01:00
Andrew Thoelke 340984b003 Fix PSA_ERROR_BAD_STATE messages
Remove some duplicated entries and added some missing ones.
2019-09-13 15:35:17 +01:00
Gilles Peskine 05c900b576 Forbid keys of size 0
Keys of size 0 generally don't make sense: a key is supposed to be
secret. There is one edge case which is "raw data" keys, which are
useful to store non-key objects in the same storage location as keys.
However those are also problematic because they involve a zero-length
buffer. Manipulating zero-length buffers in C requires special cases
with functions like malloc() and memcpy(). Additionally, 0 as a key
size already has a meaning "unspecified", which does not always
overlap seamlessly with the meaning "0".

Therefore, forbid keys of size 0. No implementation may accept them.
2019-09-12 18:29:43 +02:00
Gilles Peskine a170d927dd Clarify how key creation functions use attributes and what 0 means
Clarify how key creation functions use attributes. Explain the meaning
of attribute values, espcially what 0 means in each field where it has
a special meaning. Explain what an algorithm usage policy can be (an
algorithm, a wildcard with ANY_HASH, or 0).
2019-09-12 17:38:19 +02:00
Andrew Thoelke 5ae24ec7af Add missing error case to psa_aead_verify 2019-09-12 09:44:33 +01:00
Adrian L. Shaw 4c61c1a736 Move psa_destroy_key and psa_copy_key to Key Management section 2019-09-11 14:40:51 +01:00
Jaeden Amero 9298dca14d
Merge pull request #185 from gilles-peskine-arm/harvard-md
Remove method dispatch from md
2019-09-10 18:38:39 +01:00
Jaeden Amero 4badc92438
Merge pull request #117 from gilles-peskine-arm/psa_error_code_coverage
PSA return status coverage script
2019-09-10 16:39:23 +01:00
Jaeden Amero 4864eb5bec
Merge pull request #247 from athoelke/at-key-handles
Update the behavior of key handles
2019-09-10 14:38:56 +01:00
Andrew Thoelke 970629fc9a Fix grammar. 2019-09-09 09:56:34 +01:00
Gilles Peskine be061337c1 Document more error codes 2019-09-06 19:29:52 +02:00
Gilles Peskine 1983512803 Add backward compatibility alias for PSA_ERROR_CORRUPTION_DETECTED
This was renamed from PSA_ERROR_TAMPERING_DETECTED. Add a backward
compatibility alias in case somebody was already using it.
2019-09-06 17:48:56 +02:00
Jaeden Amero 92348d1c49 Merge remote-tracking branch 'crypto/development' into development-restricted
* crypto/development: (77 commits)
  all.sh: disable MEMORY_BUFFER_ALLOC in cmake asan build
  Unify gcc and clang cmake flags to test with UBsan
  Add an input check in psa_its_set
  Remove storage errors from psa_generate_random
  Update getting_started.md
  Update based on Jaeden's comments.
  Update getting_started.md
  Fix return code warnings
  Update getting_started.md
  Fix warnings
  Add PSA_ERROR_STORAGE_FAILURE to psa_cipher_generate_iv
  Remove errorneous insert
  Add STORAGE_FAILURE everywhere + add missing codes
  Add storage failure to psa_mac_verify_finish
  Add storage failure to psa_mac_sign_finish
  Add PSA_ERROR_STORAGE_FAILURE to psa_aead_*_setup functions
  Added PSA_ERROR_BAD_STATE to functions with operations
  Added extra bad state case to psa_hash_setup
  Add missing return codes to psa_generate_key
  Add PSA_ERROR_BUFFER_TOO_SMALL to psa_mac_compute
  ...
2019-09-06 08:56:21 +01:00
Jaeden Amero 7c2cc479b0
Merge pull request #213 from adrianlshaw/psa-api-1.0-beta
Update function return codes
2019-09-06 08:53:29 +01:00
Janos Follath 75f2c20f9c ECDSA: Explain limitations of constant blinding 2019-09-05 11:18:58 +01:00
Janos Follath 1231d210e1 Add warning for alternative ECDSA implementations
Alternative implementations are often hardware accelerators and might
not need an RNG for blinding. But if they do, then we make them misuse
the RNG in the deterministic case.

There are several way around this:
- Exposing a lower level function for replacement. This would be the
optimal solution, but litters the API and is not backward compatible.
- Introducing a new compile time option for replacing the deterministic
function. This would mostly cover the same code as
MBEDTLS_ECDSA_DETERMINISTIC and would be yet another compile time flag.
- Reusing the existing MBEDTLS_ECDSA_DETERMINISTIC macro. This changes
the algorithm used by the PK layer from deterministic to randomised if
the alternative implementation is present.

This commit implements the third option. This is a temporary solution
and should be fixed at the next device driver API change.
2019-09-05 11:18:58 +01:00
Janos Follath e65e0597a8 Deprecate the old deterministic ECDSA function
The current interface does not allow passing an RNG, which is needed for
blinding. Using the scheme's internal HMAC-DRBG results the same
blinding values for the same key and message, diminishing the
effectiveness of the countermeasure. A new function
`mbedtls_ecdsa_det_ext` is available to address this problem.
2019-09-05 11:18:58 +01:00