manpagez: man pages & more
man CURLOPT_SSH_KEYFUNCTION(3)
Home | html | info | man
CURLOPT_SSH_KEYFUNCTION(3)                            Library Functions Manual


NAME

       CURLOPT_SSH_KEYFUNCTION - callback for known host matching logic


SYNOPSIS

       #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

       This functionality affects scp and sftp


EXAMPLE

       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) {
           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");

           curl_easy_perform(curl);
       }
       }


AVAILABILITY

       Added in curl 7.19.6


RETURN VALUE

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


SEE ALSO

       CURLOPT_SSH_KEYDATA(3), CURLOPT_SSH_KNOWNHOSTS(3)

libcurl                           2024-08-05        CURLOPT_SSH_KEYFUNCTION(3)

curl 8.9.1 - Generated Mon Aug 5 15:23:24 CDT 2024
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.