| Internet Engineering Task Force | B. Fussell, Ed. |
| Internet-Draft | Cisco Systems |
| Intended status: Informational | A. Vassilev, Ed. |
| Expires: August 25, 2019 | H. Booth |
| National Institute of Standards and Technology | |
| February 21, 2019 |
Automated Cryptographic Validation Protocol
draft-fussell-acvp-spec-00
The ACV Protocol provides a method for communication between a cryptographic module that is embedded inside of a device or otherwise running on a platform accessible via computer network, and an external testing system, using standard network communication interfaces and protocols. This communication protocol can also be used to validate the correctness of the algorithm implementations in the cryptographic module with a validation authority.
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 August 25, 2019.
Copyright (c) 2019 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. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
The ACV Protocol(ACVP) introduces a method to perform cryptographic assessment and validations at a rate which meets typical industry development cycles. This provides the ability to deploy validated crypto with CVE fixes much faster than previous methods. This document describes how it is structured with respect to the client-server model, the messaging protocol, optional features and flows.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14, RFC 2119 [RFC2119].
ACVP has the following goals:
ACVP defines how to communicate a request (to execute a cryptographic operation) to a cryptographic module, and how to communicate the corresponding response (containing the output of that operation) back to a testing system. It defines a transport (based on HTTP or HTTPS [RFC7230]), an JSON message structure(which is negotiated), and a set of message exchanges. Each vector test set corresponds to a single message exchange driven from the client associated with the module under test. ACVP does not define the cryptographic algorithms, nor does it detail the precise conditions for a response to be acceptable. Instead, it references existing specifications for those algorithms, and defines a mapping between the data on the wire and the algorithm testing specification. ACVP does not define detailed conformance criteria, such as those in FIPS-140. Instead, it aims to be independent of particular conformance criteria, so that it can be used in multiple domains with different (even potentially conflicting) conformance criteria. ACVP does not define an interface that can be used to manage or control a cryptographic module.
This document is written to address multiple audiences:
The goals for this document are to provide a messaging protocol that can be used with existing authentication and communication protocols to provide a way to test crypto modules. The following functions are outside the scope of this document:
With that in mind there are several expectations when building a server used as a validation authority. A validation authority SHALL use a combination of HTTPS [RFC7230], TLS 1.2 [RFC5246] or greater and mutual authentication. Therefore a client that expects to be used with a validation authority SHALL have the same requirements. A server, proxy or client developed for the purposes of internal organizational testing only MAY choose not to include some of those features.
A server/client/proxy model is used where the roles are defined as:
+----------------------------------------+
| +-----------------+ |
+----------+ | Entropy ---------->| DRBG----Encrypt | |
| ACV | | | Auth | |
| Server |<=============>| +--------+ | | |
+----------+ | | ACV |<------->| PKI-----Key Est | |
| | Client | ^ | Sign | |
| +--------+ | | | |
| Crypto | Crypto Module | |
| Module +-----------------+ |
| Realtime |
| API |
| |
| Device Under Test (DUT) |
+----------------------------------------+
Figure 1
+------------+
| | +-----------------+
+----------+ | | Entropy -->| DRBG----Encrypt |
| ACV | | | | Auth |
| Server |<=======>| +--------+ | | |
+----------+ | | ACV | | | PKI-----Key Est |
| | Client | | <==========>| Sign |
| +--------+ | ^ | |
| | | | Crypto Module |
+------------+ | | |
| +-----------------+
Manual/Non-Realtime
Vector Exchange
Figure 2
+--------------------------------------------------+
| +-------------------------+ |
+----------+ | +---------+ | | |
| ACV | | | ACV | | | |
| Server |<=======>| Proxy |<=====>| +--------+ +--------+ | |
+----------+ | +---------+ | | ACV |<->| Crypto | | |
| | | Client | | Module | | |
| | +--------+ +--------+ | |
| | | |
| | DUT | |
| +-------------------------+ |
| Vendor/Customer Premise |
+--------------------------------------------------+
Figure 3
The following terms are consistently used throughout this document and SHOULD be used throughout its extensions:
The ACV protocol will utilize existing mechanisms for transport coordinated with JSON formatted messaging.
Protocol Layering
+-----------------------------------------------+
| JSON Formatted ACVP request/response messages |
+-----------------------------------------------+
| HTTP[S] message transfer and signaling |
+-----------------------------------------------+
| TLS for transport security(recommended) |
+-----------------------------------------------+
| TCP for transport |
|_______________________________________________|
Figure 4
+----------------------+---------------+---------------+
server path prefix resource
+----------------------+---------------+---------------+
https://acvts.nist.gov/acvp/validation/acvp/login
+----------------------+---------------+---------------+
context API
Figure 5
Note that deployments utilizing ACV Proxy server MAY use a different protocol, e.g., HTTP, custom server, context and port number to interact with the DUT.
In the table below, any parts of a resource path enclosed in curly braces, { or }, are replaced by an instance of what is described in the braces. For example {testSessionId} could be replaced with 1.
An empty cell for a resource and HTTP Method combination denotes that the server returns an HTTP Status 405 code Method not allowed (405).
The resource path is appended to the path prefix to form the URI used with an HTTP Method to perform the desired ACVP operation. For example to create a new test session using the "/testSessions" resource is "/acvp/v1/testSessions" (assuming an empty context). To create a new Test Session, the ACVP client would use the following HTTP request-line:
POST /acvp/v1/testSessions HTTP/1.1
Likewise, to request a specific vector set from the server the ACVP client would use the following request-line:
GET /acvp/v1/testSessions/1/vectorSets/1 HTTP/1.1
It is RECOMMENDED that HTTPS and TLS 1.2 or greater be used in order to enforce a secure communication method. Not all environments will have TLS so HTTP with some level of authentication may be the only option.
It is RECOMMENDED that an authentication scheme be used. Typically, a JSON Web Token (JWT) is created by the server upon successful client authentication and returned to the client to use as an authorization mechanism for accessing the server resources - see Section 10.3 below for more information. Depending on the target environment and usage objectives, the authentication can be as weak as basic HTTP authentication or as strong as TLS mutual certificate authentication. Definition of an authentication scheme will not be discussed here, but should be agreed upon between the client and server owning entities including the servers owned by the validation authorities. For the purposes of the message flow examples, no authentication will be used.
The encoding used for the request/response messaging will be JSON ([RFC7159]). The data will be identified by: Content-type: application/json In order to allow environment specific extensions to a particular version of the ACV protocol, a top-level JSON keyword, extensions will be used to extend the OE description and/or the capabilities. Extensions MAY be ignored by the ACV server. Vector and vector response data will be JSON encoded.
Standard submission size handled by the server is 4MB. In the case that the submission size is larger than 4MB, an additional port will be provided for the target end point. In order to retrieve this "large submission" URI, the user must calculate the size of the submission in bytes and POST {submissionSize:bytes} to /acvp/acvp/large with their JWT authentication token. This end point will determine if the submission requires the "large submission" URI and if so, will return the URI to the user.
The version of the ACVP protocol will be carried with each message and will contain a simple major.minor format. Major version changes will not be backward compatible, however additions and enhancements that do not disrupt compatibility will be indicated with a minor version change. A server MAY accept a down-level version from the client if it can process at a lower level. If not, it will reject the session. All subsequent messages will carry the negotiated version value.
The product registration will utilize the URI resources Section 5.2 to register and provide cryptographic capabilities. This exchange will consist of several message exchanges and carry the Company name, primary contact (OE information) as well as a detailed list of the supported cryptographic algorithms and their options to be tested during the testSession, see Figure 8.
The test exchange consists of the ACV client requesting a particular vectorSet associated with the testSession. The server responds with the vectorSet. The client has the option to process the vectorSet and return results(realtime) or request more vectorSets for processing at a later time(non-realtime). The client will repeat this process until all of the tests in the session test list have been processed. Once a vectorSet result has been POSTed to the server the client may request success/failure results from the server at any time, however if vectorSets have not been completed the overall status will be incomplete. A minimal message flow is described below Figure 8.
JSON Web Token is described in RFC 7519 and is used as an authorization mechanism for gaining access to different resources.
An example JWT:
{
"alg" : "none"
}
{
"iss" : "nist.gov",
"exp" : 1426420800,
"company" : "MyCompany",
"jti" : 0987654321,
"pkey" : "cc74f56acdba635079383a03941d68db55c7b3c2f (truncated)"
}
{
Empty octet string (since alg is none).
}
The JWT can be secured if desired using the header encryption "alg" value defined to HS256(HMAC-SHA256) or one of the other secure values. Key agreement would follow RFC7518.
The first four claims are required, however "pkey" is an optional private claim used to pass the key used for encrypting the database at the server. Enabling this option is discussed further in Section 10.10.2
JSON Web Token is described in RFC 7519 and is used as an authorization mechanism for gaining access to different resources.
In order to access any resource which requires authorization a client must supply the JWT as an Authorization header value as a Bearer token. An example header value is:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5c (truncated)"
Workflow authorization flows. All exchanges shown are over HTTP.
+--------+---------------------------------+------+--------+
| Client | |Server| Notes |
+--------+---------------------------------+------+--------+
| |POST to /login or similar with | | |
| |appropriate credentials | | |
| |-------------------------------->| | |
| | | | |
| |receive the access token | | |
| |<- - - - - - - - - - - | | |
| | | | |
Figure 6
The JWT access tokens received from either the /login server endpoint SHALL be set to expire after a pre-defined period, The specific length of the expiration period is out of scope for this specification. However, the expiration period length impacts both the security and protocol overhead. Longer expiration periods reduce the overhead but increase the window for attacks. Attempting to access a service with an expired JWT SHALL result in a "401 Unauthorized" HTTP status code. A client may renew an expired JWT access token using the mechanism shown in Figure 7 below.
JWT access token renewal flows. All exchanges shown are over HTTP.
+--------+---------------------------------+------+--------+
| Client | |Server| Notes |
+--------+---------------------------------+------+--------+
| |POST to /login or similar with | | |
| |appropriate credentials | | |
| |and expired JWT access token | | |
| |-------------------------------->| |session |
| | | |or |
| | | |login |
| | | |JWT |
| |receive the renewed access token | | |
| |<- - - - - - - - - - - | | |
Figure 7
The minimum message flow between client and server after receiving the JWT: Figure 8
Workflow message flows. All exchanges shown are over HTTP.
+--------+-----------------------------------+------+------------+
| Client | |Server| Notes |
+--------+-----------------------------------+------+------------+
| |POST /vendors | | |
| |---------------------------------->| | |
| | | | |
| |vendor URL | | |
| |<- - - - - - - - - - - -| | |
| | | | |
| |POST /modules | | |
| |---------------------------------->| | |
| | | | |
| |module URL | | |
| |<- - - - - - - - - - - -| | |
| | | | |
| |POST /oes | | |
| |---------------------------------->| | |
| | | | |
| |oes URL | | |
| |<- - - - - - - - - - - | | |
| | | | |
| |POST dependency | | |
| |---------------------------------->| | |
| | | | |
| |dependency URL | | |
| |<- - - - - - - - - - - -| | |
| | | | |
| |POST testSessions | | |
| |---------------------------------->| | |
| | | | Submit |
| |testSessions URL | |Registration|
| |<- - - - - - - - - - - -| | |
| | | | |
| |GET | | |
| |testSessions/1/vectorSets/1 | | |
| |---------------------------------->| | |
| | | | Retrieve |
| |send test vectors for vsId 1 | | Request |
| |<- - - - - - - - - - - -| | |
| | | | |
| |POST results | | Submit |
| |---------------------------------->| | Response |
| | | | |
| |GET | | |
| |testSessions/1/vectorSets/1/results| | |
| |---------------------------------->| | |
| | | | Retrieve |
| |receive results | |Disposition |
| |<- - - - - - - - - - - -| | |
Figure 8
The available properties for vendor resources are:
GET /vendors
Returns a listing of vendors.
[
{"acvVersion": <acvp-version>},
{"vendors": [
{
"url": "/acvp/v1/vendors/1",
"name": "Cisco",
"website": "www.cisco.com",
"contacts": [{
"name": "John Doe",
"email": "johndoe@cisco.com"
}]
},
{
"url": "/acvp/v1/vendors/2",
"name": "Acme, LLC",
"website": "www.acme.acme",
"emails" : [ "inquiry@acme.acme" ],
"contacts": [{
"name": "Jane Smith",
"emails": ["jane.smith@acme.acme"],
"phoneNumbers" : [
{
"name": "555-555-0001",
"type" : "fax"
}, {
"name": "555-555-0002",
"type" : "voice"
}
],
"address" : {
"street" : "123 Main Street",
"locality" : "Any Town",
"region" : "AnyState",
"country" : "USA",
"postalCode" : "123456"
}
}]
}
]}
]
POST /vendors
Request the creation of a new Vendor.
name is required and all other properties are OPTIONAL. url is not allowed.
[
{"acvVersion": <acvp-version>},
{
"name": "Acme, LLC",
"website": "www.acme.acme",
"emails" : [ "inquiry@acme.acme" ],
"contacts": [{
"name": "Jane Smith",
"emails": ["jane.smith@acme.acme"],
"phoneNumbers" : [
{
"name": "555-555-0001",
"type" : "fax"
}, {
"name": "555-555-0002",
"type" : "voice"
}
],
"address" : {
"street" : "123 Main Street",
"locality" : "Any Town",
"region" : "AnyState",
"country" : "USA",
"postalCode" : "123456"
}
}]
}
]
[
{"acvVersion": <acvp-version>},
{"url": "/acvp/v1/vendors/2"}
]
GET /vendors/{vendorId}
Retrieve Information for a specific vendor
[
{"acvVersion": <acvp-version>},
{
"url": "/acvp/v1/vendors/2",
"name": "Acme, LLC",
"website": "www.acme.acme",
"emails" : [ "inquiry@acme.acme" ],
"contacts": [{
"name": "Jane Smith",
"emails": ["jane.smith@acme.acme"],
"phoneNumbers" : [
{
"name": "555-555-0001",
"type" : "fax"
}, {
"name": "555-555-0002",
"type" : "voice"
}
],
"address" : {
"street" : "123 Main Street",
"locality" : "Any Town",
"region" : "AnyState",
"country" : "USA",
"postalCode" : "123456"
}
}]
}
]
PUT /vendors/{vendorId}
Update a vendor
The url property is not updateable.
Can be any subset of the updateable properties. If a property is not included its value is not changed. A null value for a property indicates the value should be removed.
[
{"acvVersion": <acvp-version>},
{
"name": "Acme, LLC",
"website": "www.acme.acme",
"emails" : [ "inquiry@acme.acme" ],
"contacts": [{
"name": "Jane Smith",
"emails": ["jane.smith@acme.acme"],
"phoneNumbers" : [
{
"name": "555-555-0001",
"type" : "fax"
}, {
"name": "555-555-0002",
"type" : "voice"
}
],
"address" : {
"street" : "123 Main Street",
"locality" : "Any Town",
"region" : "AnyState",
"country" : "USA",
"postalCode" : "123456"
}
}]
}
]
DELETE /vendors/{vendorId}
Delete a specific vendor.
The server is not required to remove the resource but MUST return an error if the resource will not be removed.
The available properties for module resources are:
GET /modules
Returns a list of available modules.
[
{"acvVersion": <acvp-version>},
{"modules": [
{
"url": "/acvp/v1/modules/1",
"name": "ACME ACV Test Module",
"version": "1.0",
"type": "Software",
"vendorUrl": "/acvp/v1/vendors/2",
"implementationDescription" : "ACME module."
},
{
"url": "/acvp/v1/modules/2",
"name": "ACME ACV Test Module",
"version": "2.0",
"type": "Software",
"vendorUrl": "/acvp/v1/vendors/2",
"implementationDescription" : "ACME module with features"
}
]}
]
POST /modules
Register a new module.
[
{"acvVersion": <acvp-version>},
{
"name": "ACME ACV Test Module",
"version": "3.0",
"type": "Software",
"vendorUrl": "/acvp/v1/vendors/2",
"implementationDescription" : "ACME module with more"
}
]
[
{"acvVersion": <acvp-version>},
{"url": "/acvp/v1/modules/5"}
]
GET /modules/{moduleId}
Returns information about a specific module.
[
{"acvVersion": <acvp-version>},
{
"url": "/acvp/v1/modules/2",
"name": "ACME ACV Test Module",
"version": "2.0",
"type": "Software",
"vendorUrl": "/acvp/v1/vendors/2",
"implementationDescription": "ACME module with features."
}
]
PUT /modules/{moduleId}
Update an existing module.
It may not be possible to update all properties of a module once the module has been associated with a test session.
[
{"acvVersion": <acvp-version>},
{
"implementationDescription" : "ACME module with more"
}
]
DELETE /modules/{moduleId}
Delete a module or mark as no longer in use. (Optional)
The available properties for operational environment resources are:
GET /oes
Returns a list of available operational environments.
[
{"acvVersion": <acvp-version>},
{"oes": [
{
"url": "/acvp/v1/oes/1",
"name": "Windows 10 on Intel Xeon 5100 Series Processor",
"dependencyUrls": [ "/acvp/v1/dependencies/1",
"/acvp/v1/dependencies/2"]
},
{
"url": "/acvp/v1/oes/2",
"name": "Windows 10 on AMD 6272 Opteron Processor",
"dependencyUrls": [ "/acvp/v1/dependencies/1",
"/acvp/v1/dependencies/3"]
}
]}
]
POST /oes
Create a new operational environment.
[
{"acvVersion": <acvp-version>},
{
"name": "Ubuntu Linux 3.1 on AMD 6272 Opteron Processor
with Acme installed",
"dependencyUrls": [
"/acvp/v1/dependencies/4",
"/acvp/v1/dependencies/5",
"/acvp/v1/dependencies/7"
]
}
]
[
{"acvVersion": <acvp-version>},
{"url": "/acvp/v1/oes/20"}
]
GET /oes/{oeId}
Returns information about a specific operational environment.
[
{"acvVersion": <acvp-version>},
{
"url": "/acvp/v1/oes/1",
"name": "Windows 10 on Intel Xeon 5100 Series Processor",
"dependencyUrls": [
"/acvp/v1/dependencies/1",
"/acvp/v1/dependencies/2"
]
}
]
PUT /oes/{oeId}
Update an existing operational environment.
It may not be possible to update all (or any) properties of an operational environment resource once the resource has been associated with a test session.
[
{"acvVersion": <acvp-version>},
{
"name": "Windows 10 on Intel Xeon 5100 Series Processor",
}
]
DELETE /oes/{oeId}
Delete an operational environment or mark as no longer in use. (Optional)
The available properties for dependency resources are:
GET /dependencies
Returns a list of available dependencies.
[
{"acvVersion": <acvp-version>},
{"dependencies": [
{
"type": "software",
"name": "Linux 3.1",
"cpe": "cpe-2.3:o:ubuntu:linux:3.1"
},
{
"type": "processor",
"manufacturer": "Intel",
"family": "ARK",
"name": "Xeon",
"series": "5100",
"features": ["rdrand"]
}
]}
]
POST /dependencies
Register a new dependency.
[
{"acvVersion": <acvp-version>},
{
"type": "software",
"name": "Linux 3.1",
"cpe": "cpe-2.3:o:ubuntu:linux:3.1"
}
]
[
{"acvVersion": <acvp-version>},
{"url": "/acvp/v1/dependencies/7"}
]
GET /dependencies/properties
Returns the list of available dependency properties.
An array of property objects is returned with the following properties:
[
{"acvVersion": <acvp-version>},
{"properties": [
{
"name": "name",
"dataType": "string",
"validTypes": [
"software",
"processor"
],
"description": "The name of the dependency."
},
{
"name": "swid",
"dataType": "string",
"validTypes": ["software"],
"description": "A Software identification (SWID) tag as
described in ISO/IEC 19770-2:2015. NIST IR 8060,
https://csrc.nist.gov/publications/detail/nistir/8060/final,
provides guidance on creating and maintaining SWID tags."
},
{
"name": "cpe",
"dataType": "string",
"validTypes": [
"software",
"processor"
],
"description": "A Common Platform Enumeration (CPE)
formatted name according to Version 2.3 of the CPE
Naming Specification found in NISTIR 7695,
https://csrc.nist.gov/publications/detail/nistir/7695/final."
},
{
"name": "manufacturer",
"dataType": "string",
"validTypes": ["processor"],
"description": "The name of the manufacturer of
the processor dependency."
},
{
"name": "family",
"dataType": "string",
"validTypes": ["processor"],
"description": "The name of the family of the processor."
},
{
"name": "series",
"dataType": "string",
"validTypes": ["processor"],
"description": "The name of the series of the processor."
}
]}
]
GET /dependencies/{dependencyId}
Returns information about a specific dependency.
[
{"acvVersion": <acvp-version>},
{
"type": "software",
"name": "Linux 3.1",
"cpe": "cpe-2.3:o:ubuntu:linux:3.1"
}
]
PUT /dependencies/{dependencyId}
Update an existing dependency.
It may not be possible to update all (or any) properties of a dependency resource once the resource has been associated with an operational environment.
[
{"acvVersion": <acvp-version>},
{
"name": "Linux 3.1.0",
}
]
DELETE /dependencies/{dependencyId}
Delete a dependency or mark as no longer in use. (Optional)
The Algorithm resources are informational only. [CREF3]Do we want to provide guidance on standardizing the output?
GET /algorithms
Returns a list of available algorithms on the server.
[
{"acvVersion": <acvp-version>},
{"algorithms": [
{
"url": "/acvp/v1/algorithms/2",
"name": "AES",
"mode": "GCM",
"versions": [
<acvp-version>,
<acvp-version>
]
},
{
"url": "/acvp/v1/algorithms/3",
"name": "AES",
"mode": "ECB",
"versions": [
<acvp-version>
]
}
]}
]
GET /algorithms/{algorithmId}
Retrieve Information for about a specific algorithm.
Response may vary from server depending on internal representation. [CREF4]Is this ok? Or do we want to standardize?
The available properties for test session resources are:
GET /testSessions
Returns a list of Test Sessions for the current user.
This is an OPTIONAL operation.
[
{"acvVersion": <acvp-version>},
{"testSessions": [{
"url": "/acvp/v1/testSessions/2",
"acvpVersion": <acvp-version>,
"createdOn": "2018-05-31T12:03:43Z",
"expiresOn": "2018-06-30T12:03:43Z",
"encryptAtRest": false,
"vectorSetsUrl": "/acvp/v1/testSessions/2/vectorSets",
"publishable": false,
"passed": true,
"production" : false,
"isSample": true
}]}
]
POST /testSessions
Create a new Test Session.
algorithms is an array of algorithm objects. Each algorithm object has the following available properties:
Additional properties for each algorithm are based on the algorithm definition available in each sub-specification.
If not provided isSample, production and encryptAtRest default to false.
[
{"acvVersion": <acvp-version>},
{
"isSample" : true,
"algorithms": [{
"algorithm": "TEST_ALGO_1",
"property1": true,
"property2": ["operation1", "operation2"]
}]}
]
accessToken is a JWT Token which MUST be supplied as described in Section 10.3 in order to access the Test Session.
[
{"acvVersion": <acvp-version>},
{
"url": "/acvp/v1/testSessions/2",
"acvpVersion": <acvp-version>,
"createdOn": "2018-05-31T12:03:43Z",
"expiresOn": "2018-06-30T12:03:43Z",
"encryptAtRest": false,
"vectorSetsUrl": "/acvp/v1/testSessions/2/vectorSets",
"publishable": false,
"passed": true,
"production": false,
"isSample": true,
"accessToken" : "eyJhbGciOiJIUzI1NiIsInR5cCI6Ik (truncated)"
}
]
GET /testSessions/{testSessionId}
Returns information about the specific Test Session
[
{"acvVersion": <acvp-version>},
{
"url": "/acvp/v1/testSessions/2",
"acvpVersion": <acvp-version>,
"createdOn": "2018-05-31T12:03:43Z",
"expiresOn": "2018-06-30T12:03:43Z",
"encryptAtRest": false,
"vectorSetsUrl": "/acvp/v1/testSessions/2/vectorSets",
"publishable": false,
"passed": true,
"production": false,
"isSample": true
}
]
PUT /testSessions/{testSessionId}
Certify the Test Session for validation.
Associates all of the testing information with the test session. The test session MUST be have both publishable and passed set to true.
Available properties:
[
{"acvVersion": <acvp-version>},
{
"moduleUrl": "/acvp/v1/modules/20",
"oeUrl": "/acvp/v1/oes/60",
"algorithmPrerequisites": [{
"algorithm": "TEST_ALGO_1",
"prerequisites": [
{
"algorithm": "TEST_ALGO_0",
"validationId": "123456"
},
{
"algorithm": "TEST_ALGO_0.1",
"validationId": "123456"
}
]
}],
"signature": {
"algorithm": "SHA256RSA",
"certificate": "{base64encodedcertificate}",
"digitalSignature": "{base64encodedsignature}"
}
}
]
DELETE /testSessions/{testSessionId}
Delete a test session.
Marks a test session as being cancelled and may be deleted by the server. Further operations with the test session resource may return 404 HTTP Status.
GET /testSessions/{testSessionId}/results
Request Validation Results for a Test Session
[
{"acvVersion": <acvp-version>},
{
"passed": false,
"results": [
{
"vectorSetUrl": "/acvp/v1/testSessions/2/vectorSets/1",
"status": "incomplete"
},
{
"vectorSetUrl": "/acvp/v1/testSessions/2/vectorSets/2",
"status": "passed"
}
]
}
]
The REQUIRED properties for vector set resources are:
GET /testSessions/{testSessionId}/vectorSets
Returns a list of Vector Sets for the specific Test Session.
The property returned is:
[
{"acvVersion": <acvp-version>},
{"vectorSetUrls": [
"/acvp/v1/testSessions/2/vectorSets/1",
"/acvp/v1/testSessions/2/vectorSets/2"
]}
]
GET /testSessions/{testSessionId}/vectorSets/{vectorSetId}
Vector Set download request.
The server will respond with the vector set associated with the vsId for the client to process. The test group content contained in the response will vary depending on the specific sub-specification of the algorithm and testType being tested.
[
{"acvVersion": <acvp-version>},
{
"vsId": 1,
"algorithm": "TEST_ALGO_1",
"revision": "1.0.0",
"testGroups": [
{
"tgId": 1,
"testGroupProperty1": 1,
"testType": "type1",
"tests": [
{
"tcId": 1,
"testCaseProperty1": 1,
"testCaseProperty2": "2"
},
{
"tcId": 2,
"testCaseProperty1": 3,
"testCaseProperty2": "4"
}
... additional tests ...
]
},
... additional test groups ...
{
"tgId": 3,
"testGroupProperty1": 2,
"testType": "type2",
"tests": [{
"tcId": 2139,
"testCaseProperty3": 10
}]
}
... additional test groups ...
]
}
]
If the server did not have enough time to generate the vector set for a given test session, the server may reply:
[
{ "acvVersion": <acvp-version> },
{ "vsId": 1,
"retry" : 30
}
]
Where:
The server may set the retry value based on the current server load and expected processing time to generate the vector set.
DELETE /testSessions/{testSessionId}/vectorSets/{vectorSetId}
Cancel testing for a specific Vector Set.
There may be cases where a particular vector set may not be cancelled and the entire Test Session will need to be cancelled instead.
GET /testSessions/{testSessionId}/vectorSets/{vectorSetId}/results
Request Validation Results for a Vector Set.
The client will send this request to learn the validation results for an individual vector set. Properties are:
reason - number, provides additional detail in case of a failed result value.
[
{"acvVersion": <acvp-version>},
{"results": {
"vsId": 1437,
"disposition": "incomplete",
"tests": [
{
"tcId": 12340,
"result": "passed",
"reason": ""
},
{
"tcId": 12341,
"result": "incomplete",
"reason": ""
},
{
"tcId": 12342,
"result": "failed",
"reason": "Algorithm reason XXX"
}
]
}}
]
POST /testSessions/{testSessionId}/vectorSets/{vectorSetId}/results
Initial Submission of Vector Set Test Results.
The client will send this request to submit the test results for an individual vector set. Similar to the vector set download the format will vary depending on the specific sub-specification of the algorithm and testType being tested.
[
{"acvVersion": <acvp-version>},
{
"vsId": 1437,
"revision": "1.0.0",
"testGroups": [{
"tgId": 1,
"tests": [{
"tcId": 12340,
"testCaseProperty1": "ABCD",
"testCaseProperty2": "1234"
},
{
"tcId": 12341,
"testCaseProperty1": "5678",
"testCaseProperty2": "FEDC"
}, ...
]
}, ...
]
}
]
No content response. Standard HTTP status codes will indicate success or failure of the submission, but do not indicated the disposition of the tests.
PUT /testSessions/{testSessionId}/vectorSets/{vectorSetId}/results
Update Vector Set Test Results Submission.
When one or more test cases fails, the client will need to correct the issue in the crypto module and send the responses again. The resending of responses for failed test cases will occur for an entire vector set. Therefore, even if only a single test case in the vector set failed, the client will need to download, process, and upload responses to the server for the entire vector set (presumably after the problem has been corrected in the implementation). The resending of vector set responses must occur prior to expiry.
The request content is identical to the request content described in Section 10.11.5 .
GET /testSessions/{testSessionId}/vectorSets/{vectorSetId}/expected
Expected Test Results.
The response is identical to the request content described in Section 10.11.5 .
[CREF10]Vector Sets or Test Sessions? It would be far simpler if it was Test Session based rather than Vector Set based. Vector sets can expire. For example, in terms of a validation authority use, the vector sets are one-time use only. Old vector sets can never be reused to obtain a new validation certificate for an algorithm implementation or to update an existing certificate. Expiration is a server specific definition which depends on database costs, need for artifacts, etc. If the vector set has expired, the server will reply with an expired response when the client attempts to download the vector set:
[
{"acvVersion": <acvp-version>},
{
"vsId": <vs-id>,
"status": "expired"
}
]
The ACVP protocol requires server implementations to generate test values and retain the data while the ACVP client processes and returns the results. Some crypto modules implementing the client-side ACVP protocol may not return results immediately. The ACVP protocol design implies the server must retain the test values to verify the client test responses at some time in the future. However, some test vector sets are fairly large, which could place significant storage requirements on ACVP server implementations. To alleviate long term storage requirements, ACVP allows for an expiration timestamp to be set when a test vector set is generated by the server.
The vector set expiration timestamp must be included by the server in the vector set when the client downloads the vector set. The server may change the expiration timestamp of a previously issued vector set to extend its lifetime subject to server policy. The expiration timestamp must be in the 'expiry' JSON value, which is included in the JSON encoded vector set. The expiry JSON value will be a string value of the UTC timestamp using form "YYYY-MM-DD HH:MM:SS". The following figure shows a partial JSON encoded vector set that contains the expiry value.
[
{"acvVersion": <acvp-version>},
{
"vsId": 1437,
"expiry": "2018-12-31 23:59:59",
"algorithm": "TEST_ALGO_1",
"revision": "1.0.0",
"testGroups": [
{
"tgId": 1,
"testGroupProperty1": 1,
"testType": "type1",
"tests": [
{
"tcId": 1,
"testCaseProperty1": 1,
"testCaseProperty2": "2"
},
{
"tcId": 2,
"testCaseProperty1": 3,
"testCaseProperty2": "4"
},
.
.
.
<remainder of vector set omitted from figure>
.
.
.
]
}]
}
]
Some [CREF11]should we instead add a property to indicate that paging was enabled to allow implementations to decide? resources require paging in order to avoid returning large amounts of data. To faciliate paging the following Query parameters SHOULD be allowed on resources where paging is necessary.
The response will indicate the offset and the total count using offset and total properties.
Errors will follow HTTP[S] numbering scheme. In addition errors as well as 200 messages may carry JSON encoded information that describes in detail the error and any associated troubleshooting information. Examples of client and server error messages are in Appendix B.
ACVP is intended to be an extensible protocol that supports testing of a large number of cryptographic algorithms from several different classes defined by the community. All algorithm identifiers intended for public use SHALL be documented by IANA in the ACVP IANA Registry [acvp-iana].
To add testing for a new algorithm first try to find an algorithm of the same type that is already supported by the protocol.
If it belongs to an already-supported type, check the test specification for the similar algorithm. Typically, similar algorithms share similar testing methodology.
For example, the testing of symmetric block ciphers is comprised of two test types: Algorithm Functional Tests and Monte Carlo Tests - see [sub-symmetric].
Assuming that the existing test types provide sufficient test coverage for the new algorithm, one needs to add the new block cipher algorithm to the symmertic block cipher specification [sub-symmetric], including the JSON schema for the corresponding test data exchanges between the validation server and the client. See in particular Section "Adding new algorithms" in the corresponding algorithm specification.
Next, one needs to update the IANA registry with the new algorithm by adding it to the corresponding namespace and subject to the policies stated in [acvp-iana].
Once this is completed and the corresponding server test generation and validation for that algorithm are implemented, testing can commence. Clients implementing that algorithm may register it for testing as described in Section "Capabilities Registration" in [sub-symmetric], process the test vectors generated by the validation server and return the results for validation.
If the available test types for an algorithm, existing or new, in a given class do not provide good test coverage of the algorithm, one could develop a new test type and incorporate it into the corresponding test specification for the that algorithm. See for example Section "Adding new algorithms" in [sub-symmetric] for how to add a new test type. Note that this action would require modifications of the corresponding algorithm test specification and would result in a new version of that test specification to be reflected in the IANA registry [acvp-iana].
A date type is a time string formatted according to the rules of RFC 3339; all date/times must use UTC time denoted by 'Z' suffix with no local timezone adjustment. Example is 2018-06-01T20:10:33Z
Bitstrings are used to communicate a string of bits between the ACVP server and IUT.
BitStrings SHALL be considered in big endian order, unless otherwise specified by the algorithm.
The hex string "FA" (assuming all bits are considered) SHALL represent the bits 11111010 (in MSb) or the value 250.
"valueLen" will be used as the example, but it can apply to any bit length registration/vector set/etc parameters.
When a "value" is provided along with a "valueLen", the "valueLen" MUST be considered when parsing the hex string represented in "value", EXCEPT in empty bitstring cases, which MUST be represented as an empty string "". Parsing Hex strings into Bit strings is especially important for algorithms such as the SHA variations that may only include a portion of bits from the provided hex string. When only a portion of bits from a Hex string are considered, bits for use in the bitstring SHALL be taken from the most significant bits, meaning the lesser significant bits are the bits that are dropped.
The Range object can be used to convey a range of values. It contains its own set of properties made up of "min", "max", and "increment".
A range object specifying a minimum of 0, a maximum of 8, with an increment of 1. This range object includes the values 1, 2, 3, 4, 5, 6, 7, and 8.
{"myRange": {
"min": 1,
"max": 8,
"increment": 1
}}
A range object specifying a minimum of 0, a maximum of 8, with an increment of 2. This range object includes the values 0, 2, 4, 6, and 8.
{"myRange": {
"min": 0,
"max": 8,
"increment": 2
}}
The Domain object can be used to specify a set of values similar to Range, albeit with more control. A domain can be made up of an array of objects, where those objects can be literal values, and/or Range objects.
Several sample domain objects that state 0, 8, 16, 32, 96, 128, 192, and 256 are valid values.
{"myDomain": [
{
"min": 0,
"max": 16,
"increment": 8
},
32,
96,
{
"min": 128,
"max": 256,
"increment": 64
}
]}
{"myDomain": [ 0, 8, 16, 32, 96, 128, 192, 256 ]}
Because the Domain is an array of objects consisting of (potentially) both literals and ranges, algorithms that use an array of integers can be used interchangably with the Domain object.
The IANA considerations for this memo are provided by [acvp-iana].
When an ACVP client is attached to a cryptographic module that is in use, access to ACVP MUST be controlled so that only an administrator or other authorized user can send and receive ACVP messages. This is because an attacker that has access to ACVP can potentially use it to probe for weaknesses in the cryptographic module.
Original ACV Protocol created by David McGrew, Bill Hudson and Anthony Grieco of Cisco Systems. Additional contributions made by Sam Farthing, Ellie Daw and Philip Perricone from Cisco Systems and Christopher Celi and Russell Hammett from NIST.
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. |
| [RFC3339] | Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002. |
| [RFC5246] | Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, DOI 10.17487/RFC5246, August 2008. |
| [RFC7159] | Bray, T., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, DOI 10.17487/RFC7159, March 2014. |
| [RFC7230] | Fielding, R. and J. Reschke, "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", RFC 7230, DOI 10.17487/RFC7230, June 2014. |
| [RFC7519] | Jones, M., Bradley, J. and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015. |
| [acvp-iana] | Vassilev, A., "ACVP IANA Registry", November 2018. |
| [CMVP] | Vassilev, A., "Cryptographic Algorithm Validation Program", February 2018. |
| [sub-symmetric] | Celi, C., "ACVP Symmetric Algorithm JSON Specification", 2018. |
All JSON keywords SHALL use lower camelCase format with no underscores or hyphens and use the following characters only a-z, A-Z, 0-9. Keywords SHALL abbreviate common words and phrases wherever possible for brevity.
For example: password length - pwLen plain text length - ptLen
Keywords SHOULD be chosen such that they are informative and brief, for example:
[ { "acvVersion": acvp-version }, { "results" : { "disposition" : "incomplete" } } ]
Metadata assigned to the keyword may use any format which best reflects the information being represented including hyphens, underscores alternating case, numbers, etc. However, brevity should be a major consideration, for example:
"algorithms" : [ { "algorithm" : "ACVP-AES-GCM", "mode" : "modes", "ivGen" : "internal", "ivGenMode" : "8.2.1" } All metadata representing strings or big numbers SHALL use double quotes at both ends. Big numbers require conversion from strings to whatever format is used by the DUT. Numerical values of integer size or with decimal points may use quotations if those values are generally used as a string, for example the acvVersion would generally be used in displaying information not in any mathematical operations. Something like keyLen or ptLen values would be better used without quotes to avoid having to convert the string to an integer for use in the code.
General or registration errors detected by the server SHALL result in an HTML error and description of the problem, for example:
HTTP response: 400
"error" : "Incorrectly formatted JSON (51:18):
expected field name was not provided: inBit"
Errors detected by the client SHOULD trigger an indication of the operation that failed and a detailed error description. This information can be sent to the clients local logging facility to provide traceability of communication issues, for example:
ACV Operation: SHA-512
Error: Unsupported hash algorithm