romenskiy2012/curl
1
0
Fork 0
mirror of https://github.com/curl/curl.git synced 2026-07-30 05:48:03 +03:00
Code Issues Projects Releases Packages Wiki Activity

SSL: Pinned public key hash support

Browse source
This commit is contained in:
moparisthebest 2015-06-30 20:23:54 -04:00 • committed by Daniel Stenberg
parent c00b18d540
commit 55b78c5ae9
16 changed files with 275 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

11
docs/curl.1
View file

@ -544,9 +544,11 @@ OpenSSL-powered curl to make SSL-connections much more efficiently than using
If this option is set, the default capath value will be ignored, and if it is
used several times, the last one will be used.
.IP "--pinnedpubkey <pinned public key>"
(SSL) Tells curl to use the specified public key file to verify the peer. The
file must contain a single public key in PEM or DER format.
.IP "--pinnedpubkey <pinned public key (hashes)>"
(SSL) Tells curl to use the specified public key file (or hashes) to verify the
peer. This can be a path to a file which contains a single public key in PEM or
DER format, or 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
@ -554,7 +556,8 @@ if it does not exactly match the public key provided to this option, curl will
abort the connection before sending or receiving any data.
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.
wolfSSL/CyaSSL. sha256 support added in 7.44.0 for OpenSSL,
GnuTLS, NSS and wolfSSL/CyaSSL. Other SSL backends not supported.
If this option is used several times, the last one will be used.
.IP "--cert-status"

19
docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.3
View file

@ -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.