libssh2_userauth_publickey_sk(3)

💖 libssh2_userauth_publickey_sk 💖

okay bestie, so this is a page from the libssh2 manual — like, the libssh2_userauth_publickey_sk one — and it's all about logging in with your little FIDO2 key fob thing. security key girlies rise 🫶

---

✨ NAME ✨

libssh2_userauth_publickey_sk — authenticate a session with a FIDO2 authenticator

---

✨ SYNOPSIS ✨

#include <libssh2.h>

int
libssh2_userauth_publickey_sk(LIBSSH2_SESSION *session,
                              const char *username,
                              size_t username_len,
                              const unsigned char *publickeydata,
                              size_t publickeydata_len,
                              const char *privatekeydata,
                              size_t privatekeydata_len,
                              const char *passphrase,
                              LIBSSH2_USERAUTH_SK_SIGN_FUNC((*sign_callback)),
                              void **abstract);

---

🎀 CALLBACK 🎀

here's the little callback contract, she's giving very much "define your own function" energy 💅

#define LIBSSH2_SK_PRESENCE_REQUIRED     0x01
#define LIBSSH2_SK_VERIFICATION_REQUIRED 0x04

typedef struct _LIBSSH2_SK_SIG_INFO {
    uint8_t flags;
    uint32_t counter;
    unsigned char *sig_r;
    size_t sig_r_len;
    unsigned char *sig_s;
    size_t sig_s_len;
} LIBSSH2_SK_SIG_INFO;

int name(LIBSSH2_SESSION *session, LIBSSH2_SK_SIG_INFO *sig_info,
         const unsigned char *data, size_t data_len, int algorithm,
         uint8_t flags, const char *application,
         const unsigned char *key_handle, size_t handle_len,
         void **abstract);

---

🌸 DESCRIPTION 🌸

okay so here's the rundown of every single parameter, no skipping, we're thorough in this house ✨

• session — the Session instance you got back from libssh2_session_init_ex(3).
• username — the name of the user you're trying to authenticate as.
• username_len — length of the username parameter.
• publickeydata — buffer holding the contents of a public key file. If it's NULL, the public key gets extracted from privatekeydata instead. And when you're doing certificate authentication, this buffer should hold the public certificate data.
• publickeydata_len — length of the public key data.
• privatekeydata — buffer holding the contents of a private key file.
• privatekeydata_len — length of the private key data.
• passphrase — the passphrase used when decoding the private key file.
• sign_callback — the callback that talks to your FIDO2 authenticator.
• abstract — user-provided data that gets passed along to the callback.

So what does it do? It attempts FIDO2 authentication, using either the sk-ssh-ed25519@openssh.com or sk-ecdsa-sha2-nistp256@openssh.com key exchange algorithms. iconic behaviour honestly.

🚨 heads up bestie: this function is only supported when libssh2 is backed by OpenSSL. no OpenSSL, no vibes.

---

💅 CALLBACK DESCRIPTION 💅

now the callback's own little parameter list, because she has lore:

• session — the Session instance as returned by libssh2_session_init_ex(3).
• sig_info — filled in by the callback with the signature and the accompanying information from the authenticator.
• data — the data to sign.
• data_len — the length of the data parameter.
• algorithm — the signing algorithm to use. possible values are LIBSSH2_HOSTKEY_TYPE_ED25519 and LIBSSH2_HOSTKEY_TYPE_ECDSA_256.
• flags — a bitmask specifying options for the authenticator. When LIBSSH2_SK_PRESENCE_REQUIRED is set, the authenticator requires a touch. When LIBSSH2_SK_VERIFICATION_REQUIRED is set, the authenticator requires a PIN. And fr fr: many servers and authenticators do not work properly when LIBSSH2_SK_PRESENCE_REQUIRED is not set. so like, set it. 😭
• application — a user-defined string used as the RP name for the authenticator. usually "ssh:".
• key_handle — the key handle to use for the authenticator's allow list.
• handle_len — the length of the key_handle parameter.
• abstract — user-defined data. when a PIN is required, use this to pass in the PIN, or a function pointer to retrieve the PIN.

The sign_callback is the one responsible for communicating with the hardware authenticator to generate a signature. On success, the signature information must be placed in the sig_info parameter and the callback must return 0. On failure, it should return a negative number. no pressure though 💀

---

🦋 the fields of LIBSSH2_SK_SIG_INFO 🦋

she's got layers, let's go field by field:

• flags — a bitmask specifying options for the authenticator. This should be read from the authenticator and not merely copied from the flags parameter to the callback. (yes that's a real instruction, don't be lazy 🙈)
• counter — a value returned from the authenticator.
• sig_r — for Ed25519 signatures, this contains the entire signature, as returned directly from the authenticator. For ECDSA signatures, this contains the r component of the signature in a big-endian binary representation. For both algorithms, use LIBSSH2_ALLOC to allocate the memory. It will be freed by the caller.
• sig_r_len — the length of the sig_r parameter.
• sig_s — for ECDSA signatures, this contains the s component of the signature in a big-endian binary representation. Use LIBSSH2_ALLOC to allocate the memory. It will be freed by the caller. For Ed25519 signatures, set this to NULL.
• sig_s_len — the length of the sig_s parameter.

---

⭐ RETURN VALUE ⭐

Return 0 on success or negative on failure. It returns LIBSSH2_ERROR_EAGAIN when it would otherwise block. And listen — while LIBSSH2_ERROR_EAGAIN is a negative number, it is not really a failure per se. she's just saying "not right now bestie", it's a whole different vibe. 🫶

---

😭 ERRORS 😭

some of the errors this function may return include:

• LIBSSH2_ERROR_ALLOC — an internal memory allocation call failed.
• LIBSSH2_ERROR_SOCKET_SEND — unable to send data on socket.
• LIBSSH2_ERROR_AUTHENTICATION_FAILED — failed, invalid username/key.

---

🌈 AVAILABILITY 🌈

Added in libssh2 1.10.0.

---

👑 SEE ALSO 👑

• libssh2_session_init_ex(3)

---

and that's the whole page, periodt 💜 this was libssh2, version 1.10.0, dated 1 Jun 2022 — go forth and authenticate with your little key fob, you absolute main character 🌸✨🎀