PKI Integration

This guide provides an overview of integrating with the Solaris API using a Public Key infrastructure (PKI) integration. It covers the specific requirements to ensure that data is transmitted securely and your requests are processed successfully.

PKI integration at a glance

Public Key infrastructure allows users and systems to verify the legitimacy of certificate-holding entities, and to securely exchange information over networks. This is used to ensure both authenticity - the message has truly been sent from the expected party, and integrity - the message has not been altered by unauthorized sources. Central to this is key generation and exchange:

• Each party, in this case you (the partner) and Solaris, generates a key pair. A key pair contains both a public and private key. The two keys are mathematically linked - data encrypted with the public key can only be decrypted using the respective private key.
• Both parties exchange their public keys, and securely store their respective private keys.
• After this exchange, data can be securely transmitted between both parties. The data to be sent is encrypted by the sender using the receiver's public key. On receipt of the data, the receiver can decrypt it using their private key.
• In addition, each party can use their private key to "digitally sign" data to verify it has indeed been sent by them and has not been altered in transit.

Consuming the API using a PKI integration

The primary requirements for consuming the API using a PKI integration are:

• Encryption - sensitive API-usage fields sent between your system and the API are sent in encrypted format.
• Digital signing of requests - requests made to the API must have their payloads digitally signed. All responses from the API are similarly digitally signed for your verification.
• Request headers - headers containing the payload's digital signature, and to identify the partner making the request, must be included in each request sent.

Request Headers

When using a PKI integration, requests to the Solaris API must contain the following headers:

• groupcode - Used to uniquely identify the partner making the request, containing the groupcode value provided during your onboarding.
• x-signature - Contains the digital signature of the request payload.

The headers should be included in the following form:

groupcode: <partner-groupcode>
x-signature: <digital-signature-of-request>

Both headers must be present and contain valid values otherwise the request will be rejected:

• A missing groupcode or x-signature header will return a 406 Not Acceptable response.
• An invalid value in the groupcode header or invalid signature in the x-signature header will return a 403 Forbidden response.

Encryption

When using a PKI integration you must encrypt and decrypt sensitive API usage-related fields sent to/from the API. For this purpose RSA PKCS#1 asymmetric encryption is used:

• Sensitive fields you send to the API must be encrypted by you using the Solaris public key.
• Sensitive fields received from the API are encrypted by Solaris using your public key, and must be decrypted by you using your private key.

For example, when making a Login request:

• The Password field in your request must be encrypted.
• The Contis_SecurityKey sent in the response is encrypted, and requires decryption before use.

Creating and verifying digital signatures

Providing a digital signature for a request payload

The following steps can be used to generate a digital signature for requests made to the API:

1. Ensure the request body is encoded using UTF-8 and that all sensitive fields are encrypted.
2. Use the RSA encryption algorithm, along with your private key, to encrypt the request body. This creates the digital signature of the payload.
3. Base64 encode the digital signature.
4. Include the Base64 encoded digital signature string in the x-signature request header.

Please note the input for your signature generation must exactly match the payload as it is received by Solaris, otherwise signature verification will fail and the request will be rejected.

Verifying the digital signature of a response payload

Responses from the Solaris API will include an x-signature header containing the digital signature of the payload. This can be verified as follows:

1. Decode the value in the x-signature header from Base64 to UTF-8.
2. Decrypt this decoded string using the RSA algorithm along with the Solaris public key.
3. Compare the this decrypted string to the response body to verify the signature.