1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_PROXY_PINNEDPUBLICKEY
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_PINNEDPUBLICKEY (3)
9  - CURLOPT_PROXY_CAINFO (3)
10  - CURLOPT_PROXY_CAPATH (3)
11  - CURLOPT_PROXY_SSL_VERIFYHOST (3)
12  - CURLOPT_PROXY_SSL_VERIFYPEER (3)
13Protocol:
14  - TLS
15TLS-backend:
16  - OpenSSL
17  - GnuTLS
18  - mbedTLS
19  - wolfSSL
20Added-in: 7.52.0
21---
22
23# NAME
24
25CURLOPT_PROXY_PINNEDPUBLICKEY - pinned public key for https proxy
26
27# SYNOPSIS
28
29~~~c
30#include <curl/curl.h>
31
32CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PROXY_PINNEDPUBLICKEY,
33                          char *pinnedpubkey);
34~~~
35
36# DESCRIPTION
37
38Pass a pointer to a null-terminated string as parameter. The string can be the
39filename of your pinned public key. The file format expected is "PEM" or
40"DER". The string can also be any number of base64 encoded sha256 hashes
41preceded by "sha256//" and separated by ";"
42
43When negotiating a TLS or SSL connection, the https proxy sends a certificate
44indicating its identity. A public key is extracted from this certificate and
45if it does not exactly match the public key provided to this option, libcurl
46aborts the connection before sending or receiving any data.
47
48On mismatch, *CURLE_SSL_PINNEDPUBKEYNOTMATCH* is returned.
49
50The application does not have to keep the string around after setting this
51option.
52
53Using this option multiple times makes the last set string override the
54previous ones. Set it to NULL to disable its use again.
55
56# DEFAULT
57
58NULL
59
60# %PROTOCOLS%
61
62# EXAMPLE
63
64~~~c
65int main(void)
66{
67  CURL *curl = curl_easy_init();
68  if(curl) {
69    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
70    curl_easy_setopt(curl, CURLOPT_PROXY, "https://proxy:443");
71    curl_easy_setopt(curl, CURLOPT_PROXY_PINNEDPUBLICKEY,
72                     "sha256//YhKJKSzoTt2b5FP18fvpHo7fJYqQCjA"
73                     "a3HWY3tvRMwE=;sha256//t62CeU2tQiqkexU74"
74                     "Gxa2eg7fRbEgoChTociMee9wno=");
75
76    /* Perform the request */
77    curl_easy_perform(curl);
78  }
79}
80~~~
81
82# PUBLIC KEY EXTRACTION
83
84If you do not have the https proxy server's public key file you can extract it
85from the https proxy server's certificate.
86~~~c
87# retrieve the server's certificate if you do not already have it
88#
89# be sure to examine the certificate to see if it is what you expected
90#
91# Windows-specific:
92# - Use NUL instead of /dev/null.
93# - OpenSSL may wait for input instead of disconnecting. Hit enter.
94# - If you do not have sed, then just copy the certificate into a file:
95#   Lines from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----.
96#
97openssl s_client -servername www.example.com -connect www.example.com:443 \
98  < /dev/null | sed -n "/-----BEGIN/,/-----END/p" > www.example.com.pem
99
100# extract public key in pem format from certificate
101openssl x509 -in www.example.com.pem -pubkey -noout > www.example.com.pubkey.pem
102
103# convert public key from pem to der
104openssl asn1parse -noout -inform pem -in www.example.com.pubkey.pem \
105  -out www.example.com.pubkey.der
106
107# sha256 hash and base64 encode der to string for use
108openssl dgst -sha256 -binary www.example.com.pubkey.der | openssl base64
109~~~
110The public key in PEM format contains a header, base64 data and a
111footer:
112~~~c
113-----BEGIN PUBLIC KEY-----
114[BASE 64 DATA]
115-----END PUBLIC KEY-----
116~~~
117
118# HISTORY
119
120PEM/DER support:
121
122 7.52.0: GnuTLS, OpenSSL, mbedTLS, wolfSSL
123
124sha256 support:
125
126 7.52.0: GnuTLS, OpenSSL, mbedTLS, wolfSSL
127
128Other SSL backends not supported.
129
130# %AVAILABILITY%
131
132# RETURN VALUE
133
134Returns CURLE_OK if TLS enabled, CURLE_UNKNOWN_OPTION if not, or
135CURLE_OUT_OF_MEMORY if there was insufficient heap space.
136