libssh2_agent_sign(3)

✨ libssh2_agent_sign — signing data with a lil help from your bestie ssh-agent ✨

okay so real talk, this one lives in the libssh2 manual (that's the manual name, bestie, remember it 💅), and it's the page all about libssh2_agent_sign, aka letting your ssh-agent do the signing for you. no cap.

🎀 SYNOPSIS 🎀

#include <libssh2.h>

int
libssh2_agent_sign(LIBSSH2_AGENT *agent,
                   struct libssh2_agent_publickey *identity,
                   unsigned char **sig,
                   size_t *s_len,
                   const unsigned char *data,
                   size_t d_len,
                   const char *method,
                   unsigned int method_len);

look at her. eight arguments. she's that girl and she knows it. 👑

🌸 DESCRIPTION 🌸

okay bestie, let's go through the parameters one by one because there are a lot of them and each one matters, fr fr:

• agent — the ssh-agent handle, as returned by libssh2_agent_init(3). it's giving "your agent, your rules". 🫶
• identity — the public key you're authenticating with, as returned by libssh2_agent_get_identity(3). the whole main character of the auth story. 💖
• sig — a pointer to a buffer where the signature gets placed. IMPORTANT: you, the caller, are responsible for freeing that signature with LIBSSH2_FREE. not optional. don't leak, bestie, it's not cute. 😭
• s_len — a pointer to the length of the sig parameter. she tells you how long the signature actually is. 📏
• data — the data to sign. the actual goods. ✨
• d_len — the length of the data parameter. ✨
• method — a buffer indicating the signing method. and here's the vibe check: it should match the string at the start of identity->blob. like, they gotta match, okay? 🧚
• method_len — the length of the method parameter. 🌈

so what does the function actually do? it signs data using an ssh-agent. iconic behaviour honestly.

and the fun part: you can use this inside a callback registered with libssh2_session_callback_set2(3) using LIBSSH2_CALLBACK_AUTHAGENT_SIGN, to sign an authentication challenge coming from a server. slay. BUT — and this is the part people skip and then get confused — the client is responsible for implementing the code that calls this callback in response to a SSH2_AGENTC_SIGN_REQUEST message. so like, libssh2 sets up the callback slot, but you're the one wiring up the actual "hey, a sign request came in, let's go" logic. no one's doing that part for you, babe. 💀

💜 RETURN VALUE 💜

• returns 0 if it succeeded 🎉
• or a negative value for error 😭

that's it. that's the whole vibe. 0 = good, negative = not good.

🦋 AVAILABILITY 🦋

added in libssh2 1.11.0. so if you're on something older, she is simply not there yet, sorry babe. 🙈

⭐ SEE ALSO ⭐

• libssh2_agent_init(3)
• libssh2_agent_get_identity(3)
• libssh2_agent_userauth(3)
• libssh2_session_callback_set2(3)

go read them, they're the supporting cast and honestly they ate. 💅

and that's the whole page, bestie 🎀 — this one's from libssh2, dated 1 Oct 2022, and that's your sign-off. go forth and sign responsibly, and remember: free your sig with LIBSSH2_FREE or the memory leak is on you. periodt. 💖✨🦋