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

FreeBSD Manual Pages

  
 
  

home | help
CURLOPT_SSH_KEYFUNCTION(3) curl_easy_setopt options 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	can't answer right
			       now so this causes a CURLE_DEFER	error but
			       otherwise the connection	will be	left intact
			       etc */
       };

       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,
			   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
       will only be 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_ADD_TO_FILE
	      The host+key is accepted and  libcurl  will  append  it  to  the
	      known_hosts  file	 before	 continuing  with the connection. This
	      will also	add the	host+key combo to the known_host pool kept  in
	      memory if	it wasn't 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	will continue with the connec-
	      tion. This will also add the host+key combo  to  the  known_host
	      pool kept	in memory if it	wasn't already present there.

       CURLKHSTAT_REJECT
	      The  host+key  is	 rejected. libcurl will	deny the connection to
	      continue and it will be 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
	      somehow return back and act on the host+key situation  and  then
	      retry without needing the	overhead of setting it up from scratch
	      again.

DEFAULT
       NULL

PROTOCOLS
       SFTP and	SCP

EXAMPLE
       static int keycb(CURL *easy,
			const struct curl_khkey	*knownkey,
			const struct curl_khkey	*foundkey,
			enum curl_khmatch,
			void *clientp)
       {
	 /* 'clientp' points to	the callback_data struct */
	 /* investigate	the situation and return the correct value */
	 return	CURLKHSTAT_FINE_ADD_TO_FILE;
       }
       {
	 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	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	7.72.0			 June 25, 2020	    CURLOPT_SSH_KEYFUNCTION(3)

NAME | SYNOPSIS | DESCRIPTION | DEFAULT | PROTOCOLS | EXAMPLE | AVAILABILITY | RETURN VALUE | SEE ALSO

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

home | help