NIST Entropy Quality Tests

Using Qrypt’s NIST Entropy Quality Tests

Qrypt’s NIST Entropy Quality Tests is a set of APIs that allows you to check the quality of Qrypt’s entropy using the NIST Statistical Test Suite. Tests are conducted every 10 minutes against Qrypt’s Quantum Entropy service. Accessing this service does not require a Qrypt account or access token.

About NIST Entropy Quality Tests

The NIST Entropy Quality Test suite uses the 15 statistical tests defined by the NIST Statistical Test Suite (STS). Each of these 15 tests is repeated over many samples. The APIs generate two test results:

  1. Total number of individual passing tests: considered successful if a sufficient number of individual tests pass. The threshold varies based on the number of individual tests run and is based on an alpha value of 0.01. For example, 1000 individual tests requires a 98% pass rate to be considered successful.
  2. P-value uniformity for each of the 15 tests: considered successful if all 15 tests have uniformly distributed p-values.

The tests are considered as succeeding overall if either of these criteria are met. This provides a metric for passing that is more robust to fluctuations than using either criterion alone. However, this standard does not catch certain randomness defects. For example, if the randomness was periodic with a period equal to the size used for batching, a sufficiently high portion of the tests might pass, but the P-values would not be uniform.

NIST Entropy Quality Test Endpoints

There are three endpoints for obtaining NIST entropy quality test results.

  1. NIST Logs: retrieves a specified number of recent test results
  2. Failing NIST Logs: retrieves a specified number of recent failing test results
  3. Failing NIST Random: retrieves random of recent failing tests

NIST Logs

This API contains the most recent NIST test results. To get NIST test results, you must submit an HTTP request to the API, optionally providing the number of results to view and whether they should be shown in a simplified format.

  1. Make a request to the following URL: https://nist.qrypt.com/api/v1/logs?num={num}&simple={simple}.
  2. Optionally replace {num} with the desired number of recent test results to show.
  3. Optionally replace {simple} with a true or false to specify if you want a simplified test result output.
Request Parameters
Request Fields Description
num Optional. The number of logs to show. Can be set between 1 and 100, defaulting to 5.
simple Optional. Format the logs in a summarized manner, only showing the 'tests_passed', 'time_of_completion' and 'time_of_completion_string' fields. Can be set to 'true' or 'false', defaulting to 'false'.
Response Codes
Status code Description
200 Success
Test results were successfully retrieved.
400 Bad request
The request was invalid (i.e., malformed or otherwise unacceptable). Please verify the format of the URL and the specified parameters.
500 Internal server error
The Qrypt service has encountered an internal error. Please contact Qrypt support for further assistance.
503 Service Unavailable
Please wait and try the request again.
JSON Response Fields

For a successful 200 response, the response contains a JSON-encoded structure with an array of test results with the following fields in each array element. Note that the simplified logs only contain ’tests_passed’, ’time_of_completion’ and ’time_of_completion_string’ fields.

There are two main groupings of tests. One is prefixed ’nist’ for the number of NIST STS tests that passed or failed, and the second is ‘uniformity’ for the uniformity of each NIST STS test’s P-values.

JSON Response Fields Description
tests_passed If tests passed overall. This indicates either 'nist_all_passed' or 'uniformity_all_passed' is true.
time_of_completion Unix timestamp of when the test was completed.
time_of_completion_string String timestamp of when the test was completed.
nist_all_passed If a sufficiently large percentage of NIST STS tests succeeded.
nist_fails Number of NIST STS test failures.
nist_passes Number of NIST STS test passes.
nist_success_rate NIST STS test success rate.
uniformity_all_passed If the P-values of all NIST STS tests are uniformly distributed.
uniformity_fails Number of NIST STS tests with non-uniformly distributed P-values.
uniformity_passes Number of NIST STS tests with uniformly distributed P-values.
uniformity_success_rate NIST STS test uniformity success rate.

The following illustrates an example of JSON output as returned by a request for a single log:

[
    {
        "nist_all_passed": true,
        "nist_fails": 86,
        "nist_passes": 8742,
        "nist_success_rate": 0.9855783640783642,
        "tests_passed": true,
        "time_of_completion": 1699551247.1653655,
        "time_of_completion_string": "11/09/2023 12:34",
        "uniformity_all_passed": true,
        "uniformity_fails": 0,
        "uniformity_passes": 15,
        "uniformity_success_rate": 1.0
    }
]

NIST Failed Test Logs

This API contains the most recent failed NIST test results, where both the individual test rate and uniformity tests fail. To get failed NIST test results, you must submit an HTTP request to the API.

  1. Make a request to the following URL: https://nist.qrypt.com/api/v1/failing_logs?num={num}&simple={simple}&strict={strict}&include_random={include_random}&randsize={randsize}
  2. Optionally replace {num} with the number of recent test results to show.
  3. Optionally replace {simple} with ’true’ to output simplified logs.
  4. Optionally replace {strict} with ‘false’ specify if you want to show logs that failed either the test rate or uniformity.
  5. Optionally replace {include_random} with ’true’ to see failed random. Only applicable if ‘strict’ is ’true’.
  6. Optionally replace {randsize} with the number of bits to show. Only applicable if ‘include_random’ is set to ’true’.
Request Parameters
Request Fields Description
num Optional integer. The number of logs to show. Can be set between 1 and 100, defaulting to 5.
simple Optional boolean. Format the logs in a condensed, summarized manner. Can be set to 'true' or 'false', defaulting to 'false'.
strict Optional boolean. Require that the logs must fail uniformity and test rate to be considered failing. Can be set to 'true' or 'false', defaulting to 'true'.
include_random Optional boolean. Determines if the random that failed the test will be included in the response. Only applicable when "strict" is true. Can be set to 'true' or 'false', defaulting to 'false'.
randsize Optional integer. How many bits of random to include in the response. Can be set between 1 and 5242880 (640KiB), defaulting to 1024. Only applicable when "include_random" is true.
Response Codes
Status code Description
200 Success
Test results were successfully retrieved.
400 Bad request
The request was invalid (i.e., malformed or otherwise unacceptable). Please verify the format of the URL and the specified parameters.
500 Internal server error
The Qrypt service has encountered an internal error. Please contact Qrypt support for further assistance.
503 Service Unavailable
Please wait and try the request again.
JSON Response Fields

The JSON response fields are identical to the NIST Logs API, except for the ‘random’ field. The ‘random’ field only appears if ‘include_random’ is set to ’true’.

JSON Response Fields Description
tests_passed If tests passed overall. This indicates either 'nist_all_passed' or 'uniformity_all_passed' is true.
time_of_completion Unix timestamp of when the test was completed.
time_of_completion_string String timestamp of when the test was completed.
nist_all_passed If a sufficiently large percentage of NIST STS tests succeeded.
nist_fails Number of NIST STS test failures.
nist_passes Number of NIST STS test passes.
nist_success_rate NIST STS test success rate.
uniformity_all_passed If the P-values of all NIST STS tests are uniformly distributed.
uniformity_fails Number of NIST STS tests with non-uniformly distributed P-values.
uniformity_passes Number of NIST STS tests with uniformly distributed P-values.
uniformity_success_rate NIST STS test uniformity success rate.
random The tested random that failed.

The following illustrates an example of JSON output as returned by a request for a single log:

[
    {
        "nist_all_passed": true,
        "nist_fails": 86,
        "nist_passes": 8742,
        "nist_success_rate": 0.9855783640783642,
        "tests_passed": true,
        "time_of_completion": 1699551247.1653655,
        "time_of_completion_string": "11/09/2023 12:34",
        "uniformity_all_passed": true,
        "uniformity_fails": 0,
        "uniformity_passes": 15,
        "uniformity_success_rate": 1.0,
        "random": "111110100110010100001010100011"
    }
]

NIST Failed Random

This API contains the random of the most recent strictly failing NIST tests. To get the random of failed NIST test results, you must submit an HTTP request to the API.

  1. Make a request to the following URL: https://nist.qrypt.com/api/v1/failing_random?num={num}&randsize={randsize}
  2. Optionally replace {num} with the number of recent test results to show.
  3. Optionally replace {randsize} with ’true’ to output simplified logs.
Request Parameters
Request Fields Description
num Optional integer. The number of logs to show. Can be set between 1 and 100, defaulting to 5.
randsize Optional integer. Number of bits of random to include in the response. Can be set between 1 and 5242880, defaulting to 1024.
Response Codes
Status code Description
200 Success
Test results were successfully retrieved.
400 Bad request
The request was invalid (i.e., malformed or otherwise unacceptable). Please verify the format of the URL and the specified parameters.
500 Internal server error
The Qrypt service has encountered an internal error. Please contact Qrypt support for further assistance.
503 Service Unavailable
Please wait and try the request again.
JSON Response Fields
JSON Response Fields Description
random Failing bits of random.
time_of_completion Unix timestamp of when the test was completed.
createdAt Readable timestamp of when the test was completed.

The following illustrates an example of JSON output as returned by a request for a single log:

[
    {
        "createdAt": "Thu, 09 Nov 2023 12:54:06 GMT",
        "random": "111110100110010100001010100011",
        "time_of_completion": 1699534446.5982661
    }
]