Certificates

The Certificates page (/certificates) manages the mTLS client certificates your systems present on the TCP data plane. This page is security-critical: the certificate you issue and hand to an integration is the thing SMP trusts to identify your organization on every TCP connection it accepts.

What a client certificate is for

Customer TCP traffic reaches SMP on three shared service ports — there is no port per tenant:

Port	Protocol	Engine
`11012`	Visa ISO 8583	SVE
`11013`	Mastercard ISO 8583	SME
`11014`	Raw payShield HSMaaS	SHE

SMP terminates mTLS on each of these ports. During the TLS handshake it validates the connecting client certificate against the Switchbench client CA root (issued by KMS); once connected, it computes the certificate’s SHA-256 fingerprint and resolves your org_id from it via CPS (GET /api/resolve-cert, cached). The destination port selects the protocol/engine; the client certificate selects the org — the same certificate authenticates you regardless of which of the three ports you connect to. The validated certificate is the authoritative source of tenant identity: SMP never trusts an ISO 8583 payload field (DE 32/33) on its own, only as a defense-in-depth cross-check against the certificate-resolved org.

This is why the page shows the fingerprint prominently alongside each certificate’s operator-assigned name — the name is just a label to help you recognise the certificate at a glance; it has no bearing on how SMP identifies you.

The list shows each certificate’s serial and fingerprint in full — they wrap onto the next line rather than being cut short — and each has a copy button, so you can paste the exact value into your client configuration or a support request.

For the full wire-level connection and framing contract, see Visa ISO 8583 over mTLS TCP, Mastercard ISO 8583 over mTLS TCP, and HSMaaS (raw payShield) over mTLS TCP.

Issue

Click Issue certificate.
Optionally set a name — a friendly label shown in the list, e.g. acme-prod. It is independent of the subject DN and can be changed later without affecting the certificate itself.
Optionally set a subject / DN (e.g. CN=acme,OU=prod). Leave it empty to use the default organization identifier. A plain name is accepted and becomes CN=<name>; a malformed DN is refused.
Optionally set a validity in days. Leave it empty for the default (365 days). Valid values are 1 to 3,650 days. A validity longer than the client CA’s remaining lifetime is refused, and the dashboard shows the maximum that can be issued.
Submit. CPS mints the certificate via the KMS-issued CA and returns the certificate PEM, private key PEM, and fingerprint. The result view also shows the connection details (host and the three data-plane ports) alongside them — those are fixed, always-available configuration, not part of what CPS returns or a one-time secret.

Copy the private key into your integration’s configuration now. CPS never stores it, so this result cannot be shown again — if you lose it, issue a new certificate (or see Rotating a certificate below for how to do that without downtime).

Rename

Rename changes only the certificate’s operator-assigned name — the display label used in the list when the certificate has no name, the table falls back to the subject’s common name and then to the raw subject DN, so the column is never blank. Renaming has no security effect: it does not change the subject DN, the fingerprint, or how SMP resolves your organization on the data plane. Clearing the name field explicitly removes it rather than leaving it unchanged.

Revoke

Revoking a certificate is irreversible — there is no way to reactivate it. Once revoked, its fingerprint stops resolving to your organization. What happens next depends on whether the connection is new or already open:

A new connection attempt (a fresh dial, or a reconnect after the old session drops) still completes the TLS handshake — the certificate continues to chain to the CA root, revocation doesn’t affect that — but CPS’s /api/resolve-cert lookup that follows now returns a revoked status, so SMP closes the connection immediately after the handshake, before any ISO 8583 or HSM payload is processed. If that fingerprint’s active decision was cached from a call made just before you revoked it, a new connection can still be authorized against that stale cache entry for up to its TTL (30 seconds by default) before revocation takes effect.
An open Visa or Mastercard ISO 8583 connection (ports 11012 and 11013) is re-checked every 15 seconds by default while it is idle, and its certificate is checked again before each frame it delivers. When the certificate no longer resolves as active, SMP closes the session.
An open HSMaaS connection (port 11014) has no idle re-check. Its certificate and entitlement are checked before each payShield command, and a command that fails the check is answered with SMP-ERR:FORBIDDEN_PRODUCT, and the connection is closed. Revocation takes effect on the next command once the cache TTL has passed.

Because of that, revoking a certificate does not cut off traffic immediately. Expect up to the cache TTL of continued access on every port, and up to a further 15 seconds on an idle ISO 8583 connection. Plan for that if you’re responding to a suspected key compromise, and pair the revoke with closing the affected connection at the network layer if it needs to stop immediately. For routine rotation, this is what makes an overlap window safe: see Rotating a certificate below.

Rotating a certificate without breaking a live integration

There is no in-place “renew” action — rotating a certificate means issuing a new one and retiring the old one once the new one is in use:

Issue a new certificate for the same org (optionally with a name that makes the handover obvious, e.g. acme-prod-2).
Deploy the new certificate PEM and private key to the integration, and confirm it connects successfully with the new fingerprint.
Revoke the old certificate once you’ve confirmed the integration is using the new one — an integration can hold multiple valid certificates for the same org at once, so the two can overlap while you cut over.

Rotate whenever a private key may have leaked, ahead of a certificate’s expiry (notAfter shown in the list), or as routine credential hygiene.