diff options
| -rw-r--r-- | doc/Makefile.am | 8 | ||||
| -rw-r--r-- | doc/cha-gtls-app.texi | 19 | ||||
| -rw-r--r-- | doc/cha-gtls-examples.texi | 31 | ||||
| -rw-r--r-- | doc/cha-intro-tls.texi | 10 | ||||
| -rw-r--r-- | doc/examples/Makefile.am | 8 | ||||
| -rw-r--r-- | doc/examples/ex-client-anon.c (renamed from doc/examples/ex-client1.c) | 6 | ||||
| -rw-r--r-- | doc/examples/ex-client-dtls.c (renamed from doc/examples/ex-client-udp.c) | 8 | ||||
| -rw-r--r-- | doc/examples/ex-client-psk.c | 6 | ||||
| -rw-r--r-- | doc/examples/ex-client-resume.c | 6 | ||||
| -rw-r--r-- | doc/examples/ex-client-srp.c | 6 | ||||
| -rw-r--r-- | doc/examples/ex-client-x509.c (renamed from doc/examples/ex-rfc2818.c) | 2 | ||||
| -rw-r--r-- | doc/examples/ex-serv-anon.c | 8 | ||||
| -rw-r--r-- | doc/examples/ex-serv-srp.c | 8 | ||||
| -rw-r--r-- | doc/examples/ex-serv-x509.c (renamed from doc/examples/ex-serv1.c) | 13 |
14 files changed, 98 insertions, 41 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index 41619a8863..d391260171 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -39,14 +39,14 @@ gnutls_TEXINFOS = gnutls.texi fdl-1.3.texi lgpl-2.1.texi gpl-3.0.texi \ cha-shared-key.texi cha-gtls-examples.texi # Examples. -gnutls_TEXINFOS += examples/ex-client1.c \ +gnutls_TEXINFOS += examples/ex-client-anon.c \ examples/ex-session-info.c examples/ex-verify.c \ examples/ex-cert-select.c examples/ex-client-resume.c \ - examples/ex-client-srp.c examples/ex-rfc2818.c \ - examples/ex-serv1.c examples/ex-serv-anon.c \ + examples/ex-client-srp.c examples/ex-client-x509.c \ + examples/ex-serv-x509.c examples/ex-serv-anon.c \ examples/ex-serv-pgp.c examples/ex-serv-srp.c \ examples/ex-alert.c examples/ex-x509-info.c examples/ex-crq.c \ - examples/ex-pkcs12.c + examples/ex-pkcs12.c examples/ex-client-dtls.c # Images. Make sure there are eps + png + pdf of each, plus the source dia. gnutls_TEXINFOS += gnutls-internals.dia gnutls-internals.eps \ diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi index 1037038156..03993a5ef2 100644 --- a/doc/cha-gtls-app.texi +++ b/doc/cha-gtls-app.texi @@ -9,6 +9,7 @@ * Setting up the transport layer:: * TLS handshake:: * Data transfer and termination:: +* Handling alerts:: * Priority Strings:: * Advanced and other topics:: * Using the cryptographic library:: @@ -643,6 +644,24 @@ A session can be deinitialized with the @funcref{gnutls_deinit} function. @showfuncdesc{gnutls_bye} @showfuncdesc{gnutls_deinit} +@node Handling alerts +@section Handling alerts +During a TLS connection alert messages may be exchanged by the +two peers. Those messages may be fatal, meaning the connection +must be terminated afterwards, or warning when something needs +to be reported to the peer, but without interrupting the session. +The error codes @code{GNUTLS_E_WARNING_ALERT_RECEIVED} +or @code{GNUTLS_E_FATAL_ALERT_RECEIVED} signal those alerts +when received, and may be returned by all GnuTLS functions that receive +data from the peer, being @funcref{gnutls_handshake} and @funcref{gnutls_record_recv}. +Alerts messages may be sent to the peer using @funcref{gnutls_alert_send}. + +@showfuncdesc{gnutls_alert_get} + +@showfuncdesc{gnutls_alert_send} + +@showfuncB{gnutls_error_to_alert,gnutls_alert_get_name} + @node Priority Strings @section Priority strings diff --git a/doc/cha-gtls-examples.texi b/doc/cha-gtls-examples.texi index 68230a9d33..8d364b635b 100644 --- a/doc/cha-gtls-examples.texi +++ b/doc/cha-gtls-examples.texi @@ -25,7 +25,7 @@ implemented by another example. * Obtaining session information:: * Using a callback to select the certificate to use:: * Verifying a certificate:: -* Client using a PKCS 11 token with TLS:: +* Client using a smart card with TLS:: * Client with Resume capability example:: * Simple client example with SRP authentication:: * Simple client example in C++:: @@ -40,9 +40,10 @@ The simplest client using TLS is the one that doesn't do any authentication. This means no external certificates or passwords are needed to set up the connection. As could be expected, the connection is vulnerable to man-in-the-middle (active or redirection) attacks. -However, the data is integrity and privacy protected. +However, the data are integrity protected and encrypted from +passive eavesdroppers. -@verbatiminclude examples/ex-client1.c +@verbatiminclude examples/ex-client-anon.c @node Simple client example with X.509 certificate support @subsection Simple client example with @acronym{X.509} certificate support @@ -55,16 +56,16 @@ a very simple @acronym{TLS} client, which uses the high level verification functions for certificates, but does not support session resumption. -@verbatiminclude examples/ex-rfc2818.c +@verbatiminclude examples/ex-client-x509.c @node Simple Datagram TLS client example @subsection Simple datagram @acronym{TLS} client example This is a client that uses @acronym{UDP} to connect to a -server. This is the @acronym{DTLS} equivalent to the example -in @ref{Simple client example with X.509 certificate support}. +server. This is the @acronym{DTLS} equivalent to the TLS example +with X.509 certificates. -@verbatiminclude examples/ex-client-udp.c +@verbatiminclude examples/ex-client-dtls.c @node Obtaining session information @subsection Obtaining session information @@ -96,12 +97,14 @@ functions to verify a given certificate list. @verbatiminclude examples/ex-verify.c -@node Client using a PKCS 11 token with TLS -@subsection Using a @acronym{PKCS} #11 token with TLS +@node Client using a smart card with TLS +@subsection Using a smart card with TLS @anchor{ex:pkcs11-client} +@cindex Smart card example This example will demonstrate how to load keys and certificates -from a @acronym{PKCS} #11 token, and use it with a TLS connection. +from a smart-card or any other @acronym{PKCS} #11 token, and +use it in a TLS connection. @verbatiminclude examples/ex-cert-select-pkcs11.c @@ -163,7 +166,7 @@ servers, using @acronym{GnuTLS}. * Echo server with OpenPGP authentication:: * Echo server with SRP authentication:: * Echo server with anonymous authentication:: -* Echo DTLS server with X.509 authentication:: +* DTLS echo server with X.509 authentication:: @end menu @node Echo server with X.509 authentication @@ -172,7 +175,7 @@ servers, using @acronym{GnuTLS}. This example is a very simple echo server which supports @acronym{X.509} authentication. -@verbatiminclude examples/ex-serv1.c +@verbatiminclude examples/ex-serv-x509.c @node Echo server with OpenPGP authentication @subsection Echo server with @acronym{OpenPGP} authentication @@ -203,8 +206,8 @@ used to serve the example client for anonymous authentication. @verbatiminclude examples/ex-serv-anon.c -@node Echo DTLS server with X.509 authentication -@subsection Echo DTLS server with @acronym{X.509} authentication +@node DTLS echo server with X.509 authentication +@subsection DTLS echo server with @acronym{X.509} authentication This example is a very simple echo server using Datagram TLS and @acronym{X.509} authentication. diff --git a/doc/cha-intro-tls.texi b/doc/cha-intro-tls.texi index 5f5f77d1ec..6b1bb7272e 100644 --- a/doc/cha-intro-tls.texi +++ b/doc/cha-intro-tls.texi @@ -271,18 +271,10 @@ warning. Fatal alerts always terminate the current connection, and prevent future re-negotiations using the current session ID. All alert messages are summarized in @ref{tab:alerts}. - The alert messages are protected by the record protocol, thus the information that is included does not leak. You must take extreme care for the alert information not to leak to a possible attacker, via -public log files etc. The available functions to control the alert -protocol are shown below. - -@showfuncdesc{gnutls_alert_get} - -@showfuncdesc{gnutls_alert_send} - -@showfuncB{gnutls_error_to_alert,gnutls_alert_get_name} +public log files etc. @include alerts.texi diff --git a/doc/examples/Makefile.am b/doc/examples/Makefile.am index 38d25a5dd2..aac8421610 100644 --- a/doc/examples/Makefile.am +++ b/doc/examples/Makefile.am @@ -41,11 +41,11 @@ LDADD = libexamples.la \ CXX_LDADD = $(LDADD) \ ../../lib/libgnutlsxx.la -noinst_PROGRAMS = ex-client-resume ex-client-udp -noinst_PROGRAMS += ex-cert-select ex-rfc2818 +noinst_PROGRAMS = ex-client-resume ex-client-dtls +noinst_PROGRAMS += ex-cert-select ex-client-x509 if ENABLE_PKI -noinst_PROGRAMS += ex-crq ex-serv1 ex-serv-dtls +noinst_PROGRAMS += ex-crq ex-serv-x509 ex-serv-dtls endif if ENABLE_CXX @@ -55,7 +55,7 @@ noinst_PROGRAMS += ex-cxx endif if ENABLE_ANON -noinst_PROGRAMS += ex-client1 ex-serv-anon +noinst_PROGRAMS += ex-client-anon ex-serv-anon endif if ENABLE_OPENPGP diff --git a/doc/examples/ex-client1.c b/doc/examples/ex-client-anon.c index 322e400ec0..8c06bda900 100644 --- a/doc/examples/ex-client1.c +++ b/doc/examples/ex-client-anon.c @@ -55,7 +55,11 @@ main (void) /* Perform the TLS handshake */ - ret = gnutls_handshake (session); + do + { + ret = gnutls_handshake (session); + } + while (gnutls_error_is_fatal (ret) == 0); if (ret < 0) { diff --git a/doc/examples/ex-client-udp.c b/doc/examples/ex-client-dtls.c index 7a0721a856..222762a0b5 100644 --- a/doc/examples/ex-client-udp.c +++ b/doc/examples/ex-client-dtls.c @@ -59,6 +59,8 @@ main (void) /* put the x509 credentials to the current session */ gnutls_credentials_set (session, GNUTLS_CRD_CERTIFICATE, xcred); + gnutls_server_name_set (session, GNUTLS_NAME_DNS, "my_host_name", + strlen("my_host_name")); /* connect to the peer */ sd = udp_connect (); @@ -69,7 +71,11 @@ main (void) gnutls_dtls_set_mtu (session, 1000); /* Perform the TLS handshake */ - ret = gnutls_handshake (session); + do + { + ret = gnutls_handshake (session); + } + while (gnutls_error_is_fatal (ret) == 0); if (ret < 0) { diff --git a/doc/examples/ex-client-psk.c b/doc/examples/ex-client-psk.c index 2264f076b2..7c0bd7e146 100644 --- a/doc/examples/ex-client-psk.c +++ b/doc/examples/ex-client-psk.c @@ -65,7 +65,11 @@ main (void) /* Perform the TLS handshake */ - ret = gnutls_handshake (session); + do + { + ret = gnutls_handshake (session); + } + while (gnutls_error_is_fatal (ret) == 0); if (ret < 0) { diff --git a/doc/examples/ex-client-resume.c b/doc/examples/ex-client-resume.c index 9e6e9b60fd..5aeae58c92 100644 --- a/doc/examples/ex-client-resume.c +++ b/doc/examples/ex-client-resume.c @@ -63,7 +63,11 @@ main (void) /* Perform the TLS handshake */ - ret = gnutls_handshake (session); + do + { + ret = gnutls_handshake (session); + } + while (gnutls_error_is_fatal (ret) == 0); if (ret < 0) { diff --git a/doc/examples/ex-client-srp.c b/doc/examples/ex-client-srp.c index b8ecc2b5a8..5a753abff3 100644 --- a/doc/examples/ex-client-srp.c +++ b/doc/examples/ex-client-srp.c @@ -62,7 +62,11 @@ main (void) /* Perform the TLS handshake */ - ret = gnutls_handshake (session); + do + { + ret = gnutls_handshake (session); + } + while (gnutls_error_is_fatal (ret) == 0); if (ret < 0) { diff --git a/doc/examples/ex-rfc2818.c b/doc/examples/ex-client-x509.c index f7aa08d068..c82df6523b 100644 --- a/doc/examples/ex-rfc2818.c +++ b/doc/examples/ex-client-x509.c @@ -46,6 +46,8 @@ int main (void) gnutls_init (&session, GNUTLS_CLIENT); gnutls_session_set_ptr (session, (void *) "my_host_name"); + gnutls_server_name_set (session, GNUTLS_NAME_DNS, "my_host_name", + strlen("my_host_name")); /* Use default priorities */ ret = gnutls_priority_set_direct (session, "NORMAL", &err); diff --git a/doc/examples/ex-serv-anon.c b/doc/examples/ex-serv-anon.c index ade01f4a54..93c8a70fee 100644 --- a/doc/examples/ex-serv-anon.c +++ b/doc/examples/ex-serv-anon.c @@ -116,7 +116,13 @@ main (void) sizeof (topbuf)), ntohs (sa_cli.sin_port)); gnutls_transport_set_ptr (session, (gnutls_transport_ptr_t) sd); - ret = gnutls_handshake (session); + + do + { + ret = gnutls_handshake (session); + } + while (gnutls_error_is_fatal (ret) == 0); + if (ret < 0) { close (sd); diff --git a/doc/examples/ex-serv-srp.c b/doc/examples/ex-serv-srp.c index 5dbd8cfb69..0cff30c448 100644 --- a/doc/examples/ex-serv-srp.c +++ b/doc/examples/ex-serv-srp.c @@ -117,7 +117,13 @@ main (void) sizeof (topbuf)), ntohs (sa_cli.sin_port)); gnutls_transport_set_ptr (session, (gnutls_transport_ptr_t) sd); - ret = gnutls_handshake (session); + + do + { + ret = gnutls_handshake (session); + } + while (gnutls_error_is_fatal (ret) == 0); + if (ret < 0) { close (sd); diff --git a/doc/examples/ex-serv1.c b/doc/examples/ex-serv-x509.c index eaf09f6474..5383fb3425 100644 --- a/doc/examples/ex-serv1.c +++ b/doc/examples/ex-serv-x509.c @@ -41,9 +41,10 @@ initialize_tls_session (void) gnutls_credentials_set (session, GNUTLS_CRD_CERTIFICATE, x509_cred); - /* request client certificate if any. + /* We don't request any certificate from the client. + * If we did we would need to verify it. */ - gnutls_certificate_server_set_request (session, GNUTLS_CERT_REQUEST); + gnutls_certificate_server_set_request (session, GNUTLS_CERT_IGNORE); return session; } @@ -134,7 +135,13 @@ main (void) sizeof (topbuf)), ntohs (sa_cli.sin_port)); gnutls_transport_set_ptr (session, (gnutls_transport_ptr_t) sd); - ret = gnutls_handshake (session); + + do + { + ret = gnutls_handshake (session); + } + while (gnutls_error_is_fatal (ret) == 0); + if (ret < 0) { close (sd); |