Prove your random numbers are really from RANDOM.ORG
RANDOM.ORG's Signed API will sign any true random values you generate, such that it can be verified that they originate from our service. This is useful to implement non-repudiation, e.g., to prove that your application has not tampered with the random values. Non-repudiation is useful for many types of accounting and auditing services, as well as for games and lotteries.
The Signed API is our most fundamental service we offer for building your own applications that use certified true randomness. It can be a fair amount of work to build your application on top, and we have already built some services that you may find interesting and that we offer API access to:
To get started with the Signed API, you need an API key. You can create one from the API Dashboard. We have different pricing tiers available, depending on what your numbers are for and how many you need. If you are starting out, you can sign up for a free developer key.
Your API keys let you make requests to RANDOM.ORG without further authentication. For this reason, you will probably want to keep your keys secret, especially if you are using them to generate signed random values. We will never reveal your keys to anyone, and our digital signatures include a SHA-512 hash of the key you used to make the request instead of the key itself. This links the signature to your key (and your key only) without revealing the key itself.
A response from our Signed API consists of two main parts:
randomobject, which contains the details of your true random numbers, including the following: the API method you used to generate the values, the specific parameters you gave to the method and the exact date and time at which RANDOM.ORG generated the values. The
randomobject also a SHA-512 hash of your API key, which identifies the random values as yours, as well as some user-defined data (defined by you), which will be signed also. (More about this below.)
signaturestring, which takes the form of a SHA-512 hash of the
randomobject, which has been signed with RANDOM.ORG's secret key. The signature format is specified in PKCS #1 v2.0.
When using the Signed API, your application will be making
requests to the API, and for each request, it will receive
random object and a
string. You'll want to store these values together in
your application, such that you can produce them to show
that the random values really originated from RANDOM.ORG.
You'll find more information about how to do this below.
When you request random values, it can be useful to make a commitment to how you will use the values before you actually see them. An example of a commitment could be: ‘I promise to use this value to pick the winner for my weekly sweepstakes’
The Signed API methods have an optional field called the
userData field, which allows you to specify
some additional data, which RANDOM.ORG will include in the
random object. RANDOM.ORG will not
process this data, but because it is included in the
random object, the
string proves that you did specify this data before you
saw the random values, and that you cannot have changed
the data afterwards. (If you did, the
signature string would no longer validate.)
Please note that while the
proves that you did indeed specify the data before you saw
the values, RANDOM.ORG does not check that the same
userData does not occur multiple times. For
that reason, use of the
userData field alone
does not protect you against accusations of
cherry-picking, i.e., generating random values with the
userData until you get the values you
want. For that reason, you will want to publish every
random object and
signature string returned by the Signed API,
such that your users can review them and confirm that
there are no duplicate values of your
userData field amongst them.
There are three ways that you (or the users of your application) can verify RANDOM.ORG signatures.
Read more or create an API key below. As always, you are also welcome to contact us if you have questions.