CURLOPT_PINNEDPUBLICKEY(3)

CURLOPT_PINNEDPUBLICKEY(3curl_easy_setopt optionCURLOPT_PINNEDPUBLICKEY(3)

NAME

     CURLOPT_PINNEDPUBLICKEY - set pinned public key

SYNOPSIS

     #include <curl/curl.h>

     CURLcode           curl_easy_setopt(CURL            *handle,
     CURLOPT_PINNEDPUBLICKEY, char *pinnedpubkey);

DESCRIPTION

     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 separated 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 if it does  not  exactly
     match  the  public  key  provided  to this option, curl will
     abort the connection before sending or receiving any data.

     On mismatch, CURLE_SSL_PINNEDPUBKEYNOTMATCH is returned.

     The application does not have  to  keep  the  string  around
     after setting this option.

DEFAULT

     NULL

PROTOCOLS

     All TLS based protocols: HTTPS, FTPS,  IMAPS,  POP3S,  SMTPS
     etc.

EXAMPLE

     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);
     }

PUBLIC KEY EXTRACTION

     If you do not have the server's  public  key  file  you  can
     extract it from the server's certificate.
     # retrieve the server's certificate if you don't already have it
     #

libcurl 7.58.0     Last change: April 17, 2017                  1

CURLOPT_PINNEDPUBLICKEY(3curl_easy_setopt optionCURLOPT_PINNEDPUBLICKEY(3)

     # be sure to examine the certificate to see if it is what you expected
     #
     # Windows-specific:
     # - Use NUL instead of /dev/null.
     # - OpenSSL may wait for input instead of disconnecting. Hit enter.
     # - If you don't have sed, then just copy the certificate into a file:
     #   Lines from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----.
     #
     openssl s_client -servername www.example.com -connect www.example.com:443 < /dev/null | sed -n "/-----BEGIN/,/-----END/p" > www.example.com.pem

     # extract public key in pem format from certificate
     openssl x509 -in www.example.com.pem -pubkey -noout > www.example.com.pubkey.pem

     # convert public key from pem to der
     openssl asn1parse -noout -inform pem -in www.example.com.pubkey.pem -out www.example.com.pubkey.der

     # sha256 hash and base64 encode der to string for use
     openssl dgst -sha256 -binary www.example.com.pubkey.der | openssl base64
     The public key in PEM format contains a header, base64  data
     and a footer:
     -----BEGIN PUBLIC KEY-----
     [BASE 64 DATA]
     -----END PUBLIC KEY-----

AVAILABILITY

     PEM/DER support:

       7.39.0: OpenSSL, GnuTLS and GSKit

       7.43.0: NSS and wolfSSL/CyaSSL

       7.47.0: mbedtls

       7.49.0: PolarSSL

       7.54.1: SecureTransport/DarwinSSL on macOS 10.7+/iOS 10+

     sha256 support:

       7.44.0: OpenSSL, GnuTLS, NSS and wolfSSL/CyaSSL

       7.47.0: mbedtls

       7.49.0: PolarSSL

       7.54.1: SecureTransport/DarwinSSL on macOS 10.7+/iOS 10+

     Other SSL backends not supported.

RETURN VALUE

     Returns CURLE_OK if  TLS  enabled,  CURLE_UNKNOWN_OPTION  if
     not,  or  CURLE_OUT_OF_MEMORY if there was insufficient heap

libcurl 7.58.0     Last change: April 17, 2017                  2

CURLOPT_PINNEDPUBLICKEY(3curl_easy_setopt optionCURLOPT_PINNEDPUBLICKEY(3)

     space.

SEE ALSO

     CURLOPT_SSL_VERIFYPEER(3),        CURLOPT_SSL_VERIFYHOST(3),
     CURLOPT_CAINFO(3), CURLOPT_CAPATH(3),

libcurl 7.58.0     Last change: April 17, 2017                  3