documentation updates

4 files changed, 412 insertions, 14 deletions

diff --git a/doc/tex/Makefile.am b/doc/tex/Makefile.am
index f87107fb5d..bf1248bffb 100644
--- a/doc/tex/Makefile.am
+++ b/doc/tex/Makefile.am
@@ -1,5 +1,5 @@
 EXTRA_DIST = TODO gnutls-api.tex gnutls.tex gnutls.ps gnutls.html ASN1.readme.txt \
-	ex1.tex ex2.tex ex3.tex
+	ex1.tex ex2.tex ex3.tex srp1.tex serv1.tex
 
 gnutls-api: gnutls.html gnutls.ps
 gnutls-api.tex: 
@@ -8,8 +8,7 @@ gnutls-api.tex:
 	@../scripts/gdoc -tex ../../lib/*.c >> gnutls-api.tex
 
 gnutls.ps: gnutls.tex gnutls-api.tex
-	-latex gnutls.tex
-	-dvips gnutls.dvi -o gnutls.ps
+	-latex gnutls.tex && latex gnutls.tex && dvips gnutls.dvi -o gnutls.ps
 
 gnutls.html: gnutls.tex gnutls-api.tex
 	-latex2html gnutls.tex -no_subdir 1 -split 0
diff --git a/doc/tex/gnutls.tex b/doc/tex/gnutls.tex
index d11989e132..1f348ec38e 100644
--- a/doc/tex/gnutls.tex
+++ b/doc/tex/gnutls.tex
@@ -1,21 +1,26 @@
 \documentclass{article}
+\usepackage{html}
 \begin{document}
 
-\oddsidemargin=0pt
-\marginparsep = 0pt
-\marginparwidth=0pt
-\textwidth=6cm
 
-\title{Transport Layer Security}
+\title{GNU Transport Layer Security Library}
 \author{Nikos Mavroyanopoulos}
 \maketitle
 
+\tableofcontents
+
 \section{Introduction}
 \par
 gnuTLS is a library which implements the {\bf TLS 1.0} and {\bf SSL 3.0} protocols.
 TLS stands for 'Transport Layer Security' and is the sucessor of SSL (Secure Sockets Layer).
 {\bf TLS 1.0} is described is {\it RFC 2246} and is an Internet protocol (thus it's mostly used over TCP/IP),
-that provides confidentiality, and authentication layers. 
+that provides confidentiality, and authentication layers. Currently {\bf gnuTLS} implements:
+\begin{itemize}
+ \item the {\bf TLS 1.0} and {\bf{ SSL 3.0}} protocols, without any (US) export-controlled algorithms
+ \item {\bf X509} Public Key Infrastructure (with several limitations).
+ \item {\bf SRP} for TLS authentication.
+ \item {\bf TLS Extensions}
+\end{itemize}
 
 \subsection{Confidentiality}
 \par
@@ -34,23 +39,24 @@ The following authentication schemas are supported in gnuTLS:
 
 
 
-\section{X509 Client Examples}
+\section{Client Examples}
+This section contains examples of TLS and SSL clients, using gnuTLS. 
 
+\subsection{Simple Client example with X509 Authentication}
 Let's assume now that we want to create a client which communicates
 with servers using the X509 authentication schema. The following client
 is a very simple TLS client, it does not support session resuming nor
 any other fancy features.
-
-\subsection{Simple Client example}
 \input{ex2}
 
 \subsection{Getting peer's information}
 \par The above example was the simplest form of a client, it didn't even check
 the result of the peer's certificate verification function (ie. if we have
-an authenticated connection. The following function does check the peer's X509
+an authenticated connection). The following function does check the peer's X509
 Certificate, and prints some information about the current state.
 \par
 This function should be called after a successful gnutls\_handshake().
+% \hyperref{gnutls\_handshake()}{gnutls\_handshake() (see Section }{ for more information)}{gnutls\_handshake}
 
 \input{ex3}
 
@@ -62,7 +68,7 @@ the same server a client may use session resuming. {\bf Session resuming} is a
 feature of the {\bf TLS} protocol which allows a client to connect to a server,
 after a successful handshake, without the expensive calculations (ie. use the previously
 established keys). {\bf gnuTLS} supports this feature, and this example illustrates a
-typical use of it. (This is a modification of the simple client example)
+typical use of it (This is a modification of the simple client example).
 
 \par
 Keep in mind that sessions are expired after some time (for security reasons), thus
@@ -70,6 +76,22 @@ it may be normal for a server not to resume a session even if you requested that
 
 \input{ex1}
 
+\subsection{Simple Client example with SRP Authentication}
+Although {\bf SRP} is not part of the TLS standard, gnuTLS implements
+{\it draft-ietf-tls-srp-01} which defines a way to use the SRP algorithm
+within the TLS handshake. The following client
+is a very simple SRP-TLS client which connects to a server by using 
+{\it username} and {\it password}.
+
+\input{srp1}
+
+\section{Server Examples}
+This section contains examples of TLS and SSL servers, using gnuTLS.
+
+\subsection{Echo Server with X509 and SRP authentication}
+The following example is a server which supports both {\bf SRP} and {\bf X509} authentication.
+This server also supports {\it session resuming}.
+\input{serv1}
 
 \include{gnutls-api}
 
diff --git a/doc/tex/serv1.tex b/doc/tex/serv1.tex
new file mode 100644
index 0000000000..5c60a0dede
--- /dev/null
+++ b/doc/tex/serv1.tex
@@ -0,0 +1,239 @@
+\begin{verbatim}
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <errno.h>
+#include <sys/types.h>
+#include <sys/socket.h>
+#include <netinet/in.h>
+#include <arpa/inet.h>
+#include <string.h>
+#include <unistd.h>
+#include <gnutls.h>
+
+#define KEYFILE "key.pem"
+#define CERTFILE "cert.pem"
+#define CAFILE "ca.pem"
+#define CRLFILE NULL
+
+#define SRP_PASSWD "tpasswd"
+#define SRP_PASSWD_CONF "tpasswd.conf"
+
+
+/* This is a sample TCP echo server.
+ */
+
+
+#define SA struct sockaddr
+#define ERR(err,s) if(err==-1) {perror(s);return(1);}
+#define MAX_BUF 1024
+#define PORT 5556 /* listen to 5556 port */
+
+/* These are global */
+SRP_SERVER_CREDENTIALS srp_cred;
+X509PKI_SERVER_CREDENTIALS x509_cred;
+
+GNUTLS_STATE initialize_state()
+{
+       GNUTLS_STATE state;
+       int ret;
+
+       gnutls_init(&state, GNUTLS_SERVER);
+       if ((ret = gnutls_set_db_name(state, "gnutls-rsm.db")) < 0)
+	      fprintf(stderr, "*** DB error (%d)\n\n", ret);
+
+       /* null cipher is here only for debuging 
+        * purposes.
+        */
+       gnutls_set_cipher_priority(state, GNUTLS_NULL_CIPHER,
+		GNUTLS_RIJNDAEL_CBC, GNUTLS_3DES_CBC, GNUTLS_ARCFOUR, 0);
+       gnutls_set_cipher_priority(state, GNUTLS_NULL_CIPHER,
+				GNUTLS_RIJNDAEL_CBC, GNUTLS_3DES_CBC, 0);
+       gnutls_set_compression_priority(state, GNUTLS_ZLIB, GNUTLS_NULL_COMPRESSION, 0);
+       gnutls_set_kx_priority(state, GNUTLS_KX_RSA, GNUTLS_KX_SRP, 0);
+       gnutls_set_protocol_priority(state, GNUTLS_TLS1, GNUTLS_SSL3, 0);
+       gnutls_set_mac_priority(state, GNUTLS_MAC_SHA, GNUTLS_MAC_MD5, 0);
+
+       gnutls_set_cred(state, GNUTLS_SRP, srp_cred);
+       gnutls_set_cred(state, GNUTLS_X509PKI, x509_cred);
+
+
+       return state;
+}
+
+void print_info(GNUTLS_STATE state)
+{
+       const SRP_SERVER_AUTH_INFO *srp_info;
+       const char *tmp;
+       unsigned char sesid[32];
+       int sesid_size, i;
+
+       /* print session_id specific data */
+       gnutls_get_current_session_id(state, sesid, &sesid_size);
+       printf("\n- Session ID: ");
+       for (i = 0; i < sesid_size; i++)
+	      printf("%.2X", sesid[i]);
+       printf("\n");
+
+       /* print srp specific data */
+       if (gnutls_get_auth_info_type(state) == GNUTLS_SRP) {
+	      srp_info = gnutls_get_auth_info(state);
+	      if (srp_info != NULL)
+		     printf("\n- User '%s' connected\n",
+			    srp_info->username);
+       }
+       /* print state information */
+       tmp = gnutls_version_get_name(gnutls_get_current_version(state));
+       printf("- Version: %s\n", tmp);
+
+       tmp = gnutls_kx_get_name(gnutls_get_current_kx(state));
+       printf("- Key Exchange: %s\n", tmp);
+
+       tmp =
+	   gnutls_compression_get_name
+	   (gnutls_get_current_compression_method(state));
+       printf("- Compression: %s\n", tmp);
+
+       tmp = gnutls_cipher_get_name(gnutls_get_current_cipher(state));
+       printf("- Cipher: %s\n", tmp);
+
+       tmp = gnutls_mac_get_name(gnutls_get_current_mac_algorithm(state));
+       printf("- MAC: %s\n", tmp);
+
+}
+
+
+
+int main()
+{
+       int err, listen_sd, i;
+       int sd, ret;
+       struct sockaddr_in sa_serv;
+       struct sockaddr_in sa_cli;
+       int client_len;
+       char topbuf[512];
+       GNUTLS_STATE state;
+       char buffer[MAX_BUF + 1];
+       int optval = 1;
+       int http = 0;
+       char name[256];
+
+       strcpy(name, "Echo Server");
+
+       /* this must be called once in the program
+        */
+       if (gnutls_global_init() < 0) {
+	      fprintf(stderr, "global state initialization error\n");
+	      exit(1);
+       }
+       if (gnutls_allocate_x509_server_sc(&x509_cred, 1) < 0) {
+	      fprintf(stderr, "memory error\n");
+	      exit(1);
+       }
+       if (gnutls_set_x509_server_trust(x509_cred, CAFILE, CRLFILE) < 0) {
+	      fprintf(stderr, "X509 PARSE ERROR\nDid you have ca.pem?\n");
+	      exit(1);
+       }
+       if (gnutls_set_x509_server_key(x509_cred, CERTFILE, KEYFILE) < 0) {
+	      fprintf(stderr, "X509 PARSE ERROR\nDid you have key.pem and cert.pem?\n");
+	      exit(1);
+       }
+       /* SRP_PASSWD a password file (created with the included crypt utility) 
+        * Read README.crypt prior to using SRP.
+        */
+       gnutls_allocate_srp_server_sc(&srp_cred);
+       gnutls_set_srp_server_cred(srp_cred, SRP_PASSWD, SRP_PASSWD_CONF);
+
+
+       /* Socket operations
+        */
+       listen_sd = socket(AF_INET, SOCK_STREAM, 0);
+       ERR(listen_sd, "socket");
+
+       memset(&sa_serv, '\0', sizeof(sa_serv));
+       sa_serv.sin_family = AF_INET;
+       sa_serv.sin_addr.s_addr = INADDR_ANY;
+       sa_serv.sin_port = htons(PORT);	/* Server Port number */
+
+       setsockopt(listen_sd, SOL_SOCKET, SO_REUSEADDR, &optval, sizeof(int));
+       
+       err = bind(listen_sd, (SA *) & sa_serv, sizeof(sa_serv));
+       ERR(err, "bind");
+       err = listen(listen_sd, 1024);
+       ERR(err, "listen");
+
+       printf("%s ready. Listening to port '%d'.\n\n", name, PORT);
+
+       client_len = sizeof(sa_cli);
+       for (;;) {
+	      state = initialize_state();
+
+	      sd = accept(listen_sd, (SA *) & sa_cli, &client_len);
+
+	      printf("- connection from %s, port %d\n",
+		     inet_ntop(AF_INET, &sa_cli.sin_addr, topbuf,
+			       sizeof(topbuf)), ntohs(sa_cli.sin_port));
+
+
+	      ret = gnutls_handshake(sd, state);
+	      if (ret < 0) {
+		     close(sd);
+		     gnutls_deinit(state);
+		     fprintf(stderr, "*** Handshake has failed (%s)\n\n",
+			     gnutls_strerror(ret));
+		     continue;
+	      }
+	      printf("- Handshake was completed\n");
+
+	      print_info(state);
+
+	      i = 0;
+	      for (;;) {
+		     bzero(buffer, MAX_BUF + 1);
+		     ret = gnutls_read(sd, state, buffer, MAX_BUF);
+
+		     if (gnutls_is_fatal_error(ret) == 1 || ret == 0) {
+			    if (ret == 0) {
+				   printf
+				       ("\n- Peer has closed the GNUTLS connection\n");
+				   break;
+			    } else {
+				   fprintf(stderr,
+					   "\n*** Received corrupted data(%d). Closing the connection.\n\n",
+					   ret);
+				   break;
+			    }
+
+		     }
+		     if (ret > 0) {
+			    /* echo data back to the client
+			     */
+			    gnutls_write(sd, state, buffer,
+					 strlen(buffer));
+		     }
+		     if (ret == GNUTLS_E_WARNING_ALERT_RECEIVED || ret == GNUTLS_E_FATAL_ALERT_RECEIVED) {
+			    ret = gnutls_get_last_alert(state);
+			    printf("* Received alert '%d'.\n", ret);
+		     }
+	      }
+	      printf("\n");
+	      gnutls_bye(sd, state, 1); /* do not wait for
+	                                 * the peer to close the connection.
+                                         */
+                                         
+	      close(sd);
+	      gnutls_deinit(state);
+
+       }
+       close(listen_sd);
+
+       gnutls_free_x509_server_sc(x509_cred);
+       gnutls_free_srp_server_sc(srp_cred);
+
+       gnutls_global_deinit();
+
+       return 0;
+
+}
+
+\end{verbatim}
diff --git a/doc/tex/srp1.tex b/doc/tex/srp1.tex
new file mode 100644
index 0000000000..0e986a6f7e
--- /dev/null
+++ b/doc/tex/srp1.tex
@@ -0,0 +1,138 @@
+\begin{verbatim}
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <sys/types.h>
+#include <sys/socket.h>
+#include <netinet/in.h>
+#include <arpa/inet.h>
+#include <gnutls.h>
+
+#define MAX_BUF 1024
+#define USERNAME "user"
+#define PASSWORD "password"
+#define SA struct sockaddr
+#define MSG "GET / HTTP/1.0\r\n\r\n"
+
+int main()
+{
+       const char *PORT = "443";
+       const char *SERVER = "127.0.0.1";
+       int err, ret;
+       int sd, ii;
+       struct sockaddr_in sa;
+       GNUTLS_STATE state;
+       char buffer[MAX_BUF + 1];
+       SRP_CLIENT_CREDENTIALS xcred;
+
+       if (gnutls_global_init() < 0) {
+	      fprintf(stderr, "global state initialization error\n");
+	      exit(1);
+       }
+
+       if (gnutls_allocate_srp_client_sc( &xcred)<0) {
+               fprintf(stderr, "memory error\n");
+               exit(1);
+       }
+       gnutls_set_srp_client_cred( xcred, USERNAME, PASSWORD);
+
+       /* connects to server 
+        */
+       sd = socket(AF_INET, SOCK_STREAM, 0);
+
+       memset(&sa, '\0', sizeof(sa));
+       sa.sin_family = AF_INET;
+       sa.sin_port = htons(atoi(PORT));
+       inet_pton(AF_INET, SERVER, &sa.sin_addr);
+
+       err = connect(sd, (SA *) & sa, sizeof(sa));
+       if (err < 0) {
+	      fprintf(stderr, "Connect error\n");
+	      exit(1);
+       }
+       /* Initialize TLS state 
+        */
+       gnutls_init(&state, GNUTLS_CLIENT);
+
+       /* allow both SSL3 and TLS1
+        */
+       gnutls_set_protocol_priority(state, GNUTLS_TLS1, GNUTLS_SSL3, 0);
+
+       /* allow only ARCFOUR and 3DES ciphers
+        * (3DES has the highest priority)
+        */
+       gnutls_set_cipher_priority(state, GNUTLS_3DES_CBC, GNUTLS_ARCFOUR, 0);
+
+       /* only allow null compression
+        */
+       gnutls_set_compression_priority(state, GNUTLS_NULL_COMPRESSION, 0);
+
+       /* use GNUTLS_KX_RSA
+        */
+       gnutls_set_kx_priority(state, GNUTLS_KX_SRP, 0);
+
+       /* allow the usage of both SHA and MD5
+        */
+       gnutls_set_mac_priority(state, GNUTLS_MAC_SHA, GNUTLS_MAC_MD5, 0);
+
+
+       /* put the SRP credentials to the current state
+        */
+       gnutls_set_cred(state, GNUTLS_SRP, xcred);
+
+
+       /* Perform the TLS handshake
+        */
+       ret = gnutls_handshake(sd, state);
+
+       if (ret < 0) {
+	      fprintf(stderr, "*** Handshake failed\n");
+	      gnutls_perror(ret);
+	      goto end;
+       } else {
+	      printf("- Handshake was completed\n");
+       }
+
+       gnutls_write(sd, state, MSG, strlen(MSG));
+
+       ret = gnutls_read(sd, state, buffer, MAX_BUF);
+       if (gnutls_is_fatal_error(ret) == 1 || ret == 0) {
+	      if (ret == 0) {
+		     printf("- Peer has closed the GNUTLS connection\n");
+		     goto end;
+	      } else {
+		     fprintf(stderr, "*** Received corrupted data(%d) - server has terminated the connection abnormally\n",
+			     ret);
+		     goto end;
+	      }
+       } else {
+	      if (ret == GNUTLS_E_WARNING_ALERT_RECEIVED || ret == GNUTLS_E_FATAL_ALERT_RECEIVED)
+		     printf("* Received alert [%d]\n", gnutls_get_last_alert(state));
+	      if (ret == GNUTLS_E_GOT_HELLO_REQUEST)
+		     printf("* Received HelloRequest message (server asked to rehandshake)\n");
+       }
+
+       if (ret > 0) {
+	      printf("- Received %d bytes: ", ret);
+	      for (ii = 0; ii < ret; ii++) {
+		     fputc(buffer[ii], stdout);
+	      }
+	      fputs("\n", stdout);
+       }
+       gnutls_bye(sd, state, 0);
+
+     end:
+
+       shutdown(sd, SHUT_RDWR);	/* no more receptions */
+       close(sd);
+
+       gnutls_deinit(state);
+
+       gnutls_free_srp_client_sc(xcred);
+
+       gnutls_global_deinit();
+
+       return 0;
+}
+
+\end{verbatim}
\ No newline at end of file