This is a Telesign repository for certificates
-What is Pinning? -Challenges to Pinning -Suggested Customer Action -Suggested Communication
This is not to teach our customers about pinning or encourage it among them.
What is Pinning?
Certificate pinning restricts which certificates are considered valid attempting to limiting risk. It bypasses standard PKI path validation where the server's certificate is validated against set pre-installed trusted Root Certificate Authorities(CA). Instead of allowing OS or application default trusted certificate stores to be used, operators "pin" the certificate authority (CA) issuer(s), public keys or even end-entity certificates of their choice. Clients connecting to that server will treat all other certificates as invalid and refuse to make an HTTPS connection. Pinning forces the client to validate the server’s certificate against a known copy, or specific manually installed set of Roots or Issuers. In certificate pinning the client only trusts those specifically identified server certificates installed in the code. The certificate is typically trusted against a known "fingerprint" hash but the method could use/include any identifiable attributes of the certificate as well or a specific set of custom Roots or Issuers. In server certificate pinning the code does not typically contain the full cert but a fingerprint, which is a hash of the certificate. When TLS negotiation happens and the server certificate is sent, the application hashes it with the same algorithm and compares. If they match it the TLS negotiation continues. If not then the connection is aborted. We do monitor our endpoints certificates against a known hash every day from every data center and 15 global regions.When pinning started becoming popular, the hope was that these extra layers of complexity made it harder for bad actors to use certificates in attacks or spoofs.
!(Certificate pinning.png)
Challenges to Pinning
Pinning presents a few challenges.
Renewals - Identity certificates must be renewed and this process requires no intervention with standard PKI path validation as the Root typically remains the same and the Issuer is provided during the TLS negotiations to validate the Identity certificate up to the Root. Pinning prevents PKI path validation since no Roots or Issuers are typically trusted, only the Identity certificate.
Traffic changes - Especially in relation to our CDN Endpoints. rest-ww.telesign.com, rest-api.telesign.com, rest.telesigncorp.cn and rest-mobile.telesign.com. Akamai generates its own certificate for the Akamai endpoints so the certificate hashes between Akamai and Telesign On-Prem will not match. If we needed to swap traffic onto or off of Akamai, in case of an issue, any customer that is pinning would immediately reject TLS negotiations and could not connect to Telesign API. The error seen by the customer may present either as a certificate validation error or could be a pinning specific error depending on their setup.
Certificate Compromises/Revocation - There are security issues with pinning. Sometimes certificates get revoked due compromise or other issues and when they do it is important that standard TLS negotiation can deny connections when a certificate is found on a revocation list. Pinning prevents the client from denying connections in this case as the certificate is manually trusted.
As a result of these problems and the difficulties of implementing pinning safely and robustly, there were more cases of sites being harmed by pinning than protected. The biggest problem with pinning is the lost ability to respond to certificate issues. If need arises to change keys, certificates, issuers, or CA vendor, for any reason, the client or code has to be fixed abruptly and often after an outage is already triggered. Pinning is also problematic with publicly trusted TLS certificates because they must continue adherence to ever-evolving rules, decreasing maximum lifetimes and other surprises. Certificate authories are increasing division of single use Roots and Issuers, reducing lifetimes and adding better signature and CRL functions that further reduce the original need for pinning.
Suggested Customer Action
Ideally, the customer should just use standard PKI path validations, this is over 99% of our customers. Customers that require pinning should trust all Telesign's Certs On-Prem and via CDN in their clients for their specific endpoint. The below draft stipulates the issues with pinning, our stance and the suggested action of trusting each cert in a bundle. The customer needs to trust the applicable bundle for the domain of the endpoint. I.E. rest-ww.telesign.com and rest-api.teleisgn.com only need the star_telesign_com-server-cert-bundle.pem so if sending them a communication then it only needs to contain the bundle for the endpoint they use.
The bundle will contain:
Full chain (RootCA & Issuer & Identity Certificates) of both CDN and On-Prem Endpoints.
Newly renewed Identity certificates with in the same RootCA & Issuer.
Full chain of newly renewed Identity certificates where the RootCA or Issuer are different.
A much better option than pinning is to have customers setup ALERTS when certificate fingerprints change instead of pinning. Then when certs are updated or if the API is forced to switch between On-Prem and CDN endpoints the transactions will not be rejected. The alert can instead trigger customer action to contact Telesign and ask if change is expected and valid.
In the future, it would be up to the customer to subscribe to page changes and update their cert pinning when we change the bundle(if this feature can be done on our pages). Until then the below information should be sent out to any known customers that are using certificate pinning. If this is sent out to all customers then some may read it and start pinning which is not what we want.
The client should compute the certificate hash from the PEM of each certificate in the bundle based on what ever algorithm they use. When you send them the file the File Validation hashes are to confirm the file contents. It is suggested to separate the file validation hashes in a different email or channel.
Suggested Communication
Disregard this email if your configuration does not require certificate pinning. It is not a recommended configuration and not officially supported when/if it causes issues.
The guidance and files below are provided in a best effort to help but may not prevent issues caused by pinning. Again, it is highly suggested all client TLS requests follow the traditional certificate path validation of PKI via typical RootCA trusts. If server, Issuer or specific RootCA level certificate pinning is required by your security policy please be aware of and follow the below guidance.
Any pinning can/will lead to transaction rejections by the client:
If/when certificates need to be renewed or changed for either standard or emergent reasons
If certificates must be revoked
Telesign maintains multiple server certificates for the same endpoint which may be from different Issuing and RootCAs. The bundles below contain all of the applicable server certificates, Issuers and RootCAs for a designated endpoint. Please download, validate and install the bundle for the client endpoint being used. Intermediate and Roots should be downloaded and installed from the RootCAs site directly as a best practice. They are however, included in the bundles below for convenience.
star_telesign_com-full-bundle.pem for API Customers using any *.telesign.com
File Validations - SHA256: 2bf06711065657a5dba8c5c39e1dd1be7b666a4429abeaf558f5f010cc65e097 MD5: 1e41e47bb47bfc3605ff6abafd4b6636
star_telesigncorp_cn-full-bundle.pem for API Customers using rest.telesigncorp.cn(China)
File Validations - SHA256: 49e3172dab8c1d902ed4983ac38496d91084d45af8498b3d6d84926beca8b859 MD5: ea10e865b7ad8dd165520119e3078416
star_tsentcloud_com-full-bundle.pem for API Customers using any *.tsentcloud.com
File Validations - SHA256: 2fe981c0062de50af592e2c1904eb3aa8bb36ba35a573345bcb0ff58b00a79c4 MD5: 453acb5388f94008a0fa3a61db3a04ba
Telesign does monitor the expected SHA256 hash of our endpoint's server certificates from 19 global locations. A suggested alternative to certificate pinning would be to alert on a known certificate hash change instead of blocking. This would allow applications to continue to work in cases of valid network or certificate changes to the endpoint.