Commit 55b78c5a authored by Travis Burtrum's avatar Travis Burtrum Committed by Daniel Stenberg
Browse files

SSL: Pinned public key hash support

parent c00b18d5

docs/curl.1

+7 −4
Original line number Diff line number Diff line
@@ -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"

docs/libcurl/opts/CURLOPT_PINNEDPUBLICKEY.3

+15 −4
Original line number Diff line number Diff line
@@ -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.

lib/vtls/cyassl.c

+13 −0
Original line number Diff line number Diff line
@@ -67,6 +67,7 @@ and that's a problem since options.h hasn't been included yet. */ 
#include <cyassl/error.h>

#endif

#include <cyassl/ctaocrypt/random.h>

#include <cyassl/ctaocrypt/sha256.h>



/* The last #include files should be: */

#include "curl_memory.h"
@@ -770,4 +771,16 @@ int Curl_cyassl_random(struct SessionHandle *data, 
  return 0;

}



void Curl_cyassl_sha256sum(const unsigned char *tmp, /* input */

                      size_t tmplen,

                      unsigned char *sha256sum /* output */,

                      size_t unused)

{

  Sha256 SHA256pw;

  (void)unused;

  InitSha256(&SHA256pw);

  Sha256Update(&SHA256pw, tmp, tmplen);

  Sha256Final(&SHA256pw, sha256sum);

}



#endif

lib/vtls/cyassl.h

+5 −0
Original line number Diff line number Diff line
@@ -42,6 +42,10 @@ CURLcode Curl_cyassl_connect_nonblocking(struct connectdata *conn, 
int Curl_cyassl_random(struct SessionHandle *data,

                       unsigned char *entropy,

                       size_t length);

void Curl_cyassl_sha256sum(unsigned char *tmp, /* input */

                     size_t tmplen,

                     unsigned char *sha256sum, /* output */

                     size_t unused);



/* Set the API backend definition to Schannel */

#define CURL_SSL_BACKEND CURLSSLBACKEND_CYASSL
@@ -65,6 +69,7 @@ int Curl_cyassl_random(struct SessionHandle *data, 
#define curlssl_check_cxn(x) ((void)x, -1)

#define curlssl_data_pending(x,y) Curl_cyassl_data_pending(x,y)

#define curlssl_random(x,y,z) Curl_cyassl_random(x,y,z)

#define curlssl_sha256sum(a,b,c,d) Curl_cyassl_sha256sum(a,b,c,d)



#endif /* USE_CYASSL */

#endif /* HEADER_CURL_CYASSL_H */

lib/vtls/gtls.c

+20 −0
Original line number Diff line number Diff line
@@ -39,6 +39,7 @@ 
#ifdef USE_GNUTLS_NETTLE

#include <gnutls/crypto.h>

#include <nettle/md5.h>

#include <nettle/sha2.h>

#else

#include <gcrypt.h>

#endif
@@ -1557,6 +1558,25 @@ void Curl_gtls_md5sum(unsigned char *tmp, /* input */ 
#endif

}



void Curl_gtls_sha256sum(const unsigned char *tmp, /* input */

                      size_t tmplen,

                      unsigned char *sha256sum, /* output */

                      size_t sha256len)

{

#if defined(USE_GNUTLS_NETTLE)

  struct sha256_ctx SHA256pw;

  sha256_init(&SHA256pw);

  sha256_update(&SHA256pw, (unsigned int)tmplen, tmp);

  sha256_digest(&SHA256pw, (unsigned int)sha256len, sha256sum);

#elif defined(USE_GNUTLS)

  gcry_md_hd_t SHA256pw;

  gcry_md_open(&SHA256pw, GCRY_MD_SHA256, 0);

  gcry_md_write(SHA256pw, tmp, tmplen);

  memcpy(sha256sum, gcry_md_read (SHA256pw, 0), sha256len);

  gcry_md_close(SHA256pw);

#endif

}



bool Curl_gtls_cert_status_request(void)

{

#ifdef HAS_OCSP