libssh2_userauth_password_ex(3)

💖 libssh2_userauth_password_ex — bestie's guide 💖

okay so this is a page from the libssh2 manual, and today we're learning libssh2_userauth_password_ex — the glow-up version of "let me in, I have a password." 🫶

✨ NAME ✨

libssh2_userauth_password_ex — authenticate a session with username and password

🌸 SYNOPSIS 🌸

#include <libssh2.h>

int
libssh2_userauth_password_ex(LIBSSH2_SESSION *session,
                             const char *username,
                             unsigned int username_len,
                             const char *password,
                             unsigned int password_len,
                           LIBSSH2_PASSWD_CHANGEREQ_FUNC((*passwd_change_cb)));

#define libssh2_userauth_password(session, username, password) \
     libssh2_userauth_password_ex((session), (username), \
                                  strlen(username), \
                                  (password), strlen(password), NULL)

two for the price of one, bestie — the big girl function and the lil macro wrapper that calls it for you. 💅

🦋 DESCRIPTION 🦋

here's the whole cast, one by one:

• session — the session instance, as returned by libssh2_session_init_ex(3). your main character. 👑
• username — name of the user to attempt plain password authentication for. who are we pretending to be today.
• username_len — length of the username parameter. yes she wants the length separately, don't ask, it's a vibe.
• password — the password used to authenticate username. the secret. the tea. 🙈
• password_len — length of the password parameter.
• passwd_change_cb — if the host accepts the authentication but requests that the password be changed, this callback will be issued. and like, if no callback is defined but the server required a password change, the authentication will fail. no callback, no entry, periodt. 💀

so what does it actually do? attempt basic password authentication. that's the whole job.

⚠️ lowkey important: many SSH servers which appear to support ordinary password authentication actually have it disabled and use Keyboard Interactive authentication instead — routed via PAM or another authentication backend. so if your password auth is mysteriously not working, it might not be you, it might be the server being sneaky. 😭

💜 RETURN VALUE 💜

returns 0 on success, or negative on failure. it returns LIBSSH2_ERROR_EAGAIN when it would otherwise block.

and the iconic caveat: while LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. it's just saying "not right now babe, come back later." ✨

🔥 ERRORS 🔥

some of the errors this function may return include:

• 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 picking up the phone. 📵
• LIBSSH2_ERROR_PASSWORD_EXPIRED — …and that's literally it, that's the whole description, the manual leaves it at that, no elaboration, slay I guess. 🙈
• LIBSSH2_ERROR_AUTHENTICATION_FAILED — failed, invalid username/password or public/private key. the classic. the icon. the "who even are you." 🚫

🌈 SEE ALSO 🌈

• libssh2_session_init_ex(3)

and that's the whole page bestie, we ate, no crumbs left. this was the libssh2_userauth_password_ex(3) page from the libssh2 manual, version 0.15, dated 1 Jun 2007. iykyk 💖✨🎀🦋