JSON Web Signature
Edit me

About the JSON Web Signature

The ‘JSON Web Signature’ (JWS) is used as part of a REST header to validate requests made to certain endpoints (Beneficiary creation and CT creation, for example). Having this header indicates that you have signed the request with your private key. Any requests to these specific endpoints that do not include the Javascript Object Signing and Encryption (JOSE) header will fail.

We require that you use a JWS signature for these types of requests for the pusposes of non-repudiation. By providing a JWS signature you are ensuring that you, as merchant, have generated the request; no other party has been involved; no tampering has occurred..

Steps Required to Generate a Valid Header

To create a JOSE header you will need to:

  • Generate a Private Key and a Certificate.
  • Retrieve the certificate serial number and decode it.
  • Extract the issuer details from your certificate.
  • Use the JWS Signature Generator to generate the JOSE header.

You will then use this header value in any APIs where it is required.

Generating the PKI Key and Certificate

To generate your private key and certificate:

  1. Navigate to the ‘PKI Management’ screen on the Developer Dashboard. (If you cannot see this as a menu option please contact your Account Manager - specific permissions must be enabled to allow you to access this section of the dashboard).
  2. If this is the first time using this screen you will see a notification to say that no PKI key has been generated.
  3. Click Generate PKI Key. This will generate:
    • Your Private Key
    • A Signed certificate
  4. You will be prompted to download your private key (in .key format):

Managing Certificates

Once you have generated your PKI Key you have two available actions, you can:

  • Download the certificate in .crt format. .
  • Revoke your active certificate. This will invalidate the active certificate and private key, and you will no longer be able to generate JSON Web Signatures with this key and certificate. You will need to generate a new private key and certificate.

Retrieving Details from the Certificate

In order to generate the JOSE Header you’ll need to extract certain details from your certificate:

  1. Browse to where you downloaded your certificate (.CRT file) and double-click to view its details.
  2. Locate the certificate serial number section of the certificate. This is stored as a hexadecimal number and will need to be decoded.
  3. There are various tools available online to allow you to decode the haxadecimal value, see https://www.rapidtables.com/convert/number/hex-to-decimal.html for example. (The decoded number is the kid value that you will need to generate your Header later).
  4. Next, locate the subject parameters from the certificate:
  5. The following details are required:

    Attribute Value Description
    OU Nuapay API Organization unit, this will always be 'Nuapay API' for certificates signed by Nuapay.
    CN a2av3py82w Common name, the originator technical ID
    O Nuapay Organization, will always be 'Nuapay' for certificates signed by Nuapay.
    L London Locality, will always be 'London' for certificates signed by Nuapay.
    C GB Country Name, two letter country code will always be 'GB' for certificates signed by Nuapay.

    At this point you have gathered everything you need from the Certificate. These are the details you need to generate the JOSE Header:

    Attribute Value Description
    alg RS256 Algorithm, always 'RS256'
    kid 2496611953 Key ID, use the decoded certificate serial number
    iat 0 Issued at, always '0'
    iss "C=GB, L=London, OU=Nuapay API, O=Nuapay, CN=a2av3py82w" Issuer, use the certificate subject parameters
    b64 false Base64 encoded payload, always 'false'
    crit ["b64","iat","iss"] Critical, always ["b64","iat","iss"]

    Use the JWS Signature Generator to create the JOSE Header.