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:
@ -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
52
docs/libssh2_agent_sign.3
Normal 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)
|
@ -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)
|
||||
|
@ -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)
|
||||
|
@ -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.
|
||||
|
Reference in New Issue
Block a user