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

docs/libssh2_session_callback_set.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)