Certificate Pinning

Certificate pinning is a security technique where a client validates a server's TLS certificate against a known copy (or public key hash) stored locally in the client application. While this can mitigate certain classes of man-in-the-middle attacks, it's generally not recommended for modern APIs and is especially problematic for services that use short-lived, automatically rotated certificates.

Why pinning is discouraged on Zuplo

By default, Zuplo manages SSL certificates for your custom domain through Cloudflare. These certificates are issued by either Google Trust Services or Let's Encrypt and have the following properties:

• Certificates are issued for 90 days.
• Certificates are automatically renewed approximately 30 days before expiry.
• Rotation is not guaranteed to follow a strict 90-day cadence. We may rotate certificates earlier for security, operational, or infrastructure reasons.
• Rotation happens without advance notification to the gateway owner.

Because rotation is automatic and the exact schedule isn't under your control, any client that pins a specific certificate or public key can stop working at any time. For most production APIs, this risk far outweighs the marginal security benefit pinning provides.

Recommended alternatives

If you or your clients are concerned about man-in-the-middle attacks or unauthorized certificate issuance, use these alternatives instead of pinning:

• HTTP Strict Transport Security (HSTS) to force HTTPS and prevent protocol downgrade attacks.
• CAA DNS records to restrict which certificate authorities can issue certificates for your domain.

If a client insists on pinning

Pinning is strongly discouraged, but if a client application insists on it, they can self-serve. The public portion of the certificate is returned on every TLS handshake, so anyone connecting to your domain can retrieve it using standard tools like openssl or curl. Zuplo doesn't need to send the certificate and has no record of who has downloaded it.

If a client goes down this path, they should be aware that:

• Certificates rotate automatically and can change at any time.
• Pinning the Subject Public Key Info (SPKI) hash is more resilient than pinning the full certificate, but still not guaranteed to survive rotation.
• The client is responsible for monitoring the certificate and updating their pins before the next rotation breaks their application.

Using your own long-lived SSL certificate

If you truly need full control over certificate rotation, the only supported option is to supply your own SSL certificate for your domain and have Zuplo install it. Contact support@zuplo.com to arrange this.