more doxygen documentation

git-svn-id: svn+ssh://svn.berlios.de/svnroot/repos/libssh/trunk@79 7dcaeef0-15fb-0310-b436-a5af3365683c
2006-11-07 01:45:13 +00:00 · 2006-11-07 01:45:13 +00:00 · d101fb4329
--- 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" ;
 }
+/** @} */
+
--- 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;
 }
+
+/** @} */
--- 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;
 }
+
+/** @} */
+
--- 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;
 }
+
+/** @} */
+
--- 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;
 }
+
+/** @} */
+