While organizations which control DNS and CA have likely reduced risk to trivial levels under most threat models, users and developers subjugated to other's DNS and a public CA hierarchy are exposed to non-trivial amounts of risk. In fact, history has shown those relying on outside services have suffered chronic breaches in their secure channels. The pandemic abuse of trust has resulted in users, developers and applications making security related decisions on untrusted input. The situation is somewhat of a paradox: Relying on untrusted input for security related decisions is not only bad karma, it violates a number of secure coding principals see, for example, OWASP's Injection Theory and Data Validation.
Pinning effectively removes the "conference of trust". An application which pins a certificate or public key no longer needs to depend on others - such as DNS or CAs - when making security decisions relating to a peer's identity. SSH had it right the entire time, and the rest of the world is beginning to realize the virtues of directly identifying a host or service by its public key. Others who actively engage in pinning include Google and its browser Chrome.
Chrome was successful in detecting the DigiNotar compromise which uncovered suspected interception by the Iranian government on its citizens. Users, developers, and applications expect end-to-end security on their secure channels, but some secure channels are not meeting the expectation. Examples of past failures are listed on the discussion tab for this article. This cheat sheet does not attempt to catalogue the failures in the industry, investigate the design flaws in the scaffolding, justify the lack of accountability or liability with the providers, explain the race to the bottom in services, or demystify the collusion between, for example, Browsers and CAs.
Patient 0 The original problem was the Key Distribution Problem. Insecure communications can be transformed into a secure communication problem with encryption. Encrypted communications can be transformed into an identity problem with signatures.
The identity problem terminates at the key distribution problem. They are the same problem. The Cures There are three cures for the key distribution problem.
First is to have first hand knowledge of your partner or peer i. This could be solved with SneakerNet. Unfortunately, SneakerNet does not scale and cannot be used to solve the key distribution problem.
The second is to rely on others, and it has two variants: Web of Trust and Hierarchy of Trust solve the key distribution problem in a sterile environment. However, Web of Trust and Hierarchy of Trust each requires us to rely on others - or confer trust. In practice, trusting others is showing to be problematic. Pinning is the process of associating a host with their expected X certificate or public key. Once a certificate or public key is known or seen for a host, the certificate or public key is associated or 'pinned' to the host.
In this case, the advertised identity must match one of the elements in the pinset. A host or service's certificate or public key can be added to an application at development time, or it can be added upon first encountering the certificate or public key.
The former - adding at development time - is preferred since preloading the certificate or public key out of band usually means the attacker cannot taint the pin. If the certificate or public key is added upon first encounter, you will be using key continuity.
Key continuity can fail if the attacker has a privileged position during the first encounter. Pinning leverages knowledge of the pre-existing relationship between the user and an organization or service to help make better security related decisions. Because you already have information on the server or service, you don't need to rely on generalized mechanisms meant to solve the key distribution problem.
One exception is revocation and it is discussed below in Pinning Gaps. It is also worth mention that Pinning is not Stapling. Stapling sends both the certificate and OCSP responder information in the same request to avoid the additional fetches the client should perform during path validations.
When Do You Pin? You should pin anytime you want to be relatively certain of the remote host's identity or when operating in a hostile environment. Since one or both are almost always true, you should probably pin all the time. A perfect case in point: The environment is not only hostile, it's toxic. When Do You Whitelist? If you are working for an organization which practices "egress filtering" as part of a Data Loss Prevention DLP strategy, you will likely encounter Interception Proxies.
I like to refer to these things as "good" bad guys as opposed to "bad" bad guys since both break end-to-end security and we can't tell them apart.
In this case, do not offer to whitelist the interception proxy since it defeats your security goals. Add the interception proxy's public key to your pinset after being instructed to do so by the folks in Risk Acceptance. Security and integrity on the channel could suffer, and it surely breaks end-to-end security expectations of users and organizations. For more reading on interception proxies, the additional risk they bestow, and how they fail, see Dr.
Matthew Green's How do Interception Proxies fail? How Do You Pin? The idea is to re-use the existing protocols and infrastructure, but use them in a hardened manner. For re-use, a program would keep doing the things it used to do when establishing a secure connection. To harden the channel, the program would take advantage of the OnConnect callback offered by a library, framework or platform.
In the callback, the program would verify the remote host's identity by validating its certificate or public key. While pinning does not have to occur in an OnConnect callback, its often most convenient because the underlying connection information is readily available. What Should Be Pinned?
The first thing to decide is what should be pinned. For this choice, you have two options: If you choose public keys, you have two additional choices: The three choices are explained below in more detail.
The context will help you keep your bearings at times, and Figure 1 below shows the additional information available. A certificate is an object which binds an entity such as a person or organization to a public key via a signature.
A certificate has a subjectPublicKeyInfo. The subjectPublicKeyInfo is a key with additional information. The key is for the site random. Figures 1 and 2 above clearly show the modulus n at line 28 and exponent e at line For those who want to learn more, a more in-depth discussion from a programmer's perspective can be found at the Code Project's article Cryptographic Interoperability: Certificate Certificate The certificate is easiest to pin.
When the certificate expires, you would update your application. Assuming your application has no bugs or security defects, the application would be updated every year or two.
At runtime, you retrieve the website or server's certificate in the callback. Within the callback, you compare the retrieved certificate with the certificate embedded within the program. If the comparison fails, then fail the method or function. There is a downside to pinning a certificate. If the site rotates its certificate on a regular basis, then your application would need to be updated regularly. For example, Google rotates its certificates, so you will need to update your application about once a month if it depended on Google services.
Even though Google rotates its certificates, the underlying public keys within the certificate remain static. Public Key Public Key Public key pinning is more flexible but a little trickier due to the extra steps necessary to extract the public key from a certificate. As with a certificate, the program checks the extracted public key with its embedded copy of the public key.
There are two downsides two public key pinning. First, its harder to work with keys versus certificates since you usually must extract the key from the certificate. Extraction is a minor inconvenience in Java and. Second, the key is static and may violate key rotation policies. Hashing While the three choices above used DER encoding, its also acceptable to use a hash of the information or other transforms.
In fact, the original sample programs were written using digested certificates and public keys. The samples were changed to allow a programmer to inspect the objects with tools like dumpasn1 and other ASN. Hashing also provides three additional benefits.
First, hashing allows you to anonymize a certificate or public key. This might be important if you application is concerned about leaking information during decompilation and re-engineering. Second, a digested certificate fingerprint is often available as a native API for many libraries, so its convenient to use. Finally, an organization might want to supply a reserve or back-up identity in case the primary identity is compromised.
Hashing ensures your adversaries do not see the reserved certificate or public key in advance of its use. That is, it allows an adversary or other party who successfully phishes the user to override a known good pinset with non-authentic or fraudulent information.
Second, the reporting mechanism is suppressed from broken pinsets, so a complying user agent will be complicit in the cover up after the fact. Android Since Android N, the preferred way for implementing pinning is by leveraging Android's Network Security Configuration feature, which lets apps customize their network security settings in a safe, declarative configuration file without modifying app code. If devices running a version of Android that is earlier than N need to be supported, a backport of the Network Security Configuration pinning functionality is available via the TrustKit Android library at https: Lastly, the Android documentation provides an example of how SSL validation can be customized within the app's code in order to implement pinning in the Unknown CA implementation document.