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