libssh2_knownhost_checkp(3)

💖 NAME 💖

libssh2_knownhost_checkp — bestie, this is the one that checks a host plus its key against your whole list of known hosts 🫶

✨ SYNOPSIS ✨

#include <libssh2.h>

int
libssh2_knownhost_checkp(LIBSSH2_KNOWNHOSTS *hosts,
                         const char *host, int port,
                         const char *key, size_t keylen,
                         int typemask,
                         struct libssh2_knownhost **knownhost);

🌸 DESCRIPTION 🌸

okay so this function takes a host and its key and holds them up against your entire collection of known hosts, then reports back the tea about the entry that matched (or partially matched). vibe check for host keys, basically 💅

• host — pointer to the host name, in plain text. and like, it can be the IP numerical address of the host or the full name. either one, she's flexible ✨
• port — the port number used by the host. (or a negative number if you wanna check the generic host instead.) and here's the thing: if you do give the port number, libssh2 will check the key for that specific host + port number combo in addition to the plain host name only check. so you get both, lucky you 🎀
• key — pointer to the key for the given host 🔑
• keylen — total size in bytes of the key that the key argument is pointing at
• typemask — a bitmask that spells out the format and info about the data you're passing in here. specifically: what format the host name is in, what format the key is in, and what key type it is 👑

the host name gets given as one of these types:

• LIBSSH2_KNOWNHOST_TYPE_PLAIN
• LIBSSH2_KNOWNHOST_TYPE_CUSTOM

and the key is encoded using one of these encodings:

• LIBSSH2_KNOWNHOST_KEYENC_RAW
• LIBSSH2_KNOWNHOST_KEYENC_BASE64
• knownhost — if you set this to non-NULL, it has to be a pointer to a struct libssh2_knownhost pointer. that thing gets filled in so it points at info about a known host that matches, or partially matches 🦋

⭐ RETURN VALUE ⭐

libssh2_knownhost_check(3) returns info about how well the provided host + key pair matched one of the entries in the list of known hosts.

• LIBSSH2_KNOWNHOST_CHECK_FAILURE — something prevented the check from being made 😭
• LIBSSH2_KNOWNHOST_CHECK_NOTFOUND — no host match was found 🙈
• LIBSSH2_KNOWNHOST_CHECK_MATCH — hosts and keys match 🎉 slay
• LIBSSH2_KNOWNHOST_CHECK_MISMATCH — the host was found, but the keys did not match! 💀

not me about to be dramatic but that last one is genuinely the scary one. host showed up, key said "who r u". be careful bestie.

🌈 AVAILABILITY 🌈

added in libssh2 1.2.6 — so if you're on something older, it's giving ✨nothing✨

🍓 EXAMPLE 🍓

see the ssh2_exec.c example as provided in the tarball 📦

👑 SEE ALSO 👑

• libssh2_knownhost_init(3)
• libssh2_knownhost_free(3)
• libssh2_knownhost_add(3)

and that's the whole page, bestie 💖 this one's from the libssh2 manual, dated 1 May 2010 — old but iconic, no cap. go check those host keys 🫶