Artifactspublic-v0

curl

master
ply4 git calls156 ms289 KiB2 cachedprotocol v2
157 lines4.5 KiBRaw

NAME

CURLOPT_SSH_KEYFUNCTION - callback for known host matching logic

SYNOPSIS

c
#include <curl/curl.h>

enum curl_khstat {
  CURLKHSTAT_FINE_ADD_TO_FILE,
  CURLKHSTAT_FINE,
  CURLKHSTAT_REJECT, /* reject the connection, return an error */
  CURLKHSTAT_DEFER,  /* do not accept it, but we cannot answer right
                        now. Causes a CURLE_PEER_FAILED_VERIFICATION error but
                        the connection is left intact */
  CURLKHSTAT_FINE_REPLACE
};

enum curl_khmatch {
  CURLKHMATCH_OK,       /* match */
  CURLKHMATCH_MISMATCH, /* host found, key mismatch */
  CURLKHMATCH_MISSING,  /* no matching host/key found */
};

struct curl_khkey {
  const char *key; /* points to a null-terminated string encoded with
                      base64 if len is zero, otherwise to the "raw"
                      data */
  size_t len;
  enum curl_khtype keytype;
};

int ssh_keycallback(CURL *easy,
                    const struct curl_khkey *knownkey,
                    const struct curl_khkey *foundkey,
                    enum curl_khmatch match,
                    void *clientp);

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_KEYFUNCTION,
                          ssh_keycallback);

DESCRIPTION

Pass a pointer to your callback function, which should match the prototype shown above.

It gets called when the known_host matching has been done, to allow the application to act and decide for libcurl how to proceed. The callback is only called if CURLOPT_SSH_KNOWNHOSTS(3) is also set.

This callback function gets passed the curl handle, the key from the known_hosts file knownkey, the key from the remote site foundkey, info from libcurl on the matching status and a custom pointer (set with CURLOPT_SSH_KEYDATA(3)). It must return one of the following return codes to tell libcurl how to act:

CURLKHSTAT_FINE_REPLACE

The new host+key is accepted and libcurl replaces the old host+key into the known_hosts file before continuing with the connection. This also adds the new host+key combo to the known_host pool kept in memory if it was not already present there. The adding of data to the file is done by completely replacing the file with a new copy, so the permissions of the file must allow this. (Added in 7.73.0)

CURLKHSTAT_FINE_ADD_TO_FILE

The host+key is accepted and libcurl appends it to the known_hosts file before continuing with the connection. This also adds the host+key combo to the known_host pool kept in memory if it was not already present there. The adding of data to the file is done by completely replacing the file with a new copy, so the permissions of the file must allow this.

CURLKHSTAT_FINE

The host+key is accepted libcurl continues with the connection. This also adds the host+key combo to the known_host pool kept in memory if it was not already present there.

CURLKHSTAT_REJECT

The host+key is rejected. libcurl denies the connection to continue and it is closed.

CURLKHSTAT_DEFER

The host+key is rejected, but the SSH connection is asked to be kept alive. This feature could be used when the app wants to return and act on the host+key situation and then retry without needing the overhead of setting it up from scratch again.

DEFAULT

NULL

%PROTOCOLS%

EXAMPLE

c
struct mine {
  void *custom;
};

static int keycb(CURL *easy,
                 const struct curl_khkey *knownkey,
                 const struct curl_khkey *foundkey,
                 enum curl_khmatch match,
                 void *clientp)
{
  /* 'clientp' points to the callback_data struct */
  /* investigate the situation and return the correct value */
  return CURLKHSTAT_FINE_ADD_TO_FILE;
}

int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    CURLcode result;
    struct mine callback_data;
    curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/thisfile.txt");
    curl_easy_setopt(curl, CURLOPT_SSH_KEYFUNCTION, keycb);
    curl_easy_setopt(curl, CURLOPT_SSH_KEYDATA, &callback_data);
    curl_easy_setopt(curl, CURLOPT_SSH_KNOWNHOSTS, "/home/user/known_hosts");

    result = curl_easy_perform(curl);
    curl_easy_cleanup(curl);
  }
}

%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_SSH_KEYFUNCTION
5Section: 3
6Source: libcurl
7See-also:
8 - CURLOPT_SSH_KEYDATA (3)
9 - CURLOPT_SSH_KNOWNHOSTS (3)
10Protocol:
11 - SFTP
12 - SCP
13Added-in: 7.19.6
14---
16# NAME
18CURLOPT_SSH_KEYFUNCTION - callback for known host matching logic
20# SYNOPSIS
22~~~c
23#include <curl/curl.h>
25enum curl_khstat {
26 CURLKHSTAT_FINE_ADD_TO_FILE,
27 CURLKHSTAT_FINE,
28 CURLKHSTAT_REJECT, /* reject the connection, return an error */
29 CURLKHSTAT_DEFER, /* do not accept it, but we cannot answer right
30 now. Causes a CURLE_PEER_FAILED_VERIFICATION error but
31 the connection is left intact */
32 CURLKHSTAT_FINE_REPLACE
33};
35enum curl_khmatch {
36 CURLKHMATCH_OK, /* match */
37 CURLKHMATCH_MISMATCH, /* host found, key mismatch */
38 CURLKHMATCH_MISSING, /* no matching host/key found */
39};
41struct curl_khkey {
42 const char *key; /* points to a null-terminated string encoded with
43 base64 if len is zero, otherwise to the "raw"
44 data */
45 size_t len;
46 enum curl_khtype keytype;
47};
49int ssh_keycallback(CURL *easy,
50 const struct curl_khkey *knownkey,
51 const struct curl_khkey *foundkey,
52 enum curl_khmatch match,
53 void *clientp);
55CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_KEYFUNCTION,
56 ssh_keycallback);
57~~~
59# DESCRIPTION
61Pass a pointer to your callback function, which should match the prototype
62shown above.
64It gets called when the known_host matching has been done, to allow the
65application to act and decide for libcurl how to proceed. The callback is only
66called if CURLOPT_SSH_KNOWNHOSTS(3) is also set.
68This callback function gets passed the curl handle, the key from the
69known_hosts file *knownkey*, the key from the remote site *foundkey*, info
70from libcurl on the matching status and a custom pointer (set with
71CURLOPT_SSH_KEYDATA(3)). It must return one of the following return codes to
72tell libcurl how to act:
74## CURLKHSTAT_FINE_REPLACE
76The new host+key is accepted and libcurl replaces the old host+key into the
77known_hosts file before continuing with the connection. This also adds the new
78host+key combo to the known_host pool kept in memory if it was not already
79present there. The adding of data to the file is done by completely replacing
80the file with a new copy, so the permissions of the file must allow
81this. (Added in 7.73.0)
83## CURLKHSTAT_FINE_ADD_TO_FILE
85The host+key is accepted and libcurl appends it to the known_hosts file before
86continuing with the connection. This also adds the host+key combo to the
87known_host pool kept in memory if it was not already present there. The adding
88of data to the file is done by completely replacing the file with a new copy,
89so the permissions of the file must allow this.
91## CURLKHSTAT_FINE
93The host+key is accepted libcurl continues with the connection. This also adds
94the host+key combo to the known_host pool kept in memory if it was not already
95present there.
97## CURLKHSTAT_REJECT
99The host+key is rejected. libcurl denies the connection to continue and it is
100closed.
102## CURLKHSTAT_DEFER
104The host+key is rejected, but the SSH connection is asked to be kept alive.
105This feature could be used when the app wants to return and act on the
106host+key situation and then retry without needing the overhead of setting it
107up from scratch again.
109# DEFAULT
111NULL
113# %PROTOCOLS%
115# EXAMPLE
117~~~c
118struct mine {
119 void *custom;
120};
122static int keycb(CURL *easy,
123 const struct curl_khkey *knownkey,
124 const struct curl_khkey *foundkey,
125 enum curl_khmatch match,
126 void *clientp)
128 /* 'clientp' points to the callback_data struct */
129 /* investigate the situation and return the correct value */
130 return CURLKHSTAT_FINE_ADD_TO_FILE;
133int main(void)
135 CURL *curl = curl_easy_init();
136 if(curl) {
137 CURLcode result;
138 struct mine callback_data;
139 curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/thisfile.txt");
140 curl_easy_setopt(curl, CURLOPT_SSH_KEYFUNCTION, keycb);
141 curl_easy_setopt(curl, CURLOPT_SSH_KEYDATA, &callback_data);
142 curl_easy_setopt(curl, CURLOPT_SSH_KNOWNHOSTS, "/home/user/known_hosts");
144 result = curl_easy_perform(curl);
145 curl_easy_cleanup(curl);
146 }
148~~~
150# %AVAILABILITY%
152# RETURN VALUE
154curl_easy_setopt(3) returns a CURLcode indicating success or error.
156CURLE_OK (0) means everything was OK, non-zero means an error occurred, see
157libcurl-errors(3).
Diagnostics4 git calls · 156 ms
CallStatusSizeTime0156 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 · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=150
git.response.bytes=293470
git.response.cache=HIT
git.response.duration_ms=3
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
fetch2001.8 KiB150 ms
git.upload-pack fetch
http.response.status_code=200
git.response.bytes=1843
git.response.cache=MISS
git.response.duration_ms=150
git.fetch.wants=72bbbb4d9230634420be3fde71e68a30bc44515c
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=1843
git.pkt.payload.max=1822
git.sideband.band1.bytes=1821
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
a5e33960fe13f162
Request
1aed5769…
Protocol
v2 · sha1
Agent
gitty/1.0
Filter
advertised
Fetch
shallow filter sideband-all
Capabilities
agent ls-refs fetch object-format