Amazon PSP SPI - Public API

This document contains the proposal for the public facing API that will expose the functionality of the internal Amazon SPI API.

Background

The Amazon’s Payment Service Provider Program (PSPP) is an initiative to allow Amazon to detect, prevent and take actions against potential malicious actors in their marketplace. All sellers that use the services of a Payment Service Provider (PSP) to collect their proceeds will be required to use a PSP that is part of the program. That means that in order to allow our customers to keep receiving the payments from their sales on Amazon we need to join the program.

To comply with the program we need to provide Amazon with the seller’s virtual account information in two ways:

  • Through CSV files that will get updated to an Amazon FTP in intervals no longer than an hour. The details regarding this part of the program are outside the scope of this document.

  • Through SPI API. Amazon will use this API to request information about an account number or IBAN and to set the level of detail they need for the information regarding a customer.

The requirements for the SPI API are still unfinished. But despite that we need to start working on it because once they are finished we have a limited amount of time to complete the development.

Problem Description

We need a secure way to expose our internal Amazon SPI API. The security requirements include mandatory use of TLS, client and server authentication using certificates, and payload encryption and signing.

Client and Server Authentication

The client and server will authenticate during the TLS handshake by presenting their respective certificates1 to each other. The server should not accept every certificate issued by Amazon's certificate authority, It should only accept the ones that were added to its configuration.

Message Payload

The requests and responses carry their payloads signed and encrypted.

Payload Signature

All the payloads need to be signed2 using the PS512 or PS256 algorithms. The signatures will be done following the JSON Web Signature (JWS) standard.

Payload Encryption

The payload encryption will be done following the asymmetric version of the JSON Web Encryption (JWE) standard3.

The asymmetric supported algorithms are RSA-OAEP and RSA-OAEP-256. For the underlying symmetric encryption the supported algorithms are A128CBC-HS256, A192CBC-HS384, A256CBC-HS512, A128GCM, A192GCM and A256GCM.

Certificate and Key Management

During initial setup and upon key renewal Amazon and Ebury will exchange the following pieces of information1:

Ebury sends to Amazon Amazon sends to Ebury
Server TLS certificate Client TLS certificate
Public server signature key Public client signature key
Public server encryption key Public client encryption key

Different client certificates could use different encryption and signature keys. So the client public encryption and signature keys need to be associated with the client certificate. The same applies to server keys, public and private server encryption and signature keys need to be associated with the client certificate.

Both client and server signature and encryption keys will be renewed at least once a year.

Solution

Using the existing Ebury API is not an option because the requirements, goals and users are completely different. Ebury API is an “operational API” that allows our customers to interact with our platform to execute transactions. On the other hand the new PSP SPI API is a “compliance API” that is going to be used by a third party for fraud detection and prevention.

On the security side Ebury API use tokens to identify users and secure access, even when using mTLS, and the payloads are plaintext without signatures. In the SPI API we need to use certificates to identify our users and all the payloads are encrypted and signed. Also if we mix both APIs we risk that errors in the design or implementation lead to leaks of very sensitive information to our regular API users. For those reasons the new PSP functionality needs to be fully independent of the existing customer API.

The public SPI API only needs to deal with the security requirements, since the internal SPI API will handle the business logic. For that reason the new Kong gateway is a perfect candidate for it.

Kong Public SPI API Overview

We propose to use a Kong Gateway with two plugins. The Kong mTLS plugin to perform client certificate validation and a custom cryptography and signature plugin that will check the signature and unencrypt the requests and sign and encrypt the responses.

We would configure Kong to pass the Public SPI API domain requests through the two plugins and then relay the resulting request to the internal SPI API.

The mTLS plugin is already included with Kong, we only need to configure it.

For the custom cryptography and signature plugin we would need to do some development. Kong supports plugins written in LUA and Go. Go is a better fit because multiple JOSE libraries exist for it.

Key Set Persistence

We need to store the key sets for each client certificate. In order to do so we plan to persist the following pieces of information:

  • Client certificate hash: This is used to associate the key set with a client certificate.

  • Amazon's public signature key: The key that will be used to validate incoming requests' payload signature.

  • Amazon's public encryption key: The key that will be used to encrypt outgoing requests' payload.

  • Ebury's private signature key: The key that will be used to sign outgoing requests payload.

  • Ebury's private encryption key: The key that will be used to unencrypt incoming requests' payload.

  • Key set validity start date: The date and time when the key set begins to be valid.

  • Key set expiration date: The date and time when the key set expires.

  • Description: An string to make key sets easier to manage.

Key sets will be renewed at least once per year, but we don't know if the client certificate will also be renewed at the same time. Also during the renewal process the new, and the old key sets need to be valid at the same time to avoid interruptions in the API service. For that reason we need to allow multiple key sets for the same client certificate.

Connectivity with the internal SPI API

The Kong gateway will reside in our AWS infrastructure while the internal SPI API resides in Google Cloud Platform (GCP). In order to secure access to the internal API we plan to follow the same approach proposed for other services that need connectivity between AWS and GCP, which is using an IP whitelist on the internal SPI API.

Alternatives

Our alternative solution is based on the NL Reporting solution. We can use a Nginx reverse proxy to perform the basic client certificate validation. Upstream of that proxy we would find two services, one that validates that the client certificate is one of the allowed ones and another service that performs the cryptographic operations on the payload.

Alternative Public SPI API Overview

Caveats

We can't estimate the running cost of the solution because Kong is billed by the number of requests, but we don't know yet how much traffic to expect in the SPI API.

On top of the lack of detail in the documentation, Amazon is not providing a test environment or test scripts to simulate their use of the public API. That will lead to potential compatibility issues when the API goes live.

Operation

Public SPI API will run in staging, sandbox and production and will be managed by support and devops.

Security Impact

The public SPI API provides access to the private SPI API which gives access to very sensitive client data. The access control based in certificate authentication and cryptographic signatures is strong, but we need to make sure that our implementation and configuration of the services is correct. For that reason it's really important to have a set of automated end-to-end tests in place to ensure that the system is working as expected.

Due to the sensitive nature of the information provided by the SPI API we should not log the response payloads which makes assessing the impact of any incident harder. We can explore the option of anonymizing the logged payloads or only storing the client and account ids which should be safe for logs.

The cryptography and signature plugin needs to perform cryptographic operations following the JWS and JWE standards which tend to be problematic. The support from an expert in the field would greatly improve the security of the final solution.

Performance Impact

N/A

Developer Impact

N/A

Data Consumer Impact

The new persisted data will reside in an independent database and will not interact in any way with the existing data.

Deployment

It will depend on the deployment mechanism used by the Kong gateway.

Dependencies

In order to implement the proposed solution we need the Kong gateway up and running.

References

  1. PSP Technical Specification section 3.2
  2. PSP Technical Specification section 3.3
  3. PSP Technical Specification section 3.4
  4. JWS RFC-7515
  5. JWE RFC-7516