Network Working Group C. Celi, Ed. Internet-Draft 3 April 2024 Intended status: Informational Expires: 5 October 2024 ACVP SHA3 and SHAKE JSON Specification draft-ietf-acvp-sub-sha3-01 Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 5 October 2024. Copyright Notice Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Table of Contents 1. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 2 2. Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . 2 3. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 4. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 3 4.1. Notation conventions . . . . . . . . . . . . . . . . . . 3 4.2. Terms and Definitions . . . . . . . . . . . . . . . . . . 3 4.2.1. Prompt . . . . . . . . . . . . . . . . . . . . . . . 3 4.2.2. Registration . . . . . . . . . . . . . . . . . . . . 3 4.2.3. Response . . . . . . . . . . . . . . . . . . . . . . 3 Celi Expires 5 October 2024 [Page 1] Internet-Draft ACVP SHA3 April 2024 4.2.4. Test Case . . . . . . . . . . . . . . . . . . . . . . 3 4.2.5. Test Group . . . . . . . . . . . . . . . . . . . . . 3 4.2.6. Test Vector Set . . . . . . . . . . . . . . . . . . . 3 4.2.7. Validation . . . . . . . . . . . . . . . . . . . . . 4 5. Supported Hash Algorithms . . . . . . . . . . . . . . . . . . 4 6. Test Types and Test Coverage . . . . . . . . . . . . . . . . 4 6.1. Test Types . . . . . . . . . . . . . . . . . . . . . . . 4 6.2. Monte Carlo tests for SHA3 and SHAKE . . . . . . . . . . 5 6.2.1. SHA3 Monte Carlo Test . . . . . . . . . . . . . . . . 5 6.2.2. SHAKE Monte Carlo Test . . . . . . . . . . . . . . . 6 6.3. Large Data tests for SHA-3 . . . . . . . . . . . . . . . 7 6.4. Test Coverage . . . . . . . . . . . . . . . . . . . . . . 8 6.4.1. SHA3 Requirements Covered . . . . . . . . . . . . . . 8 6.4.2. SHA3 Requirements Not Covered . . . . . . . . . . . . 8 6.4.3. SHAKE Requirements Covered . . . . . . . . . . . . . 8 6.4.4. SHAKE Requirements Not Covered . . . . . . . . . . . 9 7. Capabilities Registration . . . . . . . . . . . . . . . . . . 9 7.1. Prerequisites . . . . . . . . . . . . . . . . . . . . . . 9 7.2. SHA3 and SHAKE Algorithm Capabilities Registration . . . 10 8. Test Vectors . . . . . . . . . . . . . . . . . . . . . . . . 15 8.1. Test Groups . . . . . . . . . . . . . . . . . . . . . . . 16 8.2. Test Case JSON Schema . . . . . . . . . . . . . . . . . . 17 8.3. Test Vector Responses . . . . . . . . . . . . . . . . . . 21 9. Security Considerations . . . . . . . . . . . . . . . . . . . 26 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 11. Normative References . . . . . . . . . . . . . . . . . . . . 26 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 27 1. Acknowledgements There are no acknowledgements. 2. Abstract This document defines the JSON schema for testing SHA3 and SHAKE implementations with the ACVP specification. 3. Introduction The Automated Crypto Validation Protocol (ACVP) defines a mechanism to automatically verify the cryptographic implementation of a software or hardware crypto module. The ACVP specification defines how a crypto module communicates with an ACVP server, including crypto capabilities negotiation, session management, authentication, vector processing and more. The ACVP specification does not define algorithm specific JSON constructs for performing the crypto validation. A series of ACVP sub-specifications define the constructs for testing individual crypto algorithms. Each sub- Celi Expires 5 October 2024 [Page 2] Internet-Draft ACVP SHA3 April 2024 specification addresses a specific class of crypto algorithms. This sub-specification defines the JSON constructs for testing SHA3 and SHAKE implementations using ACVP. 4. Conventions 4.1. Notation conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "*NOT RECOMMENDED*", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 of [RFC2119] and [RFC8174] when, and only when, they appear in all capitals, as shown here. 4.2. Terms and Definitions 4.2.1. Prompt JSON sent from the server to the client describing the tests the client performs 4.2.2. Registration The initial request from the client to the server describing the capabilities of one or several algorithm, mode and revision combinations 4.2.3. Response JSON sent from the client to the server in response to the prompt 4.2.4. Test Case An individual unit of work within a prompt or response 4.2.5. Test Group A collection of test cases that share similar properties within a prompt or response 4.2.6. Test Vector Set A collection of test groups under a specific algorithm, mode, and revision Celi Expires 5 October 2024 [Page 3] Internet-Draft ACVP SHA3 April 2024 4.2.7. Validation JSON sent from the server to the client that specifies the correctness of the response 5. Supported Hash Algorithms The following SHA3-based hash algorithms MAY be advertised by this ACVP compliant crypto module: * SHA3-224 / null / 1.0 * SHA3-256 / null / 1.0 * SHA3-384 / null / 1.0 * SHA3-512 / null / 1.0 * SHA3-224 / null / 2.0 * SHA3-256 / null / 2.0 * SHA3-384 / null / 2.0 * SHA3-512 / null / 2.0 * SHAKE-128 / null / 1.0 * SHAKE-256 / null / 1.0 Other hash algorithms MAY be advertised by the ACVP module elsewhere. 6. Test Types and Test Coverage This section describes the design of the tests used to validate implementations of SHA3 and SHAKE. 6.1. Test Types There are four types of tests for these hash functions: functional tests, Monte Carlo tests, Variable Output tests and Large Data tests. Each has a specific value to be used in the testType field. The testType field definitions are: * "AFT" - Algorithm Functional Test. These tests can be processed by the client using a normal 'hash' operation. AFTs cause the implementation under test to exercise normal operations on a single block, multiple blocks, or partial blocks. In all cases, Celi Expires 5 October 2024 [Page 4] Internet-Draft ACVP SHA3 April 2024 random data is used. The functional tests are designed to verify that the logical components of the hash function or extenable output function (block chunking, block padding etc.) are operating correctly. * "MCT" - Monte Carlo Test. These tests exercise the implementation under test under strenuous circumstances. The implementation under test must process the test vectors according to the correct algorithm and mode in this document. MCTs can help detect potential memory leaks over time, and problems in allocation of resources, addressing variables, error handling, and generally improper behavior in response to random inputs. Each MCT processes 100 pseudorandom tests. Each algorithm and mode SHOULD have at least one MCT group. See Section 6.2 for implementation details. * "VOT" - Variable Output Test. These tests are for SHAKE only, and ensure that an IUT can properly perform the extendable output function to produce digests of specifc lengths. These tests differ from the AFTs for SHAKE in that the AFTs all produce a single digest size, matching the security strength of the extendable output function. The VOTs SHALL produce varying digest sizes based on the capabilities of the IUT. * "LDT" - Large Data Test. These tests are for SHA3 only. This test performs the hash function on a message that is multiple gigabytes in length. This pushes the bounds of 32-bit data types to ensure an implementation can handle all types of data. See [LDT] for more information motivating the LDT. As a multiple gigabyte message cannot be communicated naturally via ACVP, a specific structure is outlined in Section 6.3. 6.2. Monte Carlo tests for SHA3 and SHAKE 6.2.1. SHA3 Monte Carlo Test The MCTs start with an initial condition (SEED which is a single message) and perform a series of chained computations. The algorithm is shown below. | NOTE: The MCTs were updated, 7/2023, to support the case where | !SupportedMessageLengths.Contains(digestSize), a limitation of | the original MCT design. As part of this change, a new | property, mctVersion, was added to the MCT test group JSON (See | Table 5). When a value of "standard" is provided for | mctVersion in the prompt file, the standard MCT test is run. | When a value of "alternate" is provided for mctVersion in the | prompt file, the alternate MCT test is run. When the standard Celi Expires 5 October 2024 [Page 5] Internet-Draft ACVP SHA3 April 2024 | test is run, the MSG hashed will always be either the length of | the SEED or the length of the digest size. When the alternate | test is run, the MSG hashed will always be the length of the | SEED. SHA-3 Standard Monte Carlo Test: For j = 0 to 99 MD[0] = SEED; For i = 1 to 1000 MSG = MD[i-1] MD[i] = SHA3(MSG) Output MD[1000] SEED = MD[1000] SHA-3 Alternate Monte Carlo Test: MD[0] = SEED INITIAL_SEED_LENGTH = LEN(SEED) For 100 iterations For i = 1 to 1000 MSG = MD[i-1]; if LEN(MSG) >= INITIAL_SEED_LENGTH: MSG = leftmost INITIAL_SEED_LENGTH bits of MSG else: MSG = MSG || INITIAL_SEED_LENGTH - LEN(MSG) 0 bits MD[i] = SHA3(MSG) MD[0] = MD[1000] Output MD[0] 6.2.2. SHAKE Monte Carlo Test The MCTs start with an initial condition (SEED which is a single message) and perform a series of chained computations. Some values used in the algorithm are based on properties provided during the registration. They are as follows. * minOutBytes = smallest number of bytes supported * maxOutBytes = largest number of bytes supported The SHAKE function used in the pseudocode takes in a bitstring and a desired output length in bits. The MSG[i] input to SHAKE MUST always contain at least 128 bits. If this is not the case as the previous digest was too short, append empty bits to the rightmost side of the digest. The MCT algorithm is shown below. Celi Expires 5 October 2024 [Page 6] Internet-Draft ACVP SHA3 April 2024 Range = maxOutBytes - minOutBytes + 1 OutputLen = maxOutBytes For j = 0 to 99 MD[0] = SEED For i = 1 to 1000 MSG[i] = 128 leftmost bits of MD[i-1] if (MSG[i] < 128 bits) Append 0 bits on rightmost side of MSG[i] til MSG[i] is 128 bits MD[i] = SHAKE(MSG[i], OutputLen * 8) RightmostOutputBits = 16 rightmost bits of MD[i] as an integer OutputLen = minOutBytes + (RightmostOutputBits % Range) Output MD[1000], OutputLen SEED = MD[1000] 6.3. Large Data tests for SHA-3 The large data tests are intended to test the ability of a module to hash multiple gigabytes of data at once. This much information cannot be communicated via the JSON files as a normal message property. Instead a new type is defined as a large data type. It is an object that contains a small content hex string, a content length in bits, a full length in bits and an expansion technique string. The following is an example of this structure. "largeMsg": { "content": "DE26", "contentLength": 16, "fullLength": 42949672960, "expansionTechnique": "repeating" } The 'contentLength' property describes the number of bits in the 'content' property. The 'content' property is the hex string that can be expanded to the full large message. The 'expansionTechnique' describes the process used to obtain the full large message. The 'fullLength' is the final length of the full large message. There may be multiple 'expansionTechnique' types defined. Here are the types defined for SHA-3 testing. * "repeating" - Append the number of content bits specified in 'contentLength' to itself as many times as needed until a hex string of exactly 'fullLength' bits is acquired. In the example shown, the final large message would have the form "DE26DE26DE26...DE26". Celi Expires 5 October 2024 [Page 7] Internet-Draft ACVP SHA3 April 2024 There are multiple ways hash functions can be implemented in an IUT. The most common are via a single Hash() call on the message or via a series of Init(), any number of Update(), Final() calls. As noted in [LDT], the difference between these hashing techniques can have consequences in the cryptographic module. If both interfaces are offered and accessible for testing, the IUT MUST only utilize a single Update() call for the large message. 6.4. Test Coverage The tests described in this document have the intention of ensuring an implementation is conformant to [FIPS202]. 6.4.1. SHA3 Requirements Covered Sections 3 through 6 in [FIPS202] outline the Keccak construction and strucures needed to form a valid SHA3 implementation. Normal AFTs test these operations by running the algorithm. Section 7 in [FIPS202] states that any input sizes may be used within a SHA3 hash implementation. The input sizes tested in this document range from 0 bits to 65536 bits. In addition a large data test is available by special request which tests messages that are multiple gigabytes in size. 6.4.2. SHA3 Requirements Not Covered It is noted that [FIPS202] states that "different procedures that produce the correct output for every input are permitted" and thus the internal states discussed in Sections 3 through 6 SHALL NOT be tested or tracked. 6.4.3. SHAKE Requirements Covered Sections 3 through 6 in [FIPS202] outline the Keccak construction and strucures needed to form a valid SHAKE implementation. Normal AFTs test these operations by running the algorithm. VOTs exercise the ability of the implementation to perform the algorithm as well by focusing on the sponge construction. Section 7 in [FIPS202] states that any input sizes or output sizes may be used within a SHAKE implementation. The input sizes tested in this document range from 0 bits to 65536 bits. The output sizes tested in this document range from 16 bits to 65536 bits. Celi Expires 5 October 2024 [Page 8] Internet-Draft ACVP SHA3 April 2024 6.4.4. SHAKE Requirements Not Covered Again, the internal states discussed in Sections 3 through 6 SHALL NOT be tested or tracked. 7. Capabilities Registration ACVP requires crypto modules to register their capabilities. This allows the crypto module to advertise support for specific algorithms, notifying the ACVP server which algorithms need test vectors generated for the validation process. This section describes the constructs for advertising support of SHA3 and SHAKE algorithms to the ACVP server. The algorithm capabilities MUST be advertised as JSON objects within the 'algorithms' value of the ACVP registration message. The 'algorithms' value is an array, where each array element is an individual JSON object defined in this section. The 'algorithms' value is part of the 'capability_exchange' element of the ACVP JSON registration message. See the ACVP specification [ACVP] for more details on the registration message. 7.1. Prerequisites Each algorithm implementation MAY rely on other cryptographic primitives. For example, RSA Signature algorithms depend on an underlying hash function. 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: Prerequisites, if applicable, MUST be submitted in the registration as the prereqVals JSON property array inside each element of the algorithms array. Each element in the prereqVals array MUST contain the following properties +===============+=============================+===========+ | JSON Property | Description | JSON Type | +===============+=============================+===========+ | algorithm | a prerequisite algorithm | string | +---------------+-----------------------------+-----------+ | valValue | algorithm validation number | string | +---------------+-----------------------------+-----------+ Table 1: Prerequisite Properties Celi Expires 5 October 2024 [Page 9] Internet-Draft ACVP SHA3 April 2024 A "valValue" of "same" SHALL be used to indicate that the prerequisite is being met by a different algorithm in the capability exchange in the same registration. An example description of prerequisites within a single algorithm capability exchange looks like this "prereqVals": [ { "algorithm": "Alg1", "valValue": "Val-1234" }, { "algorithm": "Alg2", "valValue": "same" } ] 7.2. SHA3 and SHAKE Algorithm Capabilities Registration Each SHA3 and SHAKE algorithm capability advertised SHALL be a self- contained JSON object. The following JSON values are used for hash algorithm capabilities: Celi Expires 5 October 2024 [Page 10] Internet-Draft ACVP SHA3 April 2024 +======================+==================================+=========+ | JSON Value | Description | JSON | | | | type | +======================+==================================+=========+ | algorithm | The hash algorithm and mode | string | | | to be validated. | | +----------------------+----------------------------------+---------+ | revision | The algorithm testing | string | | | revision to use. | | +----------------------+----------------------------------+---------+ | inBit | Implementation does accept | boolean | | | bit-oriented messages | | +----------------------+----------------------------------+---------+ | inEmpty | Implementation does accept | boolean | | | null (zero-length) messages | | +----------------------+----------------------------------+---------+ | outputLen | Output length for SHAKE. | domain | | | The value for the outputLen | | | | property must consist either | | | | of a single range object or | | | | a single literal value. | | | | This restriction is made to | | | | simplify the implementation | | | | of the Monte Carlo Tests | | | | (see Section 6.2.2). | | +----------------------+----------------------------------+---------+ | outBit | SHAKE can output bit- | boolean | | | oriented messages | | +----------------------+----------------------------------+---------+ | messageLength | The message lengths in bits | domain | | | supported by the IUT. | | | | Minimum allowed is 0, | | | | maximum allowed is 65536. | | +----------------------+----------------------------------+---------+ | performLargeDataTest | Determines if the server | integer | | | should include the large | array | | | data test group defined in | | | | Section 6.3. This property | | | | is OPTIONAL, and shall | | | | include the lengths in GiB | | | | being tested. Valid options | | | | are {1, 2, 4, 8}. | | +----------------------+----------------------------------+---------+ Table 2: SHA3 and SHAKE Algorithm Capabilities JSON Values | NOTE 1: The lengths provided in the 'performLargeDataTest' | property are in gibibytes. 1GiB is equivalent to 2^30 bytes. Celi Expires 5 October 2024 [Page 11] Internet-Draft ACVP SHA3 April 2024 | NOTE 2: At least one messageLength > 0 must be supported by an | IUT in order to accommodate MCT testing. The following grid outlines which properties are REQUIRED, as well as all the possible values a server MAY support for SHA3 and SHAKE algorithms: Celi Expires 5 October 2024 [Page 12] Internet-Draft ACVP SHA3 April 2024 +=========+========+=====+=======+=========+======+=============+====================+ |algorithm|revision|inBit|inEmpty|outputLen|outBit|messageLength|performLargeDataTest| +=========+========+=====+=======+=========+======+=============+====================+ |SHA3-224 |1.0 |true,|true, | | | |[1, 2, 4, 8] | | | |false|false | | | | | +---------+--------+-----+-------+---------+------+-------------+--------------------+ |SHA3-256 |1.0 |true,|true, | | | |[1, 2, 4, 8] | | | |false|false | | | | | +---------+--------+-----+-------+---------+------+-------------+--------------------+ |SHA3-384 |1.0 |true,|true, | | | |[1, 2, 4, 8] | | | |false|false | | | | | +---------+--------+-----+-------+---------+------+-------------+--------------------+ |SHA3-512 |1.0 |true,|true, | | | |[1, 2, 4, 8] | | | |false|false | | | | | +---------+--------+-----+-------+---------+------+-------------+--------------------+ |SHA3-224 |2.0 | | | | |{"Min": 0, |[1, 2, 4, 8] | | | | | | | |"Max": 65536,| | | | | | | | |"Inc": any} | | +---------+--------+-----+-------+---------+------+-------------+--------------------+ |SHA3-256 |2.0 | | | | |{"Min": 0, |[1, 2, 4, 8] | | | | | | | |"Max": 65536,| | | | | | | | |"Inc": any} | | +---------+--------+-----+-------+---------+------+-------------+--------------------+ |SHA3-384 |2.0 | | | | |{"Min": 0, |[1, 2, 4, 8] | | | | | | | |"Max": 65536,| | | | | | | | |"Inc": any} | | +---------+--------+-----+-------+---------+------+-------------+--------------------+ |SHA3-512 |2.0 | | | | |{"Min": 0, |[1, 2, 4, 8] | | | | | | | |"Max": 65536,| | | | | | | | |"Inc": any} | | +---------+--------+-----+-------+---------+------+-------------+--------------------+ |SHAKE-128|1.0 |true,|true, |{"Min": |true, | | | | | |false|false |16, |false | | | | | | | |"Max": | | | | | | | | |65536, | | | | | | | | |"Inc": | | | | | | | | |any} | | | | +---------+--------+-----+-------+---------+------+-------------+--------------------+ |SHAKE-256|1.0 |true,|true, |{"Min": |true, | | | | | |false|false |16, |false | | | | | | | |"Max": | | | | | | | | |65536, | | | | | | | | |"Inc": | | | | | | | | |any} | | | | +---------+--------+-----+-------+---------+------+-------------+--------------------+ Table 3: SHA3 and SHAKE Capabilities Applicability Grid Celi Expires 5 October 2024 [Page 13] Internet-Draft ACVP SHA3 April 2024 The following is a example JSON object advertising support for SHA3-256 for testing revision 1.0. { "algorithm": "SHA3-256", "revision": "1.0", "mode": null, "inBit": true, "inEmpty": true, "performLargeDataTest": [1, 2, 4, 8] } The following is an example JSON object advertising support for SHAKE-128. { "algorithm": "SHAKE-128", "revision": "1.0", "mode": null, "inBit": true, "inEmpty": true, "outBit": true, "outputLen": [ { "min": 16, "max": 1024 } ] } The following is a example JSON object advertising support for SHA3-256 for testing revision 2.0. { "algorithm": "SHA3-256", "revision": "2.0", "mode": null, "messageLength": [{"min": 0, "max": 65536, "increment": 1}], "performLargeDataTest": [1, 2, 4, 8] } | NOTE: Since the increment is 1 in the above, and the minimum | value within the message length is zero, this is effectively an | "inBit" and "inEmpty" registration from the 1.0 revision | testing. If the implementation supports only byte length | messages, you could use an increment of 8. Celi Expires 5 October 2024 [Page 14] Internet-Draft ACVP SHA3 April 2024 8. 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 test session would require multiple test vector sets to be downloaded and processed by the ACVP client. Each test vector set represents an individual algorithm defined during the capability exchange. This section describes the JSON schema for a test vector set used with SHA3 and SHAKE 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. +=============+======================================+===========+ | JSON Values | Description | JSON Type | +=============+======================================+===========+ | acvVersion | Protocol version identifier | string | +-------------+--------------------------------------+-----------+ | vsId | Unique numeric vector set identifier | integer | +-------------+--------------------------------------+-----------+ | algorithm | Algorithm defined in the capability | string | | | exchange | | +-------------+--------------------------------------+-----------+ | mode | Mode defined in the capability | string | | | exchange | | +-------------+--------------------------------------+-----------+ | revision | Protocol test revision selected | string | +-------------+--------------------------------------+-----------+ | testGroups | Array of test groups containing test | array | | | data, see Section 8.1 | | +-------------+--------------------------------------+-----------+ Table 4: Top Level Test Vector JSON Elements An example of this would look like this Celi Expires 5 October 2024 [Page 15] Internet-Draft ACVP SHA3 April 2024 [ { "acvVersion": }, { "vsId": 1, "algorithm": "Alg1", "mode": "Mode1", "revision": "Revision1.0", "testGroups": [ ... ] } ] 8.1. Test Groups Test vector sets MUST contain one or many test groups, each sharing similar properties. For instance, all test vectors that use the same key size would be grouped together. The testGroups element at the top level of the test vector JSON object SHALL be the array of test groups. The Test Group JSON object MUST contain meta-data that applies to all test cases within the group. The following table describes the JSON elements that MUST appear from the server in the Test Group JSON object: +============+========================================+==========+ | JSON Value | Description | JSON | | | | type | +============+========================================+==========+ | tgId | Numeric identifier for the test group, | integer | | | unique across the entire vector set. | | +------------+----------------------------------------+----------+ | testType | Test category type. AFT, MCT or VOT | value | | | as defined in Section 6 | | +------------+----------------------------------------+----------+ | mctVersion | When testType is MCT, the type of MCT | string | | | being run, i.e., "standard" or | | | | "alternate" | | +------------+----------------------------------------+----------+ | tests | Array of individual test case JSON | array of | | | objects, which are defined in | testCase | | | Section 8.2 | objects | +------------+----------------------------------------+----------+ Table 5: Test Group JSON Object Celi Expires 5 October 2024 [Page 16] Internet-Draft ACVP SHA3 April 2024 8.2. Test Case JSON Schema Each test group SHALL contain an array of one or more test cases. Each test case is a JSON object that represents a single case to be processed by the ACVP client. The following table describes the JSON elements for each test case. +==========+=====================================+==================+ | JSON | Description | JSON type | | Value | | | +==========+=====================================+==================+ | tcId | Numeric identifier for the | integer | | | test case, unique across the | | | | entire vector set. | | +----------+-------------------------------------+------------------+ | len | Length of the message or | integer | | | seed | | +----------+-------------------------------------+------------------+ | outLen | Length of the digest | integer | +----------+-------------------------------------+------------------+ | msg | Value of the message or | string (hex) | | | seed. Messages are | | | | represented as little-endian | | | | hex for all SHA3 variations. | | +----------+-------------------------------------+------------------+ | largeMsg | Object describing the | large data | | | message for an LDT group | object, see | | | | Section 6.3 for | | | | more information | +----------+-------------------------------------+------------------+ Table 6: Test Case JSON Object | NOTE 1: All properties listed in the above table are REQUIRED | except for outLen which is only REQUIRED when the algorithm is | SHAKE-128 or SHAKE-256. | NOTE 2: The maximum value for SHAKE-128 for 'len' is 65,904 | bits when the inBit parameter is set to true in the | capabilities registration and 66,240 bits when it is set to | false. The maximum value for SHAKE-256 for 'len' is 66,428 | bits when the inBit parameter is set to true in the | capabilities registration and 65,752 bits when it is set to | false. Celi Expires 5 October 2024 [Page 17] Internet-Draft ACVP SHA3 April 2024 The following are example JSON objects for secure hash test vectors sent from the ACVP server to the crypto module. Notice that the single bit message is represented as "01". This complies with the little-endian nature of SHA3. All hex displayed is little-endian bit order when associated with SHA3 or any of its variations. [ { "acvVersion": }, { "vsId": 1564, "algorithm": "SHA3-512", "revision": "1.0", "testGroups": [ { "tgId": 1, "testType": "AFT", "tests": [ { "tcId": 1, "len": 0, "msg": "00" }, { "tcId": 2, "len": 1, "msg": "01" }] }, { "tgId": 2, "testType": "MCT", "mctVersion": "standard", "tests": [ { "tcId": 3, "len": 512, "msg": "30850bd984b14ff5aff18993329...", }] }, { "tgId": 3, "testType": "LDT", "tests": [ { "tcId": 4, "largeMsg": { "content": "DE26", "contentLength": 16, Celi Expires 5 October 2024 [Page 18] Internet-Draft ACVP SHA3 April 2024 "fullLength": 42949672960, "expansionTechnique": "repeating" } } ] }] } ] [ { "acvVersion": }, { "vsId": 1565, "algorithm": "SHA3-512", "revision": "2.0", "testGroups": [ { "tgId": 1, "testType": "AFT", "tests": [ { "tcId": 1, "len": 0, "msg": "00" }, { "tcId": 2, "len": 1, "msg": "01" }] }, { "tgId": 2, "testType": "MCT", "tests": [ { "tcId": 3, "len": 512, "msg": "30850bd984b14ff5aff18993329...", }] }, { "tgId": 3, "testType": "LDT", "tests": [ { "tcId": 4, "largeMsg": { Celi Expires 5 October 2024 [Page 19] Internet-Draft ACVP SHA3 April 2024 "content": "DE26", "contentLength": 16, "fullLength": 42949672960, "expansionTechnique": "repeating" } } ] }] } ] The following is an example JSON object for SHAKE. [ { "acvVersion": }, { "vsId": 1564, "algorithm": "SHAKE-128", "revision": "1.0", "testGroups": [ { "tgId": 1, "testType": "AFT", "tests": [ { "tcId": 1, "len": 0, "msg": "00" }, { "tcId": 2, "len": 1, "msg": "01" }] }, { "tgId": 2, "testType": "MCT", "inBit": true, "outBit": true, "inEmpty": false, "maxOutLen": 4096, "minOutLen": 128, "tests": [ { "tcId": 3, "len": 512, "msg": "30850bd984b14ff5aff18993329...", Celi Expires 5 October 2024 [Page 20] Internet-Draft ACVP SHA3 April 2024 }] }, { "tgId": 3, "testType": "VOT", "tests": [ { "tcId": 4, "len": 128, "msg": "7a4c48eb710299e4ff2be3f446327a6f", "outLen": 16 }, { "tcId": 5, "len": 128, "msg": "b16f331b3a0cf4507124b4358f9d15f5", "outLen": 144 }] }] } ] 8.3. Test Vector Responses After the ACVP client downloads and processes a vector set, it SHALL send the response vectors back to the ACVP server within the alloted timeframe. The following table describes the JSON object that represents a vector set response. +============+==================================+===========+ | JSON Value | Description | JSON Type | +============+==================================+===========+ | acvVersion | Protocol version identifier | string | +------------+----------------------------------+-----------+ | vsId | Unique numeric identifier for | integer | | | the vector set | | +------------+----------------------------------+-----------+ | testGroups | Array of JSON objects that | array of | | | represent each test vector | testGroup | | | result, which uses the same JSON | objects | | | schema as defined in Section 8.2 | | +------------+----------------------------------+-----------+ Table 7: Vector Set Response JSON Object Celi Expires 5 October 2024 [Page 21] Internet-Draft ACVP SHA3 April 2024 The testGroup Response section is used to organize the ACVP client response in a similar manner to how it receives vectors. Several algorithms SHALL require the client to send back group level properties in its response. This structure helps accommodate that. +============+=============================+==================+ | JSON Value | Description | JSON Type | +============+=============================+==================+ | tgId | The test group identifier | integer | +------------+-----------------------------+------------------+ | tests | The tests associated to the | array of | | | group specified in tgId | testCase objects | +------------+-----------------------------+------------------+ Table 8: Vector Set Group Response JSON Object Each test case is a JSON object that represents a single test object to be processed by the ACVP client. The following table describes the JSON elements for each test case object. +==============+=====================================+=============+ | JSON Value | Description | JSON Type | +==============+=====================================+=============+ | tcId | Numeric identifier for the test | integer | | | case, unique across the entire | | | | vector set. | | +--------------+-------------------------------------+-------------+ | md | The IUT's digest response to a VOT, | string | | | AFT or LDT | (hex) | +--------------+-------------------------------------+-------------+ | resultsArray | Array of JSON objects that | array of | | | represent each iteration of a Monte | objects | | | Carlo Test. Each iteration will | containing | | | contain the msg and md (and outLen | the md (and | | | for SHAKE-128 and SHAKE-256) | potentially | | | | outLen) | +--------------+-------------------------------------+-------------+ Table 9: Test Case Results JSON Object | NOTE: The 'tcId' MUST be included in every test case object | sent between the client and the server. The following are examples of JSON objects for secure hash test results sent from the crypto module to the ACVP server. The group identified by tgId 1 is a group of AFTs. The group identified by tgId 2 is a group of MCTs. The group identified by tgId 3 is a group of LDTs. Celi Expires 5 October 2024 [Page 22] Internet-Draft ACVP SHA3 April 2024 { "vsId": 0, "algorithm": "SHA3-224", "revision": "1.0", "testGroups": [ { "tgId": 1, "tests": [ { "tcId": 1, "md": "D14A028C2A3A2BC9476102BB288234C415A2B01F828EA62AC5B3E42F" }, { "tcId": 2, "md": "D14A028C2A3A2BC9476102BB288234C415A2B01F828EA62AC5B3E42F" } ] }, { "tgId": 2, "tests": [ { "tcId": 1028, "resultsArray": [ { "md": "E82B1FA3D510C2E423D03CEDF01F66C995CDD573EB63D5A33FDAE640" }, { "md": "00179AE4CE57DCBD156B981A414370B5089FA8E1098A05443DF3CD62" }, { "md": "8F6C7F546940352613E8389D4F4B87473A57CACD7E289A27E4F51965" } ] } ] }, { "tgId": 3, "tests": [ { "tcId": 1029, "md": "E4F8B44B32F5A25D1F4784601BF095CF5F7C6F4E9EAA1005AD19F09A" } ] } ] } Celi Expires 5 October 2024 [Page 23] Internet-Draft ACVP SHA3 April 2024 { "vsId": 0, "algorithm": "SHA3-224", "revision": "2.0", "testGroups": [ { "tgId": 1, "tests": [ { "tcId": 1, "md": "D14A028C2A3A2BC9476102BB288234C415A2B01F828EA62AC5B3E42F" }, { "tcId": 2, "md": "D14A028C2A3A2BC9476102BB288234C415A2B01F828EA62AC5B3E42F" } ] }, { "tgId": 2, "tests": [ { "tcId": 1028, "resultsArray": [ { "md": "E82B1FA3D510C2E423D03CEDF01F66C995CDD573EB63D5A33FDAE640" }, { "md": "00179AE4CE57DCBD156B981A414370B5089FA8E1098A05443DF3CD62" }, { "md": "8F6C7F546940352613E8389D4F4B87473A57CACD7E289A27E4F51965" } ] } ] }, { "tgId": 3, "tests": [ { "tcId": 1029, "md": "E4F8B44B32F5A25D1F4784601BF095CF5F7C6F4E9EAA1005AD19F09A" } ] } ] } Celi Expires 5 October 2024 [Page 24] Internet-Draft ACVP SHA3 April 2024 The following is an example JSON object response for SHAKE-128. The group identified by tgId 1 is a group of AFTs. The group identified by tgId 2 is a group of MCTs. The group identified by tgId 3 is a group of VOTs. { "vsId": 0, "algorithm": "SHAKE-128", "revision": "1.0", "testGroups": [ { "tgId": 1, "tests": [ { "tcId": 1, "md": "D14A028C2A3A2BC9476102BB288234C4" }, { "tcId": 2, "md": "D14A028C2A3A2BC9476102BB288234C4" } ] }, { "tgId": 2, "tests": [ { "tcId": 1028, "resultsArray": [ { "md": "E82B1FA3D510C2E423D03CEDF01F66C9", "outputLen": 128 }, { "md": "00179AE4CE57DCBD156B981A414370B5", "outputLen": 128 }, { "md": "8F6C7F546940352613E8389D4F4B8747", "outputLen": 128 } ] } ] }, { "tgId": 3, "tests": [ Celi Expires 5 October 2024 [Page 25] Internet-Draft ACVP SHA3 April 2024 { "tcId": 1029, "md": "E4F8" } ] } ] } 9. Security Considerations There are no additional security considerations outside of those outlined in the ACVP document. 10. IANA Considerations This document does not require any action by IANA. 11. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary", RFC 7991, RFC 7991, DOI 10.17487/RFC7991, December 2016, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", RFC 8174, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [FIPS202] National Institute of Standards and Technology, "SHA-3 Standard - Permutation-Based Hash and Extendable-Output Functions", NIST FIPS 202, August 2015, . [ACVP] Fussell, B., Vassilev, A., and H. Booth, "Automatic Cryptographic Validation Protocol", ACVP, 1 July 2019. [SHAVS] "The Secure Hash Algorithm Validation System (SHAVS)", NIST SHAVS. [LDT] "Extending NIST's CAVP Testing of Cryptographic Hash Function Implementations", LDT. Celi Expires 5 October 2024 [Page 26] Internet-Draft ACVP SHA3 April 2024 Author's Address Christopher Celi (editor) Email: christopher.celi@nist.gov Celi Expires 5 October 2024 [Page 27]