libssh2_userau...ey_fromfile_ex(3)

💖 libssh2_userau...ey_fromfile_ex(3) 💖

okay bestie, gather round, because this one lives in the libssh2 manual and it's literally the glow-up you need when you want to log into a session with a key that's just... sitting in a file. no cap.

✨ NAME ✨

libssh2_userauth_publickey_fromfile_ex — authenticate a session with a public key, read from a file 🗝️

🌸 SYNOPSIS 🌸

#include <libssh2.h>

int
libssh2_userauth_publickey_fromfile_ex(LIBSSH2_SESSION *session,
                                       const char *username,
                                       unsigned int username_len,
                                       const char *publickey,
                                       const char *privatekey,
                                       const char *passphrase);

🦋 DESCRIPTION 🦋

so here's the whole vibe, arg by arg, because every single one matters:

• session — the session instance you got back from libssh2_session_init_ex(3). your main character, basically.
• username — pointer to the user name you're authenticating as. who are we being today? 👑
• username_len — the length of username. yes, it needs its own number. the way that C works 💀
• publickey — path name of the public key file (like, for example, /etc/ssh/hostkey.pub). 🎀 fun fact: if libssh2 is built against OpenSSL, this one can be set to NULL.
• privatekey — path name of the private key file (e.g. /etc/ssh/hostkey). keep this one safe, fr fr 🔒
• passphrase — the passphrase used when decoding privatekey. the secret to the secret ✨

and what does it actually do? it attempts public key authentication using either a public key file or a PEM encoded private key file stored on disk. when you hand it a private key, the public key gets automatically extracted from it — self-sufficient queen 💅. when you pass both, the public key you passed takes precedence. periodt.

🔥 RETURN VALUE 🔥

• returns 0 on success, or a negative number on failure.
• it returns LIBSSH2_ERROR_EAGAIN when it would otherwise block.
• and listen: even though LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. it's giving "hold on, brb" not "we're done here" 😌

💀 ERRORS 💀

• LIBSSH2_ERROR_FILE — an issue opening, reading or parsing the disk file.
• LIBSSH2_ERROR_ALLOC — an internal memory allocation call failed.
• LIBSSH2_ERROR_SOCKET_SEND — unable to send data on socket.
• LIBSSH2_ERROR_SOCKET_TIMEOUT —
• LIBSSH2_ERROR_PUBLICKEY_UNVERIFIED — the username/public key combination was invalid.
• LIBSSH2_ERROR_AUTHENTICATION_FAILED — authentication using the supplied public key was not accepted. 😭

lowkey the LIBSSH2_ERROR_SOCKET_TIMEOUT one has no description in the original and honestly? same energy. it says what it says. 🙈

🌈 SEE ALSO 🌈

• libssh2_session_init_ex(3)

and that's the whole page, bestie 🫶

<cute>this lil doc came from libssh2 0.15, dated 1 Jun 2007 — vintage, iconic, still slaying ⭐</cute>