---
title: "What is certificate pinning (SSL pinning)?"
url: https://proxy.wiki/glossary/certificate-pinning/
type: Glossary Term
author: "proxy.wiki editorial"
published: 2026-09-06
updated: 2026-10-21
site: proxy.wiki
topics: ["Proxy fundamentals"]
license: CC BY 4.0; quote freely with attribution to https://proxy.wiki/
---

# What is certificate pinning (SSL pinning)?

> Certificate pinning is when a client accepts only a specific public key or certificate for a host, not any certificate that chains to a trusted root.

Pinning is what turns a trusted interception root into a failed connection. Without it, a client accepts any certificate that chains to a root in its store, including a root that a corporate middlebox or a debugging proxy installed there. With it, the client also checks that the server’s key is one it was told to expect, and nothing an interceptor can mint will match.

## What gets pinned

In RFC 7469, in curl and in Android, a SHA-256 hash of the certificate’s SubjectPublicKeyInfo, the encoded public key, rather than the whole certificate. A host can then renew its certificate without breaking clients, as long as it keeps the key. Android’s network security configuration works this way: a `<pin-set>` holds SHA-256 digests, a chain is valid only if it contains at least one pinned key, and Google’s documentation tells developers to always include a backup pin so a forced key change does not cut the app off until the next update. The optional `expiration` date switches pinning off for apps that are never updated, at the cost of letting an attacker wait it out.

The same hash, computed with OpenSSL 4.0.3 for example.com on 21 October 2026. It will change whenever that site changes its key.

```
$ openssl s_client -connect example.com:443 -servername example.com </dev/null 2>/dev/null \
    | openssl x509 -pubkey -noout \
    | openssl pkey -pubin -outform der \
    | openssl dgst -sha256 -binary | openssl base64
toyMGpiThuoVaTygu6QeCcnum2PKJknnGOsHalH7BzU=
```

## A pin against an interceptor, captured

curl can enforce a pin with `--pinnedpubkey sha256//<hash>`. Its manual says that if the key does not match, curl aborts the connection before sending or receiving any data. We ran curl 8.23.0 with that pin through a local Squid 6.13, first as a plain tunnel and then with ssl-bump interception signing certificates from a root we generated.

| Path | Certificate chain | Pin | Result |
| --- | --- | --- | --- |
| Direct | Public CA, accepted | Matches | 200 |
| Through a CONNECT tunnel | Public CA, accepted | Matches | 200 |
| Through ssl-bump, lab root not trusted | Rejected | Not reached | curl: (60) SSL certificate OpenSSL verify result: self-signed certificate in certificate chain (19) |
| Through ssl-bump, lab root trusted with --cacert | Accepted | Does not match | curl: (90) SSL: public key does not match pinned public key |

```
PIN='sha256//toyMGpiThuoVaTygu6QeCcnum2PKJknnGOsHalH7BzU='
curl -sS -o /dev/null -w '%{http_code}\n' --pinnedpubkey "$PIN" https://example.com/
curl -sS -o /dev/null -w '%{http_code}\n' -x http://127.0.0.1:3141 --pinnedpubkey "$PIN" https://example.com/
curl -sS -o /dev/null -w '%{http_code}\n' -x http://127.0.0.1:3142 --cacert lab-root.pem \
     --pinnedpubkey "$PIN" https://example.com/
```

The second row is the one people get wrong. An ordinary proxy never touches the certificate, so a pinned client works through it exactly as it does directly; the [CONNECT exchange](/guides/what-is-a-proxy-server/#what-actually-happens-on-the-wire) leaves the TLS handshake end to end. Pins fail only when something terminates TLS, which is [TLS interception](/glossary/tls-interception/), not proxying. The last row shows the whole point of a pin: the interceptor’s certificate passed ordinary validation and was still refused.

## Not every failure is a pin

On Android, an app targeting API level 24 or higher does not trust user-added CAs at all by default. Install an interception root on the phone and such an app rejects it with no pinning involved, just like the third row. Debug-only trust anchors are ignored unless the app is built debuggable. Before concluding that an app pins, check which of the two refusals you are looking at. Changing an app so that it accepts your certificate means modifying software you did not write, which raises legal and terms-of-service questions to settle before the technical ones.

## Why browsers dropped it

RFC 7469 defined `Public-Key-Pins`, a response header that let any site pin itself in visiting browsers. Chrome removed it in Chrome 72, citing very low adoption and the risk of denial of service and hostile pinning. An operator who loses the pinned key locks visitors out until the pin expires, and an attacker who briefly controls a site can set a pin the owner cannot undo before it expires. Pinning survives where the same party ships the client and the server: mobile apps, desktop clients and devices.

Pinning is also separate from the handshake a client presents. A pinned app still has its own [TLS fingerprint](/glossary/tls-fingerprinting/), and libraries show theirs consistently, as [our ClientHello study](/research/tls-clienthello-fingerprints/) found. Exit codes 60 and 90 above are certificate and pin failures; the proxy-side codes, 7, 28, 35 and 56, are explained under [reading the errors](/guides/how-to-use-a-proxy-with-curl/#reading-the-errors).

## Frequently asked questions

### Does a proxy break certificate pinning?

Not an ordinary one. A CONNECT proxy relays the encrypted bytes without touching the certificate, and in our test a pinned curl got a 200 through one. Pins break only when something terminates TLS and substitutes its own certificate.

### Why did browsers stop supporting the Public-Key-Pins header?

Chrome removed it in Chrome 72, citing very low adoption and the risk of denial of service and hostile pinning: a lost key or an attacker could lock visitors out until the pin expired. Pinning survives in apps whose vendor ships both client and server.

### Is pinning the same as certificate transparency?

No. Pinning is a client-side rule about which key to accept for one host. Certificate transparency is a set of public logs that make wrongly issued certificates discoverable after the fact. One prevents acceptance, the other enables detection.

## Sources

1. [RFC 7469: Public Key Pinning Extension for HTTP](https://www.rfc-editor.org/rfc/rfc7469.html)
2. [Android developers: network security configuration, pin-set, backup pins and user-added CAs](https://developer.android.com/privacy-and-security/security-config)
3. [curl manual: --pinnedpubkey](https://curl.se/docs/manpage.html#--pinnedpubkey)
4. [libcurl error codes, including 60 and 90](https://curl.se/libcurl/c/libcurl-errors.html)
5. [Chrome 72 deprecations and removals: HTTP-based Public Key Pinning removed](https://developer.chrome.com/blog/chrome-72-deps-rems)
