JSON Web Signature

Creating a Certificate Signing Request (CSR)

Before you can create a certificate you must first generate a CSR. When generating your CSR you must provide the following details:

Attribute Value Description
OU Nuapay API Organization unit, this will always be 'Nuapay API' for certificates signed by Nuapay.
CN example: a2av3py82w Common name; the merchant/partner identifier. If you don't have this identifier, please contact Nuapay Support.
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.
The process for creating a CSR varies depending on the Web Server being used and it is not possible to cover all the variations in this documentation. Details are available online for all popular Web Servers.

The Common Name CN may be either:

  • A single merchant identifier
  • Or it may be the partner identifier.

Where a partner identifier is used, the Certificate that is generated will be used to generate the JOSE header that will be used by that partner when calling API services (where non-repudiation is required) on behalf of its merchants.

Please contact Nuapay Support if you do not know your Nuapay merchant/partner identifier.

Detached Payload JWS

A signed JWS encodes information in three parts separated by periods:

  • a header
  • a payload
  • a signature

A JWS also supports a detached format that omits the payload from the JWS:

When using a detached JWS, the payload is sent as normal in the body but it is not included in the JWS.

Generating Your Certificate via REST

To generate your certificate via REST:

  1. Call the POST/certificates endpoint.
  2. Provide your CSR in the request.
  3. A successful 201 reponse will return your certificate details.

Retrieving Details from the Certificate

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

  1. Copy the cert returned in the response (as described above) and paste it into a text file.
  2. Replace the \n characters in the certificate with a new line character:
  3. Save the file as a .crt.
  4. Double-click this file to view its details.
  5. Locate the certificate serial number section of the certificate. This is stored as a hexadecimal number and will need to be decoded.

  6. There are various tools available online to allow you to decode the hexadecimal 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 signature later). In the example above, 0094cf4671 is decoded as 2496611953.
  7. Next, locate the subject parameters from the certificate:

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 (Example) Common name: the merchant/partner identifier.
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.
Only the CN will vary per merchant/partner; all other attributes are static.

The following are the details you need to generate the JOSE Header:

Attribute Value Description
alg RS256 Algorithm: always ‘RS256’
kid 2496611953 (Example) 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”]

At this point you have the following unique details:

  1. Your Private Key.
  2. The Key ID (kid): the serial number from your .crt file.
  3. The Common Name (CN): the Nuapay identifier for your merchant or partner entity. (Other certificate elements are always the same i.e. the C, OU, L, etc. )

Use these details to generate your signature.

Unit Testing

We recommend that you create a unit test that takes your inputs (as described above) and generates an appropriate JWS Signature. To better understand how best to do this please refer to the:

  • Java sample project: https://github.com/sentenial/jws-sample-java OR
  • JWS Signature Sample values to see how a specific Private Key, Certificate and payload, can be used to generate a specific JWS signature (using the JWS Generator tool). You can then use the tool to pass in YOUR private key and certificate details to generate a signature for testing purposes.

Managing Certificates

It is possible to List and Delete Certificates:

List All Certificates

Delete a Certificate