From d101fb4329f4313f1b930e9876166df3304e672a Mon Sep 17 00:00:00 2001
From: Aris Adamantiadis <aris@0xbadc0de.be>
Date: Tue, 7 Nov 2006 01:45:13 +0000
Subject: [PATCH] more doxygen documentation

git-svn-id: svn+ssh://svn.berlios.de/svnroot/repos/libssh/trunk@79 7dcaeef0-15fb-0310-b436-a5af3365683c
---
 libssh/client.c   | 22 +++++++++++++++++-
 libssh/connect.c  | 29 +++++++++++++++++++++---
 libssh/dh.c       | 16 ++++++++++++-
 libssh/keyfiles.c | 27 +++++++++++++++++++++-
 libssh/session.c  | 58 +++++++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 146 insertions(+), 6 deletions(-)

diff --git a/libssh/client.c b/libssh/client.c
index bfb52f3d..6bceb709 100644
--- a/libssh/client.c
+++ b/libssh/client.c
@@ -215,6 +215,15 @@ int ssh_service_request(SSH_SESSION *session,char *service){
     return 0;
 }
 
+/** \addtogroup ssh_session
+ *  * @{ */
+
+/** \brief connect to the ssh server
+ * \param session ssh session
+ * \return 0 on success, SSH_ERROR on error
+ * \see ssh_new()
+ * \see ssh_disconnect()
+ */
 int ssh_connect(SSH_SESSION *session){
   int fd;
   int ssh1, ssh2;
@@ -293,12 +302,21 @@ int ssh_connect(SSH_SESSION *session){
   return 0;
 }
 
+/** this is the banner showing a disclaimer to users who log in,
+ * typicaly their right or the fact that they will be monitored
+ * \brief get the issue banner from the server
+ * \param session ssh session
+ * \return NULL if there is no issue banner, else a string containing it.
+ */
 char *ssh_get_issue_banner(SSH_SESSION *session){
     if(!session->banner)
         return NULL;
     return string_to_char(session->banner);
 }
 
+/** \brief disconnect from a session (client or server)
+ * \param session ssh session
+ */
 void ssh_disconnect(SSH_SESSION *session){
     STRING *str;
     if(session->fd!= -1) {
@@ -317,7 +335,9 @@ void ssh_disconnect(SSH_SESSION *session){
 }
 
 const char *ssh_copyright(){
-    return LIBSSH_VERSION " (c) 2003-2005 Aris Adamantiadis (aris@0xbadc0de.be)"
+    return LIBSSH_VERSION " (c) 2003-2006 Aris Adamantiadis (aris@0xbadc0de.be)"
     " Distributed under the LGPL, please refer to COPYING file for informations"
     " about your rights" ;
 }
+/** @} */
+
diff --git a/libssh/connect.c b/libssh/connect.c
index fefda87c..d7962e12 100644
--- a/libssh/connect.c
+++ b/libssh/connect.c
@@ -158,8 +158,16 @@ int ssh_connect_host(SSH_SESSION *session, const char *host, const char
     return s;
 }
 
-/* returns 1 if bytes are available to read on the stream, 0 instead */
-/* -1 on select() error. */
+/** \addtogroup ssh_session
+ *  * @{ */
+
+/** \internal
+ * \brief polls the stream for activity
+ * \param session ssh session
+ * \param write value pointed to set to 1 if it is possible to write
+ * \param except value pointed to set to 1 if there is an exception
+ * \return 1 if it is possible to read, 0 otherwise, -1 on error
+ */
 int ssh_fd_poll(SSH_SESSION *session, int *write, int *except){
     struct timeval sometime;
     fd_set rdes; // read set
@@ -199,7 +207,20 @@ int ssh_fd_poll(SSH_SESSION *session, int *write, int *except){
     return session->data_to_read;
 }
 
-/* this function is a complete wrapper for the select syscall. it does more than wrapping ... */
+
+/** This functions acts more or less like the select(2) syscall.\n
+ * There is no support for writing or exceptions.\n
+ * \brief wrapper for the select syscall
+ * \param channels arrays of channels pointers finished by an NULL. It is never rewritten/
+ * \param outchannels arrays of same size that "channels", it hasn't to be initialized
+ * \param maxfd maximum +1 file descriptor from readfds
+ * \param readfds an fd_set of file descriptors to be select'ed for reading
+ * \param timeout a timeout for the select
+ * \see select(2)
+ * \return -1 if an error occured. E_INTR if it was interrupted. In that case, just restart it.
+ * \warning libssh is not threadsafe. That means that if a signal is caught during the processing
+ * of this function, you cannot call ssh functions on sessions that are busy with ssh_select()
+ */
 int ssh_select(CHANNEL **channels,CHANNEL **outchannels, int maxfd, fd_set *readfds, struct timeval *timeout){
     struct timeval zerotime;
     fd_set localset,localset2;
@@ -283,3 +304,5 @@ int ssh_select(CHANNEL **channels,CHANNEL **outchannels, int maxfd, fd_set *read
     memcpy(readfds,&localset2,sizeof(fd_set));
     return 0;
 }
+
+/** @} */
diff --git a/libssh/dh.c b/libssh/dh.c
index cbf143c0..937ca6a4 100644
--- a/libssh/dh.c
+++ b/libssh/dh.c
@@ -451,6 +451,16 @@ void generate_session_keys(SSH_SESSION *session){
     free(k_string);
 }
 
+/** \addtogroup ssh_session
+ * @{ */
+/** \brief get the md5 hash of the server public key
+ * \param session ssh session
+ * \param hash destination for the md5 hash
+ * \return size of the hash in bytes
+ * \warning it is very important that you verify at some moment that the hash matches
+ * a known server. If you don't do it, cryptography won't help you at making things secure
+ * \see ssh_is_server_known()
+ */
 int ssh_get_pubkey_hash(SSH_SESSION *session,unsigned char hash[MD5_DIGEST_LEN]){
     STRING *pubkey=session->current_crypto->server_pubkey;
     MD5CTX ctx;
@@ -462,6 +472,8 @@ int ssh_get_pubkey_hash(SSH_SESSION *session,unsigned char hash[MD5_DIGEST_LEN])
     return MD5_DIGEST_LEN;
 }
 
+/** \deprecated same as ssh_get_pubkey_hash()
+ */
 int pubkey_get_hash(SSH_SESSION *session, unsigned char hash[MD5_DIGEST_LEN]){
     return ssh_get_pubkey_hash(session,hash);
 }
@@ -560,7 +572,6 @@ static int sig_verify(SSH_SESSION *session, PUBLIC_KEY *pubkey, SIGNATURE *signa
 return -1;
 }
 
-    
 int signature_verify(SSH_SESSION *session,STRING *signature){
     PUBLIC_KEY *pubkey;
     SIGNATURE *sign;
@@ -593,3 +604,6 @@ int signature_verify(SSH_SESSION *session,STRING *signature){
     publickey_free(pubkey);
     return err;
 }
+
+/** @} */
+
diff --git a/libssh/keyfiles.c b/libssh/keyfiles.c
index b65cdfb6..5430b8c0 100644
--- a/libssh/keyfiles.c
+++ b/libssh/keyfiles.c
@@ -815,7 +815,24 @@ static char **ssh_parse_knownhost(char *filename, char *hostname, char *type){
     return ret;
 }
 
-/* public function to test if the server is known or not */
+/** \addtogroup ssh_session
+ * @{ */
+/** checks the user's known host file for a previous connection to the
+ * current server.
+ * \brief test if the server is known
+ * \param session ssh session
+ * \return SSH_SERVER_KNOWN_OK : the server is known and has not changed\n
+ * SSH_SERVER_KNOWN_CHANGED : The server key has changed. Either you are under
+ * attack or the administrator changed the key. you HAVE to warn the user about
+ * a possible attack\n
+ * SSH_SERVER_FOUND_OTHER : the server gave use a key of a type while we
+ * had an other type recorded. It is a possible attack \n
+ * SSH_SERVER_NOT_KNOWN : the server is unknown. User should confirm the MD5 is correct\n
+ * SSH_SERVER_ERROR : Some error happened
+ * \see ssh_options_set_wanted_algo()
+ * \see ssh_get_pubkey_hash()
+ * \bug there is no current way to remove or modify an entry into the known host table
+ */
 int ssh_is_server_known(SSH_SESSION *session){
     char *pubkey_64;
     BUFFER *pubkey_buffer;
@@ -893,6 +910,11 @@ int ssh_is_server_known(SSH_SESSION *session){
     return SSH_SERVER_KNOWN_OK;
 }
 
+/** You generaly uses it when ssh_is_server_known() answered SSH_SERVER_NOT_KNOWN 
+ * \brief write the current server as known in the known hosts file
+ * \param session ssh session
+ * \return 0 on success, -1 on error
+ */
 int ssh_write_knownhost(SSH_SESSION *session){
     unsigned char *pubkey_64;
     STRING *pubkey=session->current_crypto->server_pubkey;
@@ -955,3 +977,6 @@ int ssh_write_knownhost(SSH_SESSION *session){
     fclose(file);
     return 0;
 }
+
+/** @} */
+
diff --git a/libssh/session.c b/libssh/session.c
index aeee63ad..a73599e7 100644
--- a/libssh/session.c
+++ b/libssh/session.c
@@ -28,6 +28,15 @@
 #include "libssh/server.h"
 #define FIRST_CHANNEL 42 // why not ? it helps to find bugs.
 
+/** defgroup ssh_session
+ * \brief functions that manage a session
+ */
+/** \addtogroup ssh_session
+ * @{ */
+
+/** \brief creates a new ssh session
+ * \returns new ssh_session pointer
+ */
 SSH_SESSION *ssh_new() {
     SSH_SESSION *session=malloc(sizeof (SSH_SESSION));
     memset(session,0,sizeof(SSH_SESSION));
@@ -83,36 +92,68 @@ void ssh_cleanup(SSH_SESSION *session){
     free(session);
 }
 
+/** \brief disconnect impolitely from remote host
+ * \param session current ssh session
+ */
 void ssh_silent_disconnect(SSH_SESSION *session){
     close(session->fd);
     session->alive=0;
     ssh_disconnect(session);
 }
 
+/** \brief set the options for the current session
+ * \param session ssh session
+ * \param options options structure
+ * \see ssh_new()
+ * \see ssh_options_new()
+ */
 void ssh_set_options(SSH_SESSION *session, SSH_OPTIONS *options){
     session->options=options;
 }
 
+/** \brief set the session in blocking/nonblocking mode
+ * \param session ssh session
+ * \param blocking zero for nonblocking mode
+ * \bug nonblocking code is in development and won't work as expected
+ */
 void ssh_set_blocking(SSH_SESSION *session,int blocking){
     session->blocking=blocking?1:0;
 }
 
+/** In case you'd need the file descriptor of the connection 
+ * to the server/client 
+ * \brief recover the fd of connection
+ * \param session ssh session
+ * \return file descriptor of the connection, or -1 if it is
+ * not connected
+ */
 int ssh_get_fd(SSH_SESSION *session){
     return session->fd;
 }
 
+/** \brief say to the session it has data to read on the file descriptor without blocking
+ * \param session ssh session
+ */
 void ssh_set_fd_toread(SSH_SESSION *session){
     session->data_to_read=1;
 }
 
+/** \brief say the session it may write to the file descriptor without blocking
+ * \param session ssh session
+ */
 void ssh_set_fd_towrite(SSH_SESSION *session){
     session->data_to_write=1;
 }
 
+/** \brief say the session it has an exception to catch on the file descriptor
+ * \param session ssh session
+ */
 void ssh_set_fd_except(SSH_SESSION *session){
     session->data_except=1;
 }
 
+/** \warning I don't remember if this should be internal or not
+ */
 /* looks if there is data to read on the socket and parse it. */
 int ssh_handle_packets(SSH_SESSION *session){
     int w,err,r;
@@ -128,6 +169,11 @@ int ssh_handle_packets(SSH_SESSION *session){
     return r;
 }
 
+/** \brief get session status
+ * \param session ssh session
+ * \returns a bitmask including SSH_CLOSED, SSH_READ_PENDING or SSH_CLOSED_ERROR
+ * which respectively means the session is closed, has data to read on the connection socket and session was closed due to an error
+ */
 int ssh_get_status(SSH_SESSION *session){
     int ret=0;
     if(session->closed)
@@ -139,6 +185,11 @@ int ssh_get_status(SSH_SESSION *session){
     return ret;
 }
 
+/** \brief get the disconnect message from the server
+ * \param session ssh session
+ * \return message sent by the server along with the disconnect, or NULL in which case the reason of the disconnect may be found with ssh_get_error.
+ * \see ssh_get_error()
+ */
 const char *ssh_get_disconnect_message(SSH_SESSION *session){
     if(!session->closed)
         ssh_set_error(session,SSH_REQUEST_DENIED,"Connection not closed"
@@ -154,6 +205,13 @@ const char *ssh_get_disconnect_message(SSH_SESSION *session){
     return NULL;
 }
 
+/** \brief get the protocol version of the session
+ * \param session ssh session
+ * \return 1 or 2, for ssh1 or ssh2
+ */
 int ssh_get_version(SSH_SESSION *session){
     return session->version;
 }
+
+/** @} */
+