Qrypt’s Entropy as a Service is a RESTful web service that allows you to generate random data (henceforth referred to as entropy or random) that is truly random—based on quantum-mechanical phenomena.
This service requires an access token. Follow the steps in Getting Started to obtain an access token.
To get entropy from the service, you must submit an HTTP request to the REST API service, providing your access token and specifying the number of 1,024-byte blocks of entropy you would like to receive. You must also specify an access token—which identifies the user account requesting the data—in an HTTP “authorization” header. The data is returned in a JSON-encoded structure containing an array of base64-encoded strings, each of which decodes to a 1,024-byte block of entropy, as well as an integer specifying the number of strings in the array.
To ensure the privacy of your access token and the entropy data, all calls are made using an encrypted HTTPS connection.
Follow these steps in your preferred tool or language of choice to request entropy (see subsequent sections Request and Response for details):
The following sections provide more detailed explanations of the request and response.
The web service consists of one REST API call, which returns the entropy. The following table describes the properties of a valid REST API call.
| HTTP Verb | GET |
|---|---|
| URL |
https://api-eus.qrypt.com/api/v1/quantum-entropy?size={kib_entropy} {kib_entropy} is an integer that specifies the number of kibibytes (1,024 bytes) of entropy being requested. The minimum value is 1 and the maximum value is 512. If unspecified, the default value is one (1). |
| Accept (header) |
"application/json" |
| Authorization (header) |
"Bearer {qrypt_access_token}"
{qrypt_access_token} is an access token generated in the Qrypt portal. |
Qrypt’s Quantum Entropy service is hosted in several locations worldwide. This allows you to access a server that is closer to the client for better reliability and response time. The following table (Table 2) indicates which subdomain to use in your URL to access the server located in the specified region.
| Subdomain | Geographic location |
|---|---|
| api-eus | Eastern United States |
The response from the HTTP request will contain a numeric status code indicating whether or not the request succeeded and, if not, why. If successful, it will also return the entropy.
| Status code | Description |
|---|---|
| 200 | Success Entropy was successfully returned. |
| 400 |
Bad request The request was invalid (i.e., malformed or otherwise unacceptable). Please verify the format of the URL and the specified parameters. |
| 401 |
Unauthorized The access token is either invalid or has expired. |
| 403 |
Limit reached The account associated with the specified access token has already retrieved the maximum allotment of entropy allowed for the current period. Please contact a Qrypt representative to request a change to your limit. |
| 429 |
Rate Limit reached The access token used to pull random has exceeded the maximum number of requests (30) allowed for the designated time interval (10 seconds). Please wait and try again. |
| 500 |
Internal server error The Qrypt service has encountered an internal error. Please contact Qrypt support for further assistance. |
| 503 |
Not enough supply Qrypt’s supply of entropy is temporarily insufficient to fulfill the request. Please wait and try the request again. |
If a success status code of 200 was returned, the response contains a JSON-encoded structure containing an array size (which should match the kib_entropy value specified in the request) and an array of base64-encoded strings which, when decoded, contains 1,024 bytes of entropy.
| JSON Fields | Description |
|---|---|
| random | An array of base64-encoded strings (as defined in RFC 4648 §4, Base 64 Encoding) . The length of the array is specified in the size field (below). Each string, when decoded, contains a 1,024-byte sequence of entropy. |
| size | The number of base64-encoded strings in the array returned in the random field (above). |
The following illustrates an example of JSON output as returned by a request for two 1,024-byte blocks of entropy:
"random": [
"<base64 encoding of 1,024 bytes of entropy>",
"<base64 encoding of 1,024 bytes of entropy>"
],
"size": 2
The following examples demonstrate how to submit a request and display the returned entropy. In the following examples, {subdomain} should be replaced with the subdomain for a server in the geographic location you would like to use (see Table 2), {kib_entropy} should be replaced with an integer between 1 and 512, and {qrypt_access_token} should be replaced with an access token generated using your Qrypt account.
The following shows an example of how to submit a request for {kib_entropy} kibibytes of entropy using the {qrypt_access_token} via the curl command-line command. This command can be executed at a Windows or Unix command prompt.
curl https://{subdomain}.qrypt.com/api/v1/quantum-entropy?size={kib_entropy} -H "Authorization: Bearer {qrypt_access_token}"
The following shows an example of how to submit a request for {kib_entropy} kibibytes of data using the {qrypt_access_token} in PowerShell.
Specify entropy token, requested size of entropy, and subdomain
[string] $accesstoken = '{qrypt_access_token}'
[int] $kibData = {kib_entropy}
[string] $sub = '{subdomain}'
Define the request URL
[string] $url = "https://$sub.qrypt.com/api/v1/quantum-entropy?size=$kibData"
Define and submit the request
$response = Invoke-RestMethod -Method Get -Uri $url -UseBasicParsing `-Headers @{ authorization = "Bearer $accesstoken" } ` -ContentType 'application/json'
Display the entropy bytes
response.random | foreach { [Convert]::FromBase64String($_) }
The following shows an example of how to submit a request for {kib_entropy} kibibytes of data using the {qrypt_access_token} in Python.
You may need to install the “requests” module before executing this example. For example, use the following command:
python -m pip install requests
import requests
import base64
# Specify entropy token, requeststed size of entropy, and subdomain
accesstoken = '{qrypt_access_token}'
kibData = {kib_entropy}
sub = '{subdomain}'
# Define the request URL
url = f'https://{sub}.qrypt.com/api/v1/quantum-entropy'
# Define and submit the request
headers = { 'Authorization': f'Bearer {accesstoken}' }
params = { 'size': kibData }
response = requests.get( url, headers=headers, params=params)
# Display the entropy bytes
for s in response.json()['random']:
for b in base64.decodebytes( s.encode('ascii') ):
print( f'{b}')
The following shows an example of how to submit a request for {kib_entropy} kibibytes of data using the {qrypt_access_token} in JavaScript.
"use strict";
// Specify entropy token, requested size of entropy, and subdomain
let accessToken = "{qrypt_access_token}";
let kibData = { kib_entropy };
let sub = "{subdomain}";
// Define the request URL
let url = `https://${sub}.qrypt.com/api/v1/quantum-entropy?size=${kibData}`;
// Submit the request and process the response
fetch(url, {
method: "GET",
headers: {
Accept: "application/json",
Authorization: "Bearer " + accessToken,
},
})
.then((response) => response.json())
.then(function (json) {
// Display the entropy bytes
json.random.forEach((b64) =>
[...atob(b64)].forEach((c) => console.log(c.charCodeAt(0)))
);
});