Elliott Hughes | 82be86d | 2017-09-20 17:00:17 -0700 | [diff] [blame] | 1 | .\" ************************************************************************** |
| 2 | .\" * _ _ ____ _ |
| 3 | .\" * Project ___| | | | _ \| | |
| 4 | .\" * / __| | | | |_) | | |
| 5 | .\" * | (__| |_| | _ <| |___ |
| 6 | .\" * \___|\___/|_| \_\_____| |
| 7 | .\" * |
| 8 | .\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al. |
| 9 | .\" * |
| 10 | .\" * This software is licensed as described in the file COPYING, which |
| 11 | .\" * you should have received as part of this distribution. The terms |
| 12 | .\" * are also available at https://curl.haxx.se/docs/copyright.html. |
| 13 | .\" * |
| 14 | .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell |
| 15 | .\" * copies of the Software, and permit persons to whom the Software is |
| 16 | .\" * furnished to do so, under the terms of the COPYING file. |
| 17 | .\" * |
| 18 | .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY |
| 19 | .\" * KIND, either express or implied. |
| 20 | .\" * |
| 21 | .\" ************************************************************************** |
| 22 | .\" |
Elliott Hughes | 1ef06ba | 2018-05-30 15:43:58 -0700 | [diff] [blame] | 23 | .TH CURLOPT_PROXY_PINNEDPUBLICKEY 3 "May 31, 2017" "libcurl 7.60.0" "curl_easy_setopt options" |
Elliott Hughes | 82be86d | 2017-09-20 17:00:17 -0700 | [diff] [blame] | 24 | |
| 25 | .SH NAME |
| 26 | CURLOPT_PROXY_PINNEDPUBLICKEY \- set pinned public key for https proxy |
| 27 | .SH SYNOPSIS |
| 28 | #include <curl/curl.h> |
| 29 | |
| 30 | CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_PINNEDPUBLICKEY, char *pinnedpubkey); |
| 31 | .SH DESCRIPTION |
| 32 | Pass a pointer to a zero terminated string as parameter. The string can be the |
| 33 | file name of your pinned public key. The file format expected is "PEM" or "DER". |
| 34 | The string can also be any number of base64 encoded sha256 hashes preceded by |
| 35 | "sha256//" and separated by ";" |
| 36 | |
| 37 | When negotiating a TLS or SSL connection, the https proxy sends a certificate |
| 38 | indicating its identity. A public key is extracted from this certificate and |
| 39 | if it does not exactly match the public key provided to this option, curl will |
| 40 | abort the connection before sending or receiving any data. |
| 41 | |
| 42 | On mismatch, \fICURLE_SSL_PINNEDPUBKEYNOTMATCH\fP is returned. |
| 43 | |
| 44 | The application does not have to keep the string around after setting this |
| 45 | option. |
| 46 | .SH DEFAULT |
| 47 | NULL |
| 48 | .SH PROTOCOLS |
| 49 | All TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc. |
| 50 | .SH EXAMPLE |
| 51 | .nf |
| 52 | CURL *curl = curl_easy_init(); |
| 53 | if(curl) { |
| 54 | curl_easy_setopt(curl, CURLOPT_URL, "https://example.com"); |
| 55 | curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy:443"); |
| 56 | curl_easy_setopt(curl, CURLOPT_PROXY_PINNEDPUBLICKEY, |
| 57 | "sha256//YhKJKSzoTt2b5FP18fvpHo7fJYqQCjAa3HWY3tvRMwE=;sha256//t62CeU2tQiqkexU74Gxa2eg7fRbEgoChTociMee9wno="); |
| 58 | |
| 59 | /* Perform the request */ |
| 60 | curl_easy_perform(curl); |
| 61 | } |
| 62 | .fi |
| 63 | .SH PUBLIC KEY EXTRACTION |
| 64 | If you do not have the https proxy server's public key file you can extract it |
| 65 | from the https proxy server's certificate. |
| 66 | .nf |
| 67 | # retrieve the server's certificate if you don't already have it |
| 68 | # |
| 69 | # be sure to examine the certificate to see if it is what you expected |
| 70 | # |
| 71 | # Windows-specific: |
| 72 | # - Use NUL instead of /dev/null. |
| 73 | # - OpenSSL may wait for input instead of disconnecting. Hit enter. |
| 74 | # - If you don't have sed, then just copy the certificate into a file: |
| 75 | # Lines from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----. |
| 76 | # |
| 77 | openssl s_client -servername www.example.com -connect www.example.com:443 < /dev/null | sed -n "/-----BEGIN/,/-----END/p" > www.example.com.pem |
| 78 | |
| 79 | # extract public key in pem format from certificate |
| 80 | openssl x509 -in www.example.com.pem -pubkey -noout > www.example.com.pubkey.pem |
| 81 | |
| 82 | # convert public key from pem to der |
| 83 | openssl asn1parse -noout -inform pem -in www.example.com.pubkey.pem -out www.example.com.pubkey.der |
| 84 | |
| 85 | # sha256 hash and base64 encode der to string for use |
| 86 | openssl dgst -sha256 -binary www.example.com.pubkey.der | openssl base64 |
| 87 | .fi |
| 88 | The public key in PEM format contains a header, base64 data and a |
| 89 | footer: |
| 90 | .nf |
| 91 | -----BEGIN PUBLIC KEY----- |
| 92 | [BASE 64 DATA] |
| 93 | -----END PUBLIC KEY----- |
| 94 | .fi |
| 95 | .SH AVAILABILITY |
| 96 | PEM/DER support: |
| 97 | |
| 98 | 7.52.0: GSKit, GnuTLS, NSS, OpenSSL, PolarSSL, mbedtls, wolfSSL/CyaSSL |
| 99 | |
| 100 | sha256 support: |
| 101 | |
| 102 | 7.52.0: GnuTLS, NSS, OpenSSL, PolarSSL, mbedtls, wolfSSL/CyaSSL |
| 103 | |
| 104 | Other SSL backends not supported. |
| 105 | .SH RETURN VALUE |
| 106 | Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or |
| 107 | CURLE_OUT_OF_MEMORY if there was insufficient heap space. |
| 108 | .SH "SEE ALSO" |
| 109 | .BR CURLOPT_PROXY_SSL_VERIFYPEER "(3), " |
| 110 | .BR CURLOPT_PROXY_SSL_VERIFYHOST "(3), " |
| 111 | .BR CURLOPT_PROXY_CAINFO "(3), " |
| 112 | .BR CURLOPT_PROXY_CAPATH "(3), " |