Internet-Draft | ACVP SHA3 | November 2024 |
Celi | Expires 5 May 2025 | [Page] |
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 May 2025.¶
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.¶
There are no acknowledgements.¶
This document defines the JSON schema for testing SHA3 and SHAKE implementations with the ACVP specification.¶
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-specification addresses a specific class of crypto algorithms. This sub-specification defines the JSON constructs for testing SHA3 and SHAKE implementations using ACVP.¶
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.¶
The initial request from the client to the server describing the capabilities of one or several algorithm, mode and revision combinations¶
A collection of test cases that share similar properties within a prompt or response¶
A collection of test groups under a specific algorithm, mode, and revision¶
JSON sent from the server to the client that specifies the correctness of the response¶
The following SHA3-based hash algorithms MAY be advertised by this ACVP compliant crypto module:¶
Other hash algorithms MAY be advertised by the ACVP module elsewhere.¶
This section describes the design of the tests used to validate implementations of SHA3 and SHAKE.¶
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:¶
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.¶
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]¶
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.¶
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.¶
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]¶
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.¶
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.¶
The tests described in this document have the intention of ensuring an implementation is conformant to [FIPS202].¶
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.¶
Again, the internal states discussed in Sections 3 through 6 SHALL NOT be tested or tracked.¶
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.¶
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 |
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" } ]¶
Each SHA3 and SHAKE algorithm capability advertised SHALL be a self-contained JSON object. The following JSON values are used for hash algorithm capabilities:¶
JSON Value | Description | JSON type |
---|---|---|
algorithm | The hash algorithm and mode to be validated. | string |
revision | The algorithm testing revision to use. | string |
inBit | Implementation does accept bit-oriented messages | boolean |
inEmpty | Implementation does accept null (zero-length) messages | boolean |
outputLen | Output length for SHAKE. 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). | domain |
outBit | SHAKE can output bit-oriented messages | boolean |
messageLength | The message lengths in bits supported by the IUT. Minimum allowed is 0, maximum allowed is 65536. | domain |
performLargeDataTest | Determines if the server should include the large 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}. | integer array |
The following grid outlines which properties are REQUIRED, as well as all the possible values a server MAY support for SHA3 and SHAKE algorithms:¶
algorithm | revision | inBit | inEmpty | outputLen | outBit | messageLength | performLargeDataTest |
---|---|---|---|---|---|---|---|
SHA3-224 | 1.0 | true, false | true, false | [1, 2, 4, 8] | |||
SHA3-256 | 1.0 | true, false | true, false | [1, 2, 4, 8] | |||
SHA3-384 | 1.0 | true, false | true, false | [1, 2, 4, 8] | |||
SHA3-512 | 1.0 | true, false | true, false | [1, 2, 4, 8] | |||
SHA3-224 | 2.0 | {"Min": 0, "Max": 65536, "Inc": any} | [1, 2, 4, 8] | ||||
SHA3-256 | 2.0 | {"Min": 0, "Max": 65536, "Inc": any} | [1, 2, 4, 8] | ||||
SHA3-384 | 2.0 | {"Min": 0, "Max": 65536, "Inc": any} | [1, 2, 4, 8] | ||||
SHA3-512 | 2.0 | {"Min": 0, "Max": 65536, "Inc": any} | [1, 2, 4, 8] | ||||
SHAKE-128 | 1.0 | true, false | true, false | {"Min": 16, "Max": 65536, "Inc": any} | true, false | ||
SHAKE-256 | 1.0 | true, false | true, false | {"Min": 16, "Max": 65536, "Inc": any} | true, false |
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] }¶
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 cryptographic 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 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 Section 8.1 | array |
An example of this would look like this¶
[ { "acvVersion": <version> }, { "vsId": 1, "algorithm": "Alg1", "mode": "Mode1", "revision": "Revision1.0", "testGroups": [ ... ] } ]¶
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, unique across the entire vector set. | integer |
testType | Test category type. AFT, MCT or VOT as defined in Section 6 | value |
mctVersion | When testType is MCT, the type of MCT being run, i.e., "standard" or "alternate" | string |
tests | Array of individual test case JSON objects, which are defined in Section 8.2 | array of testCase objects |
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 Value | Description | JSON type |
---|---|---|
tcId | Numeric identifier for the test case, unique across the entire vector set. | integer |
len | Length of the message or seed | integer |
outLen | Length of the digest | integer |
msg | Value of the message or seed. Messages are represented as little-endian hex for all SHA3 variations. | string (hex) |
largeMsg | Object describing the message for an LDT group | large data object, see Section 6.3 for more information |
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": <acvp-version> }, { "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, "fullLength": 42949672960, "expansionTechnique": "repeating" } } ] }] } ] [ { "acvVersion": <acvp-version> }, { "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": { "content": "DE26", "contentLength": 16, "fullLength": 42949672960, "expansionTechnique": "repeating" } } ] }] } ]¶
The following is an example JSON object for SHAKE.¶
[ { "acvVersion": <acvp-version> }, { "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...", }] }, { "tgId": 3, "testType": "VOT", "tests": [ { "tcId": 4, "len": 128, "msg": "7a4c48eb710299e4ff2be3f446327a6f", "outLen": 16 }, { "tcId": 5, "len": 128, "msg": "b16f331b3a0cf4507124b4358f9d15f5", "outLen": 144 }] }] } ]¶
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 the vector set | integer |
testGroups | Array of JSON objects that represent each test vector result, which uses the same JSON schema as defined in Section 8.2 | array of testGroup objects |
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 group specified in tgId | array of testCase objects |
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 case, unique across the entire vector set. | integer |
md | The IUT's digest response to a VOT, AFT or LDT | string (hex) |
resultsArray | Array of JSON objects that represent each iteration of a Monte Carlo Test. Each iteration will contain the msg and md (and outLen for SHAKE-128 and SHAKE-256) | array of objects containing the md (and potentially outLen) |
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.¶
{ "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" } ] } ] } { "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" } ] } ] }¶
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": [ { "tcId": 1029, "md": "E4F8" } ] } ] }¶
There are no additional security considerations outside of those outlined in the ACVP document.¶
This document does not require any action by IANA.¶