SSL: Pinned public key hash support

1 files changed, 15 insertions, 4 deletions

diff --git a/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.3 b/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.3
index 94cad31f0..0d4357ab1 100644
--- a/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.3
+++ b/docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.3
@@ -28,8 +28,10 @@ CURLOPT_PINNEDPUBLICKEY \- set pinned public key
 
 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PINNEDPUBLICKEY, char *pinnedpubkey);
 .SH DESCRIPTION
-Pass a pointer to a zero terminated string as parameter. The string should be
-the file name of your pinned public key. The format expected is "PEM" or "DER".
+Pass a pointer to a zero terminated string as parameter. The string can be the
+file name of your pinned public key. The file format expected is "PEM" or "DER".
+The string can also be any number of base64 encoded sha256 hashes preceded by
+"sha256//" and seperated by ";"
 
 When negotiating a TLS or SSL connection, the server sends a certificate
 indicating its identity. A public key is extracted from this certificate and
@@ -45,6 +47,9 @@ CURL *curl = curl_easy_init();
 if(curl) {
   curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
   curl_easy_setopt(curl, CURLOPT_PINNEDPUBLICKEY, "/etc/publickey.der");
+  /* OR
+  curl_easy_setopt(curl, CURLOPT_PINNEDPUBLICKEY, "sha256//YhKJKSzoTt2b5FP18fvpHo7fJYqQCjAa3HWY3tvRMwE=;sha256//t62CeU2tQiqkexU74Gxa2eg7fRbEgoChTociMee9wno=");
+  */
 
   /* Perform the request */
   curl_easy_perform(curl);
@@ -54,9 +59,14 @@ if(curl) {
 If you do not have the server's public key file you can extract it from the
 server's certificate.
 .nf
+# extract public key in pem format from certificate
 openssl x509 -in www.test.com.pem -pubkey -noout > www.test.com.pubkey.pem
+# convert public key from pem to der
+openssl asn1parse -noout -inform pem -in www.test.com.pubkey.pem -out www.test.com.pubkey.der
+# sha256 hash and base64 encode der to string for use
+openssl dgst -sha256 -binary www.test.com.pubkey.der | openssl base64
 .fi
-The public key is output in PEM format and contains a header, base64 data and a
+The public key in PEM format contains a header, base64 data and a
 footer:
 .nf
 -----BEGIN PUBLIC KEY-----
@@ -65,7 +75,8 @@ footer:
 .fi
 .SH AVAILABILITY
 Added in 7.39.0 for OpenSSL, GnuTLS and GSKit. Added in 7.43.0 for
-NSS and wolfSSL/CyaSSL. Other SSL backends not supported.
+NSS and wolfSSL/CyaSSL. sha256 support added in 7.44.0 for OpenSSL,
+GnuTLS, NSS and wolfSSL/CyaSSL. Other SSL backends not supported.
 .SH RETURN VALUE
 Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or
 CURLE_OUT_OF_MEMORY if there was insufficient heap space.