Merge pull request #76 from athoelke/athoelke-crypto-enum-types

Reserve value 0 for most enum-like types

Author: athoelke

doc/crypto/api/keys/types.rst

@@ -457,7 +457,9 @@ Elliptic Curve keys
 
     The range of Elliptic curve family identifier values is divided as follows:
 
-    :code:`0x00 – 0x7f`
+    :code:`0x00`
+        Reserved. Not allocated to an ECC family.
+    :code:`0x01 – 0x7f`
         ECC family identifiers defined by this standard.
         Unallocated values in this range are reserved for future use.
     :code:`0x80 – 0xff`
@@ -773,7 +775,9 @@ Diffie Hellman keys
 
     The range of Diffie-Hellman group family identifier values is divided as follows:
 
-    :code:`0x00 – 0x7f`
+    :code:`0x00`
+        Reserved. Not allocated to a DH group family.
+    :code:`0x01 – 0x7f`
         DH group family identifiers defined by this standard.
         Unallocated values in this range are reserved for future use.
     :code:`0x80 – 0xff`

doc/crypto/api/ops/kdf.rst

@@ -311,6 +311,10 @@ Input step types
     .. summary::
         Encoding of the step of a key derivation.
 
+    .. admonition:: Implementation note
+
+        It is recommended that the value `0` is not allocated as a valid key derivation step.
+
 .. macro:: PSA_KEY_DERIVATION_INPUT_SECRET
     :definition: /* implementation-defined value */
 

doc/crypto/appendix/history.rst

@@ -25,6 +25,7 @@ Clarifications and fixes
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 *   Clarified the behavior of a key derivation operation when there is insufficient capacity for a call to `psa_key_derivation_output_bytes()`, `psa_key_derivation_output_key()`, `psa_key_derivation_verify_bytes()`, or `psa_key_derivation_verify_key()`.
+*   Reserved the value `0` for most enum-like integral types.
 
 Other changes
 ~~~~~~~~~~~~~

doc/crypto/overview/conventions.rst

@@ -54,6 +54,8 @@ Data types
 
 Integral types are defined for specific API elements to provide clarity in the interface definition, and to improve code readability. For example, `psa_algorithm_t` and :code:`psa_status_t`.
 
+For enum-like integral types, the value `0` is usually reserved by the API to indicate an unspecified or invalid value.
+
 Structure types are declared using ``typedef`` instead of a ``struct`` tag, also to improve code readability.
 
 Fully-defined types must be declared exactly as defined in this specification. Types that are not fully defined in this specification must be defined by an implementation. See :secref:`implementation-defined-type`.