Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
CURLOPT_SSH_KEYFUNCTION(3) Library Functions Manual CURLOPT_SSH_KEYFUNCTION(3)

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	proto-
       type 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 CUR-
       LOPT_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 re-
	      placing 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 mem-
	      ory 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 con-
	      tinue 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
       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).

SEE ALSO
       CURLOPT_SSH_KEYDATA(3), CURLOPT_SSH_KNOWNHOSTS(3)

libcurl				  2025-06-03	    CURLOPT_SSH_KEYFUNCTION(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=CURLOPT_SSH_KEYFUNCTION&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help