From 1edf987a916affa566f8b31d7e3341a4a7cbadb8 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Tue, 30 Jan 2024 12:38:03 +0000 Subject: [PATCH] Change of document status to REL/Final * Update the configuration for 'Final' status (RC2) * Update references to the status * Update description of the API status throughout the document * Update the introduction text relating to the adoption of J-PAKE and SPAKE2+ --- doc/ext-pake/about.rst | 16 +++++++++++----- doc/ext-pake/api/encodings.rst | 5 ++--- doc/ext-pake/api/pake.rst | 9 +++------ doc/ext-pake/appendix/history.rst | 2 +- doc/ext-pake/conf.py | 6 +++--- doc/ext-pake/index.rst | 10 ++++------ doc/ext-pake/overview/intro.rst | 13 ++++++++----- doc/ext-pake/references | 6 ++++++ doc/ext-pake/releases | 6 ++++-- 9 files changed, 42 insertions(+), 31 deletions(-) diff --git a/doc/ext-pake/about.rst b/doc/ext-pake/about.rst index 2a554163..ed120396 100644 --- a/doc/ext-pake/about.rst +++ b/doc/ext-pake/about.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: Copyright 2022 Arm Limited and/or its affiliates +.. SPDX-FileCopyrightText: Copyright 2022, 2024 Arm Limited and/or its affiliates .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license .. include:: releases @@ -13,12 +13,18 @@ The detailed changes in each release are described in :secref:`changes`. .. potential-for-change:: - :hide: + + The contents of this specification are stable for version |docversion|. + + The following may change in updates to the version |docversion| specification: + + * Small optional feature additions. + * Clarifications. + + Significant additions, or any changes that affect the compatibility of the interfaces defined in this specification will only be included in a new major or minor version of the specification. .. current-status:: - This document is at Beta quality status which has a particular meaning to Arm of which the recipient must be aware. - A Beta quality specification will be sufficiently stable & committed for initial product development, however all aspects of the architecture described herein remain SUBJECT TO CHANGE. - Please ensure that you have the latest revision. + This document is at Release/Final quality status. .. about:: diff --git a/doc/ext-pake/api/encodings.rst b/doc/ext-pake/api/encodings.rst index 6f573eef..bd79abef 100644 --- a/doc/ext-pake/api/encodings.rst +++ b/doc/ext-pake/api/encodings.rst @@ -6,12 +6,11 @@ Algorithm and key type encoding =============================== -These are encodings for a proposed PAKE interface for :cite-title:`PSA-CRYPT`. -It is not part of the official |API| yet. +These are encodings for a PAKE interface for :cite-title:`PSA-CRYPT`. .. note:: - The content of this specification is not part of the stable |API| and may change substantially from version to version. + These encodings will be integrated into a future version of :cite:`PSA-CRYPT`. Algorithm encoding ------------------ diff --git a/doc/ext-pake/api/pake.rst b/doc/ext-pake/api/pake.rst index 039a11e7..3696e219 100644 --- a/doc/ext-pake/api/pake.rst +++ b/doc/ext-pake/api/pake.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: Copyright 2022-2023 Arm Limited and/or its affiliates +.. SPDX-FileCopyrightText: Copyright 2022-2024 Arm Limited and/or its affiliates .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license Password-authenticated key exchange (PAKE) @@ -6,10 +6,7 @@ Password-authenticated key exchange (PAKE) .. note:: - This is a proposed PAKE interface for :cite-title:`PSA-CRYPT`. - It is not part of the official |API| yet. - - The content of this specification is not part of the stable |API| and may change substantially from version to version. + The API defined in this specification will be integrated into a future version of :cite:`PSA-CRYPT`. This chapter is divided into the following sections: @@ -37,7 +34,7 @@ Common API for PAKE :license: Apache-2.0 /* This file contains reference definitions for implementation of the - * PSA Certified Crypto API v1.2 PAKE Extension beta.2 + * PSA Certified Crypto API v1.2 PAKE Extension * * These definitions must be embedded in, or included by, psa/crypto.h */ diff --git a/doc/ext-pake/appendix/history.rst b/doc/ext-pake/appendix/history.rst index 9488f65d..55190640 100644 --- a/doc/ext-pake/appendix/history.rst +++ b/doc/ext-pake/appendix/history.rst @@ -11,7 +11,7 @@ Document change history This section provides the detailed changes made between published version of the document. -Changes between *Beta 1* and *Beta 2* +Changes between *Beta 1* and *Final* ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ API changes diff --git a/doc/ext-pake/conf.py b/doc/ext-pake/conf.py index 3be05500..3682cda9 100644 --- a/doc/ext-pake/conf.py +++ b/doc/ext-pake/conf.py @@ -26,13 +26,13 @@ 'extension_doc': 'PAKE Extension', # Arm document quality status, marked as open issue if not provided - 'quality': 'BET', + 'quality': 'REL', # Arm document issue number (within that version and quality status) # Marked as open issue if not provided - 'issue_no': 2, + 'issue_no': 0, # Identifies the sequence number of a release candidate of the same issue # default to None - 'release_candidate': 1, + 'release_candidate': 2, # Draft status - use this to indicate the document is not ready for publication 'draft': False, diff --git a/doc/ext-pake/index.rst b/doc/ext-pake/index.rst index 5161a5a8..31689078 100644 --- a/doc/ext-pake/index.rst +++ b/doc/ext-pake/index.rst @@ -1,15 +1,13 @@ -.. SPDX-FileCopyrightText: Copyright 2022-2023 Arm Limited and/or its affiliates +.. SPDX-FileCopyrightText: Copyright 2022-2024 Arm Limited and/or its affiliates .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license .. title:: - .. banner:: BETA RELEASE + .. banner:: FINAL RELEASE - This is a proposed update to the :cite-title:`PSA-CRYPT` specification. + This is an extension to the :cite-title:`PSA-CRYPT` specification. - This is a BETA release in order to enable wider review and feedback on the changes proposed to be included in a future version of the specification. - - At this quality level, the proposed changes and interfaces are complete, and suitable for initial product development. However, the specification is still subject to change. + This is a FINAL release: the proposed changes and interfaces are complete and finalized, and suitable for product development. .. abstract:: diff --git a/doc/ext-pake/overview/intro.rst b/doc/ext-pake/overview/intro.rst index cc5adf3d..93b4457c 100644 --- a/doc/ext-pake/overview/intro.rst +++ b/doc/ext-pake/overview/intro.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: Copyright 2022-2023 Arm Limited and/or its affiliates +.. SPDX-FileCopyrightText: Copyright 2022-2024 Arm Limited and/or its affiliates .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license Introduction @@ -14,13 +14,13 @@ About the |API| PAKE Extension This document defines an extension to the :cite-title:`PSA-CRYPT` specification, to provide support for :term:`Password-authenticated key exchange` (PAKE) protocols, and specifically for the J-PAKE and SPAKE2+ protocols. -When the proposed extension API is sufficiently stable to be classed as Final, it will be integrated into a future version of `[PSA-CRYPT]`. +This extension API is now classed as Final, and it will be integrated into a future version of `[PSA-CRYPT]`. This specification must be read and implemented in conjunction with `[PSA-CRYPT]`. All of the conventions, design considerations, and implementation considerations that are described in `[PSA-CRYPT]` apply to this specification. .. rationale:: Note - This version of the document includes *Rationale* commentary that provides background information relating to the design decisions that led to the current proposal. This enables the reader to understand the wider context and alternative approaches that have been considered. + This version of the document includes *Rationale* commentary that provides background information relating to the API design. This enables the reader to understand the wider context and alternative approaches that have been considered. Objectives for the PAKE Extension @@ -42,7 +42,10 @@ Requests ^^^^^^^^ Some PAKE schemes have been requested by the community and need to be supported. -Currently, these are SPAKE2+ and J-PAKE (in particular the Elliptic Curve based variant, sometimes known as ECJPAKE) +Currently, these are: + +* SPAKE2+ --- used in :cite-title:`MATTER` +* J-PAKE (in particular the Elliptic Curve based variant, sometimes known as ECJPAKE) --- used in :cite-title:`THREAD`. Standardization ^^^^^^^^^^^^^^^ @@ -67,7 +70,7 @@ Some of these schemes are used in popular protocols. This information confirms t * - J-PAKE - TLS, THREAD v1 * - SPAKE2+ - - CHIP + - MATTER * - SRP - TLS * - OPAQUE diff --git a/doc/ext-pake/references b/doc/ext-pake/references index 2d65bf26..9591ce0d 100644 --- a/doc/ext-pake/references +++ b/doc/ext-pake/references @@ -41,3 +41,9 @@ :author: IETF :publication: December 2020 :url: datatracker.ietf.org/doc/draft-bar-cfrg-spake2plus-02 + +.. reference:: THREAD + :title: Thread Specification 1.3.0 + :author: Thread Group + :publication: July 2022 + :url: www.threadgroup.org/ThreadSpec diff --git a/doc/ext-pake/releases b/doc/ext-pake/releases index bcb55e23..127b0a0d 100644 --- a/doc/ext-pake/releases +++ b/doc/ext-pake/releases @@ -13,10 +13,12 @@ Relicensed as open source under CC BY-SA 4.0. -.. release:: Beta 2 - :date: January 2024 +.. release:: Final + :date: February 2024 :confidentiality: Non-confidential Add support for the SPAKE2+ protocol. Rework the API to support augmented PAKE protocols, improve ease of use and implementation. + + API status is now Final/Release.