mirror of
https://github.com/libssh2/libssh2.git
synced 2025-04-19 02:24:04 +03:00
bc4e619e76
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
138 lines
4.9 KiB
Groff
138 lines
4.9 KiB
Groff
.TH libssh2_session_callback_set 3 "1 Jun 2007" "libssh2 0.15" "libssh2 manual"
|
|
.SH NAME
|
|
libssh2_session_callback_set - set a callback function
|
|
.SH SYNOPSIS
|
|
.nf
|
|
#include <libssh2.h>
|
|
|
|
void *
|
|
libssh2_session_callback_set(LIBSSH2_SESSION *session,
|
|
int cbtype, void *callback);
|
|
.fi
|
|
.SH DESCRIPTION
|
|
Sets a custom callback handler for a previously initialized session
|
|
object. Callbacks are triggered by the receipt of special packets at the
|
|
Transport layer. To disable a callback, set it to NULL.
|
|
|
|
\fIsession\fP - Session instance as returned by
|
|
.BR libssh2_session_init_ex(3)
|
|
|
|
\fIcbtype\fP - Callback type. One of the types listed in Callback Types.
|
|
|
|
\fIcallback\fP - Pointer to custom callback function. The prototype for
|
|
this function must match the associated callback declaration macro.
|
|
.SH CALLBACK TYPES
|
|
.IP LIBSSH2_CALLBACK_IGNORE
|
|
Called when a SSH_MSG_IGNORE message is received
|
|
.IP LIBSSH2_CALLBACK_DEBUG
|
|
Called when a SSH_MSG_DEBUG message is received
|
|
.IP LIBSSH2_CALLBACK_DISCONNECT
|
|
Called when a SSH_MSG_DISCONNECT message is received
|
|
.IP LIBSSH2_CALLBACK_MACERROR
|
|
Called when a mismatched MAC has been detected in the transport layer. If the
|
|
function returns 0, the packet will be accepted nonetheless.
|
|
.IP LIBSSH2_CALLBACK_X11
|
|
Called when an X11 connection has been accepted
|
|
.IP LIBSSH2_CALLBACK_SEND
|
|
Called when libssh2 wants to send data on the connection. Can be set to a
|
|
custom function to handle I/O your own way.
|
|
|
|
The prototype of the callback:
|
|
|
|
.nf
|
|
ssize_t sendcb(libssh2_socket_t sockfd, const void *buffer,
|
|
size_t length, int flags, void **abstract);
|
|
.fi
|
|
|
|
\fBsockfd\fP is the socket to write to, \fBbuffer\fP points to the data to
|
|
send, \fBlength\fP is the size of the data, \fBflags\fP is the flags that
|
|
would've been used to a \fIsend()\fP call and \fBabstract\fP is a pointer to
|
|
the abstract pointer set in the \fIlibssh2_session_init_ex(3)\fP call.
|
|
|
|
The callback returns the number of bytes sent, or -1 for error. The special
|
|
return code \fB-EAGAIN\fP can be returned to signal that the send was aborted
|
|
to prevent getting blocked and it needs to be called again.
|
|
.IP LIBSSH2_CALLBACK_RECV
|
|
Called when libssh2 wants to read data from the connection. Can be set to a
|
|
custom function to handle I/O your own way.
|
|
|
|
The prototype of the callback:
|
|
|
|
.nf
|
|
ssize_t recvcb(libssh2_socket_t sockfd, void *buffer,
|
|
size_t length, int flags, void **abstract);
|
|
.fi
|
|
|
|
\fBsockfd\fP is the socket to read from, \fBbuffer\fP where to store received
|
|
data into, \fBlength\fP is the size of the buffer, \fBflags\fP is the flags
|
|
that would've been used to a \fIrecv()\fP call and \fBabstract\fP is a pointer
|
|
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)
|