Authenticating with SSL/TLS

Overview

Transport Layer Security (TLS), also known by its historical name of Secure Sockets Layer (SSL), is a security protocol that provides confidentiality and integrity for messages exchanged between a client and server and, in its most typical use-case, authentication of the server by the client.

Mutual TLS authentication (mTLS), also known as Client Certificate Authentication (CCA), adds authentication of the client during the TLS handshake. This is done in a very similar way to which the client authenticates the server, using X509 certificates that are exchanged during the handshake. Once the handshake is completed your authenticated identity is checked to ensure it is authorized to make the request, the same as it would be for using our HTTP-based authentication mechanism.

In order to use mTLS, you must first securely send us one or more issuer certificates that we associate with your account. You then configure your client, with a client certificate to send, and its corresponding private key. The certificate must be signed by one of the issuer certificates that you've sent to us (or you may use an intermediate certificate signed by the issuer certificate as well, if you wish).

During the TLS handshake, our service requests that you provide a certificate. Your client sends us the certificate along with proof of possession of the private key. You may optionally include one intermediate certificate in the handshake. We then authenticate you based on five criteria:

1. The time on our servers must be within the validity period of the client, optional intermediate and issuer certificate.
2. The signature of each certificate must be valid and the trust chain terminates with one of the issuer certificates that you have previously provided us.
3. The proof of possession of the corresponding private key for the client certificate must be valid.
4. We do not have a revocation notice for any certificate in the chain.
5. If you have provided any RDNs for the client certificate's Distinguished Name, these much match.

Integration guide

Follow these steps to set up mTLS for all traffic to and from Access Worldpay.

Step 1 - Override the IP Address for Access Worldpay Hostnames

Your local configuration must override the IP addresses for try.access.worldpay.com and access.worldpay.com. This is to point your traffic through the mTLS-secured access point to our services. Without changing IPs, the TLS handshake succeeds, but as you are providing no identity or authentication data, your request fails.

Each environment has two IP addresses to provide a fault-isolating design that increases the availability of Access Worldpay via mTLS. The two IPs are hosted on and managed by two different sets of physical infrastructure. If one IP is unavailable then the other will be available.

Step 2 - Provide issuer certificates

You must provide one or more issuer certificates (via an agreed secure channel). We use this to validate client certificates that you send us.

This must be a secure channel, so that we know that the issuer certificate has come from you and not a malicious third party.

You MAY use the same issuer certificates for Try and Live, but we RECOMMEND that you do not.

Step 3 - Provide Client Cert DN validation criteria (Optional)

Provide zero or more certificate Relative Distinguished Name (RDN) type/value pairs that we match the client certificate against, when we receive it.

For example, you could specify:

C=UK
O=AwesomeMerchant

We would examine each RDN of the DN and as long as all the criteria were found, this would be accepted.

Example of accepted DN values:

• CN=client1,O=AwesomeMerchant,C=UK - (ok to add CN)
• CN=client1,C=UK,O=AwesomeMerchant - (order is not important)
• CN=client1,O=AwesomeMerchant,L=Cambridge,C=UK - (ok to add any other RDN)

Examples of rejected DN values:

• CN=client1,O=AwesomeMerchant (missing C=UK)
• CN=client1,O=AwesomeMerchants,C=UK (mismatched O RDN)

If you do not provide any criteria, we accept any valid certificate that is signed by the issuer associated with your account.

Managing your certificates

Updating the issuer certificate

When the issuer certificate approaches expiry, you MUST send us a new issuer certificate. We then accept client certificates signed by either issuer, as long as the certificate is not expired. If any certificate in the chain is expired or otherwise invalid, the TLS handshake fails.

Once an issuer certificate has expired, it is automatically deleted on our side. You do not need to explicitly request this.

Revoking certificates

If you wish to revoke a certificate, because the corresponding private key is compromised for example, then you can use a manual or automated process.

Automated: For all client, intermediate and root certificates provided by you, we check the Online Certificate Status Protocol (OCSP) URL specified in the certificate at least once every 24 hours. If we cannot reach your OCSP endpoint for more than 7 days, then we will notify you.

Manual: If you are unable to supply or update an OCSP endpoint for issuer certificates then you can contact us, via an agreed secure channel, and provide us with the identity the certificate to be revoked. We then remove that specific certificate from your account. We do not maintain a list of invalid certificates for this approach.

Certificate Revocation Lists (CRLs) are not supported.

Constraints/rules

Client certificates must be X509v3 and are subject to the following constraints:

• All certificates MUST use either RSA, DSA or ECDSA certificate signing algorithms.
• All certificates MUST use a SHA-2 cryptographic hash algorithm for signing.
• You MAY provide a single intermediate certificate along with the client certificate on each request.
• The issuer certificate that you provide MUST contain the CA basic constraint and Certificate Sign key usage extension.
• The client certificate you provide MUST contain the TLS Client Authentication key usage extension.
• The client certificate MUST contain a non-zero length distinguished name (DN) component. All sub-components, (CN, O, OU, C, etc.) are optional. You may add your own custom sub-components.
• The issuer certificate provided to us MUST be in control of your organization, to ensure that a malicious third party could not create a client certificate that would be accepted by us.
• OCSP URLs MAY be provided in the certificate using the Authority Information Access (AIA) extension.

If any of these constraints are not met, the TLS handshake is not successful and you are unable to submit requests to Access Worldpay services.

Other technical information

Use with HTTP authentication

You SHOULD NOT provide any value in the HTTP Authorization header. Any value you do provide is ignored.

TLS version

You MUST only use TLS v1.2 or TLS v1.3.

TLS v1.3 notes

The following cipher suites are supported:

• TLS_AES_128_GCM_SHA256
• TLS_AES_256_GCM_SHA384
• TLS_CHACHA20_POLY1305_SHA256

We do not support 0-RTT, due to forward secrecy and replay-attack risks.

TLS v1.2 notes

For TLS v1.2, only Authenticated Encryption with Additional Data (AEAD) suites are supported.

You MAY supply your Client certificate using a renegotiation flow after the initial handshake. However, please be aware that this has a performance implication as the renegotiation flow requires more round-trips between your client and our service.

The following cipher suites are supported:

• TLS_ECDHE_RSA_WITH_AES128_GCM_SHA256
• TLS_ECDHE_RSA_WITH_AES256_GCM_SHA384
• TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305
• TLS_ECDHE_ECDSA_WITH_AES128_GCM_SHA256
• TLS_ECDHE_ECDSA_WITH_AES256_GCM_SHA384
• TLS_ECDHE_ECDSA_WITH_CHACHA20-POLY1305

We have constrained our implementation to these cipher suites because:

1. They provide forward secrecy, i.e. ephemeral keys are used for all connections, instead of protecting using the keys in the certificate.
2. AEAD cipher modes (specifically GCM) mitigate vulnerabilities in cipher modes such as CBC.
3. SHA-2 cryptographic hash functions have no practical vulnerabilities, unlike SHA-1 and MD5, which have real-world, exploitable vulnerabilities.

mTLS advantages and disadvantages

mTLS is a more secure way for client to authenticate themselves, both for you and for us. However, it does come at a cost. Here are some of the advantages and disadvantages of mTLS.

Credentials are private

Client certificates are created and managed by you. The private keys that corresponds to the public key contained within your certificates are never shared with Worldpay. This provides you with greater control of your secrets and non-repudiation for Worldpay, should the private key ever be compromised.

Built-in credential expiry

We do not enforce an expiry date on client credentials, so you can manage your client certificates in the way that best suits your own security standards and policies.

Client autonomy

You are free to manage your client certificates however you choose: adding new certificates, revoking existing or replacing them whenever suits you. We do not require notification of this, provided that you are not changing the issuer certificate.

Complexity

Managing a Public Key Infrastructure (PKI) for certificates requires careful design, investment and ongoing maintenance to maintain an acceptable level of security. This applies especially if you must host a reliable OCSP endpoint as well.

Certificate expiry risk

If a certificate expires, your TLS handshake is unsuccessful and your request is not processed. This means that until you replace the client or issuer certificate, you are unable to process payments on our platform.

You must therefore pay close warning to certificate expiry dates.

Setting up mTLS

Setting up the keys and certificates can be a daunting task, so much so that PKI is usually managed by a dedicated security team. If you want to get started quickly using mTLS in your development and QA environments, we've created a Setting up mTLS for Try, which walks you through creating the required artifacts using the ubiquitous OpenSSL toolkit.