diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/examples/Makefile.am | 18 | ||||
| -rw-r--r-- | doc/examples/ex-client-psk.c | 119 | ||||
| -rw-r--r-- | doc/examples/ex-cxx.cpp | 101 | ||||
| -rw-r--r-- | doc/examples/ex-serv-export.c | 10 | ||||
| -rw-r--r-- | doc/examples/ex-serv-psk.c | 226 | ||||
| -rw-r--r-- | doc/examples/ex-session-info.c | 11 | ||||
| -rw-r--r-- | doc/examples/ex-x509-info.c | 3 | ||||
| -rw-r--r-- | doc/gendocs_template | 6 | ||||
| -rw-r--r-- | doc/gnutls.texi | 740 | ||||
| -rw-r--r-- | doc/protocol/draft-badra-tls-psk-new-mac-aes-gcm-02.txt | 485 | ||||
| -rw-r--r-- | doc/protocol/draft-ietf-netconf-tls-02.txt | 809 | ||||
| -rw-r--r-- | doc/protocol/draft-ietf-tls-ecc-new-mac-06.txt | 392 | ||||
| -rw-r--r-- | doc/protocol/draft-ietf-tls-ecc-new-mac-07.txt | 392 | ||||
| -rw-r--r-- | doc/protocol/draft-rescorla-tls-extended-random-00.txt | 448 | ||||
| -rw-r--r-- | doc/reference/gnutls-docs.sgml | 6 |
15 files changed, 3460 insertions, 306 deletions
diff --git a/doc/examples/Makefile.am b/doc/examples/Makefile.am index f5db096241..df1e89158f 100644 --- a/doc/examples/Makefile.am +++ b/doc/examples/Makefile.am @@ -28,8 +28,18 @@ LDADD = libexamples.la \ ../../libextra/libgnutls-extra.la \ ../../gl/libgnu.la -noinst_PROGRAMS = ex-cert-select ex-client2 ex-client-resume \ - ex-crq ex-serv1 ex-serv-export +CXX_LDADD = $(LDADD) \ + ../../lib/libgnutlsxx.la + +noinst_PROGRAMS = ex-client2 ex-client-resume +noinst_PROGRAMS += ex-cert-select ex-crq +noinst_PROGRAMS += ex-serv1 ex-serv-export + +if ENABLE_CXX +ex_cxx_SOURCES = ex-cxx.cpp +ex_cxx_LDADD = $(CXX_LDADD) +noinst_PROGRAMS += ex-cxx +endif if ENABLE_ANON noinst_PROGRAMS += ex-client1 ex-serv-anon @@ -40,6 +50,10 @@ if ENABLE_OPENPGP noinst_PROGRAMS += ex-serv-pgp endif +if ENABLE_PSK +noinst_PROGRAMS += ex-client-psk ex-serv-psk +endif + if ENABLE_SRP noinst_PROGRAMS += ex-client-srp ex-serv-srp endif diff --git a/doc/examples/ex-client-psk.c b/doc/examples/ex-client-psk.c new file mode 100644 index 0000000000..be718e0bde --- /dev/null +++ b/doc/examples/ex-client-psk.c @@ -0,0 +1,119 @@ +/* Copyright 2007, 2008 Free Software Foundation + * + * Copying and distribution of this file, with or without modification, + * are permitted in any medium without royalty provided the copyright + * notice and this notice are preserved. + */ + +#if HAVE_CONFIG_H +# include <config.h> +#endif + +#include <stdio.h> +#include <stdlib.h> +#include <string.h> +#include <sys/types.h> +#include <sys/socket.h> +#include <arpa/inet.h> +#include <unistd.h> +#include <gnutls/gnutls.h> + +/* A very basic TLS client, with PSK authentication. + */ + +#define MAX_BUF 1024 +#define CAFILE "ca.pem" +#define MSG "GET / HTTP/1.0\r\n\r\n" + +extern int tcp_connect (void); +extern void tcp_close (int sd); + +int +main (void) +{ + int ret, sd, ii; + gnutls_session_t session; + char buffer[MAX_BUF + 1]; + const char *err; + gnutls_psk_client_credentials_t pskcred; + const gnutls_datum_t key = { "DEADBEEF", 8 }; + + gnutls_global_init (); + + gnutls_psk_allocate_client_credentials (&pskcred); + gnutls_psk_set_client_credentials (pskcred, "test", &key, + GNUTLS_PSK_KEY_HEX); + + /* Initialize TLS session + */ + gnutls_init (&session, GNUTLS_CLIENT); + + /* Use default priorities */ + ret = gnutls_priority_set_direct (session, "PERFORMANCE", &err); + if (ret < 0) { + if (ret == GNUTLS_E_INVALID_REQUEST) { + fprintf(stderr, "Syntax error at: %s\n", err); + } + exit(1); + } + + /* put the x509 credentials to the current session + */ + gnutls_credentials_set (session, GNUTLS_CRD_PSK, pskcred); + + /* connect to the peer + */ + sd = tcp_connect (); + + gnutls_transport_set_ptr (session, (gnutls_transport_ptr_t) sd); + + /* Perform the TLS handshake + */ + ret = gnutls_handshake (session); + + if (ret < 0) + { + fprintf (stderr, "*** Handshake failed\n"); + gnutls_perror (ret); + goto end; + } + else + { + printf ("- Handshake was completed\n"); + } + + gnutls_record_send (session, MSG, strlen (MSG)); + + ret = gnutls_record_recv (session, buffer, MAX_BUF); + if (ret == 0) + { + printf ("- Peer has closed the TLS connection\n"); + goto end; + } + else if (ret < 0) + { + fprintf (stderr, "*** Error: %s\n", gnutls_strerror (ret)); + goto end; + } + + printf ("- Received %d bytes: ", ret); + for (ii = 0; ii < ret; ii++) + { + fputc (buffer[ii], stdout); + } + fputs ("\n", stdout); + + gnutls_bye (session, GNUTLS_SHUT_RDWR); + +end: + + tcp_close (sd); + + gnutls_deinit (session); + + gnutls_psk_free_client_credentials (pskcred); + + gnutls_global_deinit (); + + return 0; +} diff --git a/doc/examples/ex-cxx.cpp b/doc/examples/ex-cxx.cpp new file mode 100644 index 0000000000..1bade542fe --- /dev/null +++ b/doc/examples/ex-cxx.cpp @@ -0,0 +1,101 @@ +#if HAVE_CONFIG_H +# include <config.h> +#else +#endif +#include <iostream> +#include <stdexcept> +#include <gnutls/gnutls.h> +#include <gnutls/gnutlsxx.h> +#include <cstring> /* for strlen */ + +/* A very basic TLS client, with anonymous authentication. + * written by Eduardo Villanueva Che. + */ + +#define MAX_BUF 1024 +#define SA struct sockaddr + +#define CAFILE "ca.pem" +#define MSG "GET / HTTP/1.0\r\n\r\n" + +extern "C" +{ + int tcp_connect(void); + void tcp_close(int sd); +} + + +int main(void) +{ + int sd = -1; + gnutls_global_init(); + + try + { + + /* Allow connections to servers that have OpenPGP keys as well. + */ + gnutls::client_session session; + + /* X509 stuff */ + gnutls::certificate_credentials credentials; + + + /* sets the trusted cas file + */ + credentials.set_x509_trust_file(CAFILE, GNUTLS_X509_FMT_PEM); + /* put the x509 credentials to the current session + */ + session.set_credentials(credentials); + + /* Use default priorities */ + session.set_priority ("NORMAL", NULL); + + /* connect to the peer + */ + sd = tcp_connect(); + session.set_transport_ptr((gnutls_transport_ptr_t) sd); + + /* Perform the TLS handshake + */ + int ret = session.handshake(); + if (ret < 0) + { +// gnutls_perror(ret); + throw std::runtime_error("Handshake failed"); + } + else + { + std::cout << "- Handshake was completed" << std::endl; + } + + session.send(MSG, strlen(MSG)); + char buffer[MAX_BUF + 1]; + ret = session.recv(buffer, MAX_BUF); + if (ret == 0) + { + throw std::runtime_error("Peer has closed the TLS connection"); + } + else if (ret < 0) + { + throw std::runtime_error(gnutls_strerror(ret)); + } + + std::cout << "- Received " << ret << " bytes:" << std::endl; + std::cout.write(buffer, ret); + std::cout << std::endl; + + session.bye(GNUTLS_SHUT_RDWR); + } + catch (std::exception &ex) + { + std::cerr << "Exception caught: " << ex.what() << std::endl; + } + + if (sd != -1) + tcp_close(sd); + + gnutls_global_deinit(); + + return 0; +} diff --git a/doc/examples/ex-serv-export.c b/doc/examples/ex-serv-export.c index 2ff4aa6230..13f5308cca 100644 --- a/doc/examples/ex-serv-export.c +++ b/doc/examples/ex-serv-export.c @@ -1,4 +1,4 @@ -/* Copyright 2007 Free Software Foundation +/* Copyright 2007, 2008 Free Software Foundation * * Copying and distribution of this file, with or without modification, * are permitted in any medium without royalty provided the copyright @@ -248,6 +248,11 @@ main (void) } close (listen_sd); + if (TLS_SESSION_CACHE != 0) + { + wrap_db_deinit (); + } + gnutls_certificate_free_credentials (cert_cred); gnutls_global_deinit (); @@ -288,6 +293,9 @@ wrap_db_init (void) static void wrap_db_deinit (void) { + if (cache_db) + free (cache_db); + cache_db = NULL; return; } diff --git a/doc/examples/ex-serv-psk.c b/doc/examples/ex-serv-psk.c new file mode 100644 index 0000000000..a5ef67db68 --- /dev/null +++ b/doc/examples/ex-serv-psk.c @@ -0,0 +1,226 @@ +/* Copyright 2007, 2008 Free Software Foundation + * + * Copying and distribution of this file, with or without modification, + * are permitted in any medium without royalty provided the copyright + * notice and this notice are preserved. + */ + +#if HAVE_CONFIG_H +# include <config.h> +#endif + +#include <stdio.h> +#include <stdlib.h> +#include <errno.h> +#include <sys/types.h> +#include <sys/socket.h> +#include <arpa/inet.h> +#include <netinet/in.h> +#include <string.h> +#include <unistd.h> +#include <gnutls/gnutls.h> +#include <gcrypt.h> /* for gcry_control */ + +#define KEYFILE "key.pem" +#define CERTFILE "cert.pem" +#define CAFILE "ca.pem" +#define CRLFILE "crl.pem" + +/* This is a sample TLS echo server, supporting X.509 and PSK + authentication. + */ + + +#define SA struct sockaddr +#define SOCKET_ERR(err,s) if(err==-1) {perror(s);return(1);} +#define MAX_BUF 1024 +#define PORT 5556 /* listen to 5556 port */ +#define DH_BITS 1024 + +/* These are global */ +gnutls_certificate_credentials_t x509_cred; +gnutls_psk_server_credentials_t psk_cred; +gnutls_priority_t priority_cache; + +gnutls_session_t +initialize_tls_session (void) +{ + gnutls_session_t session; + + gnutls_init (&session, GNUTLS_SERVER); + + gnutls_priority_set (session, priority_cache); + + gnutls_credentials_set (session, GNUTLS_CRD_CERTIFICATE, x509_cred); + gnutls_credentials_set (session, GNUTLS_CRD_PSK, psk_cred); + + /* request client certificate if any. + */ + gnutls_certificate_server_set_request (session, GNUTLS_CERT_REQUEST); + + return session; +} + +static gnutls_dh_params_t dh_params; + +static int +generate_dh_params (void) +{ + + /* Generate Diffie Hellman parameters - for use with DHE + * kx algorithms. When short bit length is used, it might + * be wise to regenerate parameters. + * + * Check the ex-serv-export.c example for using static + * parameters. + */ + gnutls_dh_params_init (&dh_params); + gnutls_dh_params_generate2 (dh_params, DH_BITS); + + return 0; +} + +static int +pskfunc (gnutls_session_t session, const char *username, gnutls_datum_t * key) +{ + printf ("psk: username %s\n", username); + key->data = gnutls_malloc (4); + key->data[0] = 0xDE; + key->data[1] = 0xAD; + key->data[2] = 0xBE; + key->data[3] = 0xEF; + key->size = 4; + return 0; +} + +int +main (void) +{ + 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_session_t session; + char buffer[MAX_BUF + 1]; + int optval = 1; + + /* to disallow usage of the blocking /dev/random + */ + gcry_control (GCRYCTL_ENABLE_QUICK_RANDOM, 0); + + /* this must be called once in the program + */ + gnutls_global_init (); + + gnutls_certificate_allocate_credentials (&x509_cred); + gnutls_certificate_set_x509_trust_file (x509_cred, CAFILE, + GNUTLS_X509_FMT_PEM); + + gnutls_certificate_set_x509_crl_file (x509_cred, CRLFILE, + GNUTLS_X509_FMT_PEM); + + gnutls_certificate_set_x509_key_file (x509_cred, CERTFILE, KEYFILE, + GNUTLS_X509_FMT_PEM); + + gnutls_psk_allocate_server_credentials (&psk_cred); + gnutls_psk_set_server_credentials_function (psk_cred, pskfunc); + + generate_dh_params (); + + gnutls_priority_init( &priority_cache, "NORMAL:PSK", NULL); + + + gnutls_certificate_set_dh_params (x509_cred, dh_params); + + /* Socket operations + */ + listen_sd = socket (AF_INET, SOCK_STREAM, 0); + SOCKET_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)); + SOCKET_ERR (err, "bind"); + err = listen (listen_sd, 1024); + SOCKET_ERR (err, "listen"); + + printf ("Server ready. Listening to port '%d'.\n\n", PORT); + + client_len = sizeof (sa_cli); + for (;;) + { + session = initialize_tls_session (); + + 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)); + + gnutls_transport_set_ptr (session, (gnutls_transport_ptr_t) sd); + ret = gnutls_handshake (session); + if (ret < 0) + { + close (sd); + gnutls_deinit (session); + fprintf (stderr, "*** Handshake has failed (%s)\n\n", + gnutls_strerror (ret)); + continue; + } + printf ("- Handshake was completed\n"); + + /* see the Getting peer's information example */ + /* print_info(session); */ + + i = 0; + for (;;) + { + memset (buffer, 0, MAX_BUF + 1); + ret = gnutls_record_recv (session, buffer, MAX_BUF); + + if (ret == 0) + { + printf ("\n- Peer has closed the GNUTLS connection\n"); + break; + } + else if (ret < 0) + { + fprintf (stderr, "\n*** Received corrupted " + "data(%d). Closing the connection.\n\n", ret); + break; + } + else if (ret > 0) + { + /* echo data back to the client + */ + gnutls_record_send (session, buffer, strlen (buffer)); + } + } + printf ("\n"); + /* do not wait for the peer to close the connection. + */ + gnutls_bye (session, GNUTLS_SHUT_WR); + + close (sd); + gnutls_deinit (session); + + } + close (listen_sd); + + gnutls_certificate_free_credentials (x509_cred); + gnutls_psk_free_server_credentials (psk_cred); + + gnutls_priority_deinit(priority_cache); + + gnutls_global_deinit (); + + return 0; + +} diff --git a/doc/examples/ex-session-info.c b/doc/examples/ex-session-info.c index dded275152..382b038185 100644 --- a/doc/examples/ex-session-info.c +++ b/doc/examples/ex-session-info.c @@ -1,4 +1,4 @@ -/* Copyright 2007 Free Software Foundation +/* Copyright 2007, 2008 Free Software Foundation * * Copying and distribution of this file, with or without modification, * are permitted in any medium without royalty provided the copyright @@ -43,12 +43,21 @@ print_info (gnutls_session_t session) break; +#ifdef ENABLE_SRP case GNUTLS_CRD_SRP: printf ("- SRP session with username %s\n", gnutls_srp_server_get_username (session)); break; +#endif case GNUTLS_CRD_PSK: + /* This returns NULL in server side. + */ + if (gnutls_psk_client_get_hint (session) != NULL) + printf ("- PSK authentication. PSK hint '%s'\n", + gnutls_psk_client_get_hint (session)); + /* This returns NULL in client side. + */ if (gnutls_psk_server_get_username (session) != NULL) printf ("- PSK authentication. Connected as '%s'\n", gnutls_psk_server_get_username (session)); diff --git a/doc/examples/ex-x509-info.c b/doc/examples/ex-x509-info.c index 911d315d44..5ffee181e2 100644 --- a/doc/examples/ex-x509-info.c +++ b/doc/examples/ex-x509-info.c @@ -1,4 +1,4 @@ -/* Copyright 2007 Free Software Foundation +/* Copyright 2007, 2008 Free Software Foundation * * Copying and distribution of this file, with or without modification, * are permitted in any medium without royalty provided the copyright @@ -81,7 +81,6 @@ print_x509_certificate_info (gnutls_session_t session) size = sizeof (serial); gnutls_x509_crt_get_serial (cert, serial, &size); - size = sizeof (serial); printf ("\tCertificate serial number: %s\n", bin2hex (serial, size)); /* Extract some of the public key algorithm's parameters diff --git a/doc/gendocs_template b/doc/gendocs_template index 066908e023..63a636a6e4 100644 --- a/doc/gendocs_template +++ b/doc/gendocs_template @@ -59,7 +59,7 @@ (%%TEXI_TGZ_SIZE%%K bytes gzipped tar file).</a></li> </ul> -<p>You can <a href="http://www.gnu.org/order/">buy printed copies of +<p>You can <a href="http://shop.fsf.org/">buy printed copies of some manuals</a> (among other items) from the Free Software Foundation; this helps support FSF activities.</p> @@ -80,7 +80,7 @@ script</a>.)</p> <!-- Please make sure the copyright date is consistent with the document --> <!-- and that it is like this "2001, 2002" not this "2001-2002." --> </div><!-- for id="content", starts in the include above --> -<!--#include virtual="/server/footer-min.html" --> +<!--#include virtual="/server/footer.html" --> <div id="footer"> <p> @@ -94,7 +94,7 @@ Please send broken links and other corrections or suggestions to </p> <p> -Copyright © 2007 Free Software Foundation, Inc., +Copyright © 2008 Free Software Foundation, Inc., </p> <address>51 Franklin Street, Fifth Floor, Boston, MA 02111, USA</address> <p>Verbatim copying and distribution of this entire article is diff --git a/doc/gnutls.texi b/doc/gnutls.texi index 62f37c2281..49f8431f63 100644 --- a/doc/gnutls.texi +++ b/doc/gnutls.texi @@ -39,10 +39,11 @@ Documentation License''. @direntry * GnuTLS: (gnutls). Package for Transport Layer Security. * certtool: (gnutls)Invoking certtool. Manipulate certificates and keys. -* srptool: (gnutls)Invoking srptool. Simple SRP password tool. * gnutls-serv: (gnutls)Invoking gnutls-serv. GNU TLS test server. * gnutls-cli: (gnutls)Invoking gnutls-cli. GNU TLS test client. * gnutls-cli-debug: (gnutls)Invoking gnutls-cli-debug. GNU TLS debug client. +* psktool: (gnutls)Invoking psktool. Simple TLS-Pre-Shared-Keys manager. +* srptool: (gnutls)Invoking srptool. Simple SRP password tool. @end direntry @titlepage @@ -1494,6 +1495,17 @@ file can be stored to the credentials structure by calling password file format is to be used, then the function @ref{gnutls_psk_set_server_credentials_function}, should be used instead. +The server can help the client chose a suitable username and password, +by sending a hint. In the server, specify the hint by calling +@ref{gnutls_psk_set_server_credentials_hint}. The client can retrieve +the hint, for example in the callback function, using +@ref{gnutls_psk_client_get_hint}. + +There is no standard mechanism to derive a PSK key from a password +specified by the TLS PSK document. However, GnuTLS provides +@ref{gnutls_psk_netconf_derive_key} which follows the algorithm +specified in @file{draft-ietf-netconf-tls-02.txt}. + Some helper functions such as: @itemize @@ -2250,6 +2262,7 @@ implemented by another example. * Client with Resume capability example:: * Simple client example with SRP authentication:: * Simple client example with TLS/IA support:: +* Simple client example in @acronym{C++}:: * Helper function for TCP connections:: @end menu @@ -2345,6 +2358,14 @@ The following client is a simple client which uses the @verbatiminclude examples/ex-client-tlsia.c +@node Simple client example in @acronym{C++} +@subsection Simple Client Example using the @acronym{C++} API + +The following client is a simple example of a client +client utilizing the GnuTLS @acronym{C++} API. + +@verbatiminclude examples/ex-cxx.cpp + @node Helper function for TCP connections @subsection Helper Function for TCP Connections @@ -2505,58 +2526,317 @@ let you use the library for common tasks without writing an application. The applications are discussed in this chapter. @menu -* Invoking srptool:: +* Invoking certtool:: * Invoking gnutls-cli:: * Invoking gnutls-cli-debug:: * Invoking gnutls-serv:: -* Invoking certtool:: +* Invoking psktool:: +* Invoking srptool:: @end menu -@node Invoking srptool -@section Invoking srptool -@anchor{srptool} -@cindex srptool +@node Invoking certtool +@section Invoking certtool +@cindex certtool -The @file{srptool} is a very simple program that emulates the programs -in the @emph{Stanford SRP libraries}. It is intended for use in -places where you don't expect @acronym{SRP} authentication to be the -used for system users. Traditionally @emph{libsrp} used two -files. One called 'tpasswd' which holds usernames and verifiers, and -'tpasswd.conf' which holds generators and primes. +This is a program to generate @acronym{X.509} certificates, certificate +requests, CRLs and private keys. -How to use srptool: +@verbatim +Certtool help +Usage: certtool [options] + -s, --generate-self-signed + Generate a self-signed certificate. + -c, --generate-certificate + Generate a signed certificate. + --generate-proxy Generate a proxy certificate. + --generate-crl Generate a CRL. + -u, --update-certificate + Update a signed certificate. + -p, --generate-privkey Generate a private key. + -q, --generate-request Generate a PKCS #10 certificate + request. + -e, --verify-chain Verify a PEM encoded certificate chain. + The last certificate in the chain must + be a self signed one. + --verify-crl Verify a CRL. + --generate-dh-params Generate PKCS #3 encoded Diffie Hellman + parameters. + --get-dh-params Get the included PKCS #3 encoded Diffie + Hellman parameters. + --load-privkey FILE Private key file to use. + --load-request FILE Certificate request file to use. + --load-certificate FILE + Certificate file to use. + --load-ca-privkey FILE Certificate authority's private key + file to use. + --load-ca-certificate FILE + Certificate authority's certificate + file to use. + --password PASSWORD Password to use. + -i, --certificate-info Print information on a certificate. + -l, --crl-info Print information on a CRL. + --p12-info Print information on a PKCS #12 + structure. + --p7-info Print information on a PKCS #7 + structure. + --smime-to-p7 Convert S/MIME to PKCS #7 structure. + -k, --key-info Print information on a private key. + --fix-key Regenerate the parameters in a private + key. + --to-p12 Generate a PKCS #12 structure. + -8, --pkcs8 Use PKCS #8 format for private keys. + --dsa Use DSA keys. + --hash STR Hash algorithm to use for signing + (MD5,SHA1,RMD160). + --export-ciphers Use weak encryption algorithms. + --inder Use DER format for input certificates + and private keys. + --outder Use DER format for output certificates + and private keys. + --bits BITS specify the number of bits for key + generation. + --outfile FILE Output file. + --infile FILE Input file. + --template FILE Template file to use for non + interactive operation. + -d, --debug LEVEL specify the debug level. Default is 1. + -h, --help shows this help text + -v, --version shows the program's version + --copyright shows the program's license +@end verbatim + +The program can be used interactively or non interactively by +specifying the @code{--template} command line option. See below for an +example of a template file. + +How to use certtool interactively: @itemize +@item +To generate parameters for Diffie Hellman key exchange, use the command: +@example +$ certtool --generate-dh-params --outfile dh.pem +@end example @item -To create tpasswd.conf which holds the g and n values for -@acronym{SRP} protocol (generator and a large prime), run: +To generate parameters for the RSA-EXPORT key exchange, use the command: +@example +$ certtool --generate-privkey --bits 512 --outfile rsa.pem +@end example + +@end itemize + +@itemize +@item +To create a self signed certificate, use the command: @example -$ srptool --create-conf /etc/tpasswd.conf +$ certtool --generate-privkey --outfile ca-key.pem +$ certtool --generate-self-signed --load-privkey ca-key.pem \ + --outfile ca-cert.pem @end example +Note that a self-signed certificate usually belongs to a certificate +authority, that signs other certificates. + @item -This command will create /etc/tpasswd and will add user 'test' (you -will also be prompted for a password). Verifiers are stored by default -in the way libsrp expects. +To create a private key, run: @example -$ srptool --passwd /etc/tpasswd \ - --passwd-conf /etc/tpasswd.conf -u test +$ certtool --generate-privkey --outfile key.pem @end example @item -This command will check against a password. If the password matches -the one in /etc/tpasswd you will get an ok. +To generate a certificate using the private key, use the command: @example -$ srptool --passwd /etc/tpasswd \ - --passwd-conf /etc/tpasswd.conf --verify -u test +$ certtool --generate-certificate --load-privkey key.pem \ + --outfile cert.pem --load-ca-certificate ca-cert.pem \ + --load-ca-privkey ca-key.pem +@end example + +@item +To create a certificate request (needed when the certificate is issued by +another party), run: + +@example +$ certtool --generate-request --load-privkey key.pem \ + --outfile request.pem +@end example + +@item +To generate a certificate using the previous request, use the command: + +@example +$ certtool --generate-certificate --load-request request.pem \ + --outfile cert.pem \ + --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem +@end example + +@item +To view the certificate information, use: + +@example +$ certtool --certificate-info --infile cert.pem +@end example + +@item +To generate a @acronym{PKCS} #12 structure using the previous key and +certificate, use the command: + +@example +$ certtool --load-certificate cert.pem --load-privkey key.pem \ + --to-p12 --outder --outfile key.p12 +@end example + +@item +Proxy certificate can be used to delegate your credential to a +temporary, typically short-lived, certificate. To create one from the +previously created certificate, first create a temporary key and then +generate a proxy certificate for it, using the commands: + +@example +$ certtool --generate-privkey > proxy-key.pem +$ certtool --generate-proxy --load-ca-privkey key.pem \ + --load-privkey proxy-key.pem --load-certificate cert.pem \ + --outfile proxy-cert.pem +@end example + +@item +To create an empty Certificate Revocation List (CRL) do: + +@example +$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem --load-ca-certificate x509-ca.pem +@end example + +To create a CRL that contains some revoked certificates, place the +certificates in a file and use @code{--load-certificate} as follows: + +@example +$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem +@end example + +@item +To verify a Certificate Revocation List (CRL) do: + +@example +$ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem +@end example + +@end itemize + +Certtool's template file format: + +@itemize + +@item +Firstly create a file named 'cert.cfg' that contains the information +about the certificate. An example file is listed below. + +@item +Then execute: + +@example +$ certtool --generate-certificate cert.pem --load-privkey key.pem \ + --template cert.cfg \ + --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem @end example @end itemize +An example certtool template file: + +@example +# X.509 Certificate options +# +# DN options + +# The organization of the subject. +organization = "Koko inc." + +# The organizational unit of the subject. +unit = "sleeping dept." + +# The locality of the subject. +# locality = + +# The state of the certificate owner. +state = "Attiki" + +# The country of the subject. Two letter code. +country = GR + +# The common name of the certificate owner. +cn = "Cindy Lauper" + +# A user id of the certificate owner. +#uid = "clauper" + +# If the supported DN OIDs are not adequate you can set +# any OID here. +# For example set the X.520 Title and the X.520 Pseudonym +# by using OID and string pairs. +#dn_oid = "2.5.4.12" "Dr." "2.5.4.65" "jackal" + +# This is deprecated and should not be used in new +# certificates. +# pkcs9_email = "none@@none.org" + +# The serial number of the certificate +serial = 007 + +# In how many days, counting from today, this certificate will expire. +expiration_days = 700 + +# X.509 v3 extensions + +# A dnsname in case of a WWW server. +#dns_name = "www.none.org" + +# An IP address in case of a server. +#ip_address = "192.168.1.1" + +# An email in case of a person +email = "none@@none.org" + +# An URL that has CRLs (certificate revocation lists) +# available. Needed in CA certificates. +#crl_dist_points = "http://www.getcrl.crl/getcrl/" + +# Whether this is a CA certificate or not +#ca + +# Whether this certificate will be used for a TLS client +#tls_www_client + +# Whether this certificate will be used for a TLS server +#tls_www_server + +# Whether this certificate will be used to sign data (needed +# in TLS DHE ciphersuites). +signing_key + +# Whether this certificate will be used to encrypt data (needed +# in TLS RSA ciphersuites). Note that it is prefered to use different +# keys for encryption and signing. +#encryption_key + +# Whether this key will be used to sign other certificates. +#cert_signing_key + +# Whether this key will be used to sign CRLs. +#crl_signing_key + +# Whether this key will be used to sign code. +#code_signing_key + +# Whether this key will be used to sign OCSP data. +#ocsp_signing_key + +# Whether this key will be used for time stamping. +#time_stamping_key +@end example + @node Invoking gnutls-cli @section Invoking gnutls-cli @cindex gnutls-cli @@ -2614,6 +2894,70 @@ Usage: gnutls-cli [options] hostname --copyright prints the program's license @end verbatim +To connect to a server using PSK authentication, you may use something +like: + +@smallexample +$ gnutls-cli -p 5556 test.gnutls.org --pskusername jas --pskkey 9e32cf7786321a828ef7668f09fb35db --priority NORMAL:+PSK:-RSA:-DHE-RSA -d 4711 +@end smallexample + +@menu +* Example client PSK connection:: +@end menu + +@node Example client PSK connection +@subsection Example client PSK connection +@cindex PSK client + +If your server only supports the PSK ciphersuite, connecting to it +should be as simple as connecting to the server: + +@smallexample +$ ./gnutls-cli -p 5556 localhost +Resolving 'localhost'... +Connecting to '127.0.0.1:5556'... +- PSK client callback. PSK hint 'psk_identity_hint' +Enter PSK identity: psk_identity +Enter password: +- PSK authentication. PSK hint 'psk_identity_hint' +- Version: TLS1.1 +- Key Exchange: PSK +- Cipher: AES-128-CBC +- MAC: SHA1 +- Compression: NULL +- Handshake was completed + +- Simple Client Mode: +@end smallexample + +If the server supports several cipher suites, you may need to force it +to chose PSK by using a cipher priority parameter such as +@code{--priority NORMAL:+PSK:-RSA:-DHE-RSA:-DHE-PSK}. + +@cindex Netconf +Instead of using the Netconf-way to derive the PSK key from a +password, you can also give the PSK username and key directly on the +command line: + +@smallexample +$ ./gnutls-cli -p 5556 localhost --pskusername psk_identity --pskkey 88f3824b3e5659f52d00e959bacab954b6540344 +Resolving 'localhost'... +Connecting to '127.0.0.1:5556'... +- PSK authentication. PSK hint 'psk_identity_hint' +- Version: TLS1.1 +- Key Exchange: PSK +- Cipher: AES-128-CBC +- MAC: SHA1 +- Compression: NULL +- Handshake was completed + +- Simple Client Mode: +@end smallexample + +By keeping the @code{--pskusername} parameter and removing the +@code{--pskkey} parameter, it will query only for the password during +the handshake. + @node Invoking gnutls-cli-debug @section Invoking gnutls-cli-debug @cindex gnutls-cli-debug @@ -2889,309 +3233,111 @@ gnutls-serv --http \ --pskpasswd psk-passwd.txt @end example -@node Invoking certtool -@section Invoking certtool -@cindex certtool - -This is a program to generate @acronym{X.509} certificates, certificate -requests, CRLs and private keys. - -@verbatim -Certtool help -Usage: certtool [options] - -s, --generate-self-signed - Generate a self-signed certificate. - -c, --generate-certificate - Generate a signed certificate. - --generate-proxy Generate a proxy certificate. - --generate-crl Generate a CRL. - -u, --update-certificate - Update a signed certificate. - -p, --generate-privkey Generate a private key. - -q, --generate-request Generate a PKCS #10 certificate - request. - -e, --verify-chain Verify a PEM encoded certificate chain. - The last certificate in the chain must - be a self signed one. - --verify-crl Verify a CRL. - --generate-dh-params Generate PKCS #3 encoded Diffie Hellman - parameters. - --get-dh-params Get the included PKCS #3 encoded Diffie - Hellman parameters. - --load-privkey FILE Private key file to use. - --load-request FILE Certificate request file to use. - --load-certificate FILE - Certificate file to use. - --load-ca-privkey FILE Certificate authority's private key - file to use. - --load-ca-certificate FILE - Certificate authority's certificate - file to use. - --password PASSWORD Password to use. - -i, --certificate-info Print information on a certificate. - -l, --crl-info Print information on a CRL. - --p12-info Print information on a PKCS #12 - structure. - --p7-info Print information on a PKCS #7 - structure. - --smime-to-p7 Convert S/MIME to PKCS #7 structure. - -k, --key-info Print information on a private key. - --fix-key Regenerate the parameters in a private - key. - --to-p12 Generate a PKCS #12 structure. - -8, --pkcs8 Use PKCS #8 format for private keys. - --dsa Use DSA keys. - --hash STR Hash algorithm to use for signing - (MD5,SHA1,RMD160). - --export-ciphers Use weak encryption algorithms. - --inder Use DER format for input certificates - and private keys. - --outder Use DER format for output certificates - and private keys. - --bits BITS specify the number of bits for key - generation. - --outfile FILE Output file. - --infile FILE Input file. - --template FILE Template file to use for non - interactive operation. - -d, --debug LEVEL specify the debug level. Default is 1. - -h, --help shows this help text - -v, --version shows the program's version - --copyright shows the program's license -@end verbatim - -The program can be used interactively or non interactively by -specifying the @code{--template} command line option. See below for an -example of a template file. - -How to use certtool interactively: - -@itemize -@item -To generate parameters for Diffie Hellman key exchange, use the command: -@example -$ certtool --generate-dh-params --outfile dh.pem -@end example - -@item -To generate parameters for the RSA-EXPORT key exchange, use the command: -@example -$ certtool --generate-privkey --bits 512 --outfile rsa.pem -@end example - -@end itemize - -@itemize - -@item -To create a self signed certificate, use the command: -@example -$ certtool --generate-privkey --outfile ca-key.pem -$ certtool --generate-self-signed --load-privkey ca-key.pem \ - --outfile ca-cert.pem -@end example - -Note that a self-signed certificate usually belongs to a certificate -authority, that signs other certificates. +@menu +* Example server PSK connection:: +@end menu -@item -To create a private key, run: +@node Example server PSK connection +@subsection Example server PSK connection +@cindex PSK server -@example -$ certtool --generate-privkey --outfile key.pem -@end example +To set up a PSK server with @code{gnutls-serv} you need to create PSK +password file (@pxref{Invoking psktool}). In the example below, I +type @code{password} at the prompt. -@item -To generate a certificate using the private key, use the command: +@smallexample +$ ./psktool -u psk_identity -p psks.txt -n psk_identity_hint +Enter password: +Key stored to psks.txt +$ cat psks.txt +psk_identity:88f3824b3e5659f52d00e959bacab954b6540344 +$ +@end smallexample -@example -$ certtool --generate-certificate --load-privkey key.pem \ - --outfile cert.pem --load-ca-certificate ca-cert.pem \ - --load-ca-privkey ca-key.pem -@end example +After this, start the server pointing to the password file. We +disable DHE-PSK. -@item -To create a certificate request (needed when the certificate is issued by -another party), run: +@smallexample +$ ./gnutls-serv --pskpasswd psks.txt --pskhint psk_identity_hint --priority NORMAL:-DHE-PSK +Set static Diffie Hellman parameters, consider --dhparams. +Echo Server ready. Listening to port '5556'. +@end smallexample -@example -$ certtool --generate-request --load-privkey key.pem \ - --outfile request.pem -@end example +You can now connect to the server using a PSK client (@pxref{Example +client PSK connection}). -@item -To generate a certificate using the previous request, use the command: +@node Invoking psktool +@section Invoking psktool +@cindex psktool -@example -$ certtool --generate-certificate --load-request request.pem \ - --outfile cert.pem \ - --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem -@end example +This is a program to manage @acronym{PSK} username and keys. -@item -To view the certificate information, use: +@verbatim +PSKtool help +Usage : psktool [options] + -u, --username username + specify username. + -p, --passwd FILE specify a password file. + -n, --netconf-hint HINT + derive key from Netconf password, using + HINT as the psk_identity_hint. + -s, --keysize SIZE specify the key size in bytes. + -v, --version prints the program's version number + -h, --help shows this help text +@end verbatim -@example -$ certtool --certificate-info --infile cert.pem -@end example +Normally the file will generate random keys for the indicate username. +You may also derive PSK keys from passwords, using the algorithm +specified in @file{draft-ietf-netconf-tls-02.txt}. The algorithm +needs a PSK identity hint, which you specify using +@code{--netconf-hint}. To derive a PSK key from a password with an +empty PSK identity hint, using @code{--netconf-hint ""}. -@item -To generate a @acronym{PKCS} #12 structure using the previous key and -certificate, use the command: +@node Invoking srptool +@section Invoking srptool +@anchor{srptool} +@cindex srptool -@example -$ certtool --load-certificate cert.pem --load-privkey key.pem \ - --to-p12 --outder --outfile key.p12 -@end example +The @file{srptool} is a very simple program that emulates the programs +in the @emph{Stanford SRP libraries}. It is intended for use in +places where you don't expect @acronym{SRP} authentication to be the +used for system users. Traditionally @emph{libsrp} used two +files. One called 'tpasswd' which holds usernames and verifiers, and +'tpasswd.conf' which holds generators and primes. -@item -Proxy certificate can be used to delegate your credential to a -temporary, typically short-lived, certificate. To create one from the -previously created certificate, first create a temporary key and then -generate a proxy certificate for it, using the commands: +How to use srptool: -@example -$ certtool --generate-privkey > proxy-key.pem -$ certtool --generate-proxy --load-ca-privkey key.pem \ - --load-privkey proxy-key.pem --load-certificate cert.pem \ - --outfile proxy-cert.pem -@end example +@itemize @item -To create an empty Certificate Revocation List (CRL) do: - -@example -$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem --load-ca-certificate x509-ca.pem -@end example - -To create a CRL that contains some revoked certificates, place the -certificates in a file and use @code{--load-certificate} as follows: +To create tpasswd.conf which holds the g and n values for +@acronym{SRP} protocol (generator and a large prime), run: @example -$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem +$ srptool --create-conf /etc/tpasswd.conf @end example @item -To verify a Certificate Revocation List (CRL) do: +This command will create /etc/tpasswd and will add user 'test' (you +will also be prompted for a password). Verifiers are stored by default +in the way libsrp expects. @example -$ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem +$ srptool --passwd /etc/tpasswd \ + --passwd-conf /etc/tpasswd.conf -u test @end example -@end itemize - -Certtool's template file format: - -@itemize - @item -Firstly create a file named 'cert.cfg' that contains the information -about the certificate. An example file is listed below. - -@item -Then execute: +This command will check against a password. If the password matches +the one in /etc/tpasswd you will get an ok. @example -$ certtool --generate-certificate cert.pem --load-privkey key.pem \ - --template cert.cfg \ - --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem +$ srptool --passwd /etc/tpasswd \ + --passwd-conf /etc/tpasswd.conf --verify -u test @end example @end itemize -An example certtool template file: - -@example -# X.509 Certificate options -# -# DN options - -# The organization of the subject. -organization = "Koko inc." - -# The organizational unit of the subject. -unit = "sleeping dept." - -# The locality of the subject. -# locality = - -# The state of the certificate owner. -state = "Attiki" - -# The country of the subject. Two letter code. -country = GR - -# The common name of the certificate owner. -cn = "Cindy Lauper" - -# A user id of the certificate owner. -#uid = "clauper" - -# If the supported DN OIDs are not adequate you can set -# any OID here. -# For example set the X.520 Title and the X.520 Pseudonym -# by using OID and string pairs. -#dn_oid = "2.5.4.12" "Dr." "2.5.4.65" "jackal" - -# This is deprecated and should not be used in new -# certificates. -# pkcs9_email = "none@@none.org" - -# The serial number of the certificate -serial = 007 - -# In how many days, counting from today, this certificate will expire. -expiration_days = 700 - -# X.509 v3 extensions - -# A dnsname in case of a WWW server. -#dns_name = "www.none.org" - -# An IP address in case of a server. -#ip_address = "192.168.1.1" - -# An email in case of a person -email = "none@@none.org" - -# An URL that has CRLs (certificate revocation lists) -# available. Needed in CA certificates. -#crl_dist_points = "http://www.getcrl.crl/getcrl/" - -# Whether this is a CA certificate or not -#ca - -# Whether this certificate will be used for a TLS client -#tls_www_client - -# Whether this certificate will be used for a TLS server -#tls_www_server - -# Whether this certificate will be used to sign data (needed -# in TLS DHE ciphersuites). -signing_key - -# Whether this certificate will be used to encrypt data (needed -# in TLS RSA ciphersuites). Note that it is prefered to use different -# keys for encryption and signing. -#encryption_key - -# Whether this key will be used to sign other certificates. -#cert_signing_key - -# Whether this key will be used to sign CRLs. -#crl_signing_key - -# Whether this key will be used to sign code. -#code_signing_key - -# Whether this key will be used to sign OCSP data. -#ocsp_signing_key - -# Whether this key will be used for time stamping. -#time_stamping_key -@end example - @node Function reference @chapter Function Reference @cindex Function reference diff --git a/doc/protocol/draft-badra-tls-psk-new-mac-aes-gcm-02.txt b/doc/protocol/draft-badra-tls-psk-new-mac-aes-gcm-02.txt new file mode 100644 index 0000000000..91d2cb8ea4 --- /dev/null +++ b/doc/protocol/draft-badra-tls-psk-new-mac-aes-gcm-02.txt @@ -0,0 +1,485 @@ +TLS Working Group Mohamad Badra +Internet Draft LIMOS Laboratory +Intended status: Standards Track April 30, 2008 +Expires: October 2008 + + + + Pre-Shared Key Cipher Suites for Transport Layer Security (TLS) with + SHA-256/384 and AES Galois Counter Mode + draft-badra-tls-psk-new-mac-aes-gcm-02.txt + + +Status of this Memo + + By submitting this Internet-Draft, each author represents that any + applicable patent or other IPR claims of which he or she is aware + have been or will be disclosed, and any of which he or she becomes + aware will be disclosed, in accordance with Section 6 of BCP 79. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF), its areas, and its working groups. Note that + other groups may also distribute working documents as Internet- + Drafts. + + Internet-Drafts are draft documents valid for a maximum of six + months and may be updated, replaced, or obsoleted by other documents + at any time. It is inappropriate to use Internet-Drafts as + reference material or to cite them other than as "work in progress." + + The list of current Internet-Drafts can be accessed at + http://www.ietf.org/ietf/1id-abstracts.txt + + The list of Internet-Draft Shadow Directories can be accessed at + http://www.ietf.org/shadow.html + + This Internet-Draft will expire on October 30, 2008. + +Copyright Notice + + Copyright (C) The IETF Trust (2008). + +Abstract + + RFC 4279 and RFC 4785 describe pre-shared key cipher suites for + Transport Layer Security (TLS). However, all those cipher suites + use SHA-1 as their MAC algorithm. This document describes a set of + cipher suites for TLS/DTLS which uses stronger digest algorithms + + + + +Badra Expires October 30, 2008 [Page 1] + +Internet-Draft TLS PSK New MAC and AES-GCM April 2008 + + + (i.e., SHA-256 or SHA-384) and another which uses the Advanced + Encryption Standard (AES) in Galois Counter Mode (GCM). + +Table of Contents + + + 1. Introduction...................................................3 + 1.1. Conventions used in this document.........................3 + 2. PSK, DHE_PSK and RSA_PSK Key Exchange Algorithms with AES-GCM..3 + 3. PSK, DHE_PSK and RSA_PSK Key Exchange with SHA-256/384.........4 + 3.1. PSK Key Exchange Algorithm with SHA-256/384...............4 + 3.2. DHE_PSK Key Exchange Algorithm with SHA-256/384...........5 + 3.3. RSA_PSK Key Exchange Algorithm with SHA-256/384...........5 + 4. Security Considerations........................................5 + 5. IANA Considerations............................................6 + 6. Acknowledgments................................................6 + 7. References.....................................................6 + 7.1. Normative References......................................6 + 7.2. Informative References....................................7 + Author's Addresses................................................8 + Full Copyright Statement..........................................8 + Intellectual Property.............................................8 + Acknowledgment....................................................9 + + + + + + + + + + + + + + + + + + + + + + + + + + +Badra Expires October 30, 2008 [Page 2] + +Internet-Draft TLS PSK New MAC and AES-GCM April 2008 + + +1. Introduction + + TLS 1.2 [I-D.ietf-tls-rfc4346-bis], adds support for authenticated + encryption with additional data (AEAD) cipher modes [RFC5116]. This + document describes the use of Advanced Encryption Standard (AES) + [AES] in Galois Counter Mode (GCM) [GCM] (AES-GCM) with various pre- + shared key (PSK) key exchange mechanisms ([RFC4279] and [RFC4785]) + as a cipher suite for Transport Layer Security (TLS). + + This document also specifies PSK cipher suites for TLS which replace + SHA-1 by SHA-256 or SHA-384. RFC 4279 [RFC4279] and RFC 4785 + [RFC4785] describe PSK cipher suites for TLS. However, all of the + RFC 4279 and the RFC 4785 cipher suites use HMAC-SHA1 as their MAC + algorithm. Due to recent analytic work on SHA-1 [Wang05], the IETF + is gradually moving away from SHA-1 and towards stronger hash + algorithms. + + ECC based cipher suites with SHA-256/384 and AES-GCM are defined in + [I-D.ietf-tls-ecc-new-mac]; RSA, DSS and Diffie-Hellman based cipher + suites are specified in [I-D.ietf-tls-rsa-aes-gcm]. The reader is + expected to become familiar with these two memos prior to studying + this document. + +1.1. Conventions used in this document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + +2. PSK, DHE_PSK and RSA_PSK Key Exchange Algorithms with AES-GCM + + The following eight cipher suites use the new authenticated + encryption modes defined in TLS 1.2 with AES in Galois Counter Mode + (GCM) [GCM]. The cipher suites with DHE_PSK key exchange algorithm + (TLS_DHE_PSK_WITH_AES_128_GCM_SHA256 and + TLS_DHE_PSK_WITH_AES_128_GCM_SHA348) provide Perfect Forward Secrecy + (PFS). + + CipherSuite TLS_PSK_WITH_AES_128_GCM_SHA256 = {0xXX,0xXX}; + CipherSuite TLS_PSK_WITH_AES_258_GCM_SHA256 = {0xXX,0xXX}; + CipherSuite TLS_PSK_WITH_AES_128_GCM_SHA384 = {0xXX,0xXX}; + CipherSuite TLS_PSK_WITH_AES_256_GCM_SHA384 = {0xXX,0xXX}; + CipherSuite TLS_DHE_PSK_WITH_AES_128_GCM_SHA256 = {0xXX,0xXX}; + CipherSuite TLS_DHE_PSK_WITH_AES_256_GCM_SHA384 = {0xXX,0xXX}; + CipherSuite TLS_RSA_PSK_WITH_AES_128_GCM_SHA256 = {0xXX,0xXX}; + CipherSuite TLS_RSA_PSK_WITH_AES_256_GCM_SHA384 = {0xXX,0xXX}; + + + +Badra Expires October 30, 2008 [Page 3] + +Internet-Draft TLS PSK New MAC and AES-GCM April 2008 + + + These cipher suites use authenticated encryption with additional + data (AEAD) algorithms AEAD_AES_128_GCM and AEAD_AES_256_GCM + described in RFC 5116. GCM is used as described in [I-D.ietf-tls- + rsa-aes-gcm]. + + The PSK, DHE_PSK and RSA_PSK key exchanges are performed as defined + in [RFC4279]. + + The PRF algorithms SHALL be as follows: + + For cipher suites ending with _SHA256, the PRF is the TLS PRF + [I-D.ietf-tls-rfc4346-bis] with SHA-256 as the hash function. + + For cipher suites ending with _SHA384, the PRF is the TLS PRF + [I-D.ietf-tls-rfc4346-bis] with SHA-384 as the hash function. + + Implementations MUST send TLS Alert bad_record_mac for all types of + failures encountered in processing the AES-GCM algorithm. + +3. PSK, DHE_PSK and RSA_PSK Key Exchange with SHA-256/384 + + The cipher suites described in this section use AES [AES] in CBC + [CBC] mode with an HMAC-based MAC. + +3.1. PSK Key Exchange Algorithm with SHA-256/384 + + CipherSuite TLS_PSK_WITH_AES_128_CBC_SHA256 = {0xXX,0xXX}; + CipherSuite TLS_PSK_WITH_AES_256_CBC_SHA256 = {0xXX,0xXX}; + CipherSuite TLS_PSK_WITH_AES_128_CBC_SHA384 = {0xXX,0xXX}; + CipherSuite TLS_PSK_WITH_AES_256_CBC_SHA384 = {0xXX,0xXX}; + CipherSuite TLS_PSK_WITH_NULL_SHA256 = {0xXX,0xXX}; + CipherSuite TLS_PSK_WITH_NULL_SHA384 = {0xXX,0xXX}; + + The above six cipher suites are the same as the corresponding cipher + suites in RFC 4279 and RFC 4785 (with names ending in "_SHA" in + place of "_SHA256" or "_SHA384"), except for the hash and PRF + algorithms, which are SHA-256 and SHA-384 [SHS] as follows. + + CipherSuite MAC PRF + ------------ --- --- + TLS_PSK_WITH_AES_128_CBC_SHA256 HMAC-SHA-256 P_SHA-256 + TLS_PSK_WITH_AES_128_CBC_SHA384 HMAC-SHA-384 P_SHA-384 + TLS_PSK_WITH_AES_256_CBC_SHA256 HMAC-SHA-256 P_SHA-256 + TLS_PSK_WITH_AES_256_CBC_SHA384 HMAC-SHA-384 P_SHA-384 + TLS_PSK_WITH_NULL_SHA256 HMAC-SHA-256 P_SHA-256 + TLS_PSK_WITH_NULL_SHA384 HMAC-SHA-384 P_SHA-384 + + + +Badra Expires October 30, 2008 [Page 4] + +Internet-Draft TLS PSK New MAC and AES-GCM April 2008 + + +3.2. DHE_PSK Key Exchange Algorithm with SHA-256/384 + + CipherSuite TLS_DHE_PSK_WITH_AES_128_CBC_SHA256 = {0xXX,0xXX}; + CipherSuite TLS_DHE_PSK_WITH_AES_128_CBC_SHA384 = {0xXX,0xXX}; + CipherSuite TLS_DHE_PSK_WITH_AES_256_CBC_SHA256 = {0xXX,0xXX}; + CipherSuite TLS_DHE_PSK_WITH_AES_256_CBC_SHA384 = {0xXX,0xXX}; + CipherSuite TLS_DHE_PSK_WITH_NULL_SHA256 = {0xXX,0xXX}; + CipherSuite TLS_DHE_PSK_WITH_NULL_SHA384 = {0xXX,0xXX}; + + The above six cipher suites are the same as the corresponding cipher + suites in RFC 4279 and RFC 4785 (with names ending in "_SHA" in + place of "_SHA256" or "_SHA384"), except for the hash and PRF + algorithms, which are SHA-256 and SHA-384 [SHS] as follows. + + CipherSuite MAC PRF + ------------ --- --- + TLS_DHE_PSK_WITH_AES_128_CBC_SHA256 HMAC-SHA-256 P_SHA-256 + TLS_DHE_PSK_WITH_AES_128_CBC_SHA384 HMAC-SHA-384 P_SHA-384 + TLS_DHE_PSK_WITH_AES_256_CBC_SHA256 HMAC-SHA-256 P_SHA-256 + TLS_DHE_PSK_WITH_AES_256_CBC_SHA384 HMAC-SHA-384 P_SHA-384 + +3.3. RSA_PSK Key Exchange Algorithm with SHA-256/384 + + CipherSuite TLS_RSA_PSK_WITH_AES_128_CBC_SHA256 = {0xXX,0xXX}; + CipherSuite TLS_RSA_PSK_WITH_AES_128_CBC_SHA384 = {0xXX,0xXX}; + CipherSuite TLS_RSA_PSK_WITH_AES_256_CBC_SHA256 = {0xXX,0xXX}; + CipherSuite TLS_RSA_PSK_WITH_AES_256_CBC_SHA384 = {0xXX,0xXX}; + + The above four cipher suites are the same as the corresponding + cipher suites in RFC 4279 and RFC 4785 (with names ending in "_SHA" + in place of "_SHA256" or "_SHA384"), except for the hash and PRF + algorithms, which are SHA-256 and SHA-384 [SHS] as follows. + + CipherSuite MAC PRF + ------------ --- --- + TLS_RSA_PSK_WITH_AES_128_CBC_SHA256 HMAC-SHA-256 P_SHA-256 + TLS_RSA_PSK_WITH_AES_128_CBC_SHA384 HMAC-SHA-384 P_SHA-384 + TLS_RSA_PSK_WITH_AES_256_CBC_SHA256 HMAC-SHA-256 P_SHA-256 + TLS_RSA_PSK_WITH_AES_256_CBC_SHA384 HMAC-SHA-384 P_SHA-384 + +4. Security Considerations + + The security considerations in RFC 4279, RFC 4758, and [I-D.ietf- + tls-rsa-aes-gcm] apply to this document as well. In addition, as + described in [I-D.ietf-tls-rsa-aes-gcm], these cipher suites may + only be used with TLS 1.2 or greater. + + + +Badra Expires October 30, 2008 [Page 5] + +Internet-Draft TLS PSK New MAC and AES-GCM April 2008 + + +5. IANA Considerations + + IANA has assigned the following values for the cipher suites defined + in this document: + + CipherSuite TLS_PSK_WITH_AES_128_GCM_SHA256 = {0xXX,0xXX}; + CipherSuite TLS_PSK_WITH_AES_258_GCM_SHA256 = {0xXX,0xXX}; + CipherSuite TLS_PSK_WITH_AES_128_GCM_SHA384 = {0xXX,0xXX}; + CipherSuite TLS_PSK_WITH_AES_256_GCM_SHA384 = {0xXX,0xXX}; + CipherSuite TLS_DHE_PSK_WITH_AES_128_GCM_SHA256 = {0xXX,0xXX}; + CipherSuite TLS_DHE_PSK_WITH_AES_256_GCM_SHA384 = {0xXX,0xXX}; + CipherSuite TLS_RSA_PSK_WITH_AES_128_GCM_SHA256 = {0xXX,0xXX}; + CipherSuite TLS_RSA_PSK_WITH_AES_256_GCM_SHA384 = {0xXX,0xXX}; + CipherSuite TLS_PSK_WITH_AES_128_CBC_SHA256 = {0xXX,0xXX}; + CipherSuite TLS_PSK_WITH_AES_256_CBC_SHA256 = {0xXX,0xXX}; + CipherSuite TLS_PSK_WITH_AES_128_CBC_SHA384 = {0xXX,0xXX}; + CipherSuite TLS_PSK_WITH_AES_256_CBC_SHA384 = {0xXX,0xXX}; + CipherSuite TLS_PSK_WITH_NULL_SHA256 = {0xXX,0xXX}; + CipherSuite TLS_PSK_WITH_NULL_SHA384 = {0xXX,0xXX}; + CipherSuite TLS_DHE_PSK_WITH_AES_128_CBC_SHA256 = {0xXX,0xXX}; + CipherSuite TLS_DHE_PSK_WITH_AES_128_CBC_SHA384 = {0xXX,0xXX}; + CipherSuite TLS_DHE_PSK_WITH_AES_256_CBC_SHA256 = {0xXX,0xXX}; + CipherSuite TLS_DHE_PSK_WITH_AES_256_CBC_SHA384 = {0xXX,0xXX}; + CipherSuite TLS_DHE_PSK_WITH_NULL_SHA256 = {0xXX,0xXX}; + CipherSuite TLS_DHE_PSK_WITH_NULL_SHA384 = {0xXX,0xXX}; + CipherSuite TLS_RSA_PSK_WITH_AES_128_CBC_SHA256 = {0xXX,0xXX}; + CipherSuite TLS_RSA_PSK_WITH_AES_128_CBC_SHA384 = {0xXX,0xXX}; + CipherSuite TLS_RSA_PSK_WITH_AES_256_CBC_SHA256 = {0xXX,0xXX}; + CipherSuite TLS_RSA_PSK_WITH_AES_256_CBC_SHA384 = {0xXX,0xXX}; + +6. Acknowledgments + + This draft borrows heavily from [I-D.ietf-tls-ecc-new-mac] and [I- + D.ietf-tls-rsa-aes-gcm]. + +7. References + +7.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [I-D.ietf-tls-rfc4346-bis] + Dierks, T. and E. Rescorla, "The Transport Layer Security + (TLS) Protocol Version 1.2", draft-ietf-tls-rfc4346-bis- + 10, work in progress, March 2008. + + + +Badra Expires October 30, 2008 [Page 6] + +Internet-Draft TLS PSK New MAC and AES-GCM April 2008 + + + [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated + Encryption", RFC 5116, January 2008. + + [RFC4279] Eronen, P. and H. Tschofenig, "Pre-Shared Key Ciphersuites + for Transport Layer Security (TLS)", RFC 4279, December + 2005. + + [RFC4785] Blumenthal, U., Goel, P., "Pre-Shared Key (PSK) + Ciphersuites with NULL Encryption for Transport Layer + Security (TLS)", RFC 4785, January 2007. + + [AES] National Institute of Standards and Technology, + "Specification for the Advanced Encryption Standard + (AES)", FIPS 197, November 2001. + + [SHS] National Institute of Standards and Technology, "Secure + Hash Standard", FIPS 180-2, August 2002. + + [CBC] National Institute of Standards and Technology, + "Recommendation for Block Cipher Modes of Operation - + Methods and Techniques", SP 800-38A, December 2001. + + [GCM] National Institute of Standards and Technology, + "Recommendation for Block Cipher Modes of Operation: + Galois;/Counter Mode (GCM) for Confidentiality and + Authentication", SP 800-38D, November 2007. + +7.2. Informative References + + [Wang05] Wang, X., Yin, Y., and H. Yu, "Finding Collisions in the + Full SHA-1", CRYPTO 2005, August 2005. + + [I-D.ietf-tls-ecc-new-mac] + Rescorla, E., "TLS Elliptic Curve Cipher Suites with SHA- + 256/384 and AES Galois Counter Mode", draft-ietf-tls-ecc- + new-mac-06 (work in progress), April 2008. + + [I-D.ietf-tls-rsa-aes-gcm] + Salowey, J., A. Choudhury, and C. McGrew, "RSA based AES- + GCM Cipher Suites for TLS", draft-ietf-tls-rsa-aes-gcm-03 + (work in progress), April 2008. + + + + + + + + +Badra Expires October 30, 2008 [Page 7] + +Internet-Draft TLS PSK New MAC and AES-GCM April 2008 + + +Author's Addresses + + Mohamad Badra + LIMOS Laboratory - UMR6158, CNRS + France + + Email: badra@isima.fr + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2008). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on + an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE + REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE + IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL + WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY + WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE + ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS + FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed + to pertain to the implementation or use of the technology described + in this document or the extent to which any license under such + rights might or might not be available; nor does it represent that + it has made any independent effort to identify any such rights. + Information on the procedures with respect to rights in RFC + documents can be found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use + of such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository + at http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + + +Badra Expires October 30, 2008 [Page 8] + +Internet-Draft TLS PSK New MAC and AES-GCM April 2008 + + + this standard. Please address the information to the IETF at ietf- + ipr@ietf.org. + +Acknowledgment + + Funding for the RFC Editor function is provided by the IETF + Administrative Support Activity (IASA). + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Badra Expires October 30, 2008 [Page 9] + diff --git a/doc/protocol/draft-ietf-netconf-tls-02.txt b/doc/protocol/draft-ietf-netconf-tls-02.txt new file mode 100644 index 0000000000..2c37fa6a81 --- /dev/null +++ b/doc/protocol/draft-ietf-netconf-tls-02.txt @@ -0,0 +1,809 @@ +NETCONF Working Group Mohamad Badra +Internet Draft LIMOS Laboratory +Intended status: Standards Track May 27, 2008 +Expires: November 2008 + + + + NETCONF over Transport Layer Security (TLS) + draft-ietf-netconf-tls-02.txt + + +Status of this Memo + + By submitting this Internet-Draft, each author represents that any + applicable patent or other IPR claims of which he or she is aware + have been or will be disclosed, and any of which he or she becomes + aware will be disclosed, in accordance with Section 6 of BCP 79. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF), its areas, and its working groups. Note that + other groups may also distribute working documents as Internet- + Drafts. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + The list of current Internet-Drafts can be accessed at + http://www.ietf.org/ietf/1id-abstracts.txt + + The list of Internet-Draft Shadow Directories can be accessed at + http://www.ietf.org/shadow.html + + This Internet-Draft will expire on November 27, 2008. + +Copyright Notice + + Copyright (C) The IETF Trust (2008). + +Abstract + + The Network Configuration Protocol (NETCONF) provides mechanisms to + install, manipulate, and delete the configuration of network devices. + This document describes how to use the Transport Layer Protocol (TLS) + to secure NETCONF exchanges. + + + + + +Badra Expires November 27, 2008 [Page 1] + +Internet-Draft NETCONF over TLS May 2008 + + +Table of Contents + + + 1. Introduction...................................................3 + 1.1. Conventions used in this document.........................3 + 2. NETCONF over TLS...............................................3 + 2.1. Connection Initiation.....................................3 + 2.2. Connection Closure........................................4 + 3. Endpoint Authentication and Identification.....................4 + 3.1. Server Identity...........................................5 + 3.2. Client Identity...........................................6 + 3.3. Password-Based Authentication.............................6 + 4. Cipher Suite Requirements......................................7 + 5. Security Considerations........................................7 + 6. IANA Considerations............................................7 + 7. Acknowledgments................................................8 + A. Appendix - Test Vectors for the PSK Derivation Function........9 + B. Appendix - Enabling Third Party Authentication using Passwords10 + B.1. Working Group discussion at the 71st IETF meeting........12 + Normative References.............................................13 + Authors' Addresses...............................................14 + Intellectual Property and Copyright Statements...................14 + + + + + + + + + + + + + + + + + + + + + + + + + + + +Badra Expires November 27, 2008 [Page 2] + +Internet-Draft NETCONF over TLS May 2008 + + +1. Introduction + The NETCONF protocol [RFC4741] defines a simple mechanism through + which a network device can be managed. NETCONF is connection- + oriented, requiring a persistent connection between peers. This + connection must provide reliable, sequenced data delivery, integrity + and confidentiality and peers authentication. This document + describes how to use TLS [RFC4346] to secure NETCONF connections. + + Throughout this document, the terms "client" and "server" are used to + refer to the two ends of the TLS connection. The client actively + opens the TLS connection, and the server passively listens for the + incoming TLS connection. The terms "manager" and "agent" are used to + refer to the two ends of the NETCONF protocol session. The manager + issues NETCONF remote procedure call (RPC) commands, and the agent + replies to those commands. When NETCONF is run over TLS using the + mapping defined in this document, the client is always the manager, + and the server is always the agent. + +1.1. Conventions used in this document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC-2119 [RFC2119]. + +2. NETCONF over TLS + + Since TLS is application protocol-independent, NETCONF can operate on + top of the TLS protocol transparently. This document defines how + NETCONF can be used within a Transport Layer Security (TLS) session. + +2.1. Connection Initiation + + The peer acting as the NETCONF manager MUST also act as the TLS + client. It MUST connect to the server that passively listens for the + incoming TLS connection on the IANA-to-be-assigned TCP port <TBA>. + It MUST therefore send the TLS ClientHello to begin the TLS + handshake. Once the TLS handshake has been finished, the client and + the server MAY then send their NETCONF exchanges. In particular, the + client will send complete XML documents to the server containing + <rpc> elements, and the server will respond with complete XML + documents containing <rpc-reply> elements. The client MAY indicate + interest in receiving event notifications from a NETCONF server by + creating a subscription to receive event notifications [I-D.ietf-- + netconf-notification], in which the NETCONF server replies to + indicate whether the subscription request was successful and, if it + was successful, begins sending the event notifications to the NETCONF + client as the events occur within the system. All these elements are + + +Badra Expires November 27, 2008 [Page 3] + +Internet-Draft NETCONF over TLS May 2008 + + + encapsulated into TLS records of type "application data". These + records are protected using the TLS material keys. + + Current NETCONF messages don't include a message's length. This + document uses consequently the same delimiter sequence defined in + [RFC4742] and therefore the special character sequence, ]]>]]>, to + delimit XML documents. + +2.2. Connection Closure + + Either NETCONF peer MAY stop the NETCONF connection at any time and + therefore notify the other NETCONF peer that no more data on this + channel will be sent and that any data received after a closure + request will be ignored. This MAY happen when no data is received + from a connection for a long time, where the application decides what + "long" means. + + TLS has the ability for secure connection closure using the Alert + protocol. When the NETCONF peer closes the NETCONF connection, it + MUST send a TLS close_notify alert before closing the TCP connection. + Any data received after a closure alert is ignored. + + Unless a fatal error has occurred, each party is required to send a + close_notify alert before closing the write side of the connection + [RFC4346]. The other party MUST respond with a close_notify alert of + its own and close down the connection immediately, discarding any + pending writes. It is not required for the initiator of the close to + wait for the responding close_notify alert before closing the read + side of the connection. + +3. Endpoint Authentication and Identification + + NETCONF requires that its transport provide mutual authentication of + client and server, so cipher suites that are anonymous or which only + authenticate the server to the client MUST NOT be used with NETCONF. + This document specifies how to use TLS with endpoint authentication, + which can be based on either preshared keys [RFC4279] or public key + certificates [RFC4346]. Some cipher suites (e.g. + TLS_RSA_PSK_WITH_AES_128_CBC_SHA) use both. Section 3.1 describes + how the client authenticates the server if public key certificates + are provided by the server, section 3.2 describes how the server + authenticates the client if public key certificates are provided by + the client, and section 3.3 describes how the client and server + mutually authenticate one another using a password. + + + + + +Badra Expires November 27, 2008 [Page 4] + +Internet-Draft NETCONF over TLS May 2008 + + +3.1. Server Identity + + During the TLS negotiation, the client MUST carefully examine the + certificate presented by the server to determine if it meets their + expectations. Particularly, the client MUST check its understanding + of the server hostname against the server's identity as presented in + the server Certificate message, in order to prevent man-in-the-middle + attacks. + + Matching is performed according to these rules [RFC4642]: + + - The client MUST use the server hostname it used to open the + connection (or the hostname specified in TLS "server_name" + extension [RFC4366]) as the value to compare against the server + name as expressed in the server certificate. The client MUST + NOT use any form of the server hostname derived from an + insecure remote source (e.g., insecure DNS lookup). CNAME + canonicalization is not done. + + - If a subjectAltName extension of type dNSName is present in the + certificate, it MUST be used as the source of the server's + identity. + + - Matching is case-insensitive. + + - A "*" wildcard character MAY be used as the left-most name + component in the certificate. For example, *.example.com would + match a.example.com, foo.example.com, etc., but would not match + example.com. + + - If the certificate contains multiple names (e.g., more than one + dNSName field), then a match with any one of the fields is + considered acceptable. + + If the match fails, the client MUST either ask for explicit user + confirmation or terminate the connection and indicate the server's + identity is suspect. + + Additionally, clients MUST verify the binding between the identity of + the servers to which they connect and the public keys presented by + those servers. Clients SHOULD implement the algorithm in Section 6 + of [RFC5280] for general certificate validation, but MAY supplement + that algorithm with other validation methods that achieve equivalent + levels of verification (such as comparing the server certificate + against a local store of already-verified certificates and identity + bindings). + + + +Badra Expires November 27, 2008 [Page 5] + +Internet-Draft NETCONF over TLS May 2008 + + + If the client has external information as to the expected identity of + the server, the hostname check MAY be omitted. + +3.2. Client Identity + + Typically, the server has no external knowledge of what the client's + identity ought to be and so checks (other than that the client has a + certificate chain rooted in an appropriate CA) are not possible. If + a server has such knowledge (typically from some source external to + NETCONF or TLS) it MUST check the identity as described above. + +3.3. Password-Based Authentication + + [RFC4279] supports authentication based on pre-shared keys (PSKs). + These pre-shared keys are symmetric keys, shared in advance among the + communicating parties. + + The PSK can be generated in many ways and its length is variable. + Implementation of this document MAY rely on [RFC4279] to enable + password based user authentication. In this case, the password is + used to generate the PSK. It is RECOMMENDED that implementations + that allow the administrator to manually configure the password also + provide functionality for generating a new random password, taking + [RFC4086] into account. + + This document generates the PSK from the password as follow: + + PSK = SHA-1(SHA-1(psk_identity + "Key Pad for Netconf" + password) + + psk_identity_hint) + + Where + means concatenation. + + The label "Key Pad for Netconf" is an ASCII string. + + The psk_identity_hint is initially defined in section 5.1 of + [RFC4279]. The psk_identity_hint can do double duty and also provide + a form of server authentication in the case where the user has the + same password on a number of NETCONF servers. If a hint is provided, + the psk_identity_hint is encoded in the same way as in [RFC4279] and + should be a string representation of the name of the server + recognizable to the administrator or his software. In the case where + the user types a server name to connect to, it should be that string. + If the string the user enters differs from the one returned as + psk_identity_hint, the software could display the server's name and + ask the user to confirm. For automated scripts, the names could be + expected to match. It is highly recommended that implementations set + + + +Badra Expires November 27, 2008 [Page 6] + +Internet-Draft NETCONF over TLS May 2008 + + + the psk_identity_hint to the DNS name of the NETCONF server (i.e., + the TLS server). + + It is RECOMMENDED that users choose different passwords for the + different servers they manage. + + Note 1: The NETCONF over TLS implementation need not store the + password in clear text, but rather can store the value of the + inner SHA-1 (SHA-1(SHA-1(password + psk_identity + "Key Pad for + Netconf") + psk_identity_hint)), which could not be used as a + password equivalent for applications other than NETCONF. Deriving + the PSK from a password is not secure. This construction is used + because it is anticipated that people will do it anyway. + + Note 2: [RFC4279] defines some conformance requirements for the + PSK, for the PSK identity encoding and for the identity hint. The + same requirements apply here as well; in particular on the + password. Moreover, the management interface by which the + password is provided MUST accept ASCII strings of at least 64 + octets and MUST NOT add a null terminator before using them as + shared secrets. It MUST also accept a HEX encoding of the + password. The management interface MAY accept other encodings if + the algorithm for translating the encoding to a binary string is + specified. + +4. Cipher Suite Requirements + + A compliant implementation of the protocol specified in this document + MUST implement the cipher suite TLS_DHE_PSK_WITH_AES_128_CBC_SHA and + MAY implement any TLS cipher suite that provides mutual + authentication. + +5. Security Considerations + + The security considerations described throughout [RFC4346] and + [RFC4279] apply here as well. + + As with all schemes involving shared keys and passwords, special care + should be taken to protect the shared values and passwords as well as + to limit their exposure over time. Alternatively, using certificates + would provide better protection. + +6. IANA Considerations + + IANA is requested to assign a TCP port number that will be the + default port for NETCONF over TLS sessions as defined in this + document. + + +Badra Expires November 27, 2008 [Page 7] + +Internet-Draft NETCONF over TLS May 2008 + + + IANA has assigned port <TBA> for this purpose. + +7. Acknowledgments + + A significant amount of the text in Section 3.1 was lifted from + [RFC4642]. + + The author would like to acknowledge David Harrington, Miao Fuyou, + Eric Rescorla, Juergen Schoenwaelder, Simon Josefsson, Olivier + Coupelon and the NETCONF mailing list members for their comments on + the document. The author appreciates also Bert Wijnen, Mehmet Ersue + and Dan Romascanu for their efforts on issues resolving discussion, + and Charlie Kaufman for the thorough review of this document and for + the helpful comments on the password-based authentication. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Badra Expires November 27, 2008 [Page 8] + +Internet-Draft NETCONF over TLS May 2008 + + +A. Appendix - Test Vectors for the PSK Derivation Function + + The test vectors for the PSK derivation function in this document + have been cross-verified by two independent implementations. An + implementation that concurs with the results provided in this + document should be interoperable with other similar implementations. + + password = password + psk_identity = psk_identity + psk_identity_hint = psk_identity_hint + + The inner SHA-1 value (in hex): + + inner := SHA-1(password + psk_identity + "Key Pad for Netconf") + == SHA-1("psk_identityKey Pad for Netconfpassword") + => 6d6eeb6a b8d0466b 45245d07 47d86726 b41b868c + + The outer SHA-1 value (in hex): + + outer := SHA-1(inner + psk_identity_hint) + => 88f3824b 3e5659f5 2d00e959 bacab954 b6540344 + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Badra Expires November 27, 2008 [Page 9] + +Internet-Draft NETCONF over TLS May 2008 + + +B. Appendix - Enabling Third Party Authentication using Passwords + + During the 71st IETF meeting, several proposals have been proposed to + enable third party authentication that could be used in combination + with existing user authentication databases such as RADIUS. They are + listed below. More details on those proposals may be found at + https://www3.ietf.org/proceedings/08mar/slides/netconf-1/netconf- + 1.htm and + http://www.psg.com/lists/netconf/netconf.2008/msg00125.html. + + We summarize them as following: + + 1. Defining <user-login> RPC: + -------------------------- + + This option relies on JUNOS mechanism to enable an authentication + function via third parties. It consists of establishing a TLS with + no manager authentication, leaving the <request-login> RPC as the + only valid RPC. Anything else is an error. + + Once the TLS session is established, the agent MUST authenticate + the manager by emitting the following <rpc> tag element: + + <rpc-reply message-id="101" + xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> + <challenge>Password:</challenge> + </rpc-reply> + + In which the manager MUST reply with the following: + + <rpc> + <request-login> + <challenge-response>password</challenge-response> + </request-login> + </rpc> + + The rules to handle this were pretty simple: + + - The <request-login> RPC could only be performed if the session + wasn't authenticated. + + - No other RPCs could be performed if the session wasn't + authenticated. + + - The transport protocol can authenticate the session + (internally). + + + +Badra Expires November 27, 2008 [Page 10] + +Internet-Draft NETCONF over TLS May 2008 + + + + + Pros and cons: + + o is simple to do. But + + o might raise questions from the security ADs; NETCONF assumes + the authentication is part of the transport not NETCONF. + + o only works for plaintext passwords (SASL PLAIN). + + 2. Enhancing TLS: + -------------- + + The second option consists of extending TLS so the manager + authentication becomes part of TLS. This extension, detailed in + http://tools.ietf.org/id/draft-badra-tls-password-ext-01.txt, + defines a new extension and a new TLS message to the TLS protocol + to enable TLS client authentication using passwords. The extension + is used to convey the manager login, whereas the new message is + defined and sent by the manager to prove its knowledge of the + password. + + Steps during the TLS negotiation: + + - The manager adds such an extension to its TLS ClientHello. + + - If the agent agrees on using this extension, it will notify + the manager and replies with its certificate and/or its + authenticated public key. + + - The manager generates a premaster secret and encrypts it + using the agent public key. + + - The manager then computes the session key using the premaster + secret and encrypts, among others, its password with the + computed key. + + - The agent decrypts the premaster secret and computes the same + key to decrypt the password. + + - The agent checks with a database (or AAA infrastructures) to + verify the password and then to authenticate the manager. + + Pros and cons + + o is simple to do. But + + +Badra Expires November 27, 2008 [Page 11] + +Internet-Draft NETCONF over TLS May 2008 + + + o It is indeed not easy to convince TLS WG to add password + authentication extension to TLS. + + 3. Running BEEP over TLS: + ---------------------- + + It looks complex for a solution, requires that all implementations + do actually support BEEP. + + 4. Extending NETCONF with a message to start TLS: + ---------------------------------------------- + + This option consists of extending NETCONF with a new message to + start the TLS negotiation and to perform an authentication + mechanism based on RFC4422 (SASL) or on any similar protocol. + + Pros and cons + + o simple to do. But + + o might raise questions from the security ADs; NETCONF assumes + the authentication is part of the transport not NETCONF. + Moreover, it adds complexity related to the use of SASL + PLAIN. + + 5. Enable SSH (RFC4742 and TLS (as defined through this document: + -------------------------------------------------------------- + + Since SSH already defines a password-based authentication and + because this protocol MUST be implemented as a security protocol + for NETCONF, users can rely on SSH for password authentication, and + on TLS for authentication using PSK or certificates. This means the + agent SHOULD passively listen for the incoming SSH (respectively + TLS) connection on port 830 (respectively port <TBA-by-IANA>). + + Pros and cons + + o simple to do. + + o already specified by RFC4742 and by the current document. + +B.1. Working Group discussion at the 71st IETF meeting + + Some of the options have been found as not practical in the WG + session during 71st meeting. + + Options #2 and #3 have not been supported in the WG session. + + +Badra Expires November 27, 2008 [Page 12] + +Internet-Draft NETCONF over TLS May 2008 + + + Option #1 and # 4 seems to be against the security design for + NETCONF. Whether #5 or other options can be accepted by the WG + members needs to be discussed on the mailing list. + +Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC5280] Cooper, D., Santesson, S., Farrell, S., Boeyen, S., + Housley, R., and W. Polk, "Internet X.509 Public Key + Infrastructure Certificate and Certificate Revocation List + (CRL) Profile", RFC 5280, May 2008. + + [RFC4086] Eastlake, D., 3rd, Schiller, J., and S. Crocker, + "Randomness Requirements for Security", BCP 106, RFC 4086, + June 2005. + + [RFC4279] Eronen, P. and H. Tschofenig., "Pre-Shared Key Ciphersuites + for Transport Layer Security (TLS)", RFC 4279, December + 2005. + + [RFC4346] Dierks, T. and E. Rescorla, "The Transport Layer Security + (TLS) Protocol 1.1", RFC 4346, April 2006. + + [RFC4366] Blake-Wilson, S., Nystrom, M., Hopwood, D., Mikkelsen, J., + and T. Wright, "Transport Layer Security (TLS) Extensions", + RFC 4366, April 2006. + + [RFC4642] Murchison, K., Vinocur, J., Newman, C., "Using Transport + Layer Security (TLS) with Network News Transfer Protocol + (NNTP)", RFC 4642, October 2006 + + [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741, + December 2006. + + [RFC4742] Wasserman, M. and T. Goddard, "Using the NETCONF + Configuration Protocol over Secure Shell (SSH)", RFC 4742, + December 2006. + + [I-D.ietf-netconf-notification] + Chisholm, S. and H. Trevino, "NETCONF Event Notifications", + draft-ietf-netconf-notification-12.txt, (work in progress), + February 2008. + + + + + +Badra Expires November 27, 2008 [Page 13] + +Internet-Draft NETCONF over TLS May 2008 + + +Authors' Addresses + + Mohamad Badra + LIMOS Laboratory - UMR6158, CNRS + France + + Email: badra@isima.fr + +Contributors + + Ibrahim Hajjeh + INEOVATION + France + + Email: hajjeh@ineovation.com + +Intellectual Property Statement + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + +Disclaimer of Validity + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + + +Badra Expires November 27, 2008 [Page 14] + +Internet-Draft NETCONF over TLS May 2008 + + + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Copyright Statement + + Copyright (C) The IETF Trust (2008). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + +Acknowledgment + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Badra Expires November 27, 2008 [Page 15] + diff --git a/doc/protocol/draft-ietf-tls-ecc-new-mac-06.txt b/doc/protocol/draft-ietf-tls-ecc-new-mac-06.txt new file mode 100644 index 0000000000..2ac8fcaee7 --- /dev/null +++ b/doc/protocol/draft-ietf-tls-ecc-new-mac-06.txt @@ -0,0 +1,392 @@ + + + +Network Working Group E. Rescorla +Internet-Draft RTFM, Inc. +Intended status: Informational April 29, 2008 +Expires: October 31, 2008 + + +TLS Elliptic Curve Cipher Suites with SHA-256/384 and AES Galois Counter + Mode + draft-ietf-tls-ecc-new-mac-06.txt + +Status of this Memo + + By submitting this Internet-Draft, each author represents that any + applicable patent or other IPR claims of which he or she is aware + have been or will be disclosed, and any of which he or she becomes + aware will be disclosed, in accordance with Section 6 of BCP 79. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF), its areas, and its working groups. Note that + other groups may also distribute working documents as Internet- + Drafts. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + The list of current Internet-Drafts can be accessed at + http://www.ietf.org/ietf/1id-abstracts.txt. + + The list of Internet-Draft Shadow Directories can be accessed at + http://www.ietf.org/shadow.html. + + This Internet-Draft will expire on October 31, 2008. + +Copyright Notice + + Copyright (C) The IETF Trust (2008). + +Abstract + + RFC 4492 describes elliptic curve cipher suites for Transport Layer + Security (TLS). However, all those cipher suites use SHA-1 as their + MAC algorithm. This document describes sixteen new CipherSuites for + TLS/DTLS which specify stronger digest algorithms. Eight use HMAC + with SHA-256 or SHA-384 and eight use AES in Galois Counter Mode + (GCM). + + + + +Rescorla Expires October 31, 2008 [Page 1] + +Internet-Draft TLS ECC New MAC April 2008 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 1.1. Conventions Used In This Document . . . . . . . . . . . . . 3 + 2. Cipher Suites . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 2.1. HMAC-based Cipher Suites . . . . . . . . . . . . . . . . . 3 + 2.2. Galois Counter Mode-based Cipher Suites . . . . . . . . . . 4 + 3. Security Considerations . . . . . . . . . . . . . . . . . . . . 4 + 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5 + 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 5 + 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 5 + 6.1. Normative References . . . . . . . . . . . . . . . . . . . 5 + 6.2. Informative References . . . . . . . . . . . . . . . . . . 6 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 6 + Intellectual Property and Copyright Statements . . . . . . . . . . 7 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Rescorla Expires October 31, 2008 [Page 2] + +Internet-Draft TLS ECC New MAC April 2008 + + +1. Introduction + + RFC 4492 [RFC4492] describes Elliptic Curve Cryptography (ECC) cipher + suites for Transport Layer Security (TLS). However, all of the RFC + 4492 suites use HMAC-SHA1 as their MAC algorithm. Due to recent + analytic work on SHA-1 [Wang05], the IETF is gradually moving away + from SHA-1 and towards stronger hash algorithms. This document + specifies TLS ECC cipher suites which use SHA-256 and SHA-384 rather + than SHA-1. + + TLS 1.2 [I-D.ietf-tls-rfc4346-bis], adds support for authenticated + encryption with additional data (AEAD) cipher modes [RFC5116]. This + document also specifies a set of ECC cipher suites using one such + mode, Galois Counter Mode (GCM) [GCM]. Another document + [I-D.ietf-tls-rsa-aes-gcm], provides support for GCM with other key + establishment methods. + +1.1. Conventions Used In This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + + +2. Cipher Suites + + This document defines 8 new cipher suites to be added to TLS. All + use Elliptic Curve Cryptography for key exchange and digital + signature, as defined in RFC 4492. + +2.1. HMAC-based Cipher Suites + + The first eight cipher suites use AES [AES] in CBC [CBC] mode with an + HMAC-based MAC: + + CipherSuite TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 = {0xXX,XX}; + CipherSuite TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 = {0xXX,XX}; + CipherSuite TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 = {0xXX,XX}; + CipherSuite TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 = {0xXX,XX}; + + These eight cipher suites are the same as the corresponding cipher + suites in RFC 4492 (with names ending in "_SHA" in place of "_SHA256" + or "_SHA384"), except for the hash and PRF algorithms, which use SHA- + 256 and SHA-384 [SHS] as follows. + + + +Rescorla Expires October 31, 2008 [Page 3] + +Internet-Draft TLS ECC New MAC April 2008 + + + Cipher Suite MAC PRF + ------------ --- --- + TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 HMAC-SHA-256 P_SHA256 + TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 HMAC-SHA-384 P_SHA384 + TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 HMAC-SHA-256 P_SHA256 + TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 HMAC-SHA-384 P_SHA384 + TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 HMAC-SHA-256 P_SHA256 + TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 HMAC-SHA-384 P_SHA384 + TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 HMAC-SHA-256 P_SHA256 + TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 HMAC-SHA-384 P_SHA384 + +2.2. Galois Counter Mode-based Cipher Suites + + The second eight cipher suites use the same asymmetric algorithms as + those in the previous section but use the new authenticated + encryption modes defined in TLS 1.2 with AES in Galois Counter Mode + (GCM) [GCM]: + + CipherSuite TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 = {0xXX,XX}; + CipherSuite TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 = {0xXX,XX}; + CipherSuite TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 = {0xXX,XX}; + CipherSuite TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 = {0xXX,XX}; + + These cipher suites use authenticated encryption with additional data + algorithms AEAD_AES_128_GCM and AEAD_AES_256_GCM described in + [RFC5116]. GCM is used as described in [I-D.ietf-tls-rsa-aes-gcm]. + + + Cipher Suite PRF + ------------ --- + TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 P_SHA256 + TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 P_SHA384 + TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 P_SHA256 + TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 P_SHA384 + TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 P_SHA256 + TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 P_SHA384 + TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 P_SHA256 + TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 P_SHA384 + + +3. Security Considerations + + The security considerations in RFC 4346, RFC 4492, and + [I-D.ietf-tls-rsa-aes-gcm] apply to this document as well. In + + + +Rescorla Expires October 31, 2008 [Page 4] + +Internet-Draft TLS ECC New MAC April 2008 + + + addition, as described in [I-D.ietf-tls-rsa-aes-gcm], these cipher + suites may only be used with TLS 1.2 or greater. + + +4. IANA Considerations + + IANA has assigned the following values for these cipher suites: + + CipherSuite TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 = {0xXX,XX}; + CipherSuite TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 = {0xXX,XX}; + CipherSuite TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 = {0xXX,XX}; + CipherSuite TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 = {0xXX,XX}; + CipherSuite TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 = {0xXX,XX}; + CipherSuite TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 = {0xXX,XX}; + CipherSuite TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 = {0xXX,XX}; + CipherSuite TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 = {0xXX,XX}; + + +5. Acknowledgements + + This work was supported by the US Department of Defense. + + David McGrew contributed substantual sections of the GCM nonce text + as well as providing a review of this document. + + +6. References + +6.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. + Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites + for Transport Layer Security (TLS)", RFC 4492, May 2006. + + [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated + Encryption", RFC 5116, January 2008. + + + + +Rescorla Expires October 31, 2008 [Page 5] + +Internet-Draft TLS ECC New MAC April 2008 + + + [I-D.ietf-tls-rfc4346-bis] + Dierks, T. and E. Rescorla, "The Transport Layer Security + (TLS) Protocol Version 1.2", draft-ietf-tls-rfc4346-bis-10 + (work in progress), March 2008. + + [AES] National Institute of Standards and Technology, + "Specification for the Advanced Encryption Standard + (AES)", FIPS 197, November 2001. + + [SHS] National Institute of Standards and Technology, "Secure + Hash Standard", FIPS 180-2, August 2002. + + [CBC] National Institute of Standards and Technology, + "Recommendation for Block Cipher Modes of Operation - + Methods and Techniques", SP 800-38A, December 2001. + + [GCM] National Institute of Standards and Technology, + "Recommendation for Block Cipher Modes of Operation: + Galois;/Counter Mode (GCM) for Confidentiality and + Authentication", SP 800-38D, November 2007. + +6.2. Informative References + + [Wang05] Wang, X., Yin, Y., and H. Yu, "Finding Collisions in the + Full SHA-1", CRYPTO 2005, August 2005. + + [I-D.ietf-tls-rsa-aes-gcm] + Salowey, J., Choudhury, A., and D. McGrew, "AES-GCM Cipher + Suites for TLS", draft-ietf-tls-rsa-aes-gcm-03 (work in + progress), April 2008. + + +Author's Address + + Eric Rescorla + RTFM, Inc. + 2064 Edgewood Drive + Palo Alto 94303 + USA + + Email: ekr@rtfm.com + + + + + + + + + + +Rescorla Expires October 31, 2008 [Page 6] + +Internet-Draft TLS ECC New MAC April 2008 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2008). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + +Acknowledgment + + Funding for the RFC Editor function is provided by the IETF + Administrative Support Activity (IASA). + + + + + +Rescorla Expires October 31, 2008 [Page 7] + diff --git a/doc/protocol/draft-ietf-tls-ecc-new-mac-07.txt b/doc/protocol/draft-ietf-tls-ecc-new-mac-07.txt new file mode 100644 index 0000000000..774b8737f8 --- /dev/null +++ b/doc/protocol/draft-ietf-tls-ecc-new-mac-07.txt @@ -0,0 +1,392 @@ + + + +Network Working Group E. Rescorla +Internet-Draft RTFM, Inc. +Intended status: Informational May 9, 2008 +Expires: November 10, 2008 + + +TLS Elliptic Curve Cipher Suites with SHA-256/384 and AES Galois Counter + Mode + draft-ietf-tls-ecc-new-mac-07.txt + +Status of this Memo + + By submitting this Internet-Draft, each author represents that any + applicable patent or other IPR claims of which he or she is aware + have been or will be disclosed, and any of which he or she becomes + aware will be disclosed, in accordance with Section 6 of BCP 79. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF), its areas, and its working groups. Note that + other groups may also distribute working documents as Internet- + Drafts. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + The list of current Internet-Drafts can be accessed at + http://www.ietf.org/ietf/1id-abstracts.txt. + + The list of Internet-Draft Shadow Directories can be accessed at + http://www.ietf.org/shadow.html. + + This Internet-Draft will expire on November 10, 2008. + +Copyright Notice + + Copyright (C) The IETF Trust (2008). + +Abstract + + RFC 4492 describes elliptic curve cipher suites for Transport Layer + Security (TLS). However, all those cipher suites use SHA-1 as their + MAC algorithm. This document describes sixteen new cipher suites for + TLS which specify stronger digest algorithms. Eight use HMAC with + SHA-256 or SHA-384 and eight use AES in Galois Counter Mode (GCM). + + + + + +Rescorla Expires November 10, 2008 [Page 1] + +Internet-Draft TLS ECC New MAC May 2008 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 2. Conventions Used In This Document . . . . . . . . . . . . . . . 3 + 3. Cipher Suites . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 3.1. HMAC-based Cipher Suites . . . . . . . . . . . . . . . . . 3 + 3.2. Galois Counter Mode-based Cipher Suites . . . . . . . . . . 4 + 4. Security Considerations . . . . . . . . . . . . . . . . . . . . 4 + 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 4 + 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 5 + 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 5 + 7.1. Normative References . . . . . . . . . . . . . . . . . . . 5 + 7.2. Informative References . . . . . . . . . . . . . . . . . . 6 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 6 + Intellectual Property and Copyright Statements . . . . . . . . . . 7 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Rescorla Expires November 10, 2008 [Page 2] + +Internet-Draft TLS ECC New MAC May 2008 + + +1. Introduction + + RFC 4492 [RFC4492] describes Elliptic Curve Cryptography (ECC) cipher + suites for Transport Layer Security (TLS). However, all of the RFC + 4492 suites use HMAC-SHA1 as their MAC algorithm. Due to recent + analytic work on SHA-1 [Wang05], the IETF is gradually moving away + from SHA-1 and towards stronger hash algorithms. This document + specifies TLS ECC cipher suites which use SHA-256 and SHA-384 [SHS] + rather than SHA-1. + + TLS 1.2 [I-D.ietf-tls-rfc4346-bis], adds support for authenticated + encryption with additional data (AEAD) cipher modes [RFC5116]. This + document also specifies a set of ECC cipher suites using one such + mode, Galois Counter Mode (GCM) [GCM]. Another document + [I-D.ietf-tls-rsa-aes-gcm], provides support for GCM with other key + establishment methods. + + +2. Conventions Used In This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + + +3. Cipher Suites + + This document defines 16 new cipher suites to be added to TLS. All + use Elliptic Curve Cryptography for key exchange and digital + signature, as defined in RFC 4492. + +3.1. HMAC-based Cipher Suites + + The first eight cipher suites use AES [AES] in CBC [CBC] mode with an + HMAC-based MAC: + + CipherSuite TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 = {0xXX,XX}; + CipherSuite TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 = {0xXX,XX}; + CipherSuite TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 = {0xXX,XX}; + CipherSuite TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 = {0xXX,XX}; + + These eight cipher suites are the same as the corresponding cipher + suites in RFC 4492 (with names ending in "_SHA" in place of "_SHA256" + or "_SHA384"), except for the hash and PRF algorithms. + + + +Rescorla Expires November 10, 2008 [Page 3] + +Internet-Draft TLS ECC New MAC May 2008 + + + These SHALL be as follows: + + o For cipher suites ending with _SHA256, the PRF is the TLS PRF + [I-D.ietf-tls-rfc4346-bis] with SHA-256 as the hash function. The + MAC is HMAC [RFC2104] with SHA-256 as the hash function. + o For cipher suites ending with _SHA384, the PRF is the TLS PRF + [I-D.ietf-tls-rfc4346-bis] with SHA-384 as the hash function. The + MAC is HMAC [RFC2104] with SHA-384 as the hash function. + +3.2. Galois Counter Mode-based Cipher Suites + + The second eight cipher suites use the same asymmetric algorithms as + those in the previous section but use the new authenticated + encryption modes defined in TLS 1.2 with AES in Galois Counter Mode + (GCM) [GCM]: + + CipherSuite TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 = {0xXX,XX}; + CipherSuite TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 = {0xXX,XX}; + CipherSuite TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 = {0xXX,XX}; + CipherSuite TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 = {0xXX,XX}; + + These cipher suites use authenticated encryption with additional data + algorithms AEAD_AES_128_GCM and AEAD_AES_256_GCM described in + [RFC5116]. GCM is used as described in [I-D.ietf-tls-rsa-aes-gcm]. + + The PRFs SHALL be as follows: + + o For cipher suites ending with _SHA256, the PRF is the TLS PRF + [I-D.ietf-tls-rfc4346-bis] with SHA-256 as the hash function. + o For cipher suites ending with _SHA384, the PRF is the TLS PRF + [I-D.ietf-tls-rfc4346-bis] with SHA-384 as the hash function. + + +4. Security Considerations + + The security considerations in RFC 4346, RFC 4492, and + [I-D.ietf-tls-rsa-aes-gcm] apply to this document as well. In + addition, as described in [I-D.ietf-tls-rsa-aes-gcm], these cipher + suites may only be used with TLS 1.2 or greater. + + +5. IANA Considerations + + IANA has assigned the following values for these cipher suites: + + + +Rescorla Expires November 10, 2008 [Page 4] + +Internet-Draft TLS ECC New MAC May 2008 + + + CipherSuite TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384 = {0xXX,XX}; + CipherSuite TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384 = {0xXX,XX}; + CipherSuite TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 = {0xXX,XX}; + CipherSuite TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384 = {0xXX,XX}; + CipherSuite TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384 = {0xXX,XX}; + CipherSuite TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDH_ECDSA_WITH_AES_256_GCM_SHA384 = {0xXX,XX}; + CipherSuite TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 = {0xXX,XX}; + CipherSuite TLS_ECDH_RSA_WITH_AES_128_GCM_SHA256 = {0xXX,XX}; + CipherSuite TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384 = {0xXX,XX}; + + +6. Acknowledgements + + This work was supported by the US Department of Defense. + + David McGrew, Pasi Eronen, and Alfred Hoenes provided reviews of this + document. + + +7. References + +7.1. Normative References + + [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- + Hashing for Message Authentication", RFC 2104, + February 1997. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC4492] Blake-Wilson, S., Bolyard, N., Gupta, V., Hawk, C., and B. + Moeller, "Elliptic Curve Cryptography (ECC) Cipher Suites + for Transport Layer Security (TLS)", RFC 4492, May 2006. + + [RFC5116] McGrew, D., "An Interface and Algorithms for Authenticated + Encryption", RFC 5116, January 2008. + + [I-D.ietf-tls-rfc4346-bis] + Dierks, T. and E. Rescorla, "The Transport Layer Security + (TLS) Protocol Version 1.2", draft-ietf-tls-rfc4346-bis-10 + (work in progress), March 2008. + + + +Rescorla Expires November 10, 2008 [Page 5] + +Internet-Draft TLS ECC New MAC May 2008 + + + [I-D.ietf-tls-rsa-aes-gcm] + Salowey, J., Choudhury, A., and D. McGrew, "AES-GCM Cipher + Suites for TLS", draft-ietf-tls-rsa-aes-gcm-03 (work in + progress), April 2008. + + [AES] National Institute of Standards and Technology, + "Specification for the Advanced Encryption Standard + (AES)", FIPS 197, November 2001. + + [SHS] National Institute of Standards and Technology, "Secure + Hash Standard", FIPS 180-2, August 2002. + + [CBC] National Institute of Standards and Technology, + "Recommendation for Block Cipher Modes of Operation - + Methods and Techniques", SP 800-38A, December 2001. + + [GCM] National Institute of Standards and Technology, + "Recommendation for Block Cipher Modes of Operation: + Galois/Counter Mode (GCM) for Confidentiality and + Authentication", SP 800-38D, November 2007. + +7.2. Informative References + + [Wang05] Wang, X., Yin, Y., and H. Yu, "Finding Collisions in the + Full SHA-1", CRYPTO 2005, August 2005. + + +Author's Address + + Eric Rescorla + RTFM, Inc. + 2064 Edgewood Drive + Palo Alto 94303 + USA + + Email: ekr@rtfm.com + + + + + + + + + + + + + + + +Rescorla Expires November 10, 2008 [Page 6] + +Internet-Draft TLS ECC New MAC May 2008 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2008). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + +Acknowledgment + + Funding for the RFC Editor function is provided by the IETF + Administrative Support Activity (IASA). + + + + + +Rescorla Expires November 10, 2008 [Page 7] + diff --git a/doc/protocol/draft-rescorla-tls-extended-random-00.txt b/doc/protocol/draft-rescorla-tls-extended-random-00.txt new file mode 100644 index 0000000000..5b33f74178 --- /dev/null +++ b/doc/protocol/draft-rescorla-tls-extended-random-00.txt @@ -0,0 +1,448 @@ + + + +Network Working Group E. Rescorla +Internet-Draft RTFM, Inc. +Intended status: Informational M. Salter +Expires: October 31, 2008 National Security Agency + April 29, 2008 + + + Extended Random Values for TLS + draft-rescorla-tls-extended-random-00.txt + +Status of this Memo + + By submitting this Internet-Draft, each author represents that any + applicable patent or other IPR claims of which he or she is aware + have been or will be disclosed, and any of which he or she becomes + aware will be disclosed, in accordance with Section 6 of BCP 79. + + Internet-Drafts are working documents of the Internet Engineering + Task Force (IETF), its areas, and its working groups. Note that + other groups may also distribute working documents as Internet- + Drafts. + + Internet-Drafts are draft documents valid for a maximum of six months + and may be updated, replaced, or obsoleted by other documents at any + time. It is inappropriate to use Internet-Drafts as reference + material or to cite them other than as "work in progress." + + The list of current Internet-Drafts can be accessed at + http://www.ietf.org/ietf/1id-abstracts.txt. + + The list of Internet-Draft Shadow Directories can be accessed at + http://www.ietf.org/shadow.html. + + This Internet-Draft will expire on October 31, 2008. + +Copyright Notice + + Copyright (C) The IETF Trust (2008). + +Abstract + + This document describes an extension for using larger client and + server Random values with Transport Layer Security (TLS) and Datagram + TLS (DTLS). + + + + + + + +Rescorla & Salter Expires October 31, 2008 [Page 1] + +Internet-Draft Extended TLS Random April 2008 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 + 2. Conventions Used In This Document . . . . . . . . . . . . . . . 3 + 3. The ExtendedRandom Extension . . . . . . . . . . . . . . . . . 3 + 3.1. Negotiating the ExtendedRandom Extension . . . . . . . . . 4 + 3.2. PRF Modifications . . . . . . . . . . . . . . . . . . . . . 4 + 4. Security Considerations . . . . . . . . . . . . . . . . . . . . 5 + 4.1. Threats to TLS . . . . . . . . . . . . . . . . . . . . . . 5 + 4.2. Scope of Randomness . . . . . . . . . . . . . . . . . . . . 5 + 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 5 + 6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 6 + 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 6 + 7.1. Normative References . . . . . . . . . . . . . . . . . . . 6 + 7.2. Informative References . . . . . . . . . . . . . . . . . . 6 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 6 + Intellectual Property and Copyright Statements . . . . . . . . . . 8 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Rescorla & Salter Expires October 31, 2008 [Page 2] + +Internet-Draft Extended TLS Random April 2008 + + +1. Introduction + + TLS [I-D.ietf-tls-rfc4346-bis] and DTLS [RFC4347] use a 32-byte + "Random" value consisting of a 32-bit time value time and 28 randomly + generated bytes: + + struct { + uint32 gmt_unix_time; + opaque random_bytes[28]; + } Random; + + The client and server each contribute a Random value which is then + mixed with secret keying material to produce the final per- + association keying material. + + The United States Department of Defense has requested a TLS mode + which allows the use of longer public randomness values for use with + high security level cipher suites like those specified in Suite B + [I-D.rescorla-tls-suiteb]. The rationale for this as stated by DoD + is that the public randomness for each side should be at least twice + as long as the security level for cryptographic parity, which makes + the 224 bits of randomness provided by the current TLS random values + insufficient. + + This document specifies an extension which allows for additional + randomness to be exchanged in the Hello messages. + + +2. Conventions Used In This Document + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + + +3. The ExtendedRandom Extension + + This document defines a new TLS extension called "extended_random". + + The "extended_random" extension carried in a new TLS extension called + "ExtendedRandom". + + struct { + opaque extended_random_value<0..2^16-1>; + } ExtendedRandom; + + The extended_random_value MUST be a randomly generated byte string. + A cryptographically secure PRNG [RFC4086] SHOULD be used. + + + +Rescorla & Salter Expires October 31, 2008 [Page 3] + +Internet-Draft Extended TLS Random April 2008 + + +3.1. Negotiating the ExtendedRandom Extension + + The client requests support for the extended randomness feature by + sending an "extended_random" extension in its ClientHello. The + "extension_data" field contains an ExtendedRandom value. + + When a server which does not recognize the "extended_random" + extension receives one, it will ignore it as required. A server + which recognizes the extension MAY choose to ignore it, in which case + it SHOULD continue with the exchange as if it had not received the + extension. + + If the server wishes to use the extended randomness feature, it MUST + send its own "extended_random" extension with an + extended_random_value equal in length to the client's + extended_random_value. Clients SHOULD check the length of the + server's extended_random_value and generate a fatal + "illegal_parameter" error if it is present but does does not match + the length that was transmitted in the ClientHello. + + Because TLS does not permit servers to request extensions which the + client did not offer, the client may not offer the "extended_random" + extension even if the server requires it. In this case, the server + should generate a fatal "handshake_failure" alert. + + Because there is no way to mark extensions as critical, the server + may ignore the "extended_random" extension even though the client + requires it. If a client requires the extended randomness input + feature but the server does not negotiate it, the client SHOULD + generate a fatal "handshake_failure" alert. + +3.2. PRF Modifications + + When the extended randomness feature is in use, the extended random + values MUST be mixed into the PRF along with the client and server + random values during the PMS->MS conversion. Thus, the PRF becomes: + + master_secret = PRF(pre_master_secret, "master secret", + ClientHello.random + + ClientHello.extended_random_value + + ServerHello.random + + ServerHello.extended_random_value)[0..47]; + + Because new extensions may not be introduced in resumed handshakes, + mixing in the extended inputs during the MS->keying material + conversion would simply involve mixing in the same material twice. + Therefore, the extended random inputs are only used when the PMS is + converted into the MS. + + + +Rescorla & Salter Expires October 31, 2008 [Page 4] + +Internet-Draft Extended TLS Random April 2008 + + +4. Security Considerations + +4.1. Threats to TLS + + When this extension is in use it increases the amount of data that an + attacker can inject into the PRF. This potentially would allow an + attacker who had partially compromised the PRF greater scope for + influencing the output. Hash-based PRFs like the one in TLS are + designed to be fairly indifferent to the input size (the input is + already greater than the block size of most hash functions), however + there is currently no proof that a larger input space would not make + attacks easier. + + Another concern is that bad implementations might generate low + entropy extented random values. TLS is designed to function + correctly even when fed low-entropy random values because they are + primarily used to generate distinct keying material for each + connection. + +4.2. Scope of Randomness + + TLS specifies that when a session is resumed the extensions from the + original connection are used: + + If, on the other hand, the older session is resumed, then the + server MUST ignore the extensions and send a server hello + containing none of the extension types. In this case, the + functionality of these extensions negotiated during the original + session initiation is applied to the resumed session. + + This motivates why the the extended randomness does not get mixed + into the PRF when generating the keying material from the master + secret. Because the same values would be used for every connection + in a session, they would not provide any differentiation in the + keying material between the connections. + + +5. IANA Considerations + + This document defines an extension to TLS, in accordance with + [I-D.ietf-tls-rfc4366-bis]: + + enum { extended_random (??) } ExtensionType; + + [[ NOTE: These values need to be assigned by IANA ]] + + + + + + +Rescorla & Salter Expires October 31, 2008 [Page 5] + +Internet-Draft Extended TLS Random April 2008 + + +6. Acknowledgements + + This work was supported by the US Department of Defense. + + +7. References + +7.1. Normative References + + [I-D.ietf-tls-rfc4346-bis] + Dierks, T. and E. Rescorla, "The Transport Layer Security + (TLS) Protocol Version 1.2", draft-ietf-tls-rfc4346-bis-10 + (work in progress), March 2008. + + [RFC4086] Eastlake, D., Schiller, J., and S. Crocker, "Randomness + Requirements for Security", BCP 106, RFC 4086, June 2005. + +7.2. Informative References + + [I-D.ietf-tls-rfc4366-bis] + 3rd, D., "Transport Layer Security (TLS) Extensions: + Extension Definitions", draft-ietf-tls-rfc4366-bis-02 + (work in progress), February 2008. + + [I-D.rescorla-tls-suiteb] + Salter, M. and E. Rescorla, "Suite B Cipher Suites for + TLS", draft-rescorla-tls-suiteb-02 (work in progress), + April 2008. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC4347] Rescorla, E. and N. Modadugu, "Datagram Transport Layer + Security", RFC 4347, April 2006. + + +Authors' Addresses + + Eric Rescorla + RTFM, Inc. + 2064 Edgewood Drive + Palo Alto, CA 94303 + USA + + Email: ekr@rtfm.com + + + + + + +Rescorla & Salter Expires October 31, 2008 [Page 6] + +Internet-Draft Extended TLS Random April 2008 + + + Margaret Salter + National Security Agency + 9800 Savage Rd. + Fort Meade 20755-6709 + USA + + Email: msalter@restarea.ncsc.mil + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Rescorla & Salter Expires October 31, 2008 [Page 7] + +Internet-Draft Extended TLS Random April 2008 + + +Full Copyright Statement + + Copyright (C) The IETF Trust (2008). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND + THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF + THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + + +Acknowledgment + + Funding for the RFC Editor function is provided by the IETF + Administrative Support Activity (IASA). + + + + + +Rescorla & Salter Expires October 31, 2008 [Page 8] + diff --git a/doc/reference/gnutls-docs.sgml b/doc/reference/gnutls-docs.sgml index cbd9951a91..c418ae9f1e 100644 --- a/doc/reference/gnutls-docs.sgml +++ b/doc/reference/gnutls-docs.sgml @@ -33,4 +33,10 @@ <index> <title>Index</title> </index> + <index role="deprecated"> + <title>Index of deprecated symbols</title> + </index> + <index role="2.4.0"> + <title>Index of new symbols in 2.4.0</title> + </index> </book> |