From 3138b5891f0c04729f1cb9b36965b48f178679b8 Mon Sep 17 00:00:00 2001 From: Daiki Ueno Date: Wed, 23 Dec 2009 09:12:02 +0900 Subject: [PATCH] Add man pages for ssh-agent API. --- docs/Makefile.am | 7 ++++++ docs/libssh2_agent_connect.3 | 23 +++++++++++++++++++ docs/libssh2_agent_disconnect.3 | 20 ++++++++++++++++ docs/libssh2_agent_free.3 | 20 ++++++++++++++++ docs/libssh2_agent_get_identity.3 | 34 ++++++++++++++++++++++++++++ docs/libssh2_agent_init.3 | 26 +++++++++++++++++++++ docs/libssh2_agent_list_identities.3 | 24 ++++++++++++++++++++ docs/libssh2_agent_userauth.3 | 29 ++++++++++++++++++++++++ 8 files changed, 183 insertions(+) create mode 100644 docs/libssh2_agent_connect.3 create mode 100644 docs/libssh2_agent_disconnect.3 create mode 100644 docs/libssh2_agent_free.3 create mode 100644 docs/libssh2_agent_get_identity.3 create mode 100644 docs/libssh2_agent_init.3 create mode 100644 docs/libssh2_agent_list_identities.3 create mode 100644 docs/libssh2_agent_userauth.3 diff --git a/docs/Makefile.am b/docs/Makefile.am index bbeee02..7b0db51 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -3,6 +3,13 @@ EXTRA_DIST = template.3 dist_man_MANS = \ + libssh2_agent_connect.3 \ + libssh2_agent_disconnect.3 \ + libssh2_agent_free.3 \ + libssh2_agent_get_identity.3 \ + libssh2_agent_init.3 \ + libssh2_agent_list_identities.3 \ + libssh2_agent_userauth.3 \ libssh2_banner_set.3 \ libssh2_base64_decode.3 \ libssh2_channel_close.3 \ diff --git a/docs/libssh2_agent_connect.3 b/docs/libssh2_agent_connect.3 new file mode 100644 index 0000000..1c6ff6d --- /dev/null +++ b/docs/libssh2_agent_connect.3 @@ -0,0 +1,23 @@ +.\" +.\" Copyright (c) 2009 by Daiki Ueno +.\" +.TH libssh2_agent_connect 3 "23 Dec 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_agent_connect - connect to an ssh-agent +.SH SYNOPSIS +#include + +int libssh2_agent_connect(LIBSSH2_AGENT *agent); +.SH DESCRIPTION +Connect to an ssh-agent running on the system. + +Call \fBlibssh2_agent_disconnect(3)\fP to close the connection after +you're doing using it. +.SH RETURN VALUE +Returns 0 if succeeded, or a negative value for error. +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_agent_init(3) +.BR libssh2_agent_disconnect(3) + diff --git a/docs/libssh2_agent_disconnect.3 b/docs/libssh2_agent_disconnect.3 new file mode 100644 index 0000000..f9f9ef0 --- /dev/null +++ b/docs/libssh2_agent_disconnect.3 @@ -0,0 +1,20 @@ +.\" +.\" Copyright (c) 2009 by Daiki Ueno +.\" +.TH libssh2_agent_disconnect 3 "23 Dec 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_agent_disconnect - close a connection to an ssh-agent +.SH SYNOPSIS +#include + +int libssh2_agent_disconnect(LIBSSH2_AGENT *agent); +.SH DESCRIPTION +Close a connection to an ssh-agent. + +.SH RETURN VALUE +Returns 0 if succeeded, or a negative value for error. +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_agent_connect(3) +.BR libssh2_agent_free(3) diff --git a/docs/libssh2_agent_free.3 b/docs/libssh2_agent_free.3 new file mode 100644 index 0000000..197f87e --- /dev/null +++ b/docs/libssh2_agent_free.3 @@ -0,0 +1,20 @@ +.\" +.\" Copyright (c) 2009 by Daiki Ueno +.\" +.TH libssh2_agent_free 3 "28 May 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_agent_free - free an ssh-agent handle +.SH SYNOPSIS +#include + +void libssh2_agent_free(LIBSSH2_AGENT *agent); +.SH DESCRIPTION +Free an ssh-agent handle. This function also frees the internal +collection of public keys. +.SH RETURN VALUE +None. +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_agent_init(3) +.BR libssh2_agent_disconnect(3) diff --git a/docs/libssh2_agent_get_identity.3 b/docs/libssh2_agent_get_identity.3 new file mode 100644 index 0000000..a944165 --- /dev/null +++ b/docs/libssh2_agent_get_identity.3 @@ -0,0 +1,34 @@ +.\" +.\" Copyright (c) 2009 by Daiki Ueno +.\" +.TH libssh2_agent_get_identity 3 "23 Dec 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_agent_get_identity - get a public key off the collection of public keys managed by ssh-agent +.SH SYNOPSIS +#include + +int libssh2_agent_get_identity(LIBSSH2_AGENT *agent, + struct libssh2_agent_publickey **store, + struct libssh2_agent_publickey *prev); +.SH DESCRIPTION +\fIlibssh2_agent_get_identity(3)\fP allows an application to iterate +over all public keys in the collection managed by ssh-agent. + +\fIstore\fP should point to a pointer that gets filled in to point to the +public key data. + +\fIprev\fP is a pointer to a previous 'struct libssh2_agent_publickey' +as returned by a previous invoke of this function, or NULL to get the +first entry in the internal collection. +.SH RETURN VALUE +Returns 0 if everything is fine and information about a host was stored in +the \fIstore\fP struct. + +Returns 1 if it reached the end of public keys. + +Returns negative values for error +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_agent_list_identities(3) +.BR libssh2_agent_userauth(3) diff --git a/docs/libssh2_agent_init.3 b/docs/libssh2_agent_init.3 new file mode 100644 index 0000000..26e891e --- /dev/null +++ b/docs/libssh2_agent_init.3 @@ -0,0 +1,26 @@ +.\" +.\" Copyright (c) 2009 by Daiki Ueno +.\" +.TH libssh2_agent_init 3 "23 Dec 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_agent_init - init an ssh-agent handle +.SH SYNOPSIS +#include + +LIBSSH2_AGENT *libssh2_agent_init(LIBSSH2_SESSION *session); +.SH DESCRIPTION +Init an ssh-agent handle. Returns the handle to an internal +representation of an ssh-agent connection. After the successful +initialization, an application can call \fBlibssh2_agent_connect(3)\fP +to connect to a running ssh-agent. + +Call \fBlibssh2_agent_free(3)\fP to free the handle again after you're +doing using it. +.SH RETURN VALUE +Returns a handle pointer or NULL if something went wrong. The returned handle +is used as input to all other ssh-agent related functions libssh2 provides. +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_agent_connect(3) +.BR libssh2_agent_free(3) diff --git a/docs/libssh2_agent_list_identities.3 b/docs/libssh2_agent_list_identities.3 new file mode 100644 index 0000000..e1e4b54 --- /dev/null +++ b/docs/libssh2_agent_list_identities.3 @@ -0,0 +1,24 @@ +.\" +.\" Copyright (c) 2009 by Daiki Ueno +.\" +.TH libssh2_agent_list_identities 3 "23 Dec 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_agent_list_identities - request an ssh-agent to list of public keys. +.SH SYNOPSIS +#include + +int libssh2_agent_list_identities(LIBSSH2_AGENT *agent); +.SH DESCRIPTION +Request an ssh-agent to list of public keys, and stores them in the +internal collection of the handle. Call +\fIlibssh2_agent_get_identity(3)\fP to get a public key off the +collection. + +.SH RETURN VALUE +Returns 0 if succeeded, or a negative value for error. +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_agent_connect(3) +.BR libssh2_agent_get_identity(3) + diff --git a/docs/libssh2_agent_userauth.3 b/docs/libssh2_agent_userauth.3 new file mode 100644 index 0000000..3c956fe --- /dev/null +++ b/docs/libssh2_agent_userauth.3 @@ -0,0 +1,29 @@ +.\" +.\" Copyright (c) 2009 by Daiki Ueno +.\" +.TH libssh2_agent_userauth 3 "23 Dec 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_agent_userauth - authenticate a session with a public key, with the help of ssh-agent +.SH SYNOPSIS +#include + +int libssh2_agent_userauth(LIBSSH2_AGENT *agent, + const char *username, + struct libssh2_agent_publickey *identity); +.SH DESCRIPTION +\fIagent\fP - ssh-agent handle as returned by +.BR libssh2_agent_init(3) + +\fIusername\fP - Remote user name to authenticate as. + +\fIidentity\fP - Public key to authenticate with, as returned by +.BR libssh2_agent_get_identity(3) + +Attempt public key authentication with the help of ssh-agent. +.SH RETURN VALUE +Returns 0 if succeeded, or a negative value for error. +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_agent_init(3) +.BR libssh2_agent_get_identity(3)