From ff5fa94e327b46a9c5202ac4ead1d749f71ac054 Mon Sep 17 00:00:00 2001 From: Ben Kibbey Date: Sat, 4 Apr 2009 22:17:34 -0400 Subject: [PATCH] Documented SSH in the header. Also fixed formatting which broke in commit c9c5c52. --- doc/doxygen.conf.in.in | 2 +- doc/libpwmd.3 | 54 ++++++++++++++++++++++++-------------------------- src/libpwmd.h.in | 44 ++++++++++++++++++++++++++++++---------- 3 files changed, 60 insertions(+), 40 deletions(-) diff --git a/doc/doxygen.conf.in.in b/doc/doxygen.conf.in.in index 3e156653..79ae1abc 100644 --- a/doc/doxygen.conf.in.in +++ b/doc/doxygen.conf.in.in @@ -186,7 +186,7 @@ TAB_SIZE = 8 # will result in a user-defined paragraph with heading "Side Effects:". # You can put \n's in the value part of an alias to insert newlines. -ALIASES = "conn_req=\note A connection must be established before setting this option." "pre_conn_req=\note This option must be set before a connection is made when not the default." "sigalrm=\note This function will catch SIGALRM during the lifetime of the pinentry process and set it to SIG_DFL when finished. This is needed for pinentry timeouts." +ALIASES = "pre_conn_req=\note This option must be set before a connection is made when not the default." "sigalrm=\note This function will catch SIGALRM during the lifetime of the pinentry process and set it to SIG_DFL when finished. This is needed for pinentry timeouts." # Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C # sources only. Doxygen will then generate output that is more tailored for C. diff --git a/doc/libpwmd.3 b/doc/libpwmd.3 index 22b7214a..bc4563bf 100644 --- a/doc/libpwmd.3 +++ b/doc/libpwmd.3 @@ -178,8 +178,21 @@ libpwmd.h \- libpwmd is a library making it easy for applications to use the pwmd server. .SH "SSH Details" .PP +A remote connection to a pwmd server is possible by using an SSH channel which spawns a shell and executes a proxy server that connects to the pwmd local unix domain socket. Authenication is done by using SSH public key (see \fBssh-keygen(1)\fP) authentication and verifying the host key against a local file containing SHA1 hashes of known hosts. It's alot like how the standard OpenSSH does things only the known_hosts file is in a different format. +.PP +The server hash can be had by using \fBpwmd_get_hostkey()\fP and storing the result in a file. This file is then used as the \fIknown_hosts\fP argument to the SSH connection functions. +.PP +Here's an example \fBauthorized_keys(5)\fP entry. The hash portion should be the same as the contents of the \fIidentity.pub\fP file which is passed as a parameter to the SSH connection functions: +.PP +.PP +.nf + command='socat gopen:$HOME/.pwmd/socket -' ... +.fi +.PP +.PP \fBTodo\fP .RS 4 +X11 port forwarding so a remote pinentry can use the local display. .RE .PP .SH "Pinentry Details" @@ -192,27 +205,22 @@ If using a local pinentry by calling \fBpwmd_open2()\fP, \fBpwmd_save2()\fP, \fB .PP Some pinentry options can also be specified in a local configuration file \fI'~/.pwmd/pinentry.conf'\fP. These options are initial values for each invokation and may be changed by setting the appropriate \fBpwmd_option_t\fP. Each option and value is separated with a '=' on a single line. Unrecognized options are ignored. Here are the recognized options: .PP -.PD 0 -.IP "\(bu" 2 -\fBPATH\fP The full path to the location of the pinentry binary. -.IP "\(bu" 2 -\fBDISPLAY\fP The X11 display to use. -.IP "\(bu" 2 -\fBTTYNAME\fP The full path to the tty that pinentry should prompt on. -.IP "\(bu" 2 -\fBTTYTYPE\fP The terminal type of the tty which is required if DISPLAY is not set. -.PP -\fB\fP.RS 4 - +\fBParameters:\fP +.RS 4 +\fIPATH\fP The full path to the location of the pinentry binary. +.br +\fIDISPLAY\fP The X11 display to use. +.br +\fITTYNAME\fP The full path to the tty that pinentry should prompt on. +.br +\fITTYTYPE\fP The terminal type of the tty which is required if DISPLAY is not set. .RE .PP -\fBTodo\fP +\fBSee also:\fP .RS 4 -X11 forwarding. +\fBSSH Details\fP .RE .PP - -.PP .SH "Example Client" .PP The following example will list the element tree of the data file specified in the first command line argument. @@ -1110,7 +1118,7 @@ Connects to a pwmd server over an SSH channel. .br \fIport\fP The port or -1 for the default. .br -\fIidentity\fP The SSH identity to use for authentication. +\fIidentity\fP The SSH identity file to use for authentication. This should specify the private key. The public key is assumed to be \fIidentity.pub\fP. .br \fIuser\fP The username on the SSH server to login as. If NULL then invoking user will be used. .br @@ -1127,11 +1135,6 @@ Connects to a pwmd server over an SSH channel. \fBpwmd_ssh_connect_async()\fP, \fBpwmd_process()\fP, \fBSSH Details\fP .RE .PP -\fBTodo\fP -.RS 4 -X11 forwarding. -.RE -.PP .SS "gpg_error_t pwmd_ssh_connect_async (\fBpwm_t\fP * pwm, const char * host, int port, const char * identity, const char * user, const char * known_hosts)" .PP @@ -1149,7 +1152,7 @@ This is a variant of \fBpwmd_ssh_connect()\fP that will not block while doing DN .br \fIport\fP The port or -1 for the default. .br -\fIidentity\fP The SSH identity to use for authentication. +\fIidentity\fP The SSH identity file to use for authentication. This should specify the private key. The public key is assumed to be \fIidentity.pub\fP. .br \fIuser\fP The username on the SSH server to login as. If NULL, the invoking username will be used. .br @@ -1166,11 +1169,6 @@ This is a variant of \fBpwmd_ssh_connect()\fP that will not block while doing DN \fBpwmd_process()\fP, \fBSSH Details\fP .RE .PP -\fBTodo\fP -.RS 4 -X11 forwarding. -.RE -.PP .SS "char* pwmd_strdup (const char * str)" .PP diff --git a/src/libpwmd.h.in b/src/libpwmd.h.in index 2ebb2f24..8153210c 100644 --- a/src/libpwmd.h.in +++ b/src/libpwmd.h.in @@ -24,7 +24,27 @@ /*! \section ssh SSH Details * - * \todo + * A remote connection to a pwmd server is possible by using an SSH channel + * which spawns a shell and executes a proxy server that connects to the pwmd + * local unix domain socket. Authenication is done by using SSH public key + * (see \ref ssh-keygen(1)) authentication and verifying the host key against + * a local file containing SHA1 hashes of known hosts. It's alot like how the + * standard OpenSSH does things only the known_hosts file is in a different + * format. + * + * The server hash can be had by using \ref pwmd_get_hostkey() and storing the + * result in a file. This file is then used as the \a known_hosts argument to + * the SSH connection functions. + * + * Here's an example \ref authorized_keys(5) entry. The hash portion should be + * the same as the contents of the \a identity.pub file which is passed as a + * parameter to the SSH connection functions: + * + * \code + * command="socat gopen:$HOME/.pwmd/socket -" ... + * \endcode + * + * \todo X11 port forwarding so a remote pinentry can use the local display. */ /*! \section pinentry Pinentry Details @@ -51,13 +71,13 @@ * pwmd_option_t. Each option and value is separated with a '=' on a single * line. Unrecognized options are ignored. Here are the recognized options: * - * \arg \b PATH The full path to the location of the pinentry binary. - * \arg \b DISPLAY The X11 display to use. - * \arg \b TTYNAME The full path to the tty that pinentry should prompt on. - * \arg \b TTYTYPE The terminal type of the tty which is required if DISPLAY is + * \param PATH The full path to the location of the pinentry binary. + * \param DISPLAY The X11 display to use. + * \param TTYNAME The full path to the tty that pinentry should prompt on. + * \param TTYTYPE The terminal type of the tty which is required if DISPLAY is * not set. - * \par - * \todo X11 forwarding. + * + * \see \ref ssh */ /*! \section example Example Client @@ -390,14 +410,15 @@ gpg_error_t pwmd_connect(pwm_t *pwm, const char *path) * \param pwm A handle. * \param host The hostname to connect to. * \param port The port or -1 for the default. - * \param identity The SSH identity to use for authentication. + * \param identity The SSH identity file to use for authentication. This + * should specify the private key. The public key is assumed to be \a + * identity.pub. * \param user The username on the SSH server to login as. If NULL then * invoking user will be used. * \param known_hosts A file containing the public SSH server key hash in SHA1 * format. * \return 0 on success or an error code. * \see pwmd_ssh_connect_async(), pwmd_process(), \ref ssh - * \todo X11 forwarding. */ gpg_error_t pwmd_ssh_connect(pwm_t *pwm, const char *host, int port, const char *identity, const char *user, const char *known_hosts) @@ -414,14 +435,15 @@ gpg_error_t pwmd_ssh_connect(pwm_t *pwm, const char *host, int port, * \param pwm A handle. * \param host The hostname to connect to. * \param port The port or -1 for the default. - * \param identity The SSH identity to use for authentication. + * \param identity The SSH identity file to use for authentication. This + * should specify the private key. The public key is assumed to be \a + * identity.pub. * \param user The username on the SSH server to login as. If NULL, the * invoking username will be used. * \param known_hosts A file containing the public SSH server key hash in SHA1 * format. * \return 0 on success or an error code. * \see pwmd_process(), \ref ssh - * \todo X11 forwarding. */ gpg_error_t pwmd_ssh_connect_async(pwm_t *pwm, const char *host, int port, const char *identity, const char *user, const char *known_hosts) -- 2.11.4.GIT