Return to CURLOPT_SSH_KEYFUNCTION.3 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs / libcurl / opts

Annotation of embedaddon/curl/docs/libcurl/opts/CURLOPT_SSH_KEYFUNCTION.3, revision 1.1.1.1

1.1       misho       1: .\" **************************************************************************
                      2: .\" *                                  _   _ ____  _
                      3: .\" *  Project                     ___| | | |  _ \| |
                      4: .\" *                             / __| | | | |_) | |
                      5: .\" *                            | (__| |_| |  _ <| |___
                      6: .\" *                             \___|\___/|_| \_\_____|
                      7: .\" *
                      8: .\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
                      9: .\" *
                     10: .\" * This software is licensed as described in the file COPYING, which
                     11: .\" * you should have received as part of this distribution. The terms
                     12: .\" * are also available at https://curl.haxx.se/docs/copyright.html.
                     13: .\" *
                     14: .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
                     15: .\" * copies of the Software, and permit persons to whom the Software is
                     16: .\" * furnished to do so, under the terms of the COPYING file.
                     17: .\" *
                     18: .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
                     19: .\" * KIND, either express or implied.
                     20: .\" *
                     21: .\" **************************************************************************
                     22: .\"
                     23: .TH CURLOPT_SSH_KEYFUNCTION 3 "May 31, 2017" "libcurl 7.70.0" "curl_easy_setopt options"
                     24: 
                     25: .SH NAME
                     26: CURLOPT_SSH_KEYFUNCTION \- callback for known host matching logic
                     27: .SH SYNOPSIS
                     28: .nf
                     29: #include <curl/curl.h>
                     30: 
                     31: enum curl_khstat {
                     32:   CURLKHSTAT_FINE_ADD_TO_FILE,
                     33:   CURLKHSTAT_FINE,
                     34:   CURLKHSTAT_REJECT, /* reject the connection, return an error */
                     35:   CURLKHSTAT_DEFER,  /* do not accept it, but we can't answer right
                     36:                         now so this causes a CURLE_DEFER error but
                     37:                         otherwise the connection will be left intact
                     38:                         etc */
                     39: };
                     40: 
                     41: enum curl_khmatch {
                     42:   CURLKHMATCH_OK,       /* match */
                     43:   CURLKHMATCH_MISMATCH, /* host found, key mismatch! */
                     44:   CURLKHMATCH_MISSING,  /* no matching host/key found */
                     45: };
                     46: 
                     47: struct curl_khkey {
                     48:   const char *key; /* points to a zero-terminated string encoded with
                     49:                       base64 if len is zero, otherwise to the "raw"
                     50:                       data */
                     51:   size_t len;
                     52:   enum curl_khtype keytype;
                     53: };
                     54: 
                     55: int ssh_keycallback(CURL *easy,
                     56:                     const struct curl_khkey *knownkey,
                     57:                     const struct curl_khkey *foundkey,
                     58:                     enum curl_khmatch,
                     59:                     void *clientp);
                     60: 
                     61: CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_KEYFUNCTION,
                     62:                           ssh_keycallback);
                     63: .SH DESCRIPTION
                     64: Pass a pointer to your callback function, which should match the prototype
                     65: shown above.
                     66: 
                     67: It gets called when the known_host matching has been done, to allow the
                     68: application to act and decide for libcurl how to proceed. The callback will
                     69: only be called if \fICURLOPT_SSH_KNOWNHOSTS(3)\fP is also set.
                     70: 
                     71: This callback function gets passed the CURL handle, the key from the
                     72: known_hosts file \fIknownkey\fP, the key from the remote site \fIfoundkey\fP,
                     73: info from libcurl on the matching status and a custom pointer (set with
                     74: \fICURLOPT_SSH_KEYDATA(3)\fP). It MUST return one of the following return
                     75: codes to tell libcurl how to act:
                     76: 
                     77: .IP CURLKHSTAT_FINE_ADD_TO_FILE
                     78: The host+key is accepted and libcurl will append it to the known_hosts file
                     79: before continuing with the connection. This will also add the host+key combo
                     80: to the known_host pool kept in memory if it wasn't already present there. The
                     81: adding of data to the file is done by completely replacing the file with a new
                     82: copy, so the permissions of the file must allow this.
                     83: .IP CURLKHSTAT_FINE
                     84: The host+key is accepted libcurl will continue with the connection. This will
                     85: also add the host+key combo to the known_host pool kept in memory if it wasn't
                     86: already present there.
                     87: .IP CURLKHSTAT_REJECT
                     88: The host+key is rejected. libcurl will deny the connection to continue and it
                     89: will be closed.
                     90: .IP CURLKHSTAT_DEFER
                     91: The host+key is rejected, but the SSH connection is asked to be kept alive.
                     92: This feature could be used when the app wants to somehow return back and act
                     93: on the host+key situation and then retry without needing the overhead of
                     94: setting it up from scratch again.
                     95: .SH DEFAULT
                     96: NULL
                     97: .SH PROTOCOLS
                     98: SFTP and SCP
                     99: .SH EXAMPLE
                    100: .nf
                    101: static int keycb(CURL *easy,
                    102:                  const struct curl_khkey *knownkey,
                    103:                  const struct curl_khkey *foundkey,
                    104:                  enum curl_khmatch,
                    105:                  void *clientp)
                    106: {
                    107:   /* 'clientp' points to the callback_data struct */
                    108:   /* investigate the situation and return the correct value */
                    109:   return CURLKHSTAT_FINE_ADD_TO_FILE;
                    110: }
                    111: {
                    112:   curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/thisfile.txt");
                    113:   curl_easy_setopt(curl, CURLOPT_SSH_KEYFUNCTION, keycb);
                    114:   curl_easy_setopt(curl, CURLOPT_SSH_KEYDATA, &callback_data);
                    115:   curl_easy_setopt(curl, CURLOPT_SSH_KNOWNHOSTS, "/home/user/known_hosts");
                    116: 
                    117:   curl_easy_perform(curl);
                    118: }
                    119: .fi
                    120: .SH AVAILABILITY
                    121: Added in 7.19.6
                    122: .SH RETURN VALUE
                    123: Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
                    124: .SH "SEE ALSO"
                    125: .BR CURLOPT_SSH_KEYDATA "(3), " CURLOPT_SSH_KNOWNHOSTS "(3), "