Prepare Crypto spec for v1.2 release candidate

doc/crypto/api.db/psa/crypto.h

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: Copyright 2018-2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
+// SPDX-FileCopyrightText: Copyright 2018-2024 Arm Limited and/or its affiliates <open-source-office@arm.com>
 // SPDX-License-Identifier: Apache-2.0
 
 typedef /* implementation-defined type */ psa_aead_operation_t;

doc/crypto/api/keys/attributes.rst

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: Copyright 2018-2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
+.. SPDX-FileCopyrightText: Copyright 2018-2024 Arm Limited and/or its affiliates <open-source-office@arm.com>
 .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 .. header:: psa/crypto
@@ -112,7 +112,7 @@ Managing key attributes
     #.  Set the key policy with `psa_set_key_usage_flags()` and `psa_set_key_algorithm()`.
     #.  Set the key type with `psa_set_key_type()`. Skip this step if copying an existing key with `psa_copy_key()`.
     #.  When generating a random key with `psa_generate_key()` or deriving a key with `psa_key_derivation_output_key()`, set the desired key size with `psa_set_key_bits()`.
-    #.  Call a key creation function: `psa_import_key()`, `psa_generate_key()`, `psa_key_derivation_output_key()` or `psa_copy_key()`. This function reads the attribute object, creates a key with these attributes, and outputs an identifier for the newly created key.
+    #.  Call a key creation function: `psa_import_key()`, `psa_generate_key()`, `psa_key_derivation_output_key()`, `psa_key_agreement()`, or `psa_copy_key()`. This function reads the attribute object, creates a key with these attributes, and outputs an identifier for the newly created key.
     #.  Optionally call `psa_reset_key_attributes()`, now that the attribute object is no longer needed. Currently this call is not required as the attributes defined in this specification do not require additional resources beyond the object itself.
 
     A typical sequence to query a key's attributes is as follows:

doc/crypto/api/keys/lifetimes.rst

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: Copyright 2018-2022 Arm Limited and/or its affiliates <open-source-office@arm.com>
+.. SPDX-FileCopyrightText: Copyright 2018-2022, 2024 Arm Limited and/or its affiliates <open-source-office@arm.com>
 .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 .. header:: psa/crypto
@@ -273,7 +273,7 @@ Attribute accessors
 
     To make a key persistent, give it a persistent key identifier by using `psa_set_key_id()`. By default, a key that has a persistent identifier is stored in the default storage area identifier by `PSA_KEY_LIFETIME_PERSISTENT`. Call this function to choose a storage area, or to explicitly declare the key as volatile.
 
-    This function does not access storage, it merely stores the given value in the attribute object. The persistent key will be written to storage when the attribute object is passed to a key creation function such as `psa_import_key()`, `psa_generate_key()`, `psa_key_derivation_output_key()` or `psa_copy_key()`.
+    This function does not access storage, it merely stores the given value in the attribute object. The persistent key will be written to storage when the attribute object is passed to a key creation function such as `psa_import_key()`, `psa_generate_key()`, `psa_key_derivation_output_key()`, `psa_key_agreement()`, or `psa_copy_key()`.
 
     .. admonition:: Implementation note
 

doc/crypto/api/keys/management.rst

@@ -17,6 +17,7 @@ New keys can be created in the following ways:
 *   `psa_import_key()` creates a key from a data buffer provided by the application.
 *   `psa_generate_key()` creates a key from randomly generated data.
 *   `psa_key_derivation_output_key()` creates a key from data generated by a pseudorandom derivation process. See :secref:`kdf`.
+*   `psa_key_agreement()` creates a key from the shared secret result of a key agreement process. See :secref:`key-agreement`.
 *   `psa_copy_key()` duplicates an existing key with a different lifetime or with a more restrictive usage policy.
 
 When creating a key, the attributes for the new key are specified in a `psa_key_attributes_t` object. Each key creation function defines how it uses the attributes.

doc/crypto/api/library/library.rst

@@ -1,20 +1,20 @@
-.. SPDX-FileCopyrightText: Copyright 2018-2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
+.. SPDX-FileCopyrightText: Copyright 2018-2024 Arm Limited and/or its affiliates <open-source-office@arm.com>
 .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 |API| library
 =============
 
 .. header:: psa/crypto
     :seq: 1
-    :copyright: Copyright 2018-2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
+    :copyright: Copyright 2018-2024 Arm Limited and/or its affiliates <open-source-office@arm.com>
     :license: Apache-2.0
     :c++:
     :guard:
     :system-include: stddef.h stdint.h
     :include: psa/error.h
 
     /* This file is a reference template for implementation of the
-     * PSA Certified Crypto API v1.1
+     * PSA Certified Crypto API v1.2
      */
 
 

doc/crypto/api/library/status.rst

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: Copyright 2018-2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
+.. SPDX-FileCopyrightText: Copyright 2018-2024 Arm Limited and/or its affiliates <open-source-office@arm.com>
 .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 .. _status-codes:

doc/crypto/appendix/encodings.rst

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: Copyright 2022-2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
+.. SPDX-FileCopyrightText: Copyright 2022-2024 Arm Limited and/or its affiliates <open-source-office@arm.com>
 .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 .. _appendix-encodings:

doc/crypto/appendix/history.rst

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: Copyright 2018-2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
+.. SPDX-FileCopyrightText: Copyright 2018-2024 Arm Limited and/or its affiliates <open-source-office@arm.com>
 .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 Changes to the API
@@ -17,27 +17,23 @@ Changes between *1.1.2* and *1.2.0*
 Changes to the API
 ~~~~~~~~~~~~~~~~~~
 
-*   Added support for TLS 1.2 ECJPAKE-to-PMS key-derivation. See `PSA_ALG_TLS12_ECJPAKE_TO_PMS`.
-*   Changed the policy for `psa_key_derivation_verify_bytes()` and `psa_key_derivation_verify_key()`, so that these functions are also permitted when an input key has the `PSA_KEY_USAGE_DERIVE` usage flag.
-*   Removed the special treatment of :code:`PSA_ERROR_INVALID_SIGNATURE` for key derivation operations. A verification failure in `psa_key_derivation_verify_bytes()` and `psa_key_derivation_verify_key()` now puts the operation into an error state.
-*   Defined key derivation algorithms based on the Counter mode recommendations in :cite-title:`SP800-108`. See `PSA_ALG_SP800_108_COUNTER_HMAC()` and `PSA_ALG_SP800_108_COUNTER_CMAC`.
-
 *   Added `psa_key_agreement()` for standalone key agreement that outputs to a new key object. Also added `PSA_ALG_IS_STANDALONE_KEY_AGREEMENT()` as a synonym for `PSA_ALG_IS_RAW_KEY_AGREEMENT()`.
 
 *   Added support for the XChaCha20 cipher and XChaCha20-Poly1305 AEAD algorithms. See `PSA_KEY_TYPE_XCHACHA20` and `PSA_ALG_XCHACHA20_POLY1305`.
-
 *   Added support for :cite-title:`ZIGBEE` cryptographic algorithms. See `PSA_ALG_AES_MMO_ZIGBEE` and `PSA_ALG_CCM_STAR_NO_TAG`.
+*   Defined key derivation algorithms based on the Counter mode recommendations in :cite-title:`SP800-108`. See `PSA_ALG_SP800_108_COUNTER_HMAC()` and `PSA_ALG_SP800_108_COUNTER_CMAC`.
+*   Added support for TLS 1.2 ECJPAKE-to-PMS key-derivation. See `PSA_ALG_TLS12_ECJPAKE_TO_PMS`.
+
+*   Changed the policy for `psa_key_derivation_verify_bytes()` and `psa_key_derivation_verify_key()`, so that these functions are also permitted when an input key has the `PSA_KEY_USAGE_DERIVE` usage flag.
+*   Removed the special treatment of :code:`PSA_ERROR_INVALID_SIGNATURE` for key derivation operations. A verification failure in `psa_key_derivation_verify_bytes()` and `psa_key_derivation_verify_key()` now puts the operation into an error state.
 
 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.
-
 *   Changed terminology for clarification: a 'raw key agreement' algorithm is now a 'standalone key agreement', and a 'full key agreement' is a 'combined key agreement'.
 
-Other changes
-~~~~~~~~~~~~~
 
 Changes between *1.1.1* and *1.1.2*
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

doc/crypto/conf.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: Copyright 2018-2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
+# SPDX-FileCopyrightText: Copyright 2018-2024 Arm Limited and/or its affiliates <open-source-office@arm.com>
 # SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 # PSA Certified API document configuration
@@ -15,7 +15,7 @@
     'author': 'Arm Limited',
 
     # Document copyright date, default to year of 'date'
-    'copyright_date': '2018-2023',
+    'copyright_date': '2018-2024',
     'copyright': 'Arm Limited and/or its affiliates',
 
     # Arm document identifier, marked as open issue if not provided
@@ -30,9 +30,9 @@
     'issue_no': 0,
     # Identifies the sequence number of a release candidate of the same issue
     # default to None
-    'release_candidate': None,
+    'release_candidate': 1,
     # Draft status - use this to indicate the document is not ready for publication
-    'draft': True,
+    'draft': False,
 
     # Arm document confidentiality. Must be either Non-confidential or Confidential
     # Marked as open issue if not provided
@@ -43,7 +43,7 @@
     'license': 'psa-certified-api-license',
 
     # Document date, default to build date
-    'date': '23/03/2022',
+    #'date': '01/02/2024',
 
     # Default header file for API definitions
     # default to None, and can be set in documentation source

doc/crypto/overview/conventions.rst

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: Copyright 2018-2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
+.. SPDX-FileCopyrightText: Copyright 2018-2024 Arm Limited and/or its affiliates <open-source-office@arm.com>
 .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 .. _library-conventions:

doc/crypto/overview/functionality.rst

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: Copyright 2018-2023 Arm Limited and/or its affiliates <open-source-office@arm.com>
+.. SPDX-FileCopyrightText: Copyright 2018-2024 Arm Limited and/or its affiliates <open-source-office@arm.com>
 .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 .. _functionality-overview:
@@ -49,6 +49,7 @@ Keys are created using one of the *key creation functions*:
 *   `psa_import_key()`
 *   `psa_generate_key()`
 *   `psa_key_derivation_output_key()`
+*   `psa_key_agreement()`
 *   `psa_copy_key()`
 
 These output the key identifier, that is used to access the key in all other parts of the API.

doc/crypto/releases

@@ -1,4 +1,4 @@
-.. SPDX-FileCopyrightText: Copyright 2018-2022 Arm Limited and/or its affiliates <open-source-office@arm.com>
+.. SPDX-FileCopyrightText: Copyright 2018-2024 Arm Limited and/or its affiliates <open-source-office@arm.com>
 .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license
 
 .. release:: 1.0 Beta 1
@@ -54,7 +54,9 @@
     Clarifications and fixes
 
 .. release:: 1.2.0 Final
-    :date: ? 2023
+    :date: February 2024
     :confidentiality: Non-confidential
 
-    TBD
+    Better support for key agreement.
+
+    New algorithms for Zigbee, XChaCha, TLS 1.2, and key derivation.