Add XECDH protocol specification

src/draft-vandersmissen-acvp-xecdh.adoc

@@ -0,0 +1,78 @@
+= ACVP XECDH JSON Specification
+:doctype: internet-draft
+:docname: acvp-xecdh
+:docnumber: draft-vandersmissen-acvp-xecdh-01
+:abbrev: ACVP XECDH
+:ipr: trust200902
+:submission-type: independent
+:area: Internet
+:intended-series: informational
+:revdate: 2025-03-28
+:forename_initials: J.
+:lastname: Vandersmissen
+:fullname: Joachim Vandersmissen
+:organization: atsec information security corporation
+:street: 4516 Seton Center Parkway, Suite 250
+:city: Austin
+:code: 78759
+:country: United States of America
+:email: joachim@atsec.com
+:role: editor
+:docfile: draft-vandersmissen-acvp-xecdh.adoc
+:mn-document-class: ietf
+:mn-output-extensions: xml,rfc,txt,html
+:area: General
+:keyword: acvp, crypto
+
+// Singular name of the algorithm
+:spec-algorithm: Elliptic Curve Diffie-Hellman using Curve25519 and Curve448 (XECDH)
+:algo-short-name: XECDH
+
+include::common/common-sections/00-abstract.adoc[]
+
+include::common/common-sections/01-intro.adoc[]
+
+include::common/common-sections/02-conventions.adoc[]
+
+include::xecdh/sections/03-supported.adoc[]
+
+include::xecdh/sections/04-testtypes.adoc[]
+
+include::common/common-sections/05-capabilities-description.adoc[]
+
+include::common/common-sections/051-prerequisites.adoc[]
+
+include::xecdh/sections/05-capabilities.adoc[]
+
+include::xecdh/sections/05-xecdh-keygen-capabilities.adoc[]
+
+include::xecdh/sections/05-xecdh-keyver-capabilities.adoc[]
+
+include::xecdh/sections/05-xecdh-ssc-capabilities.adoc[]
+
+//include::common/common-sections/06-test-vector-intro.adoc[]
+
+include::xecdh/sections/06-test-vectors.adoc[]
+
+include::xecdh/sections/06-xecdh-keygen-test-vectors.adoc[]
+
+include::xecdh/sections/06-xecdh-keyver-test-vectors.adoc[]
+
+include::xecdh/sections/06-xecdh-ssc-test-vectors.adoc[]
+
+include::xecdh/sections/07-responses.adoc[]
+
+include::xecdh/sections/07-xecdh-keygen-responses.adoc[]
+
+include::xecdh/sections/07-xecdh-keyver-responses.adoc[]
+
+include::xecdh/sections/07-xecdh-ssc-responses.adoc[]
+
+include::common/common-sections/10-security.adoc[]
+
+include::common/common-sections/11-iana.adoc[]
+
+include::common/common-sections/99-acknowledgements.adoc[]
+
+// References must be given before appendixes
+include::xecdh/sections/98-references.adoc[]

src/xecdh/sections/03-supported.adoc

@@ -0,0 +1,9 @@
+
+[#supported]
+== Supported XECDH Algorithms
+
+The following XECDH algorithms *MAY* be advertised by the ACVP compliant cryptographic module:
+
+* XECDH / keyGen / RFC7748
+* XECDH / keyVer / RFC7748
+* XECDH / SSC / RFC7748

src/xecdh/sections/04-testtypes.adoc

@@ -0,0 +1,29 @@
+
+[#testtypes]
+== Test Types and Test Coverage
+
+[#ttypes]
+=== Test Types
+
+The ACVP server performs a set of tests on the specified XECDH algorithm in order to assess the correctness and robustness of the implementation, conformant to <<RFC7748>>. A typical ACVP validation session *SHALL* require multiple tests to be performed for every supported permutation of XECDH capabilities. This section describes the design of the tests used to validate implementations of the XECDH algorithms.
+
+* XECDH / keyGen / RFC7748 "AFT" - Algorithm Functional Test. The IUT is *REQUIRED* for each test case provided, to generate a key pair based on a curve. This information is then communicated to the ACVP server and validated.
+
+* XECDH / keyVer / RFC7748 "AFT" - Algorithm Functional Test. The ACVP server is *REQUIRED* to generate a series of public keys based on the IUT provided curve(s). The public keys generated by the server *MAY* or *MAY NOT* be valid, the IUT is *REQUIRED* to determine if the public keys provided in the test cases are valid or invalid keys as they relate to the curve.
+
+* XECDH / SSC / RFC7748 "AFT" - Algorithm Functional Test. The IUT *SHALL* act as a party in the Shared Secret Computation with the ACVP server. The server *SHALL* generate and provide all necessary information for the IUT to successfully compute a secret shared with the server.
+
+[[test_coverage]]
+=== Test Coverage
+
+* TBD...
+
+[[requirements_covered]]
+==== Requirements Covered
+
+* TBD...
+
+[[requirements_not_covered]]
+==== Requirements Not Covered
+
+* TBD...

src/xecdh/sections/05-capabilities.adoc

@@ -0,0 +1,34 @@
+
+[[prereq_algs]]
+=== Required Prerequisite Algorithms for XECDH Validations
+
+Each XECDH implementation relies on other cryptographic primitives. For example, XECDH uses an underlying DRBG algorithm. Each of these underlying algorithm primitives must be validated, either separately or as part of the same submission. ACVP provides a mechanism for specifying the required prerequisites:
+
+[[rereqs_table]]
+.Required XECDH Prerequisite Algorithms JSON Values
+|===
+| JSON Value | Description | JSON type | Valid Values
+
+| algorithm | a prerequisite algorithm | string | DRBG
+| valValue | algorithm validation number | string | actual number or "same"
+| prereqAlgVal | prerequisite algorithm validation | object with algorithm and valValue properties | see above
+| prereqVals | prerequisite algorithm validations | array of prereqAlgVal objects | see above
+|===
+
+[[XECDH_caps_reg]]
+=== XECDH Algorithm Capabilities Registration
+
+Each algorithm capability advertised is a self-contained JSON object using the following values
+
+[[caps_table]]
+.XECDH Algorithm Capabilities JSON Values
+|===
+| JSON Value | Description | JSON type | Valid Values
+
+| algorithm | The algorithm under test | string | "XECDH"
+| mode | The XECDH mode to be validated | string | "keyGen", "keyVer", or "SSC"
+| revision | The algorithm testing revision to use | string | "RFC7748"
+| prereqVals | prerequisite algorithm validations| array of prereqAlgVal objects | See <<prereq_algs>>
+|===
+
+The follwing sections offer additional *REQUIRED* JSON properties for each algorithm / mode / revision.

src/xecdh/sections/05-xecdh-keygen-capabilities.adoc

@@ -0,0 +1,37 @@
+[[mode_keyGen]]
+==== The XECDH keyGen Mode Capabilities
+
+Each XECDH keyGen mode capability set is advertised as a self-contained JSON object.
+
+[[mode_keyGenFullSet]]
+===== XECDH keyGen Full Set of Capabilities
+
+The complete list of XECDH key generation capabilities may be advertised by the ACVP compliant crypto module:
+
+[[keyGen_table]]
+.XECDH keyGen Capabilities JSON Values
+|===
+| JSON Value | Description | JSON type | Valid Values
+
+| curve | The curve names supported for the IUT in keyGen | array | Any non-empty subset of {"Curve25519", "Curve448"}
+|===
+
+An example of this is the following
+
+[source, json]
+----
+{
+    "algorithm": "XECDH",
+    "mode": "keyGen",
+    "revision": "RFC7748",
+    "prereqVals": [{
+            "algorithm": "DRBG",
+            "valValue": "123456"
+        }
+    ],
+    "curve": [
+        "Curve25519",
+        "Curve448"
+    ]
+}
+----

src/xecdh/sections/05-xecdh-keyver-capabilities.adoc

@@ -0,0 +1,37 @@
+[[mode_keyVer]]
+==== The XECDH keyVer Mode Capabilities
+
+Each XECDH keyVer mode capability set is advertised as a self-contained JSON object.
+
+[[mode_keyVerFullSet]]
+===== XECDH keyVer Full Set of Capabilities
+
+The complete list of XECDH key verification capabilities may be advertised by the ACVP compliant crypto module:
+
+[[keyVer_table]]
+.XECDH keyVer Capabilities JSON Values
+|===
+| JSON Value | Description | JSON type | Valid Values
+
+| curve | The curve names supported for the IUT in keyVer | array | Any non-empty subset of {"Curve25519", "Curve448"}
+|===
+
+An example of this is the following
+
+[source, json]
+----
+{
+    "algorithm": "XECDH",
+    "mode": "keyVer",
+    "revision": "RFC7748",
+    "prereqVals": [{
+            "algorithm": "DRBG",
+            "valValue": "123456"
+        }
+    ],
+    "curve": [
+        "Curve25519",
+        "Curve448"
+    ]
+}
+----

src/xecdh/sections/05-xecdh-ssc-capabilities.adoc

@@ -0,0 +1,37 @@
+[[mode_SSC]]
+==== The XECDH SSC Mode Capabilities
+
+Each XECDH SSC mode capability set is advertised as a self-contained JSON object.
+
+[[mode_SSCFullSet]]
+===== XECDH SSC Full Set of Capabilities
+
+The complete list of XECDH shared secret computation capabilities may be advertised by the ACVP compliant crypto module:
+
+[[SSC_table]]
+.XECDH SSC Capabilities JSON Values
+|===
+| JSON Value | Description | JSON type | Valid Values
+
+| curve | The curve names supported for the IUT in SSC | array | Any non-empty subset of {"Curve25519", "Curve448"}
+|===
+
+An example of this is the following
+
+[source, json]
+----
+{
+    "algorithm": "XECDH",
+    "mode": "SSC",
+    "revision": "RFC7748",
+    "prereqVals": [{
+            "algorithm": "DRBG",
+            "valValue": "123456"
+        }
+    ],
+    "curve": [
+        "Curve25519",
+        "Curve448"
+    ]
+}
+----

src/xecdh/sections/06-test-vectors.adoc

@@ -0,0 +1,33 @@
+[[tgjs]]
+== Test Vectors
+
+The ACVP server provides test vectors to the ACVP client, which are then processed and returned to the ACVP server for validation. A typical ACVP validation session would require multiple test vector sets to be downloaded and processed by the ACVP client. Each test vector set represents an individual XECDH function. This section describes the JSON schema for a test vector set used with XECDH algorithms.
+
+The test vector set JSON schema is a multi-level hierarchy that contains meta data for the entire vector set as well as individual test vectors to be processed by the ACVP client.The following table describes the JSON elements at the top level of the hierarchy.
+
+[[vs_top_table]]
+.Vector Set JSON Object
+|===
+| JSON Value | Description | JSON type
+
+| acvVersion | Protocol version identifier | string
+| vsId | Unique numeric identifier for the vector set | string
+| algorithm | Algorithm defined in the capability exchange | string
+| mode | Mode defined in the capability exchange | string
+| revision | Protocol test revision selected | string
+| testGroups | Array of test group JSON objects, which are defined in <<XECDH_keyGen_tgjs>>, <<XECDH_keyVer_tgjs>>, and <<XECDH_SSC_tgjs>> | array
+|===
+
+An example of this would look like this
+
+[source,json]
+----
+{
+  "acvVersion": "version",
+  "vsId": 1,
+  "algorithm": "Alg1",
+  "mode": "Mode1",
+  "revision": "RFC7748",
+  "testGroups": [ ... ]
+}
+----

src/xecdh/sections/06-xecdh-keygen-test-vectors.adoc

@@ -0,0 +1,61 @@
+[[XECDH_keyGen_tgjs]]
+=== XECDH keyGen Test Groups JSON Schema
+
+The testGroups element at the top level in the test vector JSON object is an array of test groups. Test vectors are grouped into similar test cases to reduce the amount of data transmitted in the vector set. For instance, all test vectors that use the same key size would be grouped together. The Test Group JSON object contains meta data that applies to all test vectors within the group. The following table describes the JSON elements of the Test Group JSON object.
+
+The test group for XECDH / keyGen / RFC7748 is as follows:
+
+[[XECDH_keyGen_vs_tg_table5]]
+.XECDH keyGen Test Group JSON Object
+|===
+| JSON Value | Description | JSON type
+
+| tgId | The test group identifier | integer
+| curve | The curve type used for the test vectors | string
+| testType | The testType for the group | string
+| tests | Array of individual test vector JSON objects, which are defined in <<XECDH_keyGen_tvjs>> | array
+|===
+
+[[XECDH_keyGen_tvjs]]
+=== XECDH keyGen Test Case JSON Schema
+
+Each test group contains an array of one or more test cases. Each test case is a JSON object that represents a single test vector to be processed by the ACVP client. The following table describes the JSON elements for each XECDH test vector.
+
+[[XECDH_keyGen_vs_tc_table5]]
+.Test Case JSON Object
+|===
+| JSON Value | Description | JSON type
+
+| tcId | Numeric identifier for the test case, unique across the entire vector set | integer
+|===
+
+NOTE: The client is responsible for generating a single key pair per test case.
+
+The following is an example of a prompt for XECDH / keyGen / RFC7748
+
+[source, json]
+----
+[
+    {
+        "acvVersion": <acvp-version>
+    },
+    {
+        "vsId": 1234,
+        "algorithm": "XECDH",
+        "mode": "keyGen",
+        "revision": "RFC7748",
+        "testGroups": [
+            {
+                "tgId": 1,
+                "curve": "Curve25519",
+                "testType": "AFT",
+                "tests": [
+                    {
+                        "tcId": 1
+                    }
+                ]
+            }
+        ]
+    }
+]
+----