About Signatures

Prove your random numbers are really from RANDOM.ORG

Overview

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:

Getting Started

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.

Keep your Keys Secret

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.

The Anatomy of a Signature

A response from our Signed API consists of two main parts:

  • A random object, 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 random object 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.)
  • A signature string, which takes the form of a SHA-512 hash of the random object, 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 a random object and a signature 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.

Making a Commitment

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 signed random object. RANDOM.ORG will not process this data, but because it is included in the random object, the signature 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 userData field 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 same userData until you get the values you want. For that reason, you will want to publish every single 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.

Verifying a Signature

There are three ways that you (or the users of your application) can verify RANDOM.ORG signatures.

Ready to give it a whirl?

Read more or create an API key below. As always, you are also welcome to contact us if you have questions.

API Documentation API Dashboard