Public Key Authentication

Generating a Public/Private Key

To generate a keypair for use with the API use the openssl library. We recommend using a 4096bit key:

openssl genrsa -out rs_key.pem 4096
openssl rsa -in rs_key.pem -pubout -out rs_key.pub

Configuring Keys

The private key (rs_key.pem) should remain on your production system for signing messages. The public key (rs_key.pub) should be uploaded to your account on RedShelf.com. You may upload your public key by logging into RedShelf.com and clicking on My Account in the menu. In the tab API Access you will see a text box to enter your public key.

See also

For more information see the Account Configuration section of this documentation.

Warning: Be sure not to upload your private key. It is a security risk to expose it to the internet even though it will work for verifying signed messages.

Using the client

If you are using the RedShelf Python client library the process of signing messages will be handled automatically. You need only provide your username and private key location to the library on initialization.

See also

For more information see the Python Client section of this documentation.

Rolling your own

When using your own proprietary system to connect to the API you will need to handle the process of signing messages. For Python systems the pycrypto library makes this easy. Other languages have similar libraries available.

ALL Requests: Send your username in the USER or API-USER key in your HTTP headers.

GET Requests: Sign your username and send the result in the SIGNATURE key in your HTTP headers.

POST, PATCH Requests: Sign the data in your request key and send the result in the SIGNATURE key in your HTTP headers.

Note: The username is your private username hash, not your RedShelf username (email address).

Authentication Headers

Example Headers:

Authorization: Crypto
Api-User: <your username here>
Signature: <your RSA signature here>

cURL Example

This is an example of sending a GET request to the “profile” endpoint using openssl and cURL:

The following commands will

1. hash your hashed username using SHA256

2. sign your hashed username using PKCS#1 v1.5

3. encode it into base64

4. store the base64 output into a file called signature.txt

5. send a cURL request to the RedShelf API:

   ####GET REQUEST#####
   # replace {{username_hash}} with your username hash from your RedShelf API User Page
   # Generate signature on Linux/Mac OS X with OpenSSL
   echo -n "{{username_hash}}" | openssl dgst -sha256 -sign rs_key.pem  | base64 > signature.txt
   # Generate signature on Windows Powershell with OpenSSL
   [System.IO.File]::WriteAllText(“$pwd/data.txt”,"{{username_hash}}",[System.Text.Encoding]::ASCII);
   openssl dgst -sha256 -out enc.dat -sign rs_key.pem data.txt; openssl base64 -in enc.dat | Set-Content signature.txt
   
   # Note: always include both the API_USER and USER headers with your hashed username set as both
   curl -H "USER:{{username_hash}}" -H "API_USER:{{username_hash}}" -H "SIGNATURE:$(cat signature.txt)"   -v http://api.redshelf.com/profile/
   
   ####POST REQUEST####
   # Generate signature on Linux/Mac OS X with OpenSSL
   echo -n '{"isbn": [9781133387077]}' | openssl dgst -sha256 -sign rs_key.pem  | base64 > signature.txt
   # Generate signature on Windows Powershell with OpenSSL
   [System.IO.File]::WriteAllText(“$pwd/data.txt”,'{"isbn": [9781133387077]}',[System.Text.Encoding]::ASCII);
   openssl dgst -sha256 -out enc.dat -sign rs_key.pem data.txt; openssl base64 -in enc.dat | Set-Content signature.txt
   
   # send search request for book by isbn
   curl -H "USER:{{username_hash}}" -H "API_USER:{{username_hash}}" -H "SIGNATURE:$(cat signature.txt)" \
   -X POST -H 'Content-Type: application/json' -d '{"request": {"isbn": [9781133387077]}}' \
   -v http://api.redshelf.com/v1/book/search/