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:
@../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
\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
-\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}
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
\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}
--- /dev/null
+\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}
--- /dev/null
+\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
projects / thirdparty / gnutls.git / commitdiff
