Mutual Transport Layer Security (mTLS) is an end-to-end security protocol that verifies the identity of both sides of a communication stream—the client and the Pismo platform. It provides mutual authentication between client and server, ensuring that both parties verify each other's identities before establishing a secure connection.

mTLS is mandatory for all API calls to the Pismo platform. This protocol keeps the platform in compliance with legal requirements, such as the European Union's eIDAS regulation and the revised Payment Services Directive (PSD2).

To configure mTLS, contact your Pismo representative. There are three ways to configure the signed certificate:

1. Pismo generates and signs a private and public key and sends the public key to you through a secure channel.
2. You generate a private and public key and send the public key to Pismo through a Certificate Signing Request (CSR). Pismo sends back a signed public certificate.
3. You generate your own public certificate and sign it with your own CA. You provide the signed certificate to Pismo for upload to Cloudflare. In this case, refer to the Important details section.

How the mTLS process works

The following is an overview of how the authentication process works on the Pismo platform. During the process, if either side fails to present a valid certificate, the connection drops and no data is transmitted in either direction.

1. You connect to the platform.
2. The platform sends its TLS certificate.
3. You verify the certificate.
4. You send your certificate to the platform.
5. The platform verifies the certificate.
6. The platform grants access to you.
7. Data exchange occurs securely over the encrypted TLS connection.

Important details

The Pismo platform uses Cloudflare to provide signed certificates for the mTLS process. Certificates expire after three years.

If you want to use certificates from a different signing authority, you must provide Pismo with a risk letter that shows you understand the potential risks associated with your choice. This is necessary because in such a case Pismo cannot guarantee that the parties in each connection are who they claim to be.

In addition to the certificates, Pismo uses the Cloudflare Web Application Firewall (WAF), a more robust service against distributed denial-of-service (DDoS) attacks.

⚠️

Security note

Since mTLS is mandatory for all API calls to Pismo, the platform maintains a Web Application Firewall (WAF) rule to block API endpoints without it. This rule returns the following custom HTTP status codes:

• 485 MT-PIO returned by WAF if a request is made to an endpoint with mTLS configured but a valid certificate signed or trusted by Pismo was not presented.
• 490 NM-PIO/NM-IND for all requests to endpoints without mTLS configured. WAF blocked the request and you must re-configure your application to use an endpoint with mTLS.

If you receive a 485 or 490 error, report the incident to Pismo.