Home

GitHub Repository for QRNG Open API

Readme The QRNG Open API was created by Palo Alto Networks and six technical partners (Anametric, ID Quantique, Qrypt, Quantinuum, Quantropi, and Quside) to simplify the ability to obtain high quality entropy from an external QRNG platform (source). The QRNG Open API provides a common mechanism to obtain information on the QRNG platform’s capabilities, retrieve entropy from the platform, and to check the health of the entropy provided.

Much like the OASIS’s PKCS#11 standard is designed to ensure interoperability, abstraction, and flexibility when interacting with HSMs, the QRNG Open API was created with similar goals in mind. This API eliminates the need for applications developers to integrate vendor-specific or proprietary APIs to access high-quality entropy. Instead, it allows application developers to retrieve entropy from one or more sources using a single common API. Developers can adapt to changes in their QRNG requirements without additional development effort, reducing the risk of vendor lock-in and future rework, while encouraging the use of superior entropy for cryptographic and other applications.

This API is agnostic to the deployment model of the QRNG, as long as it provides a REST API interface. This allows developers to integrate a QRNG into their applications across a wide range of environments, including deployments within their local datacenter, applications in cloud environments, or edge computing environments such as IoT. This flexibility ensures broad coverage to ensure high-quality entropy available wherever it’s necessary.

Although the QRNG Open API was created for obtaining entropy from any QRNG platform supporting the API, it is applicable to any type of entropy delivery over REST and can be used for QRNG, TRNG, and even PRNGs.

Features REST API that is simple and easy to deploy. POST command is used to fetch the entropy. Vendor extensions are supported to provide flexibility for unique capabilities outside of the QRNG Open API specification. The Open API specification doesn’t specify how the communication channel is secured as it is outside the scope. As an example, communications between the requestor and QRNG platform can be secured with industry standard protocols such as TLS. Mutual authentication (mTLS) can also be used to enhance security between the provider and the requestor. Token authentication using the Bearer mechanism or the X-API-KEY is supported in the QRNG Open API specification and can also be used to authenticate each transaction.

Deployment Examples

On-Prem Data Center Deployment A local data center deployment uses one or more QRNG sources that support the QRNG Open API and security devices, such as NGFWs, can make API calls to one or more QRNG sources to obtain high quality entropy for its cryptographic functions. The QRNG components are secured using both network and TLS security

VLANs are used to segment and secure the communications between the QRNG and requesting devices. Only authorized personnel are permitted to manage the devices on the secure VLAN and normal network traffic is segmented and never mixed. The API and entropy communications are secured using standards-based protocols, such as TLS 1.3. The TLS session can be secured with either classic encryption algorithms, post-quantum PQCs, or a combination of hybrid technologies - such as X-Wing’s X25519 and Kyber-768. Authentication may be enforced using bidirectional certificates (mTLS) or vendor provided API tokens.

Cloud-hosted EaaS Deployment A cloud deployment uses one or more QRNG sources that support the QRNG Open API and virtual applications, such as Palo Alto Networks’ VM-Series firewall, can make API calls to one or more QRNG sources to obtain high quality entropy for its cryptographic functions. The QRNG components are secured using network and TLS security as well as firewall policies:

Virtual switch is used to segment and secure the communications between the QRNG and requesting devices. Only authorized personnel are permitted to manage the devices on the QRNG vSwitch network and normal data traffic is segmented and never mixed. The API and entropy communications are secured using standards-based protocols, such as TLS 1.3. The TLS session can be secured with either classic encryption algorithms, post-quantum PQCs, or a combination of hybrid technologies - such as X-Wing’s X25519 and Kyber-768. Authentication can be enforced using bidirectional certificates and optionally with vendor provided tokens. Firewall policies can be used to restrict access and ensure only permitted applications and devices are permitted to access the cloud QRNG service. Firewall logs are used to monitor and record access.

Single Server (VM hypervisor) Deployment A single server deployment uses one or more QRNG sources installed physically (or virtually) on the server to provide the QRNG Open API. Security services, such as virtual NGFWs, can make API calls to one or more QRNG sources to obtain high quality entropy for its cryptographic functions. For QRNG devices without webserver service capabilities, these API calls may be implemented via device driver level functions that mimic the higher-level QRNG Open API features.

In virtualized environments, The API and entropy communications can optionally be secured using standards-based protocols, such as TLS 1.3. The TLS session can be secured with either classic encryption algorithms, post-quantum PQCs, or a combination of hybrid technologies - such as X-Wing’s X25519 and Kyber-768. Authentication can be enforced using bidirectional certificates and optionally with vendor provided tokens. In non-virtualized environments, security services will make direct calls to the API server. Such calls should be properly authenticated, and a vendor provided token or an authenticated Public Key may be required or utilized in that scenario.

QRNG Open API Commands

Capabilities GET Query QRNG platform’s capabilities.

Request: https://some-host/v1/capabilities GET Entropy Response: “entropy” “min_block_size: <size> [Optional. Integer value. Min block size in bytes, default to 1] “max_block_size”: <size> [Mandatory. Integer value. Max block size in bytes] “min_block_count”: <count> [Optional. Integer value. Min count size, default to 1] “max_block_count”: <count> [Mandatory. Integer value. Max count size] “entropy_types”: [<type>,…] [Optional. Array of strings. Each string corresponds to an available type] “extensions”: [<object>,…] [Extensions, Optional] {array of Json Object}

“healthtest” [Optional.] “test_threshold” [Array of strings. Each string corresponds to vendor’s test capabilities] “test_type” [Mandatory. Tests that can be performed.] “time_stamp” [Mandatory. Syntax of time tests were performed. Eg.2023-09-13T08:34:4502] “report_link” [Optional. Link to fetch detailed health test report. “source_count” [Integer value. Reports how many QRNG sources are supported.] “extensions”: [<object>,…] [Extensions, Optional] {array of Json Object}

Error Codes: “422” [Error in requesting parameter] “503” [Entropy capability source unavailable]

Entropy POST Pull entropy from external QRNG platforms.

Request: https://some-host/v1/entropy POST ”block_size”: <bytes> [Mandatory, integer] “block_count”: <count> [Optional, integer. Defaults to 1. Value for amount of blocks] “entropy_type”: <type> [Optional, string. Defaults to 1st in array. Type to obtain entropy from]

Header: Content-Type: application/json Authorization: Bearer <token> [Optional. Vendor provided authentication token] Response: “entropy”: [<random>,…] [Mandatory, base64 encoded byte string] “extensions”: [<object>,…] [Extensions, Optional] {array of Json Object} Error Codes: “422” [Error in requesting parameter] “503” [Entropy source unavailable]

Healthtest GET (Optional) Obtain health test information on entropy provided.

Request: https://some-host/v1/healthtest GET Response: “test_result” [Array of objects. Each string corresponds to vendor’s test response] “test_type” [Mandatory. Test type performed. Eg. nist_90b] “test_result” [Mandatory. Test result value. Eg. 0.94] “time_stamp” [Mandatory. Time test was performed. Eg. 2023-09-13T08:34:4502] “report_link” [Optional. Link to fetch detailed health test report. Eg. https://host/entropy_health/nist] “extensions”: [<object>,… [Extensions, Optional] {array of Json Object}

Error Codes: “422” [Error in requesting parameter] “503” [Health test source unavailable]

QRNG Open API Examples

Examples using API tokens for authentication Curl: Capabilities GET

$ curl -X GET -H “Authorization: Bearer <API_TOKEN>” “<URI>/capabilities”

Entropy POST

$ curl -X POST -d ‘{“block_size”:<BLOCK_SIZE>,”block_count”:<BLOCK_COUNT>}’ -H “Content-Type: application/json” -H “Authorization: Bearer <API_TOKEN>” “<URI>/entropy”

Health Test GET

$ curl -X GET -H “Authorization: Bearer <API_TOKEN>” “<URI>/healthtest”

Python: import requests

headers = {‘Authorization’: ‘Bearer <API_TOKEN>’} data = {‘block_size’:<BLOCK_SIZE>,’block_count’:<BLOCK_COUNT>}

response = requests.post(‘<URI>/entropy’, headers=headers, json=data) print(response.json())

response2 = request.get(‘<URI>/capabilities’, headers=headers) print(response2.json())

response3 = request.get(‘<URI>/healthtest’, headers=headers) print(response3.json())

Examples using mTLS for authentication

Curl:

Capabilities GET

$ curl -X GET “<URI>/capabilities” –cert <CLIENT_CERT> –key <CLIENT_KEY> –cacert <CA_CERT>

Entropy POST

$ curl -X POST “<URI>/entropy” -d ‘{“block_size”: <BLOCK SIZE>, “block_count”: <BLOCK COUNT>}’ -H “Content-Type: application/json” –cert <CLIENT_CERT> –key <CLIENT_KEY> –cacert <CA_CERT>

Health Test GET

$ curl “<URI>/healthtest” –cert <CLIENT_CERT> –key <CLIENT_KEY> –cacert <CA_CERT>

Python including calls Capabilities, Entropy and Health Test: import requests import json import urllib3

base_url = “<URI>” cert_files = (‘<CLIENT_CERT>’, ‘<CLIENT_KEY>’) ca_cert = ‘<CA_CERT>’

def get_request(endpoint): url = f”{base_url}/{endpoint}” response = requests.get(url, cert=cert_files, verify=ca_cert) return response.json()

def post_request(endpoint, data): url = f”{base_url}/{endpoint}” headers = {‘Content-Type’: ‘application/json’} response = requests.post(url, cert=cert_files, data=json.dumps(data), headers=headers, verify=ca_cert) return response.json()

def print_response(response): print(json.dumps(response, indent=2))

print(“\nPOST request to /entropy\n”) data1 = {“block_size”: <BLOCK SIZE>, “block_count”: <BLOCK COUNT>} response1 = post_request(“entropy”, data1) print_response(response1)

print(“\nGET request to /capabilities\n”) response2 = get_request(“capabilities”) print_response(response2)

print(“\nGET request to /healthtest\n”) response3 = get_request(“healthtest”) print_response(response3)

Contributors

Anametric https://anametric.com/ Contributors: Alexander Magyari, Mitra Mechanic Email: [email protected]

ID Quantique https://www.idquantique.com/ Contributors: Jean-Sébastien Pegon, Yvan Charbonnier Email: [email protected]

Palo Alto Networks https://paloaltonetworks.com/ Contributors: Philip Kwan, Ashish Shah, Lee Space

Qrypt https://www.qrypt.com Contributors: Charles Desbiens, Kevin Hsieh

Quantinuum https://www.quantinuum.com Contributors: Nick Van Duyn, Marion Le Masson Email: [email protected]

Quantropi https://www.quantropi.com Contributors: Alex He, Dafu Lou Email: [email protected]

Quside https://quside.com Contributors: Carlos Abellán, José Ramón Martínez, Marc Romeu, Fernando de la Iglesia [email protected]