libssh2_userau...interactive_ex(3)

💖 libssh2_userauth_keyboard_interactive_ex(3) 💖

okay bestie, gather round, because today we're talking about the libssh2 manual, section 3, and this specific lil function is giving keyboard-interactive authentication and honestly? iconic. it's libssh2_userauth_keyboard_interactive_ex and it's here to log you into a session the challenge/response way. no cap. 🎀

✨ NAME ✨

libssh2_userauth_keyboard_interactive_ex — authenticate a session using keyboard-interactive authentication 🦋

🌸 SYNOPSIS 🌸

#include <libssh2.h>

int
libssh2_userauth_keyboard_interactive_ex(LIBSSH2_SESSION *session,
                                         const char *username,
                                         unsigned int username_len,
                   LIBSSH2_USERAUTH_KBDINT_RESPONSE_FUNC(*response_callback));

💅 DESCRIPTION 💅

so here's the tea on the args, one by one, no skipping, periodt:

• session — the Session instance, which you got from libssh2_session_init_ex(3). your main character.
• username — the name of the user you're tryna do keyboard-interactive auth for. who dis.
• username_len — the length of that username parameter. yes you gotta say it out loud, it's that kind of function.
• response_callback — okay so this is the fun one. as authentication proceeds, the host is gonna issue several challenges (1 or more, not always just one, bestie) and it requires responses back. this callback gets called at that exact moment. the callback's whole job is to go get the responses for those challenges, fill in the provided data structure, and then return control. after that the responses get sent to the host. and listen — string values will be free(3)ed by the library, so don't you dare double-free them, that's not the vibe. 🙈

the callback prototype must match this, exactly, character for character:

void response(const char *name,
              int name_len, const char *instruction,
              int instruction_len,
              int num_prompts,
              const LIBSSH2_USERAUTH_KBDINT_PROMPT *prompts,
              LIBSSH2_USERAUTH_KBDINT_RESPONSE *responses,
              void **abstract);

so what does the function actually do? it Attempts keyboard-interactive (challenge/response) authentication. simple as that. slay. ✨

heads up, lowkey important: many SSH servers will always issue a single "password" challenge and ask for the actual password as the response. but — and this is the key part — it is not required by the protocol. various authentication schemes, like smartcard authentication, may use the keyboard-interactive authentication type too. so don't go assuming it's always a password situation, iykyk. 🧚

⭐ RETURN VALUE ⭐

• returns 0 on success 🎉
• returns negative on failure 😭
• returns LIBSSH2_ERROR_EAGAIN when it would otherwise block

and the way that LIBSSH2_ERROR_EAGAIN is a negative number but is not really a failure per se… it's giving "technically negative, emotionally fine". don't panic when you see it. 💜

💀 ERRORS 💀

• LIBSSH2_ERROR_ALLOC — an internal memory allocation call failed. the malloc said no. 💔
• LIBSSH2_ERROR_SOCKET_SEND — unable to send data on socket. the socket is not cooperating, bestie.
• LIBSSH2_ERROR_AUTHENTICATION_FAILED — failed, invalid username/password or public/private key. it's a no from the server, respectfully. 🫶

👑 SEE ALSO 👑

• libssh2_session_init_ex(3)

and that's the whole page, no crumbs left. this was from libssh2 version 0.19, dated 8 Mar 2008 — vintage, honestly, and still eating. mwah. 💋✨🌈