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)