CURLOPT_SSH_KEYFUNCTION(3)

1CURLOPT_SSH_KEYFUNCTION(3)          libcurl         CURLOPT_SSH_KEYFUNCTION(3)
2
3
4

NAME

6       CURLOPT_SSH_KEYFUNCTION - callback for known host matching logic
7

SYNOPSIS

9       #include <curl/curl.h>
10
11       enum curl_khstat {
12         CURLKHSTAT_FINE_ADD_TO_FILE,
13         CURLKHSTAT_FINE,
14         CURLKHSTAT_REJECT, /* reject the connection, return an error */
15         CURLKHSTAT_DEFER,  /* do not accept it, but we cannot answer right
16                               now. Causes a CURLE_PEER_FAILED_VERIFICATION error but
17                               the connection will be left intact */
18         CURLKHSTAT_FINE_REPLACE
19       };
20
21       enum curl_khmatch {
22         CURLKHMATCH_OK,       /* match */
23         CURLKHMATCH_MISMATCH, /* host found, key mismatch! */
24         CURLKHMATCH_MISSING,  /* no matching host/key found */
25       };
26
27       struct curl_khkey {
28         const char *key; /* points to a null-terminated string encoded with
29                             base64 if len is zero, otherwise to the "raw"
30                             data */
31         size_t len;
32         enum curl_khtype keytype;
33       };
34
35       int ssh_keycallback(CURL *easy,
36                           const struct curl_khkey *knownkey,
37                           const struct curl_khkey *foundkey,
38                           enum curl_khmatch match,
39                           void *clientp);
40
41       CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_KEYFUNCTION,
42                                 ssh_keycallback);
43

DESCRIPTION

45       Pass a pointer to your callback function, which should match the proto‐
46       type shown above.
47
48       It gets called when the known_host matching has been done, to allow the
49       application  to act and decide for libcurl how to proceed. The callback
50       will only be called if CURLOPT_SSH_KNOWNHOSTS(3) is also set.
51
52       This callback function gets passed the CURL handle, the  key  from  the
53       known_hosts  file knownkey, the key from the remote site foundkey, info
54       from libcurl on the matching status and a custom pointer (set with CUR‐
55       LOPT_SSH_KEYDATA(3)).  It MUST return one of the following return codes
56       to tell libcurl how to act:
57
58       CURLKHSTAT_FINE_REPLACE
59              The new host+key is accepted and libcurl will  replace  the  old
60              host+key  into  the  known_hosts file before continuing with the
61              connection.  This will also add the new host+key  combo  to  the
62              known_host  pool  kept  in  memory if it was not already present
63              there. The adding of data to the file is done by completely  re‐
64              placing the file with a new copy, so the permissions of the file
65              must allow this. (Added in 7.73.0)
66
67       CURLKHSTAT_FINE_ADD_TO_FILE
68              The host+key is accepted and  libcurl  will  append  it  to  the
69              known_hosts  file  before  continuing  with the connection. This
70              will also add the host+key combo to the known_host pool kept  in
71              memory  if  it was not already present there. The adding of data
72              to the file is done by completely replacing the file with a  new
73              copy, so the permissions of the file must allow this.
74
75       CURLKHSTAT_FINE
76              The  host+key is accepted libcurl will continue with the connec‐
77              tion. This will also add the host+key combo  to  the  known_host
78              pool kept in memory if it was not already present there.
79
80       CURLKHSTAT_REJECT
81              The  host+key  is  rejected. libcurl will deny the connection to
82              continue and it will be closed.
83
84       CURLKHSTAT_DEFER
85              The host+key is rejected, but the SSH connection is asked to  be
86              kept  alive.   This  feature could be used when the app wants to
87              somehow return back and act on the host+key situation  and  then
88              retry without needing the overhead of setting it up from scratch
89              again.
90

DEFAULT

92       NULL
93

PROTOCOLS

95       SFTP and SCP
96

EXAMPLE

98       static int keycb(CURL *easy,
99                        const struct curl_khkey *knownkey,
100                        const struct curl_khkey *foundkey,
101                        enum curl_khmatch match,
102                        void *clientp)
103       {
104         /* 'clientp' points to the callback_data struct */
105         /* investigate the situation and return the correct value */
106         return CURLKHSTAT_FINE_ADD_TO_FILE;
107       }
108       {
109         curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/thisfile.txt");
110         curl_easy_setopt(curl, CURLOPT_SSH_KEYFUNCTION, keycb);
111         curl_easy_setopt(curl, CURLOPT_SSH_KEYDATA, &callback_data);
112         curl_easy_setopt(curl, CURLOPT_SSH_KNOWNHOSTS, "/home/user/known_hosts");
113
114         curl_easy_perform(curl);
115       }
116

AVAILABILITY

118       Added in 7.19.6
119

RETURN VALUE

121       Returns CURLE_OK if the option is supported,  and  CURLE_UNKNOWN_OPTION
122       if not.
123