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:
|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 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:
- Call the
- Provide your CSR in the request.
- 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:
- Copy the
certreturned in the response (as described above) and paste it into a text file.
- Replace the
\ncharacters in the certificate with a new line character:
- Save the file as a .crt.
- Double-click this file to view its details.
Locate the certificate serial number section of the certificate. This is stored as a hexadecimal number and will need to be decoded.
- 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.
Next, locate the subject parameters from the certificate:
The following details are required:
|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:
|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:
- Your Private Key.
- The Key ID (kid): the serial number from your .crt file.
- The Common Name (CN): the Nuapay identifier for your merchant or partner entity.
(Other certificate elements are always the same i.e. the
L, etc. )
Use these details to generate your signature.
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.
It is possible to List and Delete Certificates: