From 703fbd9d112764796325a46015a0682f13097de3 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Thu, 28 May 2009 14:35:13 +0200 Subject: [PATCH] Added the initial man pages for the 7 new functions for known host handling --- docs/Makefile.am | 49 ++++++++++++++----------- docs/libssh2_knownhost_add.3 | 53 +++++++++++++++++++++++++++ docs/libssh2_knownhost_check.3 | 57 ++++++++++++++++++++++++++++++ docs/libssh2_knownhost_del.3 | 26 ++++++++++++++ docs/libssh2_knownhost_dumpfile.3 | 29 +++++++++++++++ docs/libssh2_knownhost_get.3 | 35 ++++++++++++++++++ docs/libssh2_knownhost_init.3 | 22 ++++++++++++ docs/libssh2_knownhost_parsefile.3 | 29 +++++++++++++++ 8 files changed, 279 insertions(+), 21 deletions(-) create mode 100644 docs/libssh2_knownhost_add.3 create mode 100644 docs/libssh2_knownhost_check.3 create mode 100644 docs/libssh2_knownhost_del.3 create mode 100644 docs/libssh2_knownhost_dumpfile.3 create mode 100644 docs/libssh2_knownhost_get.3 create mode 100644 docs/libssh2_knownhost_init.3 create mode 100644 docs/libssh2_knownhost_parsefile.3 diff --git a/docs/Makefile.am b/docs/Makefile.am index 5bf0fff..c18f73f 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -4,6 +4,7 @@ EXTRA_DIST = template.3 dist_man_MANS = \ libssh2_banner_set.3 \ + libssh2_base64_decode.3 \ libssh2_channel_close.3 \ libssh2_channel_direct_tcpip_ex.3 \ libssh2_channel_eof.3 \ @@ -21,23 +22,44 @@ dist_man_MANS = \ libssh2_channel_receive_window_adjust.3 \ libssh2_channel_receive_window_adjust2.3 \ libssh2_channel_request_pty_ex.3 \ + libssh2_channel_request_pty_size_ex.3 \ libssh2_channel_send_eof.3 \ libssh2_channel_set_blocking.3 \ libssh2_channel_setenv_ex.3 \ - libssh2_channel_wait_eof.3 \ libssh2_channel_wait_closed.3 \ + libssh2_channel_wait_eof.3 \ libssh2_channel_window_read_ex.3 \ libssh2_channel_window_write_ex.3 \ libssh2_channel_write_ex.3 \ libssh2_channel_x11_req_ex.3 \ + libssh2_free_host_entry.3 \ + libssh2_host_entry_match.3 \ libssh2_hostkey_hash.3 \ + libssh2_knownhost_add.3 \ + libssh2_knownhost_check.3 \ + libssh2_knownhost_del.3 \ + libssh2_knownhost_dumpfile.3 \ + libssh2_knownhost_get.3 \ + libssh2_knownhost_init.3 \ + libssh2_knownhost_parsefile.3 \ + libssh2_new_host_entry.3 \ + libssh2_poll.3 \ + libssh2_poll_channel_read.3 \ + libssh2_publickey_add_ex.3 \ + libssh2_publickey_init.3 \ + libssh2_publickey_list_fetch.3 \ + libssh2_publickey_list_free.3 \ + libssh2_publickey_remove_ex.3 \ + libssh2_publickey_shutdown.3 \ libssh2_scp_recv.3 \ libssh2_scp_send_ex.3 \ libssh2_session_abstract.3 \ libssh2_session_block_directions.3 \ libssh2_session_callback_set.3 \ - libssh2_session_free.3 \ libssh2_session_disconnect_ex.3 \ + libssh2_session_flag.3 \ + libssh2_session_free.3 \ + libssh2_session_get_blocking.3 \ libssh2_session_init_ex.3 \ libssh2_session_last_errno.3 \ libssh2_session_last_error.3 \ @@ -45,14 +67,12 @@ dist_man_MANS = \ libssh2_session_methods.3 \ libssh2_session_set_blocking.3 \ libssh2_session_startup.3 \ - libssh2_poll.3 \ - libssh2_poll_channel_read.3 \ libssh2_sftp_close_handle.3 \ libssh2_sftp_fstat_ex.3 \ - libssh2_sftp_last_error.3 \ libssh2_sftp_init.3 \ - libssh2_sftp_open_ex.3 \ + libssh2_sftp_last_error.3 \ libssh2_sftp_mkdir_ex.3 \ + libssh2_sftp_open_ex.3 \ libssh2_sftp_read.3 \ libssh2_sftp_readdir_ex.3 \ libssh2_sftp_rename_ex.3 \ @@ -65,24 +85,11 @@ dist_man_MANS = \ libssh2_sftp_tell64.3 \ libssh2_sftp_unlink_ex.3 \ libssh2_sftp_write.3 \ + libssh2_trace.3 \ libssh2_userauth_authenticated.3 \ + libssh2_userauth_hostbased_fromfile_ex.3 \ libssh2_userauth_keyboard_interactive_ex.3 \ libssh2_userauth_list.3 \ libssh2_userauth_password_ex.3 \ libssh2_userauth_publickey_fromfile_ex.3 \ - libssh2_base64_decode.3 \ - libssh2_trace.3 \ libssh2_version.3 - libssh2_channel_request_pty_size_ex.3 \ - libssh2_free_host_entry.3 \ - libssh2_host_entry_match.3 \ - libssh2_new_host_entry.3 \ - libssh2_publickey_add_ex.3 \ - libssh2_publickey_init.3 \ - libssh2_publickey_list_fetch.3 \ - libssh2_publickey_list_free.3 \ - libssh2_publickey_remove_ex.3 \ - libssh2_publickey_shutdown.3 \ - libssh2_session_flag.3 \ - libssh2_session_get_blocking.3 \ - libssh2_userauth_hostbased_fromfile_ex.3 diff --git a/docs/libssh2_knownhost_add.3 b/docs/libssh2_knownhost_add.3 new file mode 100644 index 0000000..a416a3f --- /dev/null +++ b/docs/libssh2_knownhost_add.3 @@ -0,0 +1,53 @@ + +.\" Copyright (c) 2009 by Daniel Stenberg +.\" +.TH libssh2_knownhost_add 3 "28 May 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_knownhost_add - add a known host +.SH SYNOPSIS +#include + +int libssh2_knownhost_add(LIBSSH2_KNOWNHOSTS *hosts, + char *host, char *salt, + char *key, size_t keylen, + int typemask); +.SH DESCRIPTION +Adds a known host to the collection of known hosts identified by the 'hosts' +handle. + +\fIhost\fP is a pointer the host name in plain text or hashed. If hashed, it +must be provided base64 encoded. The host name can be the IP numerical address +of the host or the full name. + +\fIsalt\P is a pointer to the salt used for the host hashing, if the host is +provided hashed. If the host is provided in plain text, salt has no meaning. +The salt has to be provided base64 encoded. + +\fIkey\fP is a pointer to the key for the given host. + +\fIkeylen\fP is the total size in bytes of the key pointed to by the \fIkey\fP +argument + +\fItypemask\fP is a bitmask that specifies format and info about the data +passed to this function. Specificly, it details what format the host name is, +what format the key is and what key type it is. + +The host name is given as one of the following types: +LIBSSH2_KNOWNHOST_TYPE_PLAIN, LIBSSH2_KNOWNHOST_TYPE_SHA1 or +LIBSSH2_KNOWNHOST_TYPE_CUSTOM. + +The key is encoded using one of the following encodings: +LIBSSH2_KNOWNHOST_KEYENC_RAW or LIBSSH2_KNOWNHOST_KEYENC_BASE64. + +The key is using one of these algorithms: +LIBSSH2_KNOWNHOST_KEY_RSA1, LIBSSH2_KNOWNHOST_KEY_SSHRSA or +LIBSSH2_KNOWNHOST_KEY_SSHDSS. +.SH RETURN VALUE +Returns a regular libssh2 error code, where negative values are error codes +and 0 indicates success. +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_knownhost_init(3) +.BR libssh2_knownhost_free(3) +.BR libssh2_knownhost_check(3) diff --git a/docs/libssh2_knownhost_check.3 b/docs/libssh2_knownhost_check.3 new file mode 100644 index 0000000..6a3143d --- /dev/null +++ b/docs/libssh2_knownhost_check.3 @@ -0,0 +1,57 @@ +.\" +.\" Copyright (c) 2009 by Daniel Stenberg +.\" +.TH libssh2_knownhost_check 3 "28 May 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_knownhost_check - check a host+key against the list of known hosts +.SH SYNOPSIS +#include + +int libssh2_knownhost_check(LIBSSH2_KNOWNHOSTS *hosts, + char *host, char *key, size_t keylen, + int typemask, + struct libssh2_knownhost *knownhost); +.SH DESCRIPTION +Checks a host and its associated key against the collection of known hosts, +and returns info back about the (partially) matched entry. + +\fIhost\fP is a pointer the host name in plain text. The host name can be the +IP numerical address of the host or the full name. + +\fIkey\fP is a pointer to the key for the given host. + +\fIkeylen\fP is the total size in bytes of the key pointed to by the \fIkey\fP +argument + +\fItypemask\fP is a bitmask that specifies format and info about the data +passed to this function. Specificly, it details what format the host name is, +what format the key is and what key type it is. + +The host name is given as one of the following types: +LIBSSH2_KNOWNHOST_TYPE_PLAIN or LIBSSH2_KNOWNHOST_TYPE_CUSTOM. + +The key is encoded using one of the following encodings: +LIBSSH2_KNOWNHOST_KEYENC_RAW or LIBSSH2_KNOWNHOST_KEYENC_BASE64. + +\fIknownhost\fP if set to non-NULL, it must be a pointer to a 'struct +libssh2_knownhost' which gets filled in with info about a match or a partial +match. +.SH RETURN VALUE +\fIlibssh2_knownhost_check(3)\fP returns info about how well the provided +host + key pair matched one of the entries in the list of known hosts. + +LIBSSH2_KNOWNHOST_CHECK_FAILURE - something prevented the check to be made + +LIBSSH2_KNOWNHOST_CHECK_NOTFOUND - no host match was found + +LIBSSH2_KNOWNHOST_CHECK_MATCH - hosts and keys match. + +LIBSSH2_KNOWNHOST_CHECK_MISMATCH - host was found, but the keys didn't match! +.SH AVAILABILITY +Added in libssh2 1.2 +.SH EXAMPLE +See the ssh2_exec.c example as provided in the tarball. +.SH SEE ALSO +.BR libssh2_knownhost_init(3) +.BR libssh2_knownhost_free(3) +.BR libssh2_knownhost_add(3) diff --git a/docs/libssh2_knownhost_del.3 b/docs/libssh2_knownhost_del.3 new file mode 100644 index 0000000..75a8eaf --- /dev/null +++ b/docs/libssh2_knownhost_del.3 @@ -0,0 +1,26 @@ +.\" +.\" Copyright (c) 2009 by Daniel Stenberg +.\" +.TH libssh2_knownhost_del 3 "28 May 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_knownhost_del - delete a known host entry +.SH SYNOPSIS +#include + +int libssh2_knownhost_del(LIBSSH2_KNOWNHOSTS *hosts, + struct libssh2_knownhost *entry); +.SH DESCRIPTION +Delete a known host entry from the collection of known hosts. + +\fIentry\fP is a pointer to a struct that you can extract with +\fIlibssh2_knownhost_check(3)\fP or \fIlibssh2_knownhost_get(3)\fP. +.SH RETURN VALUE +Returns a regular libssh2 error code, where negative values are error codes +and 0 indicates success. +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_knownhost_init(3) +.BR libssh2_knownhost_free(3) +.BR libssh2_knownhost_add(3) +.BR libssh2_knownhost_check(3) diff --git a/docs/libssh2_knownhost_dumpfile.3 b/docs/libssh2_knownhost_dumpfile.3 new file mode 100644 index 0000000..8ef1bd6 --- /dev/null +++ b/docs/libssh2_knownhost_dumpfile.3 @@ -0,0 +1,29 @@ +.\" +.\" Copyright (c) 2009 by Daniel Stenberg +.\" +.TH libssh2_knownhost_dumpfile 3 "28 May 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_knownhost_dumpfile - write a collection of known hosts to a file +.SH SYNOPSIS +#include + +int libssh2_knownhost_dumpfile(LIBSSH2_KNOWNHOSTS *hosts, + const char *filename, int type); +.SH DESCRIPTION +Writes all the known hosts to the specified file using the specified file +format. + +\fIfilename\fP specifies what filename to create + +\fItype\fP specifies what file type it is, and +\fILIBSSH2_KNOWNHOST_FILE_OPENSSH\fP is the only currently supported +format. +.SH RETURN VALUE +Returns a regular libssh2 error code, where negative values are error codes +and 0 indicates success. +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_knownhost_parsefile(3) +.BR libssh2_knownhost_add(3) + diff --git a/docs/libssh2_knownhost_get.3 b/docs/libssh2_knownhost_get.3 new file mode 100644 index 0000000..466ee7b --- /dev/null +++ b/docs/libssh2_knownhost_get.3 @@ -0,0 +1,35 @@ +.\" +.\" Copyright (c) 2009 by Daniel Stenberg +.\" +.TH libssh2_knownhost_get 3 "28 May 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_knownhost_get - get a known host off the collection of known hosts +.SH SYNOPSIS +#include + +int libssh2_knownhost_get(LIBSSH2_KNOWNHOSTS *hosts, + struct libssh2_knownhost *store, + struct libssh2_knownhost *prev): +.SH DESCRIPTION +\fIlibssh2_knownhost_get(3)\fP allows an application to iterate over all known +hosts in the collection. + +\fIstore\fP should point to a memory area allocated to fit a struct stored by +this function. + +\fIprev\fP is a pointer to a previous 'struct libssh2_knownhost' 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 hosts. + +Returns negative values for error +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_knownhost_parsefile(3) +.BR libssh2_knownhost_dumpfile(3) +.BR libssh2_knownhost_add(3) diff --git a/docs/libssh2_knownhost_init.3 b/docs/libssh2_knownhost_init.3 new file mode 100644 index 0000000..52518f0 --- /dev/null +++ b/docs/libssh2_knownhost_init.3 @@ -0,0 +1,22 @@ +.\" +.\" Copyright (c) 2009 by Daniel Stenberg +.\" +.TH libssh2_knownhost_init 3 "28 May 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_knownhost_init - init a collection of known hosts +.SH SYNOPSIS +#include + +LIBSSH2_KNOWNHOSTS *libssh2_knownhost_init(LIBSSH2_SESSION *session); +.SH DESCRIPTION +Init a collection of known hosts for this session. Returns the handle to an +internal representation of a known host collection. +.SH RETURN VALUE +Returns a handle pointer or NULL if something went wrong. The returned handle +is used as input to all other known host related functions libssh2 provides. +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_knownhost_free(3) +.BR libssh2_knownhost_add(3) +.BR libssh2_knownhost_check(3) diff --git a/docs/libssh2_knownhost_parsefile.3 b/docs/libssh2_knownhost_parsefile.3 new file mode 100644 index 0000000..96293d9 --- /dev/null +++ b/docs/libssh2_knownhost_parsefile.3 @@ -0,0 +1,29 @@ +.\" +.\" Copyright (c) 2009 by Daniel Stenberg +.\" +.TH libssh2_knownhost_parsefile 3 "28 May 2009" "libssh2 1.2" "libssh2 manual" +.SH NAME +libssh2_knownhost_parsefile - parse a file of known hosts +.SH SYNOPSIS +#include + +int libssh2_knownhost_parsefile(LIBSSH2_KNOWNHOSTS *hosts, + const char *filename, int type); +.SH DESCRIPTION +Reads a collection of known hosts from a specified file and adds them to the +collection of known hosts. + +\fIfilename\fP specifies which file to read + +\fItype\fP specifies what file type it is, and +\fILIBSSH2_KNOWNHOST_FILE_OPENSSH\fP is the only currently supported +format. This file is normally found named ~/.ssh/known_hosts +.SH RETURN VALUE +Returns a regular libssh2 error code, where negative values are error codes +and 0 indicates success. +.SH AVAILABILITY +Added in libssh2 1.2 +.SH SEE ALSO +.BR libssh2_knownhost_init(3) +.BR libssh2_knownhost_free(3) +.BR libssh2_knownhost_check(3)