1---
2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_SSH_HOSTKEYFUNCTION
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_SSH_HOSTKEYDATA (3)
9  - CURLOPT_SSH_KNOWNHOSTS (3)
10Protocol:
11  - SFTP
12  - SCP
13Added-in: 7.84.0
14---
15
16# NAME
17
18CURLOPT_SSH_HOSTKEYFUNCTION - callback to check host key
19
20# SYNOPSIS
21
22~~~c
23#include <curl/curl.h>
24
25int keycallback(void *clientp,
26                int keytype,
27                const char *key,
28                size_t keylen);
29
30CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSH_HOSTKEYFUNCTION,
31                          keycallback);
32~~~
33
34# DESCRIPTION
35
36Pass a pointer to your callback function, which should match the prototype
37shown above. It overrides CURLOPT_SSH_KNOWNHOSTS(3).
38
39This callback gets called when the verification of the SSH host key is needed.
40
41**key** is **keylen** bytes long and is the key to check. **keytype**
42says what type it is, from the **CURLKHTYPE_*** series in the
43**curl_khtype** enum.
44
45**clientp** is a custom pointer set with CURLOPT_SSH_HOSTKEYDATA(3).
46
47The callback MUST return one of the following return codes to tell libcurl how
48to act:
49
50## CURLKHMATCH_OK
51
52The host key is accepted, the connection should continue.
53
54## CURLKHMATCH_MISMATCH
55
56the host key is rejected, the connection is canceled.
57
58# DEFAULT
59
60NULL
61
62# %PROTOCOLS%
63
64# EXAMPLE
65
66~~~c
67struct mine {
68  void *custom;
69};
70
71int hostkeycb(void *clientp,    /* passed with CURLOPT_SSH_HOSTKEYDATA */
72              int keytype,      /* CURLKHTYPE */
73              const char *key,  /* host key to check */
74              size_t keylen)    /* length of the key */
75{
76  /* 'clientp' points to the callback_data struct */
77  /* investigate the situation and return the correct value */
78  return CURLKHMATCH_OK;
79}
80int main(void)
81{
82  struct mine callback_data;
83  CURL *curl = curl_easy_init();
84  if(curl) {
85    curl_easy_setopt(curl, CURLOPT_URL, "sftp://example.com/thisfile.txt");
86    curl_easy_setopt(curl, CURLOPT_SSH_HOSTKEYFUNCTION, hostkeycb);
87    curl_easy_setopt(curl, CURLOPT_SSH_HOSTKEYDATA, &callback_data);
88
89    curl_easy_perform(curl);
90  }
91}
92~~~
93
94# NOTES
95
96Work only with the libssh2 backend.
97
98# %AVAILABILITY%
99
100# RETURN VALUE
101
102Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
103