Dev/SSL Certificate Pinning

From Whonix

< Dev



Defaults Discussion[edit]

Reasons for not enabling this feature by default:

  • The feature is not yet implemented.
  • Usefulness.
  • Implementation.
    • torbrowser-launcher is not installable from Debian stable at time of writing. TODO: expand
    • Whonix ™ is still installing tb-updater [archive] rather than torbrowser-launcher [archive] by default because, see ticket [archive]. So the certificate file /usr/share/torbrowser-launcher/torproject.pem is not installed by default.
    • It might be a Debian packaging bug to have whonixcheck depend on torbrowser-launcher for this purpose? Ignorable point, because whonixcheck is too specific to be included into Debian official repository anyhow.
    • We would also have to install torbrowser-launcher on Whonix-Gateway ™, so the certificate file /usr/share/torbrowser-launcher/torproject.pem gets installed by default. But since by Whonix ™ design, users must not use Tor Browser in Whonix-Gateway ™, we would have to hide (config-package-dev displace) torbrowser-launcher's start menu entries as well as build a wrapper around its binaries to warn against this. This is doable, but no one has implemented that yet.
    • We are unaware of any other package or even project that does provide SSL certificates for direct pinning (do not confuse this with SSL CA pinning), that we could rely on. Apparently there is not even a list of certain domains and their SSL certificates (public key hashes) (do not confuse this with SSL CA pinning).
  • Maintenance burden.
    • The Tor Project (TPO) refused to maintain an OpenPGP signed certificate [archive]. (They are excused: maintenance burden. TODO: expand)
    • Relying on torbrowser-launcher [archive] to maintain The Tor Project's SSL certificate file /usr/share/torbrowser-launcher/torproject.pem.
      • One time the maintainer of torbrowser-launcher was busy and needed ~1 month to upgrade TPO's SSL certificate file. (reference [archive]) He is excused, because he is a volunteer maintaining the software, under no obligations, probably earning no money with torbrowser-launcher, having other obligations. This is Freedom Software. Thank you for torbrowser-launcher!
      • The plan of the maintainer of torbrowser-launcher is to wait until the certificate breaks before upgrading it. This is already the best the maintainer can do in the absence of better support from TPO for this use case. No blame here. Everyone is excused here, also TPO, since maintaining this adds up to the maintenance burden. (reference [archive])
      • See also torbrowser-launcher issues search "pin" [archive] for eventual further issues with pinning.

TODO: expand



Please don't confuse SSL CA (Certificate Authority) pinning SSL direct pinning.

See also: [archive]

PIN Certificate Authority[edit]

Weaker method (still better than no pinning at all), more easy to maintain.

Install required software.

sudo apt-get install ca-certificates curl

Test, expected to work.

curl --verbose --tlsv1.2 --proto =https --capath /invalid/ --cacert /usr/share/ca-certificates/mozilla/DigiCert_High_Assurance_EV_Root_CA.crt

Test, expected to fail.

curl --verbose --tlsv1.2 --proto =https --capath /invalid/ --cacert /usr/share/ca-certificates/mozilla/AddTrust_External_Root.crt

PIN Certificate Directly[edit]

curl method[edit]


Better method, more difficult to maintain.

Get the Certificate[edit]


Install required software:

apt-get install ca-certificates curl

Download the public SSL certificate.

pem Format[edit]
Method 1[edit]

Method 1 just getting the certificate.

openssl s_client -connect >./x.cert </dev/null
Method 2[edit]

Or better method 2, getting the certificate while pinning's certificate authority.

openssl s_client -connect -CAfile /usr/share/ca-certificates/mozilla/DigiCert_Assured_ID_Root_CA.crt >./x.cert </dev/null
Method 3[edit]

Or even better method 3, getting the certificate while pinning's certificate authority and automatically extracting the certificate.

echo -n | openssl s_client -connect -CAfile /usr/share/ca-certificates/mozilla/DigiCert_Assured_ID_Root_CA.crt | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > ./torproject.pem
der Format[edit]


source [archive]

openssl s_client -connect 2>&1 < /dev/null | sed -n '/-----BEGIN/,/-----END/p' | openssl x509 -noout -pubkey | openssl rsa -pubin -outform DER >

Verify the Certificate[edit]

Get SHA-1 fingerprint:

openssl x509 -noout -in torproject.pem -fingerprint -sha1

Get SHA-256 fingerprint:

openssl x509 -noout -in torproject.pem -fingerprint -sha256

Manually compare SHA-1 and SHA-256 fingerprints with FAQ: SSL [archive].




Optionally render the ca-certificates useless for testing purposes. Using curl here, but wget has a bug [archive] and uses the ca-files anyway.

sudo mv /usr/share/ca-certificates /usr/share/ca-certificates_

Download with curl and the pinned certificate:


This needs curl 7.39.0 or above, because older versions do not support --pinnedpubkey.

curl --tlsv1.2 --proto =https --cacert ./torproject.pem > check.html

Eventually undo.

sudo mv /usr/share/ca-certificates_ /usr/share/ca-certificates

Alternate perl method[edit]

Source [archive]. Not reviewed!

# Code snippets taken from Net::SSLeay documentation and mildly modified.
# Requires a newer version of SSLeay (tested with 1.48)
# Needless to say, verify correct $host and $fingerprint before testing!!!

use Net::SSLeay qw(get_https3);

$host = "";
$port = 443;
$fingerprint = "C1:95:6D:C8:A7:DF:B2:A5:A5:69:34:DA:09:77:8E:3A:11:02:33:58";

($p, $resp, $hdrs, $server_cert) = get_https3($host, $port, '/');
if (!defined($server_cert) || ($server_cert == 0)) {
    warn "Subject Name: undefined, Issuer  Name: undefined";
} elsif (Net::SSLeay::X509_get_fingerprint($server_cert, "sha1") ne $fingerprint) {
    warn 'Invalid certificate fingerprint '
        .  Net::SSLeay::X509_get_fingerprint($server_cert, "sha1")
        . ' for ' . Net::SSLeay::X509_NAME_oneline(
} else {
    print $p;



text=Jobs in USA
Jobs in USA

Search engines: YaCy | Qwant | ecosia | MetaGer | peekier | Whonix ™ Wiki

Follow: 1024px-Telegram 2019 Logo.svg.png Iconfinder Apple Mail 2697658.png Twitter.png Facebook.png Rss.png Reddit.jpg 200px-Mastodon Logotype (Simple).svg.png

Support: 1024px-Telegram 2019 Logo.svg.png Discourse logo.png Matrix logo.svg.png

Donate: Donate Bank Wire Paypal Bitcoin accepted here Monero accepted here Contriute

Whonix donate bitcoin.png Monero donate Whonix.png United Federation of Planets 1000px.png

Twitter-share-button.png Facebook-share-button.png Telegram-share.png link=mailto:?subject=Dev/SSL Certificate Pinning&body= link= Certificate Pinning link= Certificate Pinning link= Certificate Pinning%20 Certificate Pinning

Check out the Whonix ™ News Blog. Rss.png

https link onion link

This is a wiki. Want to improve this page? Help is welcome and volunteer contributions are happily considered! Read, understand and agree to Conditions for Contributions to Whonix ™, then Edit! Edits are held for moderation. Policy of Whonix Website and Whonix Chat and Policy On Nonfreedom Software applies.

Copyright (C) 2012 - 2021 ENCRYPTED SUPPORT LP. Whonix ™ is a trademark. Whonix ™ is a licensee [archive] of the Open Invention Network [archive]. Unless otherwise noted, the content of this page is copyrighted and licensed under the same Freedom Software license as Whonix ™ itself. (Why?)

The personal opinions of moderators or contributors to the Whonix ™ project do not represent the project as a whole.

Whonix ™ is a derivative of and not affiliated with Debian [archive]. Debian is a registered trademark [archive] owned by Software in the Public Interest, Inc [archive].

Whonix ™ is produced independently from the Tor® [archive] anonymity software and carries no guarantee from The Tor Project [archive] about quality, suitability or anything else.

By using our website, you acknowledge that you have read, understood and agreed to our Privacy Policy, Cookie Policy, Terms of Service, and E-Sign Consent. Whonix ™ is provided by ENCRYPTED SUPPORT LP. See Imprint, Contact.

By using our website, you acknowledge that you have read, understood and agreed to our Privacy Policy, Cookie Policy, Terms of Service, and E-Sign Consent.