Artifactspublic-v0

curl

master
ply4 git calls308 ms289 KiB2 cachedprotocol v2
159 lines4.0 KiBRaw

NAME

CURLOPT_PINNEDPUBLICKEY - pinned public key

SYNOPSIS

c
#include <curl/curl.h>

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

DESCRIPTION

Pass a pointer to a null-terminated string as parameter. The string can be the filename 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 aborts the connection before sending or receiving any data.

This option is independent of option CURLOPT_SSL_VERIFYPEER(3). If you turn off that option then the peer is still verified by public key.

On mismatch, CURLE_SSL_PINNEDPUBKEYNOTMATCH is returned.

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

The pinned public key is used to verify the initial origin used in a transfer. If the transfer is set to follow redirects to other origins, they are not checked against this key.

For LDAP, this option only has an effect when using the OpenLDAP backend, which routes TLS through libcurl. It is not supported by AppleLDAP.

DEFAULT

NULL

%PROTOCOLS%

EXAMPLE

c
int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    CURLcode result;
    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//YhKJKSzoTt2b5FP18fvpHo7fJYqQCjAa3HWY3"
                     "tvRMwE=;sha256//t62CeU2tQiqkexU74Gxa2eg7fRbEg"
                     "oChTociMee9wno=");
    */

    /* Perform the request */
    result = curl_easy_perform(curl);
    curl_easy_cleanup(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 do not already have it
#
# 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 do not have sed, then 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-----

HISTORY

PEM/DER support

7.39.0: OpenSSL, GnuTLS

7.43.0: wolfSSL

7.47.0: mbedTLS

7.58.1: Schannel

sha256 support

7.44.0: OpenSSL, GnuTLS and wolfSSL

7.47.0: mbedTLS

7.58.1: Schannel

Other SSL backends not supported.

%AVAILABILITY%

RETURN VALUE

curl_easy_setopt(3) returns a CURLcode indicating success or error.

CURLE_OK (0) means everything was OK, non-zero means an error occurred, see libcurl-errors(3).

1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_PINNEDPUBLICKEY
5Section: 3
6Source: libcurl
7See-also:
8 - CURLOPT_CAINFO (3)
9 - CURLOPT_CAPATH (3)
10 - CURLOPT_SSL_VERIFYHOST (3)
11 - CURLOPT_SSL_VERIFYPEER (3)
12Protocol:
13 - TLS
14TLS-backend:
15 - OpenSSL
16 - GnuTLS
17 - wolfSSL
18 - mbedTLS
19 - Schannel
20Added-in: 7.39.0
21---
23# NAME
25CURLOPT_PINNEDPUBLICKEY - pinned public key
27# SYNOPSIS
29~~~c
30#include <curl/curl.h>
32CURLcode curl_easy_setopt(CURL *handle, CURLOPT_PINNEDPUBLICKEY,
33 char *pinnedpubkey);
34~~~
36# DESCRIPTION
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 `;`.
43When negotiating a TLS or SSL connection, the server 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, curl
46aborts the connection before sending or receiving any data.
48This option is independent of option CURLOPT_SSL_VERIFYPEER(3). If you turn
49off that option then the peer is still verified by public key.
51On mismatch, *CURLE_SSL_PINNEDPUBKEYNOTMATCH* is returned.
53The application does not have to keep the string around after setting this
54option.
56The pinned public key is used to verify the initial origin used in a transfer.
57If the transfer is set to follow redirects to other origins, they are *not*
58checked against this key.
60For LDAP, this option only has an effect when using the OpenLDAP backend,
61which routes TLS through libcurl. It is not supported by AppleLDAP.
63# DEFAULT
65NULL
67# %PROTOCOLS%
69# EXAMPLE
71~~~c
72int main(void)
74 CURL *curl = curl_easy_init();
75 if(curl) {
76 CURLcode result;
77 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
78 curl_easy_setopt(curl, CURLOPT_PINNEDPUBLICKEY, "/etc/publickey.der");
79 /* OR
80 curl_easy_setopt(curl, CURLOPT_PINNEDPUBLICKEY,
81 "sha256//YhKJKSzoTt2b5FP18fvpHo7fJYqQCjAa3HWY3"
82 "tvRMwE=;sha256//t62CeU2tQiqkexU74Gxa2eg7fRbEg"
83 "oChTociMee9wno=");
84 */
86 /* Perform the request */
87 result = curl_easy_perform(curl);
88 curl_easy_cleanup(curl);
89 }
91~~~
93# PUBLIC KEY EXTRACTION
95If you do not have the server's public key file you can extract it from the
96server's certificate.
97~~~
98# retrieve the server's certificate if you do not already have it
100# be sure to examine the certificate to see if it is what you expected
102# Windows-specific:
103# - Use NUL instead of /dev/null.
104# - OpenSSL may wait for input instead of disconnecting. Hit enter.
105# - If you do not have sed, then copy the certificate into a file:
106# Lines from -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----.
108openssl s_client -servername www.example.com -connect www.example.com:443 \
109 < /dev/null | sed -n "/-----BEGIN/,/-----END/p" > www.example.com.pem
111# extract public key in pem format from certificate
112openssl x509 -in www.example.com.pem -pubkey -noout > www.example.com.pubkey.pem
114# convert public key from pem to der
115openssl asn1parse -noout -inform pem -in www.example.com.pubkey.pem \
116 -out www.example.com.pubkey.der
118# sha256 hash and base64 encode der to string for use
119openssl dgst -sha256 -binary www.example.com.pubkey.der | openssl base64
120~~~
122The public key in PEM format contains a header, base64 data and a
123footer:
124~~~
125-----BEGIN PUBLIC KEY-----
126[BASE 64 DATA]
127-----END PUBLIC KEY-----
128~~~
130# HISTORY
132## PEM/DER support
1347.39.0: OpenSSL, GnuTLS
1367.43.0: wolfSSL
1387.47.0: mbedTLS
1407.58.1: Schannel
142## sha256 support
1447.44.0: OpenSSL, GnuTLS and wolfSSL
1467.47.0: mbedTLS
1487.58.1: Schannel
150Other SSL backends not supported.
152# %AVAILABILITY%
154# RETURN VALUE
156curl_easy_setopt(3) returns a CURLcode indicating success or error.
158CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
159libcurl-errors(3).
Diagnostics4 git calls · 308 ms
CallStatusSizeTime0308 ms
discover200152 B3 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=152
git.server.agent=gitty/1.0
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch object-format
git.server.fetch=shallow filter sideband-all
git.protocol.version=2
git.pkt.frames=8
git.pkt.data=6
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=152
git.pkt.payload.max=34
ls-refs200149 B · hit3 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=149
git.response.cache=HIT
git.response.duration_ms=3
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=149
git.pkt.payload.max=78
git.ls_refs.count=2
git.ls_refs.head=refs/heads/master
fetchblob:none · deepen 10200287 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=303
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=blob:none
git.fetch.filter.requested=tree:0
git.fetch.filter.fallback=blob:none
git.fetch.filter.learned=false
git.fetch.wants=31c911efe5652725e930f4d2e60c9060e5f6646d
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=10
git.pkt.data=8
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=293470
git.pkt.payload.max=65516
git.sideband.band1.bytes=293354
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=87
git.pack.bytes=293354
git.pack.ofs_delta=0
git.pack.ref_delta=1
git.pack.chain.max=1
git.pack.trailer=6a646bcda6740bab42e321b51998b52ea15146c0
git.pack.full=86
Open pack map
fetch2002.0 KiB303 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=2015
git.response.cache=MISS
git.response.duration_ms=303
git.fetch.wants=06d1ede3debc0bd5fb9597546e0ebf56706ea819
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=3
git.pkt.data=2
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=2015
git.pkt.payload.max=1994
git.sideband.band1.bytes=1993
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://5ad2236b39de4c8bd8f6270ea63f3ea9.artifacts.cloudflare.net/git/public-v0/curl.git
Ref
refs/heads/master
Commit
31c911efe5652725e930f4d2e60c9060e5f6646d
cf-ray
a5e37c736abd3a24
Request
b92e3b77…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format