From: Andre <maan@meins.(none)>
Date: Sun, 28 Jan 2007 22:26:10 +0000 (+0100)
Subject: command.c: add documentation of handle_connect()
X-Git-Tag: v0.2.15~64
X-Git-Url: http://git.tuebingen.mpg.de/?p=paraslash.git;a=commitdiff_plain;h=caadfae04a53e7ed8eb96a7e0bb9dd0ac574851d

command.c: add documentation of handle_connect()
---

diff --git a/command.c b/command.c
index 7bde617e..bf3371f0 100644
--- a/command.c
+++ b/command.c
@@ -757,6 +757,37 @@ static void rc4_send(unsigned long len, const unsigned char *indata,
 	RC4(&rc4_send_key, len, indata, outdata);
 }
 
+/**
+ * perform user authentication and execute a command
+ *
+ * \param fd the file descriptor to send output to
+ * \param addr socket address info of peer
+ *
+ * \return EXIT_SUCCESS or EXIT_FAILURE
+ *
+ * Whenever para_server accepts an incoming tcp connection on
+ * the port it listens on, it forks and the resulting child
+ * calls this function.
+ *
+ * An RSA-based challenge/response is used to authenticate
+ * the peer. It that authentication succeeds, a random RC4
+ * session key is generated and sent back to the peer,
+ * encrypted with its RSA public key.  From this point on,
+ * all transfers are crypted with this session key.
+ *
+ * Next it is checked if the peer supplied  a valid server
+ * command or a command for the audio file selector currently
+ * in use.  If yes, and if the user has sufficient
+ * permissions to execute that command, the function calls
+ * the corresponding command handler which does argument
+ * checking and further processing.
+ *
+ * In order to cope with a DOS attacks, a timeout is set up
+ * which terminates the function if the connection was not
+ * authenticated when the timeout expires.
+ *
+ * \sa alarm(2), rc4(3), crypt.c, crypt.h
+ */
 int handle_connect(int fd, struct sockaddr_in *addr)
 {
 	int numbytes, ret, argc, use_rc4 = 0;