aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAris Adamantiadis <aris@0xbadc0de.be>2006-11-07 01:45:13 +0000
committerAris Adamantiadis <aris@0xbadc0de.be>2006-11-07 01:45:13 +0000
commitd101fb4329f4313f1b930e9876166df3304e672a (patch)
tree25189df8f32687ace3681e7fdc20f778758649c4
parent24aeed5d1f40291c0c33a34403b212434e8f4e85 (diff)
downloadlibssh-d101fb4329f4313f1b930e9876166df3304e672a.tar.gz
libssh-d101fb4329f4313f1b930e9876166df3304e672a.tar.xz
libssh-d101fb4329f4313f1b930e9876166df3304e672a.zip
more doxygen documentation
git-svn-id: svn+ssh://svn.berlios.de/svnroot/repos/libssh/trunk@79 7dcaeef0-15fb-0310-b436-a5af3365683c
-rw-r--r--libssh/client.c22
-rw-r--r--libssh/connect.c29
-rw-r--r--libssh/dh.c16
-rw-r--r--libssh/keyfiles.c27
-rw-r--r--libssh/session.c58
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;
}
+
+/** @} */
+