1
0
mirror of https://github.com/libssh2/libssh2.git synced 2025-07-31 00:03:08 +03:00

Agent forwarding implementation (#752)

This PR contains a series of patches that date back many years and I
believe were discussed on the mailing list, but never merged. We have
been using these in our local copy of libssh2 without issue since 2015,
if not earlier. I believe this is the full set of changes, as we tried
to use comments to mark where our copy of libssh2 differs from the
canonical version.

This also contains changes I made earlier this year, but which were not
discussed on the mailing list, to support certificates and FIDO2 keys
with agent forwarding.

Note that this is not a complete implementation of agent forwarding, as
that is outside the scope of libssh2. Clients still need to provide
their own implementation that parses ssh-agent methods after calling
libssh2_channel_read() and calls the appropriate callback messages in
libssh2. See the man page changes in this PR for more details.

Integration-patches-by: Viktor Szakats

* prefer size_t
* prefer unsigned int over u_int in public function
* add const
* docs, indent, checksrc, debug call, compiler warning fixes
This commit is contained in:
Michael Buckley
2023-04-22 01:54:20 -07:00
committed by GitHub
parent fba0b52b6a
commit bc4e619e76
12 changed files with 551 additions and 26 deletions

View File

@ -10,6 +10,7 @@ dist_man_MANS = \
libssh2_agent_init.3 \
libssh2_agent_list_identities.3 \
libssh2_agent_set_identity_path.3 \
libssh2_agent_sign.3 \
libssh2_agent_userauth.3 \
libssh2_banner_set.3 \
libssh2_base64_decode.3 \

52
docs/libssh2_agent_sign.3 Normal file
View File

@ -0,0 +1,52 @@
.TH libssh2_agent_sign 3 "1 Oct 2022" "libssh2 1.11.0" "libssh2 manual"
.SH NAME
libssh2_agent_sign - sign data, with the help of ssh-agent
.SH SYNOPSIS
.nf
#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);
.fi
.SH DESCRIPTION
\fIagent\fP - ssh-agent handle as returned by
.BR libssh2_agent_init(3)
\fIidentity\fP - Public key to authenticate with, as returned by
.BR libssh2_agent_get_identity(3)
\fIsig\fP - A pointer to a buffer in which to place the signature. The caller
is responsible for freeing the signature with LIBSSH2_FREE.
\fIs_len\fP - A pointer to the length of the sig parameter.
\fIdata\fP - The data to sign.
\fId_len\fP - The length of the data parameter.
\fImethod\fP - A buffer indicating the signing method. This should match the
string at the start of identity->blob.
\fImethod_len\fP - The length of the method parameter.
Sign data using an ssh-agent. This function can be used in a callback
registered with libssh2_session_callback_set(3) using
LIBSSH2_CALLBACK_AUTHAGENT_SIGN to sign an authentication challenge from a
server. However, the client is responsible for implementing the code that calls
this callback in response to a SSH2_AGENTC_SIGN_REQUEST message.
.SH RETURN VALUE
Returns 0 if succeeded, or a negative value for error.
.SH AVAILABILITY
Added in libssh2 1.11.0
.SH SEE ALSO
.BR libssh2_agent_init(3)
.BR libssh2_agent_get_identity(3)
.BR libssh2_agent_userauth(3)
.BR libssh2_session_callback_set(3)

View File

@ -30,3 +30,4 @@ Added in libssh2 1.2
.SH SEE ALSO
.BR libssh2_agent_init(3)
.BR libssh2_agent_get_identity(3)
.BR libssh2_agent_sign(3)

View File

@ -71,8 +71,67 @@ to the abstract pointer set in the \fIlibssh2_session_init_ex(3)\fP call.
The callback returns the number of bytes read, or -1 for error. The special
return code \fB-EAGAIN\fP can be returned to signal that the read was aborted
to prevent getting blocked and it needs to be called again.
.IP LIBSSH2_CALLBACK_AUTHAGENT
Called during authentication process to allow the client to connect to the
ssh-agent and perform any setup, such as configuring the agent or adding keys.
The prototype of the callback:
.nf
void authagent(LIBSSH2_SESSION* session, LIBSSH2_CHANNEL *channel,
void **abstract);
.fi
.IP LIBSSH2_CALLBACK_AUTHAGENT_IDENTITIES
Not called by libssh2. The client is responsible for calling this method when
a SSH2_AGENTC_REQUEST_IDENTITIES message has been received.
The prototype of the callback:
.nf
void identities(LIBSSH2_SESSION* session, void *buffer,
const char *agent_path,
void **abstract)
.fi
\fBbuffer\fP must be filled in by the callback. Different clients may implement
this differently. For example, one client may pass in an unsigned char ** for
this parameter, while another may pass in a pointer to a struct.
Regardless of the type of buffer used, the client will need to send back a list
of identities in the following format.
uint32 buffer length
uint32 number of entries
entries
Where each entry in the entries list is of the format:
string data
cstring comment
\fBagent_path\fP The path to a running ssh-agent on the client machine, from
which identities can be listed.
.IP LIBSSH2_CALLBACK_AUTHAGENT_SIGN
Not called by libssh2. The client is responsible for calling this method when
a SSH2_AGENTC_SIGN_REQUEST message has been received.
The prototype of the callback:
.nf
void sign(LIBSSH2_SESSION* session,
unsigned char *blob, unsigned int blen,
const unsigned char *data, unsigned int dlen,
unsigned char **sig, unsigned int *sig_len,
const char *agent_path,
void **abstract);
.fi
When interfacing with an ssh-agent installed on the client system, this method
can call libssh2_agent_sign(3) to perform signing.
.SH RETURN VALUE
Pointer to previous callback handler. Returns NULL if no prior callback
handler was set or the callback type was unknown.
.SH SEE ALSO
.BR libssh2_session_init_ex(3)
.BR libssh2_agent_sign(3)

View File

@ -9,6 +9,8 @@ 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,
@ -43,6 +45,13 @@ int name(LIBSSH2_SESSION *session, LIBSSH2_SK_SIG_INFO *sig_info,
\fIusername_len\fP - Length of username parameter.
\fIpublickeydata\fP - Buffer containing the contents of a public key file. If
NULL, the public key will be extracted from the privatekeydata. When using
certificate authentication, this buffer should contain the public certificate
data.
\fIpublickeydata_len\fP - Length of public key data.
\fIprivatekeydata\fP - Buffer containing the contents of a private key file.
\fIprivatekeydata_len\fP - Length of private key data.