diff options
| -rw-r--r-- | NEWS | 10 | ||||
| -rw-r--r-- | doc/cha-auth.texi | 462 | ||||
| -rw-r--r-- | doc/cha-bib.texi | 143 | ||||
| -rw-r--r-- | doc/cha-cert-auth.texi | 626 | ||||
| -rw-r--r-- | doc/cha-ciphersuites.texi | 44 | ||||
| -rw-r--r-- | doc/cha-copying.texi | 29 | ||||
| -rw-r--r-- | doc/cha-functions.texi | 120 | ||||
| -rw-r--r-- | doc/cha-internals.texi | 336 | ||||
| -rw-r--r-- | doc/cha-intro-tls.texi | 783 | ||||
| -rw-r--r-- | doc/cha-library.texi | 188 | ||||
| -rw-r--r-- | doc/cha-preface.texi | 257 | ||||
| -rw-r--r-- | doc/cha-programs.texi | 853 | ||||
| -rw-r--r-- | doc/cha-tls-app.texi | 130 | ||||
| -rw-r--r-- | doc/gnutls.texi | 4281 | ||||
| -rw-r--r-- | lib/includes/gnutls/pkcs11.h | 8 | ||||
| -rw-r--r-- | lib/libgnutls.map | 1 | ||||
| -rw-r--r-- | lib/pkcs11.c | 16 |
17 files changed, 4005 insertions, 4282 deletions
@@ -21,8 +21,12 @@ similar gnutls_certificate_set_server_retrieve_function() and gnutls_certificate_set_client_retrieve_function(). In addition it support PKCS #11 private keys. +** libgnutls: Added gnutls_pkcs11_copy_x509_crt(), gnutls_pkcs11_copy_x509_privkey(), +and gnutls_pkcs11_delete_url() to allow copying and deleting data in tokens. + ** certtool: Added new options: --pkcs11-list-tokens, --pkcs11-list-all ---pkcs11-list-all-certs, --pkcs11-list-trusted, --pkcs11-list-certs +--pkcs11-list-all-certs, --pkcs11-list-trusted, --pkcs11-list-certs, +--pkcs11-delete-url, --pkcs11-write ** gnutls-cli/gnutls-serv: --x509cafile, --x509certfile and --x509keyfile can now accept a PKCS #11 URL in addition to a file. This will allow for @@ -45,7 +49,6 @@ gnutls_pkcs11_obj_init: ADDED gnutls_pkcs11_obj_import_url: ADDED gnutls_pkcs11_obj_export_url: ADDED gnutls_pkcs11_obj_deinit: ADDED -gnutls_pkcs11_obj_list_deinit: ADDED gnutls_pkcs11_obj_export: ADDED gnutls_pkcs11_obj_list_import_url: ADDED gnutls_pkcs11_obj_export: ADDED @@ -98,6 +101,9 @@ gnutls_pubkey_import_dsa_raw: ADDED gnutls_pubkey_import_rsa_raw: ADDED gnutls_x509_crt_set_pubkey: ADDED gnutls_x509_crq_set_pubkey: ADDED +gnutls_pkcs11_copy_x509_crt: ADDED +gnutls_pkcs11_copy_x509_privkey: ADDED +gnutls_pkcs11_delete_url: ADDED * Version 2.9.10 (released 2010-04-22) diff --git a/doc/cha-auth.texi b/doc/cha-auth.texi new file mode 100644 index 0000000000..39da7a5c9a --- /dev/null +++ b/doc/cha-auth.texi @@ -0,0 +1,462 @@ +@node Authentication methods +@chapter Authentication Methods + +The @acronym{TLS} protocol provides confidentiality and encryption, +but also offers authentication, which is a prerequisite for a secure +connection. The available authentication methods in @acronym{GnuTLS} +are: + +@itemize + +@item Certificate authentication + +@item Anonymous authentication + +@item @acronym{SRP} authentication + +@item @acronym{PSK} authentication + +@end itemize + +@menu +* Certificate authentication:: +* Anonymous authentication:: +* Authentication using SRP:: +* Authentication using PSK:: +* Authentication and credentials:: +* Parameters stored in credentials:: +@end menu + +@node Certificate authentication +@section Certificate Authentication + +@subsection Authentication Using @acronym{X.509} Certificates +@cindex @acronym{X.509} certificates + +@acronym{X.509} certificates contain the public parameters, of a +public key algorithm, and an authority's signature, which proves the +authenticity of the parameters. @xref{The X.509 trust model}, for +more information on @acronym{X.509} protocols. + +@subsection Authentication Using @acronym{OpenPGP} Keys +@cindex @acronym{OpenPGP} Keys + +@acronym{OpenPGP} keys also contain public parameters of a public key +algorithm, and signatures from several other parties. Depending on +whether a signer is trusted the key is considered trusted or not. +@acronym{GnuTLS}'s @acronym{OpenPGP} authentication implementation is +based on the @xcite{TLSPGP} proposal. + +@xref{The OpenPGP trust model}, for more information about the +@acronym{OpenPGP} trust model. For a more detailed introduction to +@acronym{OpenPGP} and @acronym{GnuPG} see @xcite{GPGH}. + +@subsection Using Certificate Authentication + +In @acronym{GnuTLS} both the @acronym{OpenPGP} and @acronym{X.509} +certificates are part of the certificate authentication and thus are +handled using a common API. + +When using certificates the server is required to have at least one +certificate and private key pair. A client may or may not have such a +pair. The certificate and key pair should be loaded, before any +@acronym{TLS} session is initialized, in a certificate credentials +structure. This should be done by using +@ref{gnutls_certificate_set_x509_key_file} or +@ref{gnutls_certificate_set_openpgp_key_file} depending on the +certificate type. In the @acronym{X.509} case, the functions will +also accept and use a certificate list that leads to a trusted +authority. The certificate list must be ordered in such way that every +certificate certifies the one before it. The trusted authority's +certificate need not to be included, since the peer should possess it +already. + +As an alternative, a callback may be used so the server or the client +specify the certificate and the key at the handshake time. That +callback can be set using the functions: + +@itemize + +@item @ref{gnutls_certificate_server_set_retrieve_function} + +@item @ref{gnutls_certificate_client_set_retrieve_function} + +@end itemize + +Clients and servers that will select certificates using callback +functions should select a certificate according the peer's signature +algorithm preferences. To get those preferences use +@ref{gnutls_sign_algorithm_get_requested}. + +Certificate verification is possible by loading the trusted +authorities into the credentials structure by using +@ref{gnutls_certificate_set_x509_trust_file} or +@ref{gnutls_certificate_set_openpgp_keyring_file} for openpgp +keys. Note however that the peer's certificate is not automatically +verified, you should call @ref{gnutls_certificate_verify_peers2}, +after a successful handshake, to verify the signatures of the +certificate. An alternative way, which reports a more detailed +verification output, is to use @ref{gnutls_certificate_get_peers} to +obtain the raw certificate of the peer and verify it using the +functions discussed in @ref{The X.509 trust model}. + +In a handshake, the negotiated cipher suite depends on the +certificate's parameters, so not all key exchange methods will be +available with some certificates. @acronym{GnuTLS} will disable +ciphersuites that are not compatible with the key, or the enabled +authentication methods. For example keys marked as sign-only, will +not be able to access the plain RSA ciphersuites, but only the +@code{DHE_RSA} ones. It is recommended not to use RSA keys for both +signing and encryption. If possible use the same key for the +@code{DHE_RSA} and @code{RSA_EXPORT} ciphersuites, which use signing, +and a different key for the plain RSA ciphersuites, which use +encryption. All the key exchange methods shown below are available in +certificate authentication. + +Note that the DHE key exchange methods are generally +slower@footnote{It really depends on the group used. Primes with +lesser bits are always faster, but also easier to break. Values less +than 768 should not be used today} than plain RSA and require Diffie +Hellman parameters to be generated and associated with a credentials +structure, by the server. The @code{RSA-EXPORT} method also requires +512 bit RSA parameters, that should also be generated and associated +with the credentials structure. See the functions: + +@itemize + +@item @ref{gnutls_dh_params_generate2} + +@item @ref{gnutls_certificate_set_dh_params} + +@item @ref{gnutls_rsa_params_generate2} + +@item @ref{gnutls_certificate_set_rsa_export_params} + +@end itemize + +Sometimes in order to avoid bottlenecks in programs it is usefull to +store and read parameters from formats that can be generated by +external programs such as @code{certtool}. This is possible with +@acronym{GnuTLS} by using the following functions: + +@itemize + +@item @ref{gnutls_dh_params_import_pkcs3} + +@item @ref{gnutls_rsa_params_import_pkcs1} + +@item @ref{gnutls_dh_params_export_pkcs3} + +@item @ref{gnutls_rsa_params_export_pkcs1} + +@end itemize + +Key exchange algorithms for @acronym{OpenPGP} and @acronym{X.509} +certificates: + +@table @code + +@item RSA: +The RSA algorithm is used to encrypt a key and send it to the peer. +The certificate must allow the key to be used for encryption. + +@item RSA_EXPORT: +The RSA algorithm is used to encrypt a key and send it to the peer. +In the EXPORT algorithm, the server signs temporary RSA parameters of +512 bits --- which are considered weak --- and sends them to the +client. + +@item DHE_RSA: +The RSA algorithm is used to sign Ephemeral Diffie-Hellman parameters +which are sent to the peer. The key in the certificate must allow the +key to be used for signing. Note that key exchange algorithms which +use Ephemeral Diffie-Hellman parameters, offer perfect forward +secrecy. That means that even if the private key used for signing is +compromised, it cannot be used to reveal past session data. + +@item DHE_DSS: +The DSS algorithm is used to sign Ephemeral Diffie-Hellman parameters +which are sent to the peer. The certificate must contain DSA +parameters to use this key exchange algorithm. DSS stands for Digital +Signature Standard. + +@end table + +@node Anonymous authentication +@section Anonymous Authentication +@cindex Anonymous authentication + +The anonymous key exchange performs encryption but there is no +indication of the identity of the peer. This kind of authentication +is vulnerable to a man in the middle attack, but this protocol can be +used even if there is no prior communication and trusted parties with +the peer, or when full anonymity is required. Unless really required, +do not use anonymous authentication. Available key exchange methods +are shown below. + +Note that the key exchange methods for anonymous authentication +require Diffie-Hellman parameters to be generated by the server and +associated with an anonymous credentials structure. + +Supported anonymous key exchange algorithms: + +@table @code + +@item ANON_DH: +This algorithm exchanges Diffie-Hellman parameters. + +@end table + +@node Authentication using SRP +@section Authentication using @acronym{SRP} +@cindex @acronym{SRP} authentication + +Authentication via the Secure Remote Password protocol, +@acronym{SRP}@footnote{@acronym{SRP} is described in @xcite{RFC2945}}, +is supported. The @acronym{SRP} key exchange is an extension to the +@acronym{TLS} protocol, and it is a password based authentication +(unlike @acronym{X.509} or @acronym{OpenPGP} that use certificates). +The two peers can be identified using a single password, or there can +be combinations where the client is authenticated using @acronym{SRP} +and the server using a certificate. + +The advantage of @acronym{SRP} authentication, over other proposed +secure password authentication schemes, is that @acronym{SRP} does not +require the server to hold the user's password. This kind of +protection is similar to the one used traditionally in the @emph{UNIX} +@file{/etc/passwd} file, where the contents of this file did not cause +harm to the system security if they were revealed. The @acronym{SRP} +needs instead of the plain password something called a verifier, which +is calculated using the user's password, and if stolen cannot be used +to impersonate the user. Check @xcite{TOMSRP} for a detailed +description of the @acronym{SRP} protocol and the Stanford +@acronym{SRP} libraries, which includes a PAM module that synchronizes +the system's users passwords with the @acronym{SRP} password +files. That way @acronym{SRP} authentication could be used for all the +system's users. + +The implementation in @acronym{GnuTLS} is based on paper +@xcite{TLSSRP}. The supported @acronym{SRP} key exchange methods are: + +@table @code + +@item SRP: +Authentication using the @acronym{SRP} protocol. + +@item SRP_DSS: +Client authentication using the @acronym{SRP} protocol. Server is +authenticated using a certificate with DSA parameters. + +@item SRP_RSA: +Client authentication using the @acronym{SRP} protocol. Server is +authenticated using a certificate with RSA parameters. + +@end table + +If clients supporting @acronym{SRP} know the username and password +before the connection, should initialize the client credentials and +call the function @ref{gnutls_srp_set_client_credentials}. +Alternatively they could specify a callback function by using the +function @ref{gnutls_srp_set_client_credentials_function}. This has +the advantage that allows probing the server for @acronym{SRP} +support. In that case the callback function will be called twice per +handshake. The first time is before the ciphersuite is negotiated, +and if the callback returns a negative error code, the callback will +be called again if @acronym{SRP} has been negotiated. This uses a +special @acronym{TLS}-@acronym{SRP} handshake idiom in order to avoid, +in interactive applications, to ask the user for @acronym{SRP} +password and username if the server does not negotiate an +@acronym{SRP} ciphersuite. + +In server side the default behaviour of @acronym{GnuTLS} is to read +the usernames and @acronym{SRP} verifiers from password files. These +password files are the ones used by the @emph{Stanford srp libraries} +and can be specified using the +@ref{gnutls_srp_set_server_credentials_file}. If a different +password file format is to be used, then the function +@ref{gnutls_srp_set_server_credentials_function}, should be called, +in order to set an appropriate callback. + +Some helper functions such as + +@itemize + +@item @ref{gnutls_srp_verifier} + +@item @ref{gnutls_srp_base64_encode} + +@item @ref{gnutls_srp_base64_decode} + +@end itemize + +are included in @acronym{GnuTLS}, and can be used to generate and +maintain @acronym{SRP} verifiers and password files. A program to +manipulate the required parameters for @acronym{SRP} authentication is +also included. @xref{srptool}, for more information. + + +@node Authentication using PSK +@section Authentication using @acronym{PSK} +@cindex @acronym{PSK} authentication + +Authentication using Pre-shared keys is a method to authenticate using +usernames and binary keys. This protocol avoids making use of public +key infrastructure and expensive calculations, thus it is suitable for +constraint clients. + +The implementation in @acronym{GnuTLS} is based on paper +@xcite{TLSPSK}. The supported @acronym{PSK} key exchange methods are: + +@table @code + +@item PSK: +Authentication using the @acronym{PSK} protocol. + +@item DHE-PSK: +Authentication using the @acronym{PSK} protocol and Diffie-Hellman key +exchange. This method offers perfect forward secrecy. + +@end table + +Clients supporting @acronym{PSK} should supply the username and key +before the connection to the client credentials by calling the +function @ref{gnutls_psk_set_client_credentials}. Alternatively they +could specify a callback function by using the function +@ref{gnutls_psk_set_client_credentials_function}. This has the +advantage that the callback will be called only if @acronym{PSK} has +been negotiated. + +In server side the default behaviour of @acronym{GnuTLS} is to read +the usernames and @acronym{PSK} keys from a password file. The +password file should contain usernames and keys in hexadecimal +format. The name of the password file can be stored to the credentials +structure by calling @ref{gnutls_psk_set_server_credentials_file}. If +a different 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 + +@item @ref{gnutls_hex_encode} + +@item @ref{gnutls_hex_decode} + +@end itemize + +are included in @acronym{GnuTLS}, and may be used to generate and +maintain @acronym{PSK} keys. + + +@node Authentication and credentials +@section Authentication and Credentials + +In @acronym{GnuTLS} every key exchange method is associated with a +credentials type. So in order to enable to enable a specific method, +the corresponding credentials type should be initialized and set using +@ref{gnutls_credentials_set}. A mapping is shown below. + +Key exchange algorithms and the corresponding credential types: + +@multitable @columnfractions .3 .3 .3 + +@headitem Key exchange @tab Client credentials @tab Server credentials + +@item @code{KX_RSA} +@item @code{KX_DHE_RSA} +@item @code{KX_DHE_DSS} +@item @code{KX_RSA_EXPORT} +@tab @code{CRD_CERTIFICATE} +@tab @code{CRD_CERTIFICATE} + +@item @code{KX_SRP_RSA} +@tab @code{CRD_SRP} +@tab @code{CRD_SRP} +@item @code{KX_SRP_DSS} +@tab +@tab @code{CRD_CERTIFICATE} + +@item @code{KX_SRP} +@tab @code{CRD_SRP} +@tab @code{CRD_SRP} + +@item @code{KX_ANON_DH} +@tab @code{CRD_ANON} +@tab @code{CRD_ANON} + +@item @code{KX_PSK} +@tab @code{CRD_PSK} +@tab @code{CRD_PSK} + +@end multitable + +@node Parameters stored in credentials +@section Parameters Stored in Credentials + +Several parameters such as the ones used for Diffie-Hellman +authentication are stored within the credentials structures, so all +sessions can access them. Those parameters are stored in structures +such as @code{gnutls_dh_params_t} and @code{gnutls_rsa_params_t}, and +functions like @ref{gnutls_certificate_set_dh_params} and +@ref{gnutls_certificate_set_rsa_export_params} can be used to +associate those parameters with the given credentials structure. + +Since those parameters need to be renewed from time to time and a +global structure such as the credentials, may not be easy to modify +since it is accessible by all sessions, an alternative interface is +available using a callback function. This can be set using the +@ref{gnutls_certificate_set_params_function}. An example is shown +below. + +@example +#include <gnutls.h> + +gnutls_rsa_params_t rsa_params; +gnutls_dh_params_t dh_params; + +/* This function will be called once a session requests DH + * or RSA parameters. The parameters returned (if any) will + * be used for the first handshake only. + */ +static int get_params( gnutls_session_t session, + gnutls_params_type_t type, + gnutls_params_st *st) +@{ + if (type == GNUTLS_PARAMS_RSA_EXPORT) + st->params.rsa_export = rsa_params; + else if (type == GNUTLS_PARAMS_DH) + st->params.dh = dh_params; + else return -1; + + st->type = type; + /* do not deinitialize those parameters. + */ + st->deinit = 0; + + return 0; +@} + +int main() +@{ + gnutls_certificate_credentials_t cert_cred; + + initialize_params(); + + /* ... + */ + + gnutls_certificate_set_params_function( cert_cred, get_params); +@} +@end example diff --git a/doc/cha-bib.texi b/doc/cha-bib.texi new file mode 100644 index 0000000000..d52744e867 --- /dev/null +++ b/doc/cha-bib.texi @@ -0,0 +1,143 @@ +@node Bibliography +@unnumbered Bibliography + +@table @asis + +@item @anchor{CBCATT}[CBCATT] +Bodo Moeller, "Security of CBC Ciphersuites in SSL/TLS: Problems and +Countermeasures", 2002, available from +@url{http://www.openssl.org/~bodo/tls-cbc.txt}. + +@item @anchor{GPGH}[GPGH] +Mike Ashley, "The GNU Privacy Handbook", 2002, available from +@url{http://www.gnupg.org/gph/en/manual.pdf}. + +@item @anchor{GUTPKI}[GUTPKI] +Peter Gutmann, "Everything you never wanted to know about PKI but were +forced to find out", Available from +@url{http://www.cs.auckland.ac.nz/~pgut001/}. + +@item @anchor{NISTSP80057}[NISTSP80057] +NIST Special Publication 800-57, "Recommendation for Key Management - +Part 1: General (Revised)", March 2007, available from +@url{http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57-Part1-revised2_Mar08-2007.pdf}. + +@item @anchor{RFC2246}[RFC2246] +Tim Dierks and Christopher Allen, "The TLS Protocol Version 1.0", +January 1999, Available from +@url{http://www.ietf.org/rfc/rfc2246.txt}. + +@item @anchor{RFC4346}[RFC4346] +Tim Dierks and Eric Rescorla, "The TLS Protocol Version 1.1", Match +2006, Available from @url{http://www.ietf.org/rfc/rfc4346.txt}. + +@item @anchor{RFC2440}[RFC2440] +Jon Callas, Lutz Donnerhacke, Hal Finney and Rodney Thayer, "OpenPGP +Message Format", November 1998, Available from +@url{http://www.ietf.org/rfc/rfc2440.txt}. + +@item @anchor{RFC4880}[RFC4880] +Jon Callas, Lutz Donnerhacke, Hal Finney, David Shaw and Rodney +Thayer, "OpenPGP Message Format", November 2007, Available from +@url{http://www.ietf.org/rfc/rfc4880.txt}. + +@item @anchor{RFC4211}[RFC4211] +J. Schaad, "Internet X.509 Public Key Infrastructure Certificate +Request Message Format (CRMF)", September 2005, Available from +@url{http://www.ietf.org/rfc/rfc4211.txt}. + +@item @anchor{RFC2817}[RFC2817] +Rohit Khare and Scott Lawrence, "Upgrading to TLS Within HTTP/1.1", +May 2000, Available from @url{http://www.ietf.org/rfc/rfc2817.txt} + +@item @anchor{RFC2818}[RFC2818] +Eric Rescorla, "HTTP Over TLS", May 2000, Available from +@url{http://www.ietf/rfc/rfc2818.txt}. + +@item @anchor{RFC2945}[RFC2945] +Tom Wu, "The SRP Authentication and Key Exchange System", September +2000, Available from @url{http://www.ietf.org/rfc/rfc2945.txt}. + +@item @anchor{RFC2986}[RFC2986] +Magnus Nystrom and Burt Kaliski, "PKCS 10 v1.7: Certification Request +Syntax Specification", November 2000, Available from +@url{http://www.ietf.org/rfc/rfc2986.txt}. + +@item @anchor{PKIX}[PKIX] +D. Cooper, S. Santesson, S. Farrel, S. Boeyen, R. Housley, W. Polk, +"Internet X.509 Public Key Infrastructure Certificate and Certificate +Revocation List (CRL) Profile", May 2008, available from +@url{http://www.ietf.org/rfc/rfc5280.txt}. + +@item @anchor{RFC3749}[RFC3749] +Scott Hollenbeck, "Transport Layer Security Protocol Compression +Methods", May 2004, available from +@url{http://www.ietf.org/rfc/rfc3749.txt}. + +@item @anchor{RFC3820}[RFC3820] +Steven Tuecke, Von Welch, Doug Engert, Laura Pearlman, and Mary +Thompson, "Internet X.509 Public Key Infrastructure (PKI) Proxy +Certificate Profile", June 2004, available from +@url{http://www.ietf.org/rfc/rfc3820}. + +@item @anchor{RFC5746}[RFC5746] +E. Rescorla, M. Ray, S. Dispensa, and N. Oskov, "Transport Layer +Security (TLS) Renegotiation Indication Extension", February 2010, +available from @url{http://www.ietf.org/rfc/rfc5746}. + +@item @anchor{TLSTKT}[TLSTKT] +Joseph Salowey, Hao Zhou, Pasi Eronen, Hannes Tschofenig, "Transport +Layer Security (TLS) Session Resumption without Server-Side State", +January 2008, available from @url{http://www.ietf.org/rfc/rfc5077}. + +@item @anchor{PKCS12}[PKCS12] +RSA Laboratories, "PKCS 12 v1.0: Personal Information Exchange +Syntax", June 1999, Available from @url{http://www.rsa.com}. + +@item @anchor{RESCORLA}[RESCORLA] +Eric Rescorla, "SSL and TLS: Designing and Building Secure Systems", +2001 + +@item @anchor{SELKEY}[SELKEY] +Arjen Lenstra and Eric Verheul, "Selecting Cryptographic Key Sizes", +2003, available from @url{http://www.win.tue.nl/~klenstra/key.pdf}. + +@item @anchor{SSL3}[SSL3] +Alan Freier, Philip Karlton and Paul Kocher, "The SSL Protocol Version +3.0", November 1996, Available from +@url{http://wp.netscape.com/eng/ssl3/draft302.txt}. + +@item @anchor{STEVENS}[STEVENS] +Richard Stevens, "UNIX Network Programming, Volume 1", Prentice Hall +PTR, January 1998 + +@item @anchor{TLSEXT}[TLSEXT] +Simon Blake-Wilson, Magnus Nystrom, David Hopwood, Jan Mikkelsen and +Tim Wright, "Transport Layer Security (TLS) Extensions", June 2003, +Available from @url{http://www.ietf.org/rfc/rfc3546.txt}. + +@item @anchor{TLSPGP}[TLSPGP] +Nikos Mavrogiannopoulos, "Using OpenPGP keys for TLS authentication", +April 2004, November 2007. Available from +@url{http://www.ietf.org/rfc/rfc5081.txt}. + +@item @anchor{TLSSRP}[TLSSRP] +David Taylor, Trevor Perrin, Tom Wu and Nikos Mavrogiannopoulos, +"Using SRP for TLS Authentication", November 2007. Available from +@url{http://www.ietf.org/rfc/rfc5054.txt}. + +@item @anchor{TLSPSK}[TLSPSK] +Pasi Eronen and Hannes Tschofenig, "Pre-shared key Ciphersuites for +TLS", December 2005, Available from +@url{http://www.ietf.org/rfc/rfc4279.txt}. + +@item @anchor{TOMSRP}[TOMSRP] +Tom Wu, "The Stanford SRP Authentication Project", Available at +@url{http://srp.stanford.edu/}. + +@item @anchor{WEGER}[WEGER] +Arjen Lenstra and Xiaoyun Wang and Benne de Weger, "Colliding X.509 +Certificates", Cryptology ePrint Archive, Report 2005/067, Available +at @url{http://eprint.iacr.org/}. + +@end table diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi new file mode 100644 index 0000000000..7b76857eff --- /dev/null +++ b/doc/cha-cert-auth.texi @@ -0,0 +1,626 @@ +@node More on certificate authentication +@chapter More on Certificate Authentication +@anchor{Certificate Authentication} +@cindex Certificate authentication + +@menu +* The X.509 trust model:: +* The OpenPGP trust model:: +* Digital signatures:: +* PKCS #11 tokens:: +@end menu + +@node The X.509 trust model +@section The @acronym{X.509} Trust Model +@cindex @acronym{X.509} certificates + +The @acronym{X.509} protocols rely on a hierarchical trust model. In +this trust model Certification Authorities (CAs) are used to certify +entities. Usually more than one certification authorities exist, and +certification authorities may certify other authorities to issue +certificates as well, following a hierarchical model. + +@image{gnutls-x509,7cm,9.5cm} + +One needs to trust one or more CAs for his secure communications. In +that case only the certificates issued by the trusted authorities are +acceptable. See the figure above for a typical example. The API for +handling @acronym{X.509} certificates is described at section +@ref{sec:x509api}. Some examples are listed below. + +@menu +* X.509 certificates:: +* Verifying X.509 certificate paths:: +* PKCS #10 certificate requests:: +* PKCS #12 structures:: +@end menu + +@node X.509 certificates +@subsection @acronym{X.509} Certificates + +An @acronym{X.509} certificate usually contains information about the +certificate holder, the signer, a unique serial number, expiration +dates and some other fields @xcite{PKIX} as shown in the table below. + +@table @code + +@item version: +The field that indicates the version of the certificate. + +@item serialNumber: +This field holds a unique serial number per certificate. + +@item issuer: +Holds the issuer's distinguished name. + +@item validity: +The activation and expiration dates. + +@item subject: +The subject's distinguished name of the certificate. + +@item extensions: +The extensions are fields only present in version 3 certificates. + +@end table + +The certificate's @emph{subject or issuer name} is not just a single +string. It is a Distinguished name and in the @acronym{ASN.1} +notation is a sequence of several object IDs with their corresponding +values. Some of available OIDs to be used in an @acronym{X.509} +distinguished name are defined in @file{gnutls/x509.h}. + +The @emph{Version} field in a certificate has values either 1 or 3 for +version 3 certificates. Version 1 certificates do not support the +extensions field so it is not possible to distinguish a CA from a +person, thus their usage should be avoided. + +The @emph{validity} dates are there to indicate the date that the +specific certificate was activated and the date the certificate's key +would be considered invalid. + +Certificate @emph{extensions} are there to include information about +the certificate's subject that did not fit in the typical certificate +fields. Those may be e-mail addresses, flags that indicate whether the +belongs to a CA etc. All the supported @acronym{X.509} version 3 +extensions are shown in the table below. + +@table @code + +@item subject key id (2.5.29.14): +An identifier of the key of the subject. + +@item authority key id (2.5.29.35): +An identifier of the authority's key used to sign the certificate. + +@item subject alternative name (2.5.29.17): +Alternative names to subject's distinguished name. + +@item key usage (2.5.29.15): +Constraints the key's usage of the certificate. + +@item extended key usage (2.5.29.37): +Constraints the purpose of the certificate. + +@item basic constraints (2.5.29.19): +Indicates whether this is a CA certificate or not, and specify the +maximum path lengths of certificate chains. + +@item CRL distribution points (2.5.29.31): +This extension is set by the CA, in order to inform about the issued +CRLs. + +@item Proxy Certification Information (1.3.6.1.5.5.7.1.14): +Proxy Certificates includes this extension that contains the OID of +the proxy policy language used, and can specify limits on the maximum +lengths of proxy chains. Proxy Certificates are specified in +@xcite{RFC3820}. + +@end table + +In @acronym{GnuTLS} the @acronym{X.509} certificate structures are +handled using the @code{gnutls_x509_crt_t} type and the corresponding +private keys with the @code{gnutls_x509_privkey_t} type. All the +available functions for @acronym{X.509} certificate handling have +their prototypes in @file{gnutls/x509.h}. An example program to +demonstrate the @acronym{X.509} parsing capabilities can be found at +section @ref{ex:x509-info}. + +@node Verifying X.509 certificate paths +@subsection Verifying @acronym{X.509} Certificate Paths +@cindex Verifying certificate paths + +Verifying certificate paths is important in @acronym{X.509} +authentication. For this purpose the function +@ref{gnutls_x509_crt_verify} is provided. The output of this function +is the bitwise OR of the elements of the +@code{gnutls_certificate_status_t} enumeration. A detailed +description of these elements can be found in figure below. The +function @ref{gnutls_certificate_verify_peers2} is equivalent to the +previous one, and will verify the peer's certificate in a TLS session. + +@table @code + +@item GNUTLS_CERT_INVALID: +The certificate is not signed by one of the known authorities, or +the signature is invalid. + +@item GNUTLS_CERT_REVOKED: +The certificate has been revoked by its CA. + +@item GNUTLS_CERT_SIGNER_NOT_FOUND: +The certificate's issuer is not known. This is the case when the +issuer is not in the trusted certificates list. + +@item GNUTLS_CERT_SIGNER_NOT_CA: +The certificate's signer was not a CA. This may happen if +this was a version 1 certificate, which is common with some CAs, or +a version 3 certificate without the basic constrains extension. + +@anchor{GNUTLS_CERT_INSECURE_ALGORITHM} +@item GNUTLS_CERT_INSECURE_ALGORITHM: +The certificate was signed using an insecure algorithm such as MD2 or +MD5. These algorithms have been broken and should not be trusted. + +@end table + +There is also to possibility to pass some input to the verification +functions in the form of flags. For @ref{gnutls_x509_crt_verify} the +flags are passed straightforward, but +@ref{gnutls_certificate_verify_peers2} depends on the flags set by +calling @ref{gnutls_certificate_set_verify_flags}. All the available +flags are part of the enumeration +@ref{gnutls_certificate_verify_flags} and are explained in the table +below. + +@anchor{gnutls_certificate_verify_flags} +@tindex gnutls_certificate_verify_flags +@table @code +@item GNUTLS_VERIFY_DISABLE_CA_SIGN: +If set a signer does not have to be a certificate authority. This +flag should normaly be disabled, unless you know what this means. + +@item GNUTLS_VERIFY_ALLOW_X509_V1_CA_CRT: +Allow only trusted CA certificates that have version 1. This is +safer than GNUTLS_VERIFY_ALLOW_ANY_X509_V1_CA_CRT, and should be +used instead. That way only signers in your trusted list will be +allowed to have certificates of version 1. + +@item GNUTLS_VERIFY_ALLOW_ANY_X509_V1_CA_CRT: +Allow CA certificates that have version 1 (both root and +intermediate). This is dangerous since those haven't the +basicConstraints extension. Must be used in combination with +GNUTLS_VERIFY_ALLOW_X509_V1_CA_CRT. + +@item GNUTLS_VERIFY_DO_NOT_ALLOW_SAME: +If a certificate is not signed by anyone trusted but exists in +the trusted CA list do not treat it as trusted. + +@item GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2: +Allow certificates to be signed using the old MD2 algorithm. + +@item GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5: +Allow certificates to be signed using the broken MD5 algorithm. +@end table + +Although the verification of a certificate path indicates that the +certificate is signed by trusted authority, does not reveal anything +about the peer's identity. It is required to verify if the +certificate's owner is the one you expect. For more information +consult @xcite{RFC2818} and section @ref{ex:verify} for an example. + +@node PKCS #10 certificate requests +@subsection @acronym{PKCS} #10 Certificate Requests +@cindex Certificate requests +@cindex @acronym{PKCS} #10 + +A certificate request is a structure, which contain information about +an applicant of a certificate service. It usually contains a private +key, a distinguished name and secondary data such as a challenge +password. @acronym{GnuTLS} supports the requests defined in +@acronym{PKCS} #10 @xcite{RFC2986}. Other certificate request's format +such as PKIX's @xcite{RFC4211} are not currently supported. + +In @acronym{GnuTLS} the @acronym{PKCS} #10 structures are handled +using the @code{gnutls_x509_crq_t} type. An example of a certificate +request generation can be found at section @ref{ex:crq}. + +@node PKCS #12 structures +@subsection @acronym{PKCS} #12 Structures +@cindex @acronym{PKCS} #12 + +A @acronym{PKCS} #12 structure @xcite{PKCS12} usually contains a user's +private keys and certificates. It is commonly used in browsers to +export and import the user's identities. + +In @acronym{GnuTLS} the @acronym{PKCS} #12 structures are handled +using the @code{gnutls_pkcs12_t} type. This is an abstract type that +may hold several @code{gnutls_pkcs12_bag_t} types. The Bag types are +the holders of the actual data, which may be certificates, private +keys or encrypted data. An Bag of type encrypted should be decrypted +in order for its data to be accessed. + +An example of a @acronym{PKCS} #12 structure generation can be found +at section @ref{ex:pkcs12}. + +@node The OpenPGP trust model +@section The @acronym{OpenPGP} Trust Model +@cindex @acronym{OpenPGP} Keys + +The @acronym{OpenPGP} key authentication relies on a distributed trust +model, called the ``web of trust''. The ``web of trust'' uses a +decentralized system of trusted introducers, which are the same as a +CA. @acronym{OpenPGP} allows anyone to sign anyone's else public +key. When Alice signs Bob's key, she is introducing Bob's key to +anyone who trusts Alice. If someone trusts Alice to introduce keys, +then Alice is a trusted introducer in the mind of that observer. + +@image{gnutls-pgp,11cm,9cm} + +For example: If David trusts Alice to be an introducer, and Alice +signed Bob's key, Dave also trusts Bob's key to be the real one. + +There are some key points that are important in that model. In the +example Alice has to sign Bob's key, only if she is sure that the key +belongs to Bob. Otherwise she may also make Dave falsely believe that +this is Bob's key. Dave has also the responsibility to know who to +trust. This model is similar to real life relations. + +Just see how Charlie behaves in the previous example. Although he has +signed Bob's key - because he knows, somehow, that it belongs to Bob - +he does not trust Bob to be an introducer. Charlie decided to trust +only Kevin, for some reason. A reason could be that Bob is lazy +enough, and signs other people's keys without being sure that they +belong to the actual owner. + +@subsection @acronym{OpenPGP} Keys + +In @acronym{GnuTLS} the @acronym{OpenPGP} key structures +@xcite{RFC2440} are handled using the @code{gnutls_openpgp_crt_t} type +and the corresponding private keys with the +@code{gnutls_openpgp_privkey_t} type. All the prototypes for the key +handling functions can be found at @file{gnutls/openpgp.h}. + +@subsection Verifying an @acronym{OpenPGP} Key + +The verification functions of @acronym{OpenPGP} keys, included in +@acronym{GnuTLS}, are simple ones, and do not use the features of the +``web of trust''. For that reason, if the verification needs are +complex, the assistance of external tools like @acronym{GnuPG} and +GPGME (@url{http://www.gnupg.org/related_software/gpgme/}) is +recommended. + +There is one verification function in @acronym{GnuTLS}, the +@ref{gnutls_openpgp_crt_verify_ring}. This checks an +@acronym{OpenPGP} key against a given set of public keys (keyring) and +returns the key status. The key verification status is the same as in +@acronym{X.509} certificates, although the meaning and interpretation +are different. For example an @acronym{OpenPGP} key may be valid, if +the self signature is ok, even if no signers were found. The meaning +of verification status is shown in the figure below. + +@table @code + +@item CERT_INVALID: +A signature on the key is invalid. That means that the key was +modified by somebody, or corrupted during transport. + +@item CERT_REVOKED: +The key has been revoked by its owner. + +@item CERT_SIGNER_NOT_FOUND: +The key was not signed by a known signer. + +@item GNUTLS_CERT_INSECURE_ALGORITHM: +The certificate was signed using an insecure algorithm such as MD2 or +MD5. These algorithms have been broken and should not be trusted. + +@end table + +@node Digital signatures +@section Digital Signatures +@cindex Digital signatures + +In this section we will provide some information about digital +signatures, how they work, and give the rationale for disabling some +of the algorithms used. + +Digital signatures work by using somebody's secret key to sign some +arbitrary data. Then anybody else could use the public key of that +person to verify the signature. Since the data may be arbitrary it is +not suitable input to a cryptographic digital signature algorithm. For +this reason and also for performance cryptographic hash algorithms are +used to preprocess the input to the signature algorithm. This works as +long as it is difficult enough to generate two different messages with +the same hash algorithm output. In that case the same signature could +be used as a proof for both messages. Nobody wants to sign an innocent +message of donating 1 @euro{} to Greenpeace and find out that he +donated 1.000.000 @euro{} to Bad Inc. + +For a hash algorithm to be called cryptographic the following three +requirements must hold: + +@enumerate +@item Preimage resistance. +That means the algorithm must be one way and given the output of the +hash function @math{H(x)}, it is impossible to calculate @math{x}. + +@item 2nd preimage resistance. +That means that given a pair @math{x,y} with @math{y=H(x)} it is +impossible to calculate an @math{x'} such that @math{y=H(x')}. + +@item Collision resistance. +That means that it is impossible to calculate random @math{x} and +@math{x'} such @math{H(x')=H(x)}. +@end enumerate + +The last two requirements in the list are the most important in +digital signatures. These protect against somebody who would like to +generate two messages with the same hash output. When an algorithm is +considered broken usually it means that the Collision resistance of +the algorithm is less than brute force. Using the birthday paradox the +brute force attack takes +@iftex +@math{2^{(\rm{hash\ size}) / 2}} +@end iftex +@ifnottex +@math{2^{((hash size) / 2)}} +@end ifnottex +operations. Today colliding certificates using the MD5 hash algorithm +have been generated as shown in @xcite{WEGER}. + +There has been cryptographic results for the SHA-1 hash algorithms as +well, although they are not yet critical. Before 2004, MD5 had a +presumed collision strength of @math{2^{64}}, but it has been showed +to have a collision strength well under @math{2^{50}}. As of November +2005, it is believed that SHA-1's collision strength is around +@math{2^{63}}. We consider this sufficiently hard so that we still +support SHA-1. We anticipate that SHA-256/386/512 will be used in +publicly-distributed certificates in the future. When @math{2^{63}} +can be considered too weak compared to the computer power available +sometime in the future, SHA-1 will be disabled as well. The collision +attacks on SHA-1 may also get better, given the new interest in tools +for creating them. + +@subsection Trading Security for Interoperability + +If you connect to a server and use GnuTLS' functions to verify the +certificate chain, and get a @ref{GNUTLS_CERT_INSECURE_ALGORITHM} +validation error (@pxref{Verifying X.509 certificate paths}), it means +that somewhere in the certificate chain there is a certificate signed +using @code{RSA-MD2} or @code{RSA-MD5}. These two digital signature +algorithms are considered broken, so GnuTLS fail when attempting to +verify the certificate. In some situations, it may be useful to be +able to verify the certificate chain anyway, assuming an attacker did +not utilize the fact that these signatures algorithms are broken. +This section will give help on how to achieve that. + +First, it is important to know that you do not have to enable any of +the flags discussed here to be able to use trusted root CA +certificates signed using @code{RSA-MD2} or @code{RSA-MD5}. The only +attack today is that it is possible to generate certificates with +colliding signatures (collision resistance); you cannot generate a +certificate that has the same signature as an already existing +signature (2nd preimage resistance). + +If you are using @ref{gnutls_certificate_verify_peers2} to verify the +certificate chain, you can call +@ref{gnutls_certificate_set_verify_flags} with the +@code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2} or +@code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5} flag, as in: + +@example + gnutls_certificate_set_verify_flags (x509cred, + GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5); +@end example + +This will tell the verifier algorithm to enable @code{RSA-MD5} when +verifying the certificates. + +If you are using @ref{gnutls_x509_crt_verify} or +@ref{gnutls_x509_crt_list_verify}, you can pass the +@code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5} parameter directly in the +@code{flags} parameter. + +If you are using these flags, it may also be a good idea to warn the +user when verification failure occur for this reason. The simplest is +to not use the flags by default, and only fall back to using them +after warning the user. If you wish to inspect the certificate chain +yourself, you can use @ref{gnutls_certificate_get_peers} to extract +the raw server's certificate chain, then use +@ref{gnutls_x509_crt_import} to parse each of the certificates, and +then use @ref{gnutls_x509_crt_get_signature_algorithm} to find out the +signing algorithm used for each certificate. If any of the +intermediary certificates are using @code{GNUTLS_SIGN_RSA_MD2} or +@code{GNUTLS_SIGN_RSA_MD5}, you could present a warning. + + +@node PKCS #11 tokens +@section @acronym{PKCS #11} tokens +@anchor{sec:pkcs11} +@cindex @acronym{PKCS #11} tokens + +@subsection Introduction +This section copes with the @acronym{PKCS #11} support in @acronym{GnuTLS}. +@acronym{PKCS #11} is plugin API allowing applications to access cryptographic +operations on a token, as well as to objects residing on the token. A token can +be a real hardware token such as a smart card, or it can be a software component +such as @acronym{Gnome Keyring}. The objects residing on such token can be +certificates, public keys, private keys or even plain data or secret keys. Of those +certificates and public/private key pairs can be used with @acronym{GnuTLS}. It's +main advantage is that it allows operations on private key objects such as decryption +and signing without accessing the key itself. + +@subsection Initialization +To allow all the @acronym{GnuTLS} applications to access @acronym{PKCS #11} tokens +it is adviceable to use @code{/etc/gnutls/pkcs11.conf}. This file has the following +format: + +@verbatim +load=/usr/lib/opensc-pkcs11.so +load=/usr/lib/gnome-keyring/gnome-keyring-pkcs11.so +@end verbatim + +If you use this file, then there is no need for other initialization in +@acronym{GnuTLS}, except for the PIN and token functions, to allow retrieving a PIN +when accessing a protected object, such as a private key, or allowing probing +the user to insert the token. All the initialization functions are below. + +@itemize + +@item @ref{gnutls_pkcs11_init}: Global initialization + +@item @ref{gnutls_pkcs11_deinit}: Global deinitialization + +@item @ref{gnutls_pkcs11_set_token_function}: Sets the token insertion function + +@item @ref{gnutls_pkcs11_set_pin_function}: Sets the PIN request function + +@item @ref{gnutls_pkcs11_add_provider}: Adds an additional @acronym{PKCS #11} provider + +@end itemize + +@subsection Reading Objects + +All @acronym{PKCS #11} objects are referenced by @acronym{GnuTLS} functions by +URLs as described in @code{draft-pechanec-pkcs11uri-01}. For example a public +key on a smart card may be referenced as: + +@example +pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315;manufacturer=EnterSafe;\ +object=test1;objecttype=public;\ +id=32:f1:53:f3:e3:79:90:b0:86:24:14:10:77:ca:5d:ec:2d:15:fa:ed +@end example + +while the smart card itself can be referenced as: +@example +pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315;manufacturer=EnterSafe +@end example + + +Objects can be accessed with the following functions +@itemize + +@item @ref{gnutls_pkcs11_obj_init}: Initializes an object + +@item @ref{gnutls_pkcs11_obj_import_url}: To import an object from a url + +@item @ref{gnutls_pkcs11_obj_export_url}: To export the URL of the object + +@item @ref{gnutls_pkcs11_obj_deinit}: To deinitialize an object + +@item @ref{gnutls_pkcs11_obj_export}: To export data associated with object + +@item @ref{gnutls_pkcs11_obj_get_info}: To obtain information about an object + +@item @ref{gnutls_pkcs11_obj_list_import_url}: To mass load of objects + +@item @ref{gnutls_x509_crt_import_pkcs11}: Import a certificate object + +@item @ref{gnutls_x509_crt_import_pkcs11_url}: Helper function to directly import a URL into a certificate + +@item @ref{gnutls_x509_crt_list_import_pkcs11}: Mass import of certificates + +@end itemize + + +Functions that relate to token handling are shown below +@itemize + +@item @ref{gnutls_pkcs11_token_get_url}: Returns the URL of a token + +@item @ref{gnutls_pkcs11_token_get_info}: Obtain information about a token + +@item @ref{gnutls_pkcs11_token_get_flags}: Returns flags about a token (i.e. hardware or software) + +@end itemize + +The following example will list all tokens. +@verbatim +int i; +char* url; + + gnutls_global_init(); + + for (i=0;;i++) { + ret = gnutls_pkcs11_token_get_url(i, &url); + if (ret == GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE) + break; + + if (ret < 0) + exit(1); + + fprintf(stdout, "Token[%d]: URL: %s\n", i, url); + } + gnutls_global_deinit(); +@end verbatim + + +The next one will list all objects in a token: +@verbatim +gnutls_pkcs11_obj_t *obj_list; +unsigned int obj_list_size = 0; +gnutls_datum_t cinfo; +int i; + + crt_list_size = 0; + ret = gnutls_pkcs11_obj_list_import_url( crt_list, NULL, url, \ + GNUTLS_PKCS11_OBJ_ATTR_CRT_WITH_PRIVKEY); + if (ret < 0 && ret != GNUTLS_E_SHORT_MEMORY_BUFFER) + exit(1); + + crt_list = malloc(sizeof(*crt_list)*crt_list_size); + if (crt_list == NULL) + exit(1); + + ret = gnutls_pkcs11_obj_list_import_url( crt_list, &crt_list_size, url, flags); + if (ret < 0) + exit(1); + + /* now all certificates are in crt_list */ + + for (i=0;i<crt_list_size;i++) { + + ret = gnutls_x509_crt_init(&xcrt); + if (ret < 0) + exit(1); + + ret = gnutls_x509_crt_import_pkcs11(xcrt, crt_list[i]); + if (ret < 0) + exit(1); + + ret = gnutls_x509_crt_print (xcrt, GNUTLS_CRT_PRINT_FULL, &cinfo); + if (ret < 0) + exit(1); + + fprintf(stdout, "cert[%d]:\n %s\n\n", cinfo.data); + + gnutls_free(cinfo.data); + gnutls_x509_crt_deinit(&xcrt); + } +@end verbatim + + +@subsection Writing Objects + +With @acronym{GnuTLS} you can copy existing private keys and certificates +to a token. This can be achieved with the following functions + +@itemize + +@item @ref{gnutls_pkcs11_delete_url}: To delete an object + +@item @ref{gnutls_pkcs11_copy_x509_privkey}: To copy a private key to a token + +@item @ref{gnutls_pkcs11_copy_x509_crt}: To copy a certificate to a token + +@end itemize + + +@subsection Using a @acronym{PKCS #11} token with TLS + +This example will demonstrate how to load keys and certificates +from a @acronym{PKCS} #11 token, and use it with a TLS connection. + +@verbatiminclude examples/ex-cert-select-pkcs11.c + diff --git a/doc/cha-ciphersuites.texi b/doc/cha-ciphersuites.texi new file mode 100644 index 0000000000..e0fad2218f --- /dev/null +++ b/doc/cha-ciphersuites.texi @@ -0,0 +1,44 @@ +@node All the supported ciphersuites in GnuTLS +@chapter All the Supported Ciphersuites in @acronym{GnuTLS} +@anchor{ciphersuites} +@cindex Ciphersuites + +@include algorithms.texi + +Some additional information regarding some of the algorithms: + +@table @code +@item RSA +RSA is public key cryptosystem designed by Ronald Rivest, Adi Shamir +and Leonard Adleman. It can be used with any hash functions. + +@item DSA +DSA is the USA's Digital Signature Standard. It uses only the SHA-1 +hash algorithm. + +@item MD2 +MD2 is a cryptographic hash algorithm designed by Ron Rivest. It is +optimized for 8-bit processors. Outputs 128 bits of data. There are +no known weaknesses of this algorithm but since this algorithm is +rarely used and not really studied it should not be used today. + +@item MD5 +MD5 is a cryptographic hash algorithm designed by Ron Rivest. Outputs +128 bits of data. It is considered to be broken. + +@item SHA-1 +SHA is a cryptographic hash algorithm designed by NSA. Outputs 160 +bits of data. It is also considered to be broken, though no practical +attacks have been found. + +@item RMD160 +RIPEMD is a cryptographic hash algorithm developed in the framework of +the EU project RIPE. Outputs 160 bits of data. + +@end table + +@c +@c Guile Bindings +@c + +@include guile.texi diff --git a/doc/cha-copying.texi b/doc/cha-copying.texi new file mode 100644 index 0000000000..d35dd92e55 --- /dev/null +++ b/doc/cha-copying.texi @@ -0,0 +1,29 @@ +@node Copying Information +@appendix Copying Information + +@menu +* GNU Free Documentation License:: License for copying this manual. +* GNU LGPL:: License for copying the core GnuTLS library. +* GNU GPL:: License for copying GnuTLS-extra and tools. +@end menu + +@node GNU Free Documentation License +@appendixsec GNU Free Documentation License + +@cindex FDL, GNU Free Documentation License + +@include fdl-1.3.texi + +@node GNU LGPL +@appendixsec GNU Lesser General Public License +@cindex LGPL, GNU Lesser General Public License +@cindex License, GNU LGPL + +@include lgpl-2.1.texi + +@node GNU GPL +@appendixsec GNU General Public License +@cindex GPL, GNU General Public License +@cindex License, GNU GPL + +@include gpl-3.0.texi diff --git a/doc/cha-functions.texi b/doc/cha-functions.texi new file mode 100644 index 0000000000..f73bc571e9 --- /dev/null +++ b/doc/cha-functions.texi @@ -0,0 +1,120 @@ +@node Function reference +@chapter Function Reference +@cindex Function reference + +@menu +* Core functions:: +* X.509 certificate functions:: +* GnuTLS-extra functions:: +* OpenPGP functions:: +* TLS Inner Application (TLS/IA) functions:: +* Error codes and descriptions:: +@end menu + +@node Core functions +@section Core Functions + +The prototypes for the following functions lie in +@file{gnutls/gnutls.h}. + +@include gnutls-api.texi + +@node X.509 certificate functions +@section @acronym{X.509} Certificate Functions +@anchor{sec:x509api} +@cindex @acronym{X.509} Functions + +The following functions are to be used for @acronym{X.509} certificate handling. +Their prototypes lie in @file{gnutls/x509.h}. + +@include x509-api.texi + +@node GnuTLS-extra functions +@section @acronym{GnuTLS-extra} Functions +@cindex @acronym{GnuTLS-extra} functions + +These functions are only available in the GPLv3+ version of the +library called @code{gnutls-extra}. The prototypes for this library +lie in @file{gnutls/extra.h}. + +@include extra-api.texi + +@node OpenPGP functions +@section @acronym{OpenPGP} Functions +@cindex @acronym{OpenPGP} functions +@anchor{sec:openpgpapi} + +The following functions are to be used for @acronym{OpenPGP} +certificate handling. Their prototypes lie in +@file{gnutls/openpgp.h}. + +@include pgp-api.texi + +@node TLS Inner Application (TLS/IA) functions +@section @acronym{TLS} Inner Application (@acronym{TLS/IA}) Functions +@cindex @acronym{TLS} Inner Application (@acronym{TLS/IA}) functions +@cindex Inner Application (@acronym{TLS/IA}) functions + +The following functions are used for @acronym{TLS} Inner Application +(@acronym{TLS/IA}). Their prototypes lie in @file{gnutls/extra.h}. +You need to link with @file{libgnutls-extra} to be able to use these +functions (@pxref{GnuTLS-extra functions}). + +The typical control flow in an TLS/IA client (that would not require +an Application Phase for resumed sessions) would be similar to the +following: + +@example +int client_avp (gnuls_session_t *session, void *ptr, + const char *last, size_t lastlen, + char **new, size_t *newlen) +@{ +... +@} +... +int main () +@{ + gnutls_ia_client_credentials_t iacred; +... + gnutls_init (&session, GNUTLS_CLIENT); +... + /* Enable TLS/IA. */ + gnutls_ia_allocate_client_credentials(&iacred); + gnutls_ia_set_client_avp_function(iacred, client_avp); + gnutls_credentials_set (session, GNUTLS_CRD_IA, iacred); +... + ret = gnutls_handshake (session); + // Error handling... +... + if (gnutls_ia_handshake_p (session)) + @{ + ret = gnutls_ia_handshake (session); + // Error handling... +... +@end example + +See below for detailed descriptions of all the functions used above. + +The function @code{client_avp} would have to be implemented by your +application. The function is responsible for handling the AVP data. +See @code{gnutls_ia_set_client_avp_function} below for more +information on how that function should be implemented. + +The control flow in a typical server is similar to the above, use +@code{gnutls_ia_server_credentials_t} instead of +@code{gnutls_ia_client_credentials_t}, and replace the call to the +client functions with the corresponding server functions. + +@include ia-api.texi + +@node Error codes and descriptions +@section Error Codes and Descriptions +@anchor{Error Codes} +@cindex Error codes + +The error codes used throughout the library are described below. The +return code @code{GNUTLS_E_SUCCESS} indicate successful operation, and +is guaranteed to have the value 0, so you can use it in logical +expressions. + +@include error_codes.texi diff --git a/doc/cha-internals.texi b/doc/cha-internals.texi new file mode 100644 index 0000000000..fda6221699 --- /dev/null +++ b/doc/cha-internals.texi @@ -0,0 +1,336 @@ +@node Internal architecture of GnuTLS +@chapter Internal Architecture of GnuTLS +@cindex Internal architecture + +This chapter is to give a brief description of the +way @acronym{GnuTLS} works. The focus is to give an idea +to potential developers and those who want to know what +happens inside the black box. + +@menu +* The TLS Protocol:: +* TLS Handshake Protocol:: +* TLS Authentication Methods:: +* TLS Extension Handling:: +* Certificate Handling:: +* Cryptographic Backend:: +@end menu + +@node The TLS Protocol +@section The TLS Protocol +The main needs for the TLS protocol to be used are +shown in the image below. + +@image{gnutls-client-server-use-case,9cm} + +This is being accomplished by the following object diagram. +Note that since @acronym{GnuTLS} is being developed in C +object are just structures with attributes. The operations listed +are functions that require the first parameter to be that object. +@image{gnutls-objects,15cm} + +@node TLS Handshake Protocol +@section TLS Handshake Protocol +The @acronym{GnuTLS} handshake protocol is implemented as a state +machine that waits for input or returns immediately when the non-blocking +transport layer functions are used. The main idea is shown in the following +figure. + +@image{gnutls-handshake-state,9cm} + +Also the way the input is processed varies per ciphersuite. Several +implementations of the internal handlers are available and +@ref{gnutls_handshake} only multiplexes the input to the appropriate +handler. For example a @acronym{PSK} ciphersuite has a different +implementation of the @code{process_client_key_exchange} than a +certificate ciphersuite. + +@image{gnutls-handshake-sequence,12cm} + +@node TLS Authentication Methods +@section TLS Authentication Methods +In @acronym{GnuTLS} authentication methods can be implemented quite +easily. Since the required changes to add a new authentication method +affect only the handshake protocol, a simple interface is used. An +authentication method needs only to implement the functions as seen in +the figure below. + +@image{gnutls-mod_auth_st,12cm} + +The functions that need to be implemented are the ones responsible for +interpreting the handshake protocol messages. It is common for such +functions to read data from one or more @code{credentials_t} +structures@footnote{such as the +@code{gnutls_certificate_credentials_t} structures} and write data, +such as certificates, usernames etc. to @code{auth_info_t} structures. + +Simple examples of existing authentication methods can be seen in +@code{auth_psk.c} for PSK ciphersuites and @code{auth_srp.c} for SRP +ciphersuites. After implementing these functions the structure holding +its pointers has to be registered in @code{gnutls_algorithms.c} in the +@code{_gnutls_kx_algorithms} structure. + +@node TLS Extension Handling +@section TLS Extension Handling +As with authentication methods, the TLS extensions handlers can be +implemented using the following interface. + +@image{gnutls-extensions_st,12cm} + +Here there are two functions, one for receiving the extension data +and one for sending. These functions have to check internally whether +they operate in client or server side. + +A simple example of an extension handler can be seen in +@code{ext_srp.c} After implementing these functions, together with the +extension number they handle, they have to be registered in +@code{gnutls_extensions.c} in the @code{_gnutls_extensions} structure. + +@subsection Adding a New TLS Extension + +Adding support for a new TLS extension is done from time to time, and +the process to do so is not difficult. Here are the steps you need to +follow if you wish to do this yourself. For sake of discussion, let's +consider adding support for the hypothetical TLS extension +@code{foobar}. + +@enumerate + +@item Add @code{configure} option like @code{--enable-foobar} or @code{--disable-foobar}. + +Which to chose depends on whether you intend to make the extension be +enabled by default. Look at existing checks (i.e., SRP, authz) for +how to model the code. For example: + +@example +AC_MSG_CHECKING([whether to disable foobar support]) +AC_ARG_ENABLE(foobar, + AS_HELP_STRING([--disable-foobar], + [disable foobar support]), + ac_enable_foobar=no) +if test x$ac_enable_foobar != xno; then + AC_MSG_RESULT(no) + AC_DEFINE(ENABLE_FOOBAR, 1, [enable foobar]) +else + ac_full=0 + AC_MSG_RESULT(yes) +fi +AM_CONDITIONAL(ENABLE_FOOBAR, test "$ac_enable_foobar" != "no") +@end example + +These lines should go in @code{lib/m4/hooks.m4}. + +@item Add IANA extension value to @code{extensions_t} in @code{gnutls_int.h}. + +A good name for the value would be GNUTLS_EXTENSION_FOOBAR. Check +with @url{http://www.iana.org/assignments/tls-extensiontype-values} +for allocated values. For experiments, you could pick a number but +remember that some consider it a bad idea to deploy such modified +version since it will lead to interoperability problems in the future +when the IANA allocates that number to someone else, or when the +foobar protocol is allocated another number. + +@item Add an entry to @code{_gnutls_extensions} in @code{gnutls_extensions.c}. + +A typical entry would be: + +@example + int ret; + + /* ... + */ + +#if ENABLE_FOOBAR + ret = gnutls_ext_register (GNUTLS_EXTENSION_FOOBAR, + "FOOBAR", + GNUTLS_EXT_TLS, + _gnutls_foobar_recv_params, + _gnutls_foobar_send_params); + if (ret != GNUTLS_E_SUCCESS) + return ret; +#endif +@end example + +The GNUTLS_EXTENSION_FOOBAR is the integer value you added to +@code{gnutls_int.h} earlier. The two functions are new functions that +you will need to implement, most likely you'll need to add an +@code{#include "ext_foobar.h"} as well. + +@item Add new files @code{ext_foobar.c} and @code{ext_foobar.h} that implements the extension. + +The functions you are responsible to add are those mentioned in the +previous step. As a starter, you could add this: + +@example +int +_gnutls_foobar_recv_params (gnutls_session_t session, + const opaque * data, + size_t data_size) +@{ + return 0; +@} + +int +_gnutls_foobar_send_params (gnutls_session_t session, + opaque * data, + size_t _data_size) +@{ + return 0; +@} +@end example + +The @code{_gnutls_foobar_recv_params} function is responsible for +parsing incoming extension data (both in the client and server). + +The @code{_gnutls_foobar_send_params} function is responsible for +sending extension data (both in the client and server). + +If you receive length fields that doesn't match, return +@code{GNUTLS_E_UNEXPECTED_PACKET_LENGTH}. If you receive invalid +data, return @code{GNUTLS_E_RECEIVED_ILLEGAL_PARAMETER}. You can use +other error codes too. Return 0 on success. + +The function typically store some information in the @code{session} +variable for later usage. If you need to add new fields there, check +@code{tls_ext_st} in @code{gnutls_int.h} and compare with existing TLS +extension specific variables. + +Recall that both the client and server both send and receives +parameters, and your code most likely will need to do different things +depending on which mode it is in. It may be useful to make this +distinction explicit in the code. Thus, for example, a better +template than above would be: + +@example +int +_gnutls_foobar_recv_params (gnutls_session_t session, + const opaque * data, + size_t data_size) +@{ + if (session->security_parameters.entity == GNUTLS_CLIENT) + return foobar_recv_client (session, data, data_size); + else + return foobar_recv_server (session, data, data_size); +@} + +int +_gnutls_foobar_send_params (gnutls_session_t session, + opaque * data, + size_t data_size) +@{ + if (session->security_parameters.entity == GNUTLS_CLIENT) + return foobar_send_client (session, data, data_size); + else + return foobar_send_server (session, data, data_size); +@} +@end example + +The functions used would be declared as @code{static} functions, of +the appropriate prototype, in the same file. + +When adding the files, you'll need to add them to @code{Makefile.am} +as well, for example: + +@example +if ENABLE_FOOBAR +COBJECTS += ext_foobar.c +HFILES += ext_foobar.h +endif +@end example + +@item Add API functions to enable/disable the extension. + +Normally the client will have one API to request use of the extension, +and setting some extension specific data. The server will have one +API to let the library know that it is willing to accept the +extension, often this is implemented through a callback but it doesn't +have to. + +The APIs need to be added to @code{includes/gnutls/gnutls.h} or +@code{includes/gnutls/extra.h} as appropriate. It is recommended that +if you don't have a requirement to use the LGPLv2.1+ license for your +extension, that you place your work under the GPLv3+ license and thus +in the libgnutls-extra library. + +You can implement the API function in the @code{ext_foobar.c} file, or +if that file ends up becoming rather larger, add a +@code{gnutls_foobar.c} file. + +To make the API available in the shared library you need to add the +symbol in @code{lib/libgnutls.map} or +@code{libextra/libgnutls-extra.map} as appropriate, so that the symbol +is exported properly. + +When writing GTK-DOC style documentation for your new APIs, don't +forget to add @code{Since:} tags to indicate the GnuTLS version the +API was introduced in. + +@end enumerate + +@node Certificate Handling +@section Certificate Handling +What is provided by the certificate handling functions +is summarized in the following diagram. + +@image{gnutls-certificate-user-use-case,12cm} + +@node Cryptographic Backend +@section Cryptographic Backend +Several new systems provide hardware assisted cryptographic algorithm +implementations that offer implementations some orders of magnitude +faster than the software. For this reason GnuTLS supports by default +the /dev/crypto device usually found in FreeBSD and OpenBSD system, to +take advantage of installed hardware. + +In addition it is possible to override parts of the crypto backend or the +whole. It is possible to override them both at runtime and compile +time, however here we will discuss the runtime possibility. The API +available for this functionality is in @code{gnutls/crypto.h} header +file. + +@subsection Override specific algorithms +When an optimized implementation of a single algorithm is available, +say a hardware assisted version of @acronym{AES-CBC} then the +following functions can be used to register those algorithms. + +@itemize + +@item @ref{gnutls_crypto_single_cipher_register2} +To register a cipher algorithm. + +@ref{gnutls_crypto_single_digest_register2} +To register a hash (digest) or MAC algorithm. + +@end itemize + +Those registration functions will only replace the specified algorithm +and leave the rest of subsystem intact. + +@subsection Override parts of the backend +In some systems, such as embedded ones, it might be desirable to +override big parts of the cryptographic backend, or even all of +them. For this reason the following functions are provided. + +@itemize + +@item @ref{gnutls_crypto_cipher_register2} +To override the cryptographic algorithms backend. + +@item @ref{gnutls_crypto_digest_register2} +To override the digest algorithms backend. + +@item @ref{gnutls_crypto_rnd_register2} +To override the random number generator backend. + +@item @ref{gnutls_crypto_bigint_register2} +To override the big number number operations backend. + +@item @ref{gnutls_crypto_pk_register2} +To override the public key encryption backend. This is tight to the +big number operations so either both of them should be updated or care +must be taken to use the same format. + +@end itemize + +If all of them are used then GnuTLS will no longer use libgcrypt. + diff --git a/doc/cha-intro-tls.texi b/doc/cha-intro-tls.texi new file mode 100644 index 0000000000..f7b88d07a1 --- /dev/null +++ b/doc/cha-intro-tls.texi @@ -0,0 +1,783 @@ +@node Introduction to TLS +@chapter Introduction to @acronym{TLS} + +@acronym{TLS} stands for ``Transport Layer Security'' and is the +successor of SSL, the Secure Sockets Layer protocol @xcite{SSL3} +designed by Netscape. @acronym{TLS} is an Internet protocol, defined +by @acronym{IETF}@footnote{IETF, or Internet Engineering Task Force, +is a large open international community of network designers, +operators, vendors, and researchers concerned with the evolution of +the Internet architecture and the smooth operation of the Internet. +It is open to any interested individual.}, described in @acronym{RFC} +4346 and also in @xcite{RESCORLA}. The protocol provides +confidentiality, and authentication layers over any reliable transport +layer. The description, below, refers to @acronym{TLS} 1.0 but also +applies to @acronym{TLS} 1.1 @xcite{RFC4346} and @acronym{SSL} 3.0, +since the differences of these protocols are minor. Older protocols +such as @acronym{SSL} 2.0 are not discussed nor implemented in +@acronym{GnuTLS} since they are not considered secure today. GnuTLS +also supports @acronym{X.509} and @acronym{OpenPGP} @xcite{RFC4880}. + +@menu +* TLS layers:: +* The transport layer:: +* The TLS record protocol:: +* The TLS Alert Protocol:: +* The TLS Handshake Protocol:: +* TLS Extensions:: +* Selecting cryptographic key sizes:: +* On SSL 2 and older protocols:: +* On Record Padding:: +* Safe Renegotiation:: +@end menu + +@node TLS layers +@section TLS Layers +@cindex TLS Layers + +@acronym{TLS} is a layered protocol, and consists of the Record +Protocol, the Handshake Protocol and the Alert Protocol. The Record +Protocol is to serve all other protocols and is above the transport +layer. The Record protocol offers symmetric encryption, data +authenticity, and optionally compression. + +The Alert protocol offers some signaling to the other protocols. It +can help informing the peer for the cause of failures and other error +conditions. @xref{The Alert Protocol}, for more information. The +alert protocol is above the record protocol. + +The Handshake protocol is responsible for the security parameters' +negotiation, the initial key exchange and authentication. @xref{The +Handshake Protocol}, for more information about the handshake +protocol. The protocol layering in TLS is shown in the figure below. + +@image{gnutls-layers,12cm,8cm} + +@node The transport layer +@section The Transport Layer +@cindex Transport protocol + +@acronym{TLS} is not limited to one transport layer, it can be used +above any transport layer, as long as it is a reliable one. A set of +functions is provided and their purpose is to load to @acronym{GnuTLS} the +required callbacks to access the transport layer. + +@itemize +@item @ref{gnutls_transport_set_push_function} +@item @ref{gnutls_transport_set_pull_function} +@item @ref{gnutls_transport_set_ptr} +@item @ref{gnutls_transport_set_lowat} +@item @ref{gnutls_transport_set_errno} +@end itemize + +These functions accept a callback function as a parameter. The +callback functions should return the number of bytes written, or -1 on +error and should set @code{errno} appropriately. + +In some environments, setting @code{errno} is unreliable, for example +Windows have several errno variables in different CRTs, or it may be +that errno is not a thread-local variable. If this is a concern to +you, call @code{gnutls_transport_set_errno} with the intended errno +value instead of setting @code{errno} directly. + +@acronym{GnuTLS} currently only interprets the EINTR and EAGAIN errno +values and returns the corresponding @acronym{GnuTLS} error codes +@code{GNUTLS_E_INTERRUPTED} and @code{GNUTLS_E_AGAIN}. These values +are usually returned by interrupted system calls, or when non blocking +IO is used. All @acronym{GnuTLS} functions can be resumed (called +again), if any of these error codes is returned. The error codes +above refer to the system call, not the @acronym{GnuTLS} function, +since signals do not interrupt @acronym{GnuTLS}' functions. + +For non blocking sockets or other custom made pull/push functions +the @ref{gnutls_transport_set_lowat} must be called, with a zero +low water mark value. + +By default, if the transport functions are not set, @acronym{GnuTLS} +will use the Berkeley Sockets functions. In this case +@acronym{GnuTLS} will use some hacks in order for @code{select} to +work, thus making it easy to add @acronym{TLS} support to existing +TCP/IP servers. + +@node The TLS record protocol +@section The TLS Record Protocol +@cindex Record protocol + +The Record protocol is the secure communications provider. Its purpose +is to encrypt, authenticate and ---optionally--- compress packets. +The following functions are available: + +@table @asis + +@item @ref{gnutls_record_send}: +To send a record packet (with application data). + +@item @ref{gnutls_record_recv}: +To receive a record packet (with application data). + +@item @ref{gnutls_record_get_direction}: +To get the direction of the last interrupted function call. +@end table + +As you may have already noticed, the functions which access the Record +protocol, are quite limited, given the importance of this protocol in +@acronym{TLS}. This is because the Record protocol's parameters are +all set by the Handshake protocol. + +The Record protocol initially starts with NULL parameters, which means +no encryption, and no MAC is used. Encryption and authentication begin +just after the handshake protocol has finished. + +@menu +* Encryption algorithms used in the record layer:: +* Compression algorithms used in the record layer:: +* Weaknesses and countermeasures:: +@end menu + +@node Encryption algorithms used in the record layer +@subsection Encryption Algorithms Used in the Record Layer +@cindex Symmetric encryption algorithms + +Confidentiality in the record layer is achieved by using symmetric +block encryption algorithms like @code{3DES}, @code{AES}@footnote{AES, +or Advanced Encryption Standard, is actually the RIJNDAEL algorithm. +This is the algorithm that replaced DES.}, or stream algorithms like +@code{ARCFOUR_128}@footnote{@code{ARCFOUR_128} is a compatible +algorithm with RSA's RC4 algorithm, which is considered to be a trade +secret.}. Ciphers are encryption algorithms that use a single, secret, +key to encrypt and decrypt data. Block algorithms in TLS also provide +protection against statistical analysis of the data. Thus, if you're +using the @acronym{TLS} protocol, a random number of blocks will be +appended to data, to prevent eavesdroppers from guessing the actual +data size. + +Supported cipher algorithms: + +@table @code +@item 3DES_CBC +@code{3DES_CBC} is the DES block cipher algorithm used with triple +encryption (EDE). Has 64 bits block size and is used in CBC mode. + +@item ARCFOUR_128 +ARCFOUR is a fast stream cipher. + +@item ARCFOUR_40 +This is the ARCFOUR cipher that is fed with a 40 bit key, +which is considered weak. + +@item AES_CBC +AES or RIJNDAEL is the block cipher algorithm that replaces the old +DES algorithm. Has 128 bits block size and is used in CBC mode. This +is not officially supported in TLS. +@end table + +Supported MAC algorithms: + +@table @code +@item MAC_MD5 +MD5 is a cryptographic hash algorithm designed by Ron Rivest. Outputs +128 bits of data. + +@item MAC_SHA +SHA is a cryptographic hash algorithm designed by NSA. Outputs 160 +bits of data. + +@end table + +@node Compression algorithms used in the record layer +@subsection Compression Algorithms Used in the Record Layer +@cindex Compression algorithms + +The TLS record layer also supports compression. The algorithms +implemented in @acronym{GnuTLS} can be found in the table below. +All the algorithms except for DEFLATE which is +referenced in @xcite{RFC3749}, should be considered as +@acronym{GnuTLS}' extensions@footnote{You should use +@ref{gnutls_handshake_set_private_extensions} to enable private +extensions.}, and should be advertised only when the peer is known to +have a compliant client, to avoid interoperability problems. + +The included algorithms perform really good when text, or other +compressible data are to be transfered, but offer nothing on already +compressed data, such as compressed images, zipped archives etc. +These compression algorithms, may be useful in high bandwidth TLS +tunnels, and in cases where network usage has to be minimized. As a +drawback, compression increases latency. + +The record layer compression in @acronym{GnuTLS} is implemented based +on the proposal @xcite{RFC3749}. +The supported compression algorithms are: + +@table @code +@item DEFLATE +Zlib compression, using the deflate algorithm. + +@item LZO +LZO is a very fast compression algorithm. This algorithm is only +available if the @acronym{GnuTLS-extra} library has been initialized +and the private extensions are enabled, and if GnuTLS was built with +LZO support. + +@end table + +@node Weaknesses and countermeasures +@subsection Weaknesses and Countermeasures + +Some weaknesses that may affect the security of the Record layer have +been found in @acronym{TLS} 1.0 protocol. These weaknesses can be +exploited by active attackers, and exploit the facts that + +@enumerate + +@item +@acronym{TLS} has separate alerts for ``decryption_failed'' and +``bad_record_mac'' + +@item +The decryption failure reason can be detected by timing the response +time. + +@item +The IV for CBC encrypted packets is the last block of the previous +encrypted packet. + +@end enumerate + +Those weaknesses were solved in @acronym{TLS} 1.1 @xcite{RFC4346} +which is implemented in @acronym{GnuTLS}. For a detailed discussion +see the archives of the TLS Working Group mailing list and the paper +@xcite{CBCATT}. + +@node The TLS Alert Protocol +@section The TLS Alert Protocol +@anchor{The Alert Protocol} +@cindex Alert protocol + +The Alert protocol is there to allow signals to be sent between peers. +These signals are mostly used to inform the peer about the cause of a +protocol failure. Some of these signals are used internally by the +protocol and the application protocol does not have to cope with them +(see @code{GNUTLS_A_CLOSE_NOTIFY}), and others refer to the +application protocol solely (see @code{GNUTLS_A_USER_CANCELLED}). An +alert signal includes a level indication which may be either fatal or +warning. Fatal alerts always terminate the current connection, and +prevent future renegotiations using the current session ID. + +The alert messages are protected by the record protocol, thus the +information that is included does not leak. You must take extreme care +for the alert information not to leak to a possible attacker, via +public log files etc. + +@table @asis +@item @ref{gnutls_alert_send}: +To send an alert signal. + +@item @ref{gnutls_error_to_alert}: +To map a gnutls error number to an alert signal. + +@item @ref{gnutls_alert_get}: +Returns the last received alert. + +@item @ref{gnutls_alert_get_name}: +Returns the name, in a character array, of the given alert. + +@end table + +@node The TLS Handshake Protocol +@section The TLS Handshake Protocol +@anchor{The Handshake Protocol} +@cindex Handshake protocol + +The Handshake protocol is responsible for the ciphersuite negotiation, +the initial key exchange, and the authentication of the two peers. +This is fully controlled by the application layer, thus your program +has to set up the required parameters. Available functions to control +the handshake protocol include: + +@table @asis +@item @ref{gnutls_priority_init}: +To initialize a priority set of ciphers. + +@item @ref{gnutls_priority_deinit}: +To deinitialize a priority set of ciphers. + +@item @ref{gnutls_priority_set}: +To associate a priority set with a @acronym{TLS} session. + +@item @ref{gnutls_priority_set_direct}: +To directly associate a session with a given priority string. + +@item @ref{gnutls_credentials_set}: +To set the appropriate credentials structures. + +@item @ref{gnutls_certificate_server_set_request}: +To set whether client certificate is required or not. + +@item @ref{gnutls_handshake}: +To initiate the handshake. +@end table + +@subsection TLS Cipher Suites + +The Handshake Protocol of @acronym{TLS} negotiates cipher suites of +the form @code{TLS_DHE_RSA_WITH_3DES_CBC_SHA}. The usual cipher +suites contain these parameters: + +@itemize + +@item The key exchange algorithm. +@code{DHE_RSA} in the example. + +@item The Symmetric encryption algorithm and mode +@code{3DES_CBC} in this example. + +@item The MAC@footnote{MAC stands for Message Authentication Code. It can be described as a keyed hash algorithm. See RFC2104.} algorithm used for authentication. +@code{MAC_SHA} is used in the above example. + +@end itemize + +The cipher suite negotiated in the handshake protocol will affect the +Record Protocol, by enabling encryption and data authentication. Note +that you should not over rely on @acronym{TLS} to negotiate the +strongest available cipher suite. Do not enable ciphers and algorithms +that you consider weak. + +The priority functions, dicussed above, allow the application layer to +enable and set priorities on the individual ciphers. It may imply that +all combinations of ciphersuites are allowed, but this is not +true. For several reasons, not discussed here, some combinations were +not defined in the @acronym{TLS} protocol. The supported ciphersuites +are shown in @ref{ciphersuites}. + +@subsection Client Authentication +@cindex Client Certificate authentication + +In the case of ciphersuites that use certificate authentication, the +authentication of the client is optional in @acronym{TLS}. A server +may request a certificate from the client --- using the +@ref{gnutls_certificate_server_set_request} function. If a certificate +is to be requested from the client during the handshake, the server +will send a certificate request message that contains a list of +acceptable certificate signers. In @acronym{GnuTLS} the certificate +signers list is constructed using the trusted Certificate Authorities +by the server. That is the ones set using +@itemize +@item @ref{gnutls_certificate_set_x509_trust_file} +@item @ref{gnutls_certificate_set_x509_trust_mem} +@end itemize + +Sending of the names of the CAs can be controlled using +@ref{gnutls_certificate_send_x509_rdn_sequence}. The client, then, may +send a certificate, signed by one of the server's acceptable signers. + +@subsection Resuming Sessions +@anchor{resume} +@cindex Resuming sessions + +The @ref{gnutls_handshake} function, is expensive since a lot of +calculations are performed. In order to support many fast connections +to the same server a client may use session resuming. @strong{Session +resuming} is a feature of the @acronym{TLS} protocol which allows a +client to connect to a server, after a successful handshake, without +the expensive calculations. This is achieved by using the previously +established keys. @acronym{GnuTLS} supports this feature, and the +example (@pxref{ex:resume-client}) illustrates a typical use of it. + +Keep in mind that sessions are expired after some time, for security +reasons, thus it may be normal for a server not to resume a session +even if you requested that. Also note that you must enable, using the +priority functions, at least the algorithms used in the last session. + +@subsection Resuming Internals + +The resuming capability, mostly in the server side, is one of the +problems of a thread-safe TLS implementations. The problem is that all +threads must share information in order to be able to resume +sessions. The gnutls approach is, in case of a client, to leave all +the burden of resuming to the client. I.e., copy and keep the +necessary parameters. See the functions: + +@itemize + +@item @ref{gnutls_session_get_data} + +@item @ref{gnutls_session_get_id} + +@item @ref{gnutls_session_set_data} + +@end itemize + +The server side is different. A server has to specify some callback +functions which store, retrieve and delete session data. These can be +registered with: + +@itemize + +@item @ref{gnutls_db_set_remove_function} + +@item @ref{gnutls_db_set_store_function} + +@item @ref{gnutls_db_set_retrieve_function} + +@item @ref{gnutls_db_set_ptr} + +@end itemize + +It might also be useful to be able to check for expired sessions in +order to remove them, and save space. The function +@ref{gnutls_db_check_entry} is provided for that reason. + +@node TLS Extensions +@section TLS Extensions +@cindex TLS Extensions + +A number of extensions to the @acronym{TLS} protocol have been +proposed mainly in @xcite{TLSEXT}. The extensions supported +in @acronym{GnuTLS} are: + +@itemize +@item Maximum fragment length negotiation +@item Server name indication +@item Session tickets +@end itemize + +and they will be discussed in the subsections that follow. + +@subsection Maximum Fragment Length Negotiation +@cindex TLS Extensions +@cindex Maximum fragment length + +This extension allows a @acronym{TLS} implementation to negotiate a +smaller value for record packet maximum length. This extension may be +useful to clients with constrained capabilities. See the +@ref{gnutls_record_set_max_size} and the +@ref{gnutls_record_get_max_size} functions. + +@subsection Server Name Indication +@anchor{serverind} +@cindex TLS Extensions +@cindex Server name indication + +A common problem in @acronym{HTTPS} servers is the fact that the +@acronym{TLS} protocol is not aware of the hostname that a client +connects to, when the handshake procedure begins. For that reason the +@acronym{TLS} server has no way to know which certificate to send. + +This extension solves that problem within the @acronym{TLS} protocol, +and allows a client to send the HTTP hostname before the handshake +begins within the first handshake packet. The functions +@ref{gnutls_server_name_set} and @ref{gnutls_server_name_get} can be +used to enable this extension, or to retrieve the name sent by a +client. + +@subsection Session Tickets +@cindex TLS Extensions +@cindex Session Tickets +@cindex Ticket + +To resume a TLS session the server normally store some state. This +complicates deployment, and typical situations the client can cache +information and send it to the server instead. The Session Ticket +extension implements this idea, and it is documented in +RFC 5077 @xcite{TLSTKT}. + +Clients can enable support for TLS tickets with +@ref{gnutls_session_ticket_enable_client} and servers use +@ref{gnutls_session_ticket_key_generate} to generate a key and +@ref{gnutls_session_ticket_enable_server} to enable the extension. +Clients resume sessions using the ticket using the normal session +resume functions, @ref{resume}. + +@node Selecting cryptographic key sizes +@section Selecting Cryptographic Key Sizes +@cindex key sizes + +In TLS, since a lot of algorithms are involved, it is not easy to set +a consistent security level. For this reason this section will +present some correspondance between key sizes of symmetric algorithms +and public key algorithms based on the most conservative values of +@xcite{SELKEY}. Those can be used to generate certificates with +appropriate key sizes as well as parameters for Diffie-Hellman and SRP +authentication. + +@multitable @columnfractions .15 .20 .20 .20 + +@item Year +@tab Symmetric key size +@tab RSA key size, DH and SRP prime size +@tab ECC key size + +@item 1982 +@tab 56 +@tab 417 +@tab 105 + +@item 1988 +@tab 61 +@tab 566 +@tab 114 + +@item 2002 +@tab 72 +@tab 1028 +@tab 139 + +@item 2015 +@tab 82 +@tab 1613 +@tab 173 + +@item 2028 +@tab 92 +@tab 2362 +@tab 210 + +@item 2040 +@tab 101 +@tab 3214 +@tab 244 + +@item 2050 +@tab 109 +@tab 4047 +@tab 272 + +@end multitable + +The first column provides an estimation of the year until these +parameters are considered safe and the rest of the columns list the +parameters for the various algorithms. + +Note however that the values suggested here are nothing more than an +educated guess that is valid today. There are no guarrantees that an +algorithm will remain unbreakable or that these values will remain +constant in time. There could be scientific breakthroughs that cannot +be predicted or total failure of the current public key systems by +quantum computers. On the other hand though the cryptosystems used in +TLS are selected in a conservative way and such catastrophic +breakthroughs or failures are believed to be unlikely. + +NIST publication SP 800-57 @xcite{NISTSP80057} contains a similar +table that extends beyond the key sizes given above. + +@multitable @columnfractions .15 .20 .20 .20 + +@item Bits of security +@tab Symmetric key algorithms +@tab RSA key size, DSA, DH and SRP prime size +@tab ECC key size + +@item 80 +@tab 2TDEA +@tab 1024 +@tab 160-223 + +@item 112 +@tab 3DES +@tab 2048 +@tab 224-255 + +@item 128 +@tab AES-128 +@tab 3072 +@tab 256-383 + +@item 192 +@tab AES-192 +@tab 7680 +@tab 384-511 + +@item 256 +@tab AES-256 +@tab 15360 +@tab 512+ + +@end multitable + +The recommendations are fairly consistent. + +@node On SSL 2 and older protocols +@section On SSL 2 and Older Protocols +@cindex SSL 2 + +One of the initial decisions in the @acronym{GnuTLS} development was +to implement the known security protocols for the transport layer. +Initially @acronym{TLS} 1.0 was implemented since it was the latest at +that time, and was considered to be the most advanced in security +properties. Later the @acronym{SSL} 3.0 protocol was implemented +since it is still the only protocol supported by several servers and +there are no serious security vulnerabilities known. + +One question that may arise is why we didn't implement @acronym{SSL} +2.0 in the library. There are several reasons, most important being +that it has serious security flaws, unacceptable for a modern security +library. Other than that, this protocol is barely used by anyone +these days since it has been deprecated since 1996. The security +problems in @acronym{SSL} 2.0 include: + +@itemize + +@item Message integrity compromised. +The @acronym{SSLv2} message authentication uses the MD5 function, and +is insecure. + +@item Man-in-the-middle attack. +There is no protection of the handshake in @acronym{SSLv2}, which +permits a man-in-the-middle attack. + +@item Truncation attack. +@acronym{SSLv2} relies on TCP FIN to close the session, so the +attacker can forge a TCP FIN, and the peer cannot tell if it was a +legitimate end of data or not. + +@item Weak message integrity for export ciphers. +The cryptographic keys in @acronym{SSLv2} are used for both message +authentication and encryption, so if weak encryption schemes are +negotiated (say 40-bit keys) the message authentication code use the +same weak key, which isn't necessary. + +@end itemize + +@cindex PCT +Other protocols such as Microsoft's @acronym{PCT} 1 and @acronym{PCT} +2 were not implemented because they were also abandoned and deprecated +by @acronym{SSL} 3.0 and later @acronym{TLS} 1.0. + +@node On Record Padding +@section On Record Padding +@cindex Record padding +@cindex Bad record MAC + +The TLS protocol allows for random padding of records, to make it more +difficult to perform analysis on the length of exchanged messages. +(In RFC 4346 this is specified in section 6.2.3.2.) GnuTLS appears to +be one of few implementation that take advantage of this text, and pad +records by a random length. + +The TLS implementation in the Symbian operating system, frequently +used by Nokia and Sony-Ericsson mobile phones, cannot handle +non-minimal record padding. What happens when one of these clients +handshake with a GnuTLS server is that the client will fail to compute +the correct MAC for the record. The client sends a TLS alert +(@code{bad_record_mac}) and disconnects. Typically this will result +in error messages such as 'A TLS fatal alert has been received', 'Bad +record MAC', or both, on the GnuTLS server side. + +GnuTLS implements a work around for this problem. However, it has to +be enabled specifically. It can be enabled by using +@ref{gnutls_record_disable_padding}, or @ref{gnutls_priority_set} with +the @code{%COMPAT} priority string. + +If you implement an application that have a configuration file, we +recommend that you make it possible for users or administrators to +specify a GnuTLS protocol priority string, which is used by your +application via @ref{gnutls_priority_set}. To allow the best +flexibility, make it possible to have a different priority string for +different incoming IP addresses. + +To enable the workaround in the @code{gnutls-cli} client or the +@code{gnutls-serv} server, for testing of other implementations, use +the following parameter: @code{--priority "%COMPAT"}. + +This problem has been discussed on mailing lists and in bug reports. +This section tries to collect all pieces of information that we know +about the problem. If you wish to go back to the old discussions, +here are some links: + +@url{http://bugs.debian.org/390712} + +@url{http://bugs.debian.org/402861} + +@url{http://bugs.debian.org/438137} + +@url{http://thread.gmane.org/gmane.ietf.tls/3079} + +@node Safe Renegotiation +@section Safe Renegotiation +@cindex renegotiation + +Some application protocols and implementations uses the TLS +renegotiation feature in a manner that enables attackers to insert +content of his choice in the beginning of a TLS session. + +One easy to understand vulnerability is HTTPS when servers request +client certificates optionally for certain parts of a web site. The +attack works by having the attacker simulate a client and connect to a +server, with server-only authentication, and send some data intended +to cause harm. When the proper client attempts to contact the server, +the attacker hijacks that connection and uses the TLS renegotiation +feature with the server and splices in the client connection to the +already established connection between the attacker and server. The +attacker will not be able to read the data exchanged between the +client and the server. However, the server will (incorrectly) assume +that the data sent by the attacker was sent by the now authenticated +client. The result is a prefix plain-text injection attack. + +The above is just one example. Other vulnerabilities exists that do +not rely on the TLS renegotiation to change the client's authenticated +status (either TLS or application layer). + +While fixing these application protocols and implementations would be +one natural reaction, an extension to TLS has been designed that +cryptographically binds together any renegotiated handshakes with the +initial negotiation. When the extension is used, the attack is +detected and the session can be terminated. The extension is +specified in @xcite{RFC5746}. + +GnuTLS supports the safe renegotiation extension. The default +behavior is as follows. Clients will attempt to negotiate the safe +renegotiation extension when talking to servers. Servers will accept +the extension when presented by clients. Clients and servers will +permit an initial handshake to complete even when the other side does +not support the safe renegotiation extension. Clients and servers +will refuse renegotiation attempts when the extension has not been +negotiated. + +Note that permitting clients to connect to servers even when the safe +renegotiation extension is not negotiated open up for some attacks. +Changing this default behaviour would prevent interoperability against +the majority of deployed servers out there. We will reconsider this +default behaviour in the future when more servers have been upgraded. +Note that it is easy to configure clients to always require the safe +renegotiation extension from servers (see below on the +%SAFE_RENEGOTIATION priority string). + + +To modify the default behaviour, we have introduced some new priority +strings. The priority strings can be used by applications +(@pxref{gnutls_priority_set}) and end users (e.g., @code{--priority} +parameter to @code{gnutls-cli} and @code{gnutls-serv}). + +The @code{%UNSAFE_RENEGOTIATION} priority string permits +(re-)handshakes even when the safe renegotiation extension was not +negotiated. The @code{%SAFE_RENEGOTIATION} priority string makes +client require the extension for every handshake and servers will refuse +renegotiation without it. + +To enforce your clients to upgrade to a version that supports safe +renegotiation the %INITIAL_SAFE_RENEGOTIATION priority string should +be used at server side. This will deny any (re-)handshakes unless the +client supports the extension. This however will prevent all clients +that do not support the extension from connecting to server, even if +they do not use renegotiation. + +It is possible to disable use of the extension completely, in both +clients and servers, by using the @code{%DISABLE_SAFE_RENEGOTIATION} +priority string however we strongly recommend you to only do this for +debugging and test purposes. + +The default values if the flags above are not specified are: +@table @code + +@item Server: +%SAFE_RENEGOTIATION + +@item Client: +%UNSAFE_RENEGOTIATION + +@end table + +For applications we have introduced a new API related to safe +renegotiation. The @ref{gnutls_safe_renegotiation_status} function is +used to check if the extension has been negotiated on a session, and +can be used both by clients and servers. diff --git a/doc/cha-library.texi b/doc/cha-library.texi new file mode 100644 index 0000000000..9213ea69d7 --- /dev/null +++ b/doc/cha-library.texi @@ -0,0 +1,188 @@ +@node The Library +@chapter The Library + +In brief @acronym{GnuTLS} can be described as a library which offers an API +to access secure communication protocols. These protocols provide +privacy over insecure lines, and were designed to prevent +eavesdropping, tampering, or message forgery. + +Technically @acronym{GnuTLS} is a portable ANSI C based library which +implements the TLS 1.1 and SSL 3.0 protocols (@xref{Introduction to +TLS}, for a more detailed description of the protocols), accompanied +with the required framework for authentication and public key +infrastructure. Important features of the @acronym{GnuTLS} library +include: + +@itemize + +@item Support for TLS 1.0, TLS 1.1, and SSL 3.0 protocols. + +@item Support for both @acronym{X.509} and @acronym{OpenPGP} certificates. + +@item Support for handling and verification of certificates. + +@item Support for @acronym{SRP} for TLS authentication. + +@item Support for @acronym{PSK} for TLS authentication. + +@item Support for TLS Extension mechanism. + +@item Support for TLS Compression Methods. + +@end itemize + +Additionally @acronym{GnuTLS} provides a limited emulation API for the +widely used OpenSSL@footnote{@url{http://www.openssl.org/}} library, +to ease integration with existing applications. + +@acronym{GnuTLS} consists of three independent parts, namely the ``TLS +protocol part'', the ``Certificate part'', and the ``Cryptographic +backend'' part. The `TLS protocol part' is the actual protocol +implementation, and is entirely implemented within the +@acronym{GnuTLS} library. The `Certificate part' consists of the +certificate parsing, and verification functions which is partially +implemented in the @acronym{GnuTLS} library. The +@acronym{Libtasn1}@footnote{@url{ftp://ftp.gnupg.org/gcrypt/alpha/gnutls/libtasn1/}}, +a library which offers @acronym{ASN.1} parsing capabilities, is used +for the @acronym{X.509} certificate parsing functions. A smaller +version of +@acronym{OpenCDK}@footnote{@url{ftp://ftp.gnupg.org/gcrypt/alpha/gnutls/opencdk/}} +is used for the @acronym{OpenPGP} key support in @acronym{GnuTLS}. +The ``Cryptographic backend'' is provided by the +@acronym{Libgcrypt}@footnote{@url{ftp://ftp.gnupg.org/gcrypt/alpha/libgcrypt/}} +library@footnote{On current versions of GnuTLS it is possible to +override the default crypto backend. Check @pxref{Cryptographic +Backend} for details}. + +In order to ease integration in embedded systems, parts of the +@acronym{GnuTLS} library can be disabled at compile time. That way a +small library, with the required features, can be generated. + +@menu +* General Idea:: +* Error handling:: +* Memory handling:: +* Callback functions:: +@end menu + +@node General Idea +@section General Idea + +A brief description of how @acronym{GnuTLS} works internally is shown +at the figure below. This section may be easier to understand after +having seen the examples (@pxref{examples}). + +@image{gnutls-internals,12cm,8cm} + +As shown in the figure, there is a read-only global state that is +initialized once by the global initialization function. This global +structure, among others, contains the memory allocation functions +used, and some structures needed for the @acronym{ASN.1} parser. This +structure is never modified by any @acronym{GnuTLS} function, except +for the deinitialization function which frees all memory allocated in +the global structure and is called after the program has permanently +finished using @acronym{GnuTLS}. + +The credentials structure is used by some authentication methods, such +as certificate authentication (@pxref{Certificate Authentication}). A +credentials structure may contain certificates, private keys, +temporary parameters for Diffie-Hellman or RSA key exchange, and other +stuff that may be shared between several TLS sessions. + +This structure should be initialized using the appropriate +initialization functions. For example an application which uses +certificate authentication would probably initialize the credentials, +using the appropriate functions, and put its trusted certificates in +this structure. The next step is to associate the credentials +structure with each @acronym{TLS} session. + +A @acronym{GnuTLS} session contains all the required stuff for a +session to handle one secure connection. This session calls directly +to the transport layer functions, in order to communicate with the +peer. Every session has a unique session ID shared with the peer. + +Since TLS sessions can be resumed, servers would probably need a +database backend to hold the session's parameters. Every +@acronym{GnuTLS} session after a successful handshake calls the +appropriate backend function (@xref{resume}, for information on +initialization) to store the newly negotiated session. The session +database is examined by the server just after having received the +client hello@footnote{The first message in a @acronym{TLS} handshake}, +and if the session ID sent by the client, matches a stored session, +the stored session will be retrieved, and the new session will be a +resumed one, and will share the same session ID with the previous one. + +@node Error handling +@section Error Handling + +In @acronym{GnuTLS} most functions return an integer type as a result. +In almost all cases a zero or a positive number means success, and a +negative number indicates failure, or a situation that some action has +to be taken. Thus negative error codes may be fatal or not. + +Fatal errors terminate the connection immediately and further sends +and receives will be disallowed. An example of a fatal error code is +@code{GNUTLS_E_DECRYPTION_FAILED}. Non-fatal errors may warn about +something, i.e., a warning alert was received, or indicate the some +action has to be taken. This is the case with the error code +@code{GNUTLS_E_REHANDSHAKE} returned by @ref{gnutls_record_recv}. +This error code indicates that the server requests a re-handshake. The +client may ignore this request, or may reply with an alert. You can +test if an error code is a fatal one by using the +@ref{gnutls_error_is_fatal}. + +If any non fatal errors, that require an action, are to be returned by +a function, these error codes will be documented in the function's +reference. @xref{Error Codes}, for all the error codes. + +@node Memory handling +@section Memory Handling + +@acronym{GnuTLS} internally handles heap allocated objects +differently, depending on the sensitivity of the data they +contain. However for performance reasons, the default memory functions +do not overwrite sensitive data from memory, nor protect such objects +from being written to the swap. In order to change the default +behavior the @ref{gnutls_global_set_mem_functions} function is +available which can be used to set other memory handlers than the +defaults. + +The @acronym{Libgcrypt} library on which @acronym{GnuTLS} depends, has +such secure memory allocation functions available. These should be +used in cases where even the system's swap memory is not considered +secure. See the documentation of @acronym{Libgcrypt} for more +information. + +@node Callback functions +@section Callback Functions +@cindex Callback functions + +There are several cases where @acronym{GnuTLS} may need some out of +band input from your program. This is now implemented using some +callback functions, which your program is expected to register. + +An example of this type of functions are the push and pull callbacks +which are used to specify the functions that will retrieve and send +data to the transport layer. + +@itemize + +@item @ref{gnutls_transport_set_push_function} + +@item @ref{gnutls_transport_set_pull_function} + +@end itemize + +Other callback functions such as the one set by +@ref{gnutls_srp_set_server_credentials_function}, may require more +complicated input, including data to be allocated. These callbacks +should allocate and free memory using the functions shown below. + +@itemize + +@item @ref{gnutls_malloc} + +@item @ref{gnutls_free} + +@end itemize + diff --git a/doc/cha-preface.texi b/doc/cha-preface.texi new file mode 100644 index 0000000000..1c4058bf45 --- /dev/null +++ b/doc/cha-preface.texi @@ -0,0 +1,257 @@ +@node Preface +@chapter Preface + +This document tries to demonstrate and explain the @acronym{GnuTLS} +library API. A brief introduction to the protocols and the technology +involved, is also included so that an application programmer can +better understand the @acronym{GnuTLS} purpose and actual offerings. +Even if @acronym{GnuTLS} is a typical library software, it operates +over several security and cryptographic protocols, which require the +programmer to make careful and correct usage of them, otherwise he +risks to offer just a false sense of security. Security and the +network security terms are very general terms even for computer +software thus cannot be easily restricted to a single cryptographic +library. For that reason, do not consider a program secure just +because it uses @acronym{GnuTLS}; there are several ways to compromise +a program or a communication line and @acronym{GnuTLS} only helps with +some of them. + +Although this document tries to be self contained, basic network +programming and PKI knowlegde is assumed in most of it. A good +introduction to networking can be found in @xcite{STEVENS} and for +Public Key Infrastructure in @xcite{GUTPKI}. + +@anchor{Availability} + +Updated versions of the @acronym{GnuTLS} software and this document +will be available from @url{http://www.gnutls.org/} and +@url{http://www.gnu.org/software/gnutls/}. + +@menu +* Getting help:: +* Commercial Support:: +* Downloading and Installing:: +* Bug Reports:: +* Contributing:: +@end menu + +@node Getting help +@section Getting Help + +A mailing list where users may help each other exists, and you can +reach it by sending e-mail to @email{help-gnutls@@gnu.org}. Archives +of the mailing list discussions, and an interface to manage +subscriptions, is available through the World Wide Web at +@url{http://lists.gnu.org/mailman/listinfo/help-gnutls}. + +A mailing list for developers are also available, see +@url{http://www.gnu.org/software/gnutls/lists.html}. + +Bug reports should be sent to @email{bug-gnutls@@gnu.org}, see +@xref{Bug Reports}. + +@node Commercial Support +@section Commercial Support + +Commercial support is available for users of GnuTLS. The kind of +support that can be purchased may include: + +@itemize + +@item Implement new features. +Such as a new TLS extension. + +@item Port GnuTLS to new platforms. +This could include porting to an embedded platforms that may need +memory or size optimization. + +@item Integrating TLS as a security environment in your existing project. + +@item System design of components related to TLS. + +@end itemize + +If you are interested, please write to: + +@verbatim +Simon Josefsson Datakonsult +Hagagatan 24 +113 47 Stockholm +Sweden + +E-mail: simon@josefsson.org +@end verbatim + +If your company provides support related to GnuTLS and would like to +be mentioned here, contact the author (@pxref{Bug Reports}). + +@node Downloading and Installing +@section Downloading and Installing +@cindex Installation +@cindex Download + +GnuTLS is available for download from the following URL: + +@url{http://www.gnutls.org/download.html} + +The latest version is stored in a file, e.g., +@samp{gnutls-@value{VERSION}.tar.gz} where the @samp{@value{VERSION}} +value is the highest version number in the directory. + +GnuTLS uses a Linux-like development cycle: even minor version numbers +indicate a stable release and a odd minor version number indicates a +development release. For example, GnuTLS 1.6.3 denote a stable +release since 6 is even, and GnuTLS 1.7.11 denote a development +release since 7 is odd. + +GnuTLS depends on Libgcrypt, +and you will need to install Libgcrypt +before installing GnuTLS. Libgcrypt is available from +@url{ftp://ftp.gnupg.org/gcrypt/libgcrypt}. Libgcrypt needs another +library, libgpg-error, and you need to install libgpg-error before +installing Libgcrypt. Libgpg-error is available from +@url{ftp://ftp.gnupg.org/gcrypt/libgpg-error}. + +Don't forget to verify the cryptographic signature after downloading +source code packages. + +The package is then extracted, configured and built like many other +packages that use Autoconf. For detailed information on configuring +and building it, refer to the @file{INSTALL} file that is part of the +distribution archive. Typically you invoke @code{./configure} and +then @code{make check install}. There are a number of compile-time +parameters, as discussed below. + +The compression libraries (libz and lzo) are optional dependencies. +You can get libz from @url{http://www.zlib.net/}. You can get lzo +from @url{http://www.oberhumer.com/opensource/lzo/}. + +The X.509 part of GnuTLS needs ASN.1 functionality, from a library +called libtasn1. A copy of libtasn1 is included in GnuTLS. If you +want to install it separately (e.g., to make it possibly to use +libtasn1 in other programs), you can get it from +@url{http://www.gnu.org/software/gnutls/download.html}. + +The OpenPGP part of GnuTLS uses a stripped down version of OpenCDK for +parsing OpenPGP packets. It is included GnuTLS. Use parameter +@code{--disable-openpgp-authentication} to disable the OpenPGP +functionality in GnuTLS. Unfortunately, we didn't have resources to +maintain the code in a separate library. + +Regarding the Guile bindings, there are additional installation +considerations, see @xref{Guile Preparations}. + +A few @code{configure} options may be relevant, summarized in the +table. + +@table @code + +@item --disable-srp-authentication +@itemx --disable-psk-authentication +@itemx --disable-anon-authentication +@itemx --disable-extra-pki +@itemx --disable-openpgp-authentication +@itemx --disable-openssl-compatibility +Disable or enable particular features. Generally not recommended. + +@end table + +For the complete list, refer to the output from @code{configure +--help}. + +@node Bug Reports +@section Bug Reports +@cindex Reporting Bugs + +If you think you have found a bug in GnuTLS, please investigate it and +report it. + +@itemize @bullet + +@item Please make sure that the bug is really in GnuTLS, and +preferably also check that it hasn't already been fixed in the latest +version. + +@item You have to send us a test case that makes it possible for us to +reproduce the bug. + +@item You also have to explain what is wrong; if you get a crash, or +if the results printed are not good and in that case, in what way. +Make sure that the bug report includes all information you would need +to fix this kind of bug for someone else. + +@end itemize + +Please make an effort to produce a self-contained report, with +something definite that can be tested or debugged. Vague queries or +piecemeal messages are difficult to act on and don't help the +development effort. + +If your bug report is good, we will do our best to help you to get a +corrected version of the software; if the bug report is poor, we won't +do anything about it (apart from asking you to send better bug +reports). + +If you think something in this manual is unclear, or downright +incorrect, or if the language needs to be improved, please also send a +note. + +Send your bug report to: + +@center @samp{bug-gnutls@@gnu.org} + +@node Contributing +@section Contributing +@cindex Contributing +@cindex Hacking + +If you want to submit a patch for inclusion -- from solve a typo you +discovered, up to adding support for a new feature -- you should +submit it as a bug report (@pxref{Bug Reports}). There are some +things that you can do to increase the chances for it to be included +in the official package. + +Unless your patch is very small (say, under 10 lines) we require that +you assign the copyright of your work to the Free Software Foundation. +This is to protect the freedom of the project. If you have not +already signed papers, we will send you the necessary information when +you submit your contribution. + +For contributions that doesn't consist of actual programming code, the +only guidelines are common sense. Use it. + +For code contributions, a number of style guides will help you: + +@itemize @bullet + +@item Coding Style. +Follow the GNU Standards document (@pxref{top, GNU Coding Standards,, +standards}). + +If you normally code using another coding standard, there is no +problem, but you should use @samp{indent} to reformat the code +(@pxref{top, GNU Indent,, indent}) before submitting your work. + +@item Use the unified diff format @samp{diff -u}. + +@item Return errors. +No reason whatsoever should abort the execution of the library. Even +memory allocation errors, e.g. when malloc return NULL, should work +although result in an error code. + +@item Design with thread safety in mind. +Don't use global variables. Don't even write to per-handle global +variables unless the documented behaviour of the function you write is +to write to the per-handle global variable. + +@item Avoid using the C math library. +It causes problems for embedded implementations, and in most +situations it is very easy to avoid using it. + +@item Document your functions. +Use comments before each function headers, that, if properly +formatted, are extracted into Texinfo manuals and GTK-DOC web pages. + +@item Supply a ChangeLog and NEWS entries, where appropriate. + +@end itemize diff --git a/doc/cha-programs.texi b/doc/cha-programs.texi new file mode 100644 index 0000000000..c1b940ca13 --- /dev/null +++ b/doc/cha-programs.texi @@ -0,0 +1,853 @@ +@node Included programs +@chapter Included Programs + +Included with @acronym{GnuTLS} are also a few command line tools that +let you use the library for common tasks without writing an +application. The applications are discussed in this chapter. + +@menu +* Invoking certtool:: +* Invoking gnutls-cli:: +* Invoking gnutls-cli-debug:: +* Invoking gnutls-serv:: +* Invoking psktool:: +* Invoking srptool:: +@end menu + +@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 +@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. + +@item +To create a private key (RSA by default), run: + +@example +$ certtool --generate-privkey --outfile key.pem +@end example + +To create a DSA private key, run: + +@example +$ certtool --dsa --generate-privkey --outfile key-dsa.pem +@end example + +@item +To generate a certificate using the private key, use the command: + +@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 + +@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 + +Some tools (reportedly web browsers) have problems with that file +because it does not contain the CA certificate for the certificate. +To work around that problem in the tool, you can use the +@samp{--load-ca-certificate} parameter as follows: + +@example +$ certtool --load-ca-certificate ca.pem \ + --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" +#dns_name = "www.morethanone.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 preferred 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 + +Simple client program to set up a TLS connection to some other +computer. It sets up a TLS connection and forwards data from the +standard input to the secured socket and vice versa. + +@verbatim +GnuTLS test client +Usage: gnutls-cli [options] hostname + + -d, --debug integer Enable debugging + -r, --resume Connect, establish a session. Connect + again and resume this session. + -s, --starttls Connect, establish a plain session and + start TLS when EOF or a SIGALRM is + received. + --crlf Send CR LF instead of LF. + --x509fmtder Use DER format for certificates to read + from. + -f, --fingerprint Send the openpgp fingerprint, instead + of the key. + --disable-extensions Disable all the TLS extensions. + --print-cert Print the certificate in PEM format. + --recordsize integer The maximum record size to advertize. + -V, --verbose More verbose output. + --ciphers cipher1 cipher2... + Ciphers to enable. + --protocols protocol1 protocol2... + Protocols to enable. + --comp comp1 comp2... Compression methods to enable. + --macs mac1 mac2... MACs to enable. + --kx kx1 kx2... Key exchange methods to enable. + --ctypes certType1 certType2... + Certificate types to enable. + --priority PRIORITY STRING + Priorities string. + --x509cafile FILE Certificate file to use. + --x509crlfile FILE CRL file to use. + --pgpkeyfile FILE PGP Key file to use. + --pgpkeyring FILE PGP Key ring file to use. + --pgpcertfile FILE PGP Public Key (certificate) file to + use. + --pgpsubkey HEX|auto PGP subkey to use. + --x509keyfile FILE X.509 key file to use. + --x509certfile FILE X.509 Certificate file to use. + --srpusername NAME SRP username to use. + --srppasswd PASSWD SRP password to use. + --pskusername NAME PSK username to use. + --pskkey KEY PSK key (in hex) to use. + --opaque-prf-input DATA + Use Opaque PRF Input DATA. + -p, --port PORT The port to connect to. + --insecure Don't abort program if server + certificate can't be validated. + -l, --list Print a list of the supported + algorithms and modes. + -h, --help prints this help + -v, --version prints the program's version number +@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 + +This program was created to assist in debugging @acronym{GnuTLS}, but +it might be useful to extract a @acronym{TLS} server's capabilities. +It's purpose is to connect onto a @acronym{TLS} server, perform some +tests and print the server's capabilities. If called with the `-v' +parameter a more checks will be performed. An example output is: + +@smallexample +crystal:/cvs/gnutls/src$ ./gnutls-cli-debug localhost -p 5556 +Resolving 'localhost'... +Connecting to '127.0.0.1:5556'... +Checking for TLS 1.1 support... yes +Checking fallback from TLS 1.1 to... N/A +Checking for TLS 1.0 support... yes +Checking for SSL 3.0 support... yes +Checking for version rollback bug in RSA PMS... no +Checking for version rollback bug in Client Hello... no +Checking whether we need to disable TLS 1.0... N/A +Checking whether the server ignores the RSA PMS version... no +Checking whether the server can accept Hello Extensions... yes +Checking whether the server can accept cipher suites not in SSL 3.0 spec... yes +Checking whether the server can accept a bogus TLS record version in the client hello... yes +Checking for certificate information... N/A +Checking for trusted CAs... N/A +Checking whether the server understands TLS closure alerts... yes +Checking whether the server supports session resumption... yes +Checking for export-grade ciphersuite support... no +Checking RSA-export ciphersuite info... N/A +Checking for anonymous authentication support... no +Checking anonymous Diffie-Hellman group info... N/A +Checking for ephemeral Diffie-Hellman support... no +Checking ephemeral Diffie-Hellman group info... N/A +Checking for AES cipher support (TLS extension)... yes +Checking for 3DES cipher support... yes +Checking for ARCFOUR 128 cipher support... yes +Checking for ARCFOUR 40 cipher support... no +Checking for MD5 MAC support... yes +Checking for SHA1 MAC support... yes +Checking for ZLIB compression support (TLS extension)... yes +Checking for LZO compression support (GnuTLS extension)... yes +Checking for max record size (TLS extension)... yes +Checking for SRP authentication support (TLS extension)... yes +Checking for OpenPGP authentication support (TLS extension)... no +@end smallexample + +@node Invoking gnutls-serv +@section Invoking gnutls-serv +@cindex gnutls-serv + +Simple server program that listens to incoming TLS connections. + +@verbatim +GnuTLS test server +Usage: gnutls-serv [options] + + -d, --debug integer Enable debugging + -g, --generate Generate Diffie-Hellman Parameters. + -p, --port integer The port to connect to. + -q, --quiet Suppress some messages. + --nodb Does not use the resume database. + --http Act as an HTTP Server. + --echo Act as an Echo Server. + --dhparams FILE DH params file to use. + --x509fmtder Use DER format for certificates + --x509cafile FILE Certificate file to use. + --x509crlfile FILE CRL file to use. + --pgpkeyring FILE PGP Key ring file to use. + --pgpkeyfile FILE PGP Key file to use. + --pgpcertfile FILE PGP Public Key (certificate) file to + use. + --pgpsubkey HEX|auto PGP subkey to use. + --x509keyfile FILE X.509 key file to use. + --x509certfile FILE X.509 Certificate file to use. + --x509dsakeyfile FILE Alternative X.509 key file to use. + --x509dsacertfile FILE Alternative X.509 certificate file to + use. + -r, --require-cert Require a valid certificate. + -a, --disable-client-cert + Disable request for a client + certificate. + --pskpasswd FILE PSK password file to use. + --pskhint HINT PSK identity hint to use. + --srppasswd FILE SRP password file to use. + --srppasswdconf FILE SRP password conf file to use. + --opaque-prf-input DATA + Use Opaque PRF Input DATA. + --ciphers cipher1 cipher2... + Ciphers to enable. + --protocols protocol1 protocol2... + Protocols to enable. + --comp comp1 comp2... Compression methods to enable. + --macs mac1 mac2... MACs to enable. + --kx kx1 kx2... Key exchange methods to enable. + --ctypes certType1 certType2... + Certificate types to enable. + --priority PRIORITY STRING + Priorities string. + -l, --list Print a list of the supported + algorithms and modes. + -h, --help prints this help + -v, --version prints the program's version number +@end verbatim + +@subsection Setting Up a Test HTTPS Server +@cindex HTTPS server +@cindex debug server + +Running your own TLS server based on GnuTLS can be useful when +debugging clients and/or GnuTLS itself. This section describes how to +use @code{gnutls-serv} as a simple HTTPS server. + +The most basic server can be started as: + +@example +gnutls-serv --http +@end example + +It will only support anonymous ciphersuites, which many TLS clients +refuse to use. + +The next step is to add support for X.509. First we generate a CA: + +@example +certtool --generate-privkey > x509-ca-key.pem +echo 'cn = GnuTLS test CA' > ca.tmpl +echo 'ca' >> ca.tmpl +echo 'cert_signing_key' >> ca.tmpl +certtool --generate-self-signed --load-privkey x509-ca-key.pem \ + --template ca.tmpl --outfile x509-ca.pem +... +@end example + +Then generate a server certificate. Remember to change the dns_name +value to the name of your server host, or skip that command to avoid +the field. + +@example +certtool --generate-privkey > x509-server-key.pem +echo 'organization = GnuTLS test server' > server.tmpl +echo 'cn = test.gnutls.org' >> server.tmpl +echo 'tls_www_server' >> server.tmpl +echo 'encryption_key' >> server.tmpl +echo 'signing_key' >> server.tmpl +echo 'dns_name = test.gnutls.org' >> server.tmpl +certtool --generate-certificate --load-privkey x509-server-key.pem \ + --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \ + --template server.tmpl --outfile x509-server.pem +... +@end example + +For use in the client, you may want to generate a client certificate +as well. + +@example +certtool --generate-privkey > x509-client-key.pem +echo 'cn = GnuTLS test client' > client.tmpl +echo 'tls_www_client' >> client.tmpl +echo 'encryption_key' >> client.tmpl +echo 'signing_key' >> client.tmpl +certtool --generate-certificate --load-privkey x509-client-key.pem \ + --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \ + --template client.tmpl --outfile x509-client.pem +... +@end example + +To be able to import the client key/certificate into some +applications, you will need to convert them into a PKCS#12 structure. +This also encrypts the security sensitive key with a password. + +@example +certtool --to-p12 --load-ca-certificate x509-ca.pem --load-privkey x509-client-key.pem --load-certificate x509-client.pem --outder --outfile x509-client.p12 +@end example + +For icing, we'll create a proxy certificate for the client too. + +@example +certtool --generate-privkey > x509-proxy-key.pem +echo 'cn = GnuTLS test client proxy' > proxy.tmpl +certtool --generate-proxy --load-privkey x509-proxy-key.pem \ + --load-ca-certificate x509-client.pem --load-ca-privkey x509-client-key.pem \ + --load-certificate x509-client.pem --template proxy.tmpl \ + --outfile x509-proxy.pem +... +@end example + +Then start the server again: + +@example +gnutls-serv --http \ + --x509cafile x509-ca.pem \ + --x509keyfile x509-server-key.pem \ + --x509certfile x509-server.pem +@end example + +Try connecting to the server using your web browser. Note that the +server listens to port 5556 by default. + +While you are at it, to allow connections using DSA, you can also +create a DSA key and certificate for the server. These credentials +will be used in the final example below. + +@example +certtool --generate-privkey --dsa > x509-server-key-dsa.pem +certtool --generate-certificate --load-privkey x509-server-key-dsa.pem \ + --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \ + --template server.tmpl --outfile x509-server-dsa.pem +... +@end example + +The next step is to create OpenPGP credentials for the server. + +@example +gpg --gen-key +...enter whatever details you want, use 'test.gnutls.org' as name... +@end example + +Make a note of the OpenPGP key identifier of the newly generated key, +here it was @code{5D1D14D8}. You will need to export the key for +GnuTLS to be able to use it. + +@example +gpg -a --export 5D1D14D8 > openpgp-server.txt +gpg --export 5D1D14D8 > openpgp-server.bin +gpg --export-secret-keys 5D1D14D8 > openpgp-server-key.bin +gpg -a --export-secret-keys 5D1D14D8 > openpgp-server-key.txt +@end example + +Let's start the server with support for OpenPGP credentials: + +@example +gnutls-serv --http \ + --pgpkeyfile openpgp-server-key.txt \ + --pgpcertfile openpgp-server.txt +@end example + +The next step is to add support for SRP authentication. + +@example +srptool --create-conf srp-tpasswd.conf +srptool --passwd-conf srp-tpasswd.conf --username jas --passwd srp-passwd.txt +Enter password: [TYPE "foo"] +@end example + +Start the server with SRP support: + +@example +gnutls-serv --http \ + --srppasswdconf srp-tpasswd.conf \ + --srppasswd srp-passwd.txt +@end example + +Let's also add support for PSK. + +@example +$ psktool --passwd psk-passwd.txt +@end example + +Start the server with PSK support: + +@example +gnutls-serv --http \ + --pskpasswd psk-passwd.txt +@end example + +Finally, we start the server with all the earlier parameters and you +get this command: + +@example +gnutls-serv --http \ + --x509cafile x509-ca.pem \ + --x509keyfile x509-server-key.pem \ + --x509certfile x509-server.pem \ + --x509dsakeyfile x509-server-key-dsa.pem \ + --x509dsacertfile x509-server-dsa.pem \ + --pgpkeyfile openpgp-server-key.txt \ + --pgpcertfile openpgp-server.txt \ + --srppasswdconf srp-tpasswd.conf \ + --srppasswd srp-passwd.txt \ + --pskpasswd psk-passwd.txt +@end example + +@menu +* Example server PSK connection:: +@end menu + +@node Example server PSK connection +@subsection Example server PSK connection +@cindex PSK server + +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. + +@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 + +After this, start the server pointing to the password file. We +disable DHE-PSK. + +@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 + +You can now connect to the server using a PSK client (@pxref{Example +client PSK connection}). + +@node Invoking psktool +@section Invoking psktool +@cindex psktool + +This is a program to manage @acronym{PSK} username and keys. + +@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 + +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 ""}. + +@node Invoking srptool +@section Invoking srptool +@anchor{srptool} +@cindex srptool + +The @file{srptool} is a very simple program that emulates the programs +in the @emph{Stanford SRP libraries}, see +@url{http://srp.stanford.edu/}. 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 @code{tpasswd} +which holds usernames and verifiers, and @code{tpasswd.conf} which +holds generators and primes. + +How to use srptool: + +@itemize + +@item +To create tpasswd.conf which holds the g and n values for +@acronym{SRP} protocol (generator and a large prime), run: + +@example +$ srptool --create-conf /etc/tpasswd.conf +@end example + +@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. + +@example +$ srptool --passwd /etc/tpasswd \ + --passwd-conf /etc/tpasswd.conf -u test +@end example + +@item +This command will check against a password. If the password matches +the one in /etc/tpasswd you will get an ok. + +@example +$ srptool --passwd /etc/tpasswd \ + --passwd-conf /etc/tpasswd.conf --verify -u test +@end example + +@end itemize diff --git a/doc/cha-tls-app.texi b/doc/cha-tls-app.texi new file mode 100644 index 0000000000..a34d891a93 --- /dev/null +++ b/doc/cha-tls-app.texi @@ -0,0 +1,130 @@ +@node How to use TLS in application protocols +@chapter How To Use @acronym{TLS} in Application Protocols + +This chapter is intended to provide some hints on how to use the +@acronym{TLS} over simple custom made application protocols. The +discussion below mainly refers to the @emph{TCP/IP} transport layer +but may be extended to other ones too. + +@menu +* Separate ports:: +* Upward negotiation:: +@end menu + +@node Separate ports +@section Separate Ports + +Traditionally @acronym{SSL} was used in application protocols by +assigning a new port number for the secure services. That way two +separate ports were assigned, one for the non secure sessions, and one +for the secured ones. This has the benefit that if a user requests a +secure session then the client will try to connect to the secure port +and fail otherwise. The only possible attack with this method is a +denial of service one. The most famous example of this method is the +famous ``HTTP over TLS'' or @acronym{HTTPS} protocol @xcite{RFC2818}. + +Despite its wide use, this method is not as good as it seems. This +approach starts the @acronym{TLS} Handshake procedure just after the +client connects on the ---so called--- secure port. That way the +@acronym{TLS} protocol does not know anything about the client, and +popular methods like the host advertising in HTTP do not +work@footnote{See also the Server Name Indication extension on +@ref{serverind}.}. There is no way for the client to say ``I +connected to YYY server'' before the Handshake starts, so the server +cannot possibly know which certificate to use. + +Other than that it requires two separate ports to run a single +service, which is unnecessary complication. Due to the fact that there +is a limitation on the available privileged ports, this approach was +soon obsoleted. + +@node Upward negotiation +@section Upward Negotiation + +Other application protocols@footnote{See LDAP, IMAP etc.} use a +different approach to enable the secure layer. They use something +called the ``TLS upgrade'' method. This method is quite tricky but it +is more flexible. The idea is to extend the application protocol to +have a ``STARTTLS'' request, whose purpose it to start the TLS +protocols just after the client requests it. This is a really neat +idea and does not require an extra port. + +This method is used by almost all modern protocols and there is even +the @xcite{RFC2817} paper which proposes extensions to HTTP to support +it. + +The tricky part, in this method, is that the ``STARTTLS'' request is +sent in the clear, thus is vulnerable to modifications. A typical +attack is to modify the messages in a way that the client is fooled +and thinks that the server does not have the ``STARTTLS'' capability. +See a typical conversation of a hypothetical protocol: + +@quotation +(client connects to the server) + +CLIENT: HELLO I'M MR. XXX + +SERVER: NICE TO MEET YOU XXX + +CLIENT: PLEASE START TLS + +SERVER: OK + +*** TLS STARTS + +CLIENT: HERE ARE SOME CONFIDENTIAL DATA +@end quotation + +And see an example of a conversation where someone is acting +in between: + +@quotation +(client connects to the server) + +CLIENT: HELLO I'M MR. XXX + +SERVER: NICE TO MEET YOU XXX + +CLIENT: PLEASE START TLS + +(here someone inserts this message) + +SERVER: SORRY I DON'T HAVE THIS CAPABILITY + +CLIENT: HERE ARE SOME CONFIDENTIAL DATA +@end quotation + +As you can see above the client was fooled, and was dummy enough to +send the confidential data in the clear. + +How to avoid the above attack? As you may have already thought this +one is easy to avoid. The client has to ask the user before it +connects whether the user requests @acronym{TLS} or not. If the user +answered that he certainly wants the secure layer the last +conversation should be: + +@quotation +(client connects to the server) + +CLIENT: HELLO I'M MR. XXX + +SERVER: NICE TO MEET YOU XXX + +CLIENT: PLEASE START TLS + +(here someone inserts this message) + +SERVER: SORRY I DON'T HAVE THIS CAPABILITY + +CLIENT: BYE + +(the client notifies the user that the secure connection was not possible) +@end quotation + +This method, if implemented properly, is far better than the +traditional method, and the security properties remain the same, since +only denial of service is possible. The benefit is that the server may +request additional data before the @acronym{TLS} Handshake protocol +starts, in order to send the correct certificate, use the correct +password file@footnote{in @acronym{SRP} authentication}, or anything +else! diff --git a/doc/gnutls.texi b/doc/gnutls.texi index 84cc674447..bbecd1f8bf 100644 --- a/doc/gnutls.texi +++ b/doc/gnutls.texi @@ -90,4286 +90,29 @@ Documentation License''. * Bibliography:: @end menu +@include cha-preface.texi -@node Preface -@chapter Preface +@include cha-library.texi -This document tries to demonstrate and explain the @acronym{GnuTLS} -library API. A brief introduction to the protocols and the technology -involved, is also included so that an application programmer can -better understand the @acronym{GnuTLS} purpose and actual offerings. -Even if @acronym{GnuTLS} is a typical library software, it operates -over several security and cryptographic protocols, which require the -programmer to make careful and correct usage of them, otherwise he -risks to offer just a false sense of security. Security and the -network security terms are very general terms even for computer -software thus cannot be easily restricted to a single cryptographic -library. For that reason, do not consider a program secure just -because it uses @acronym{GnuTLS}; there are several ways to compromise -a program or a communication line and @acronym{GnuTLS} only helps with -some of them. +@include cha-intro-tls.texi -Although this document tries to be self contained, basic network -programming and PKI knowlegde is assumed in most of it. A good -introduction to networking can be found in @xcite{STEVENS} and for -Public Key Infrastructure in @xcite{GUTPKI}. +@include cha-auth.texi -@anchor{Availability} +@include cha-cert-auth.texi -Updated versions of the @acronym{GnuTLS} software and this document -will be available from @url{http://www.gnutls.org/} and -@url{http://www.gnu.org/software/gnutls/}. +@include cha-tls-app.texi -@menu -* Getting help:: -* Commercial Support:: -* Downloading and Installing:: -* Bug Reports:: -* Contributing:: -@end menu - -@node Getting help -@section Getting Help - -A mailing list where users may help each other exists, and you can -reach it by sending e-mail to @email{help-gnutls@@gnu.org}. Archives -of the mailing list discussions, and an interface to manage -subscriptions, is available through the World Wide Web at -@url{http://lists.gnu.org/mailman/listinfo/help-gnutls}. - -A mailing list for developers are also available, see -@url{http://www.gnu.org/software/gnutls/lists.html}. - -Bug reports should be sent to @email{bug-gnutls@@gnu.org}, see -@xref{Bug Reports}. - -@node Commercial Support -@section Commercial Support - -Commercial support is available for users of GnuTLS. The kind of -support that can be purchased may include: - -@itemize - -@item Implement new features. -Such as a new TLS extension. - -@item Port GnuTLS to new platforms. -This could include porting to an embedded platforms that may need -memory or size optimization. - -@item Integrating TLS as a security environment in your existing project. - -@item System design of components related to TLS. - -@end itemize - -If you are interested, please write to: - -@verbatim -Simon Josefsson Datakonsult -Hagagatan 24 -113 47 Stockholm -Sweden - -E-mail: simon@josefsson.org -@end verbatim - -If your company provides support related to GnuTLS and would like to -be mentioned here, contact the author (@pxref{Bug Reports}). - -@node Downloading and Installing -@section Downloading and Installing -@cindex Installation -@cindex Download - -GnuTLS is available for download from the following URL: - -@url{http://www.gnutls.org/download.html} - -The latest version is stored in a file, e.g., -@samp{gnutls-@value{VERSION}.tar.gz} where the @samp{@value{VERSION}} -value is the highest version number in the directory. - -GnuTLS uses a Linux-like development cycle: even minor version numbers -indicate a stable release and a odd minor version number indicates a -development release. For example, GnuTLS 1.6.3 denote a stable -release since 6 is even, and GnuTLS 1.7.11 denote a development -release since 7 is odd. - -GnuTLS depends on Libgcrypt, -and you will need to install Libgcrypt -before installing GnuTLS. Libgcrypt is available from -@url{ftp://ftp.gnupg.org/gcrypt/libgcrypt}. Libgcrypt needs another -library, libgpg-error, and you need to install libgpg-error before -installing Libgcrypt. Libgpg-error is available from -@url{ftp://ftp.gnupg.org/gcrypt/libgpg-error}. - -Don't forget to verify the cryptographic signature after downloading -source code packages. - -The package is then extracted, configured and built like many other -packages that use Autoconf. For detailed information on configuring -and building it, refer to the @file{INSTALL} file that is part of the -distribution archive. Typically you invoke @code{./configure} and -then @code{make check install}. There are a number of compile-time -parameters, as discussed below. - -The compression libraries (libz and lzo) are optional dependencies. -You can get libz from @url{http://www.zlib.net/}. You can get lzo -from @url{http://www.oberhumer.com/opensource/lzo/}. - -The X.509 part of GnuTLS needs ASN.1 functionality, from a library -called libtasn1. A copy of libtasn1 is included in GnuTLS. If you -want to install it separately (e.g., to make it possibly to use -libtasn1 in other programs), you can get it from -@url{http://www.gnu.org/software/gnutls/download.html}. - -The OpenPGP part of GnuTLS uses a stripped down version of OpenCDK for -parsing OpenPGP packets. It is included GnuTLS. Use parameter -@code{--disable-openpgp-authentication} to disable the OpenPGP -functionality in GnuTLS. Unfortunately, we didn't have resources to -maintain the code in a separate library. - -Regarding the Guile bindings, there are additional installation -considerations, see @xref{Guile Preparations}. - -A few @code{configure} options may be relevant, summarized in the -table. - -@table @code - -@item --disable-srp-authentication -@itemx --disable-psk-authentication -@itemx --disable-anon-authentication -@itemx --disable-extra-pki -@itemx --disable-openpgp-authentication -@itemx --disable-openssl-compatibility -Disable or enable particular features. Generally not recommended. - -@end table - -For the complete list, refer to the output from @code{configure ---help}. - -@node Bug Reports -@section Bug Reports -@cindex Reporting Bugs - -If you think you have found a bug in GnuTLS, please investigate it and -report it. - -@itemize @bullet - -@item Please make sure that the bug is really in GnuTLS, and -preferably also check that it hasn't already been fixed in the latest -version. - -@item You have to send us a test case that makes it possible for us to -reproduce the bug. - -@item You also have to explain what is wrong; if you get a crash, or -if the results printed are not good and in that case, in what way. -Make sure that the bug report includes all information you would need -to fix this kind of bug for someone else. - -@end itemize - -Please make an effort to produce a self-contained report, with -something definite that can be tested or debugged. Vague queries or -piecemeal messages are difficult to act on and don't help the -development effort. - -If your bug report is good, we will do our best to help you to get a -corrected version of the software; if the bug report is poor, we won't -do anything about it (apart from asking you to send better bug -reports). - -If you think something in this manual is unclear, or downright -incorrect, or if the language needs to be improved, please also send a -note. - -Send your bug report to: - -@center @samp{bug-gnutls@@gnu.org} - -@node Contributing -@section Contributing -@cindex Contributing -@cindex Hacking - -If you want to submit a patch for inclusion -- from solve a typo you -discovered, up to adding support for a new feature -- you should -submit it as a bug report (@pxref{Bug Reports}). There are some -things that you can do to increase the chances for it to be included -in the official package. - -Unless your patch is very small (say, under 10 lines) we require that -you assign the copyright of your work to the Free Software Foundation. -This is to protect the freedom of the project. If you have not -already signed papers, we will send you the necessary information when -you submit your contribution. - -For contributions that doesn't consist of actual programming code, the -only guidelines are common sense. Use it. - -For code contributions, a number of style guides will help you: - -@itemize @bullet - -@item Coding Style. -Follow the GNU Standards document (@pxref{top, GNU Coding Standards,, -standards}). - -If you normally code using another coding standard, there is no -problem, but you should use @samp{indent} to reformat the code -(@pxref{top, GNU Indent,, indent}) before submitting your work. - -@item Use the unified diff format @samp{diff -u}. - -@item Return errors. -No reason whatsoever should abort the execution of the library. Even -memory allocation errors, e.g. when malloc return NULL, should work -although result in an error code. - -@item Design with thread safety in mind. -Don't use global variables. Don't even write to per-handle global -variables unless the documented behaviour of the function you write is -to write to the per-handle global variable. - -@item Avoid using the C math library. -It causes problems for embedded implementations, and in most -situations it is very easy to avoid using it. - -@item Document your functions. -Use comments before each function headers, that, if properly -formatted, are extracted into Texinfo manuals and GTK-DOC web pages. - -@item Supply a ChangeLog and NEWS entries, where appropriate. - -@end itemize -@node The Library -@chapter The Library - -In brief @acronym{GnuTLS} can be described as a library which offers an API -to access secure communication protocols. These protocols provide -privacy over insecure lines, and were designed to prevent -eavesdropping, tampering, or message forgery. - -Technically @acronym{GnuTLS} is a portable ANSI C based library which -implements the TLS 1.1 and SSL 3.0 protocols (@xref{Introduction to -TLS}, for a more detailed description of the protocols), accompanied -with the required framework for authentication and public key -infrastructure. Important features of the @acronym{GnuTLS} library -include: - -@itemize - -@item Support for TLS 1.0, TLS 1.1, and SSL 3.0 protocols. - -@item Support for both @acronym{X.509} and @acronym{OpenPGP} certificates. - -@item Support for handling and verification of certificates. - -@item Support for @acronym{SRP} for TLS authentication. - -@item Support for @acronym{PSK} for TLS authentication. - -@item Support for TLS Extension mechanism. - -@item Support for TLS Compression Methods. - -@end itemize - -Additionally @acronym{GnuTLS} provides a limited emulation API for the -widely used OpenSSL@footnote{@url{http://www.openssl.org/}} library, -to ease integration with existing applications. - -@acronym{GnuTLS} consists of three independent parts, namely the ``TLS -protocol part'', the ``Certificate part'', and the ``Cryptographic -backend'' part. The `TLS protocol part' is the actual protocol -implementation, and is entirely implemented within the -@acronym{GnuTLS} library. The `Certificate part' consists of the -certificate parsing, and verification functions which is partially -implemented in the @acronym{GnuTLS} library. The -@acronym{Libtasn1}@footnote{@url{ftp://ftp.gnupg.org/gcrypt/alpha/gnutls/libtasn1/}}, -a library which offers @acronym{ASN.1} parsing capabilities, is used -for the @acronym{X.509} certificate parsing functions. A smaller -version of -@acronym{OpenCDK}@footnote{@url{ftp://ftp.gnupg.org/gcrypt/alpha/gnutls/opencdk/}} -is used for the @acronym{OpenPGP} key support in @acronym{GnuTLS}. -The ``Cryptographic backend'' is provided by the -@acronym{Libgcrypt}@footnote{@url{ftp://ftp.gnupg.org/gcrypt/alpha/libgcrypt/}} -library@footnote{On current versions of GnuTLS it is possible to -override the default crypto backend. Check @pxref{Cryptographic -Backend} for details}. - -In order to ease integration in embedded systems, parts of the -@acronym{GnuTLS} library can be disabled at compile time. That way a -small library, with the required features, can be generated. - -@menu -* General Idea:: -* Error handling:: -* Memory handling:: -* Callback functions:: -@end menu - -@node General Idea -@section General Idea - -A brief description of how @acronym{GnuTLS} works internally is shown -at the figure below. This section may be easier to understand after -having seen the examples (@pxref{examples}). - -@image{gnutls-internals,12cm,8cm} - -As shown in the figure, there is a read-only global state that is -initialized once by the global initialization function. This global -structure, among others, contains the memory allocation functions -used, and some structures needed for the @acronym{ASN.1} parser. This -structure is never modified by any @acronym{GnuTLS} function, except -for the deinitialization function which frees all memory allocated in -the global structure and is called after the program has permanently -finished using @acronym{GnuTLS}. - -The credentials structure is used by some authentication methods, such -as certificate authentication (@pxref{Certificate Authentication}). A -credentials structure may contain certificates, private keys, -temporary parameters for Diffie-Hellman or RSA key exchange, and other -stuff that may be shared between several TLS sessions. - -This structure should be initialized using the appropriate -initialization functions. For example an application which uses -certificate authentication would probably initialize the credentials, -using the appropriate functions, and put its trusted certificates in -this structure. The next step is to associate the credentials -structure with each @acronym{TLS} session. - -A @acronym{GnuTLS} session contains all the required stuff for a -session to handle one secure connection. This session calls directly -to the transport layer functions, in order to communicate with the -peer. Every session has a unique session ID shared with the peer. - -Since TLS sessions can be resumed, servers would probably need a -database backend to hold the session's parameters. Every -@acronym{GnuTLS} session after a successful handshake calls the -appropriate backend function (@xref{resume}, for information on -initialization) to store the newly negotiated session. The session -database is examined by the server just after having received the -client hello@footnote{The first message in a @acronym{TLS} handshake}, -and if the session ID sent by the client, matches a stored session, -the stored session will be retrieved, and the new session will be a -resumed one, and will share the same session ID with the previous one. - -@node Error handling -@section Error Handling - -In @acronym{GnuTLS} most functions return an integer type as a result. -In almost all cases a zero or a positive number means success, and a -negative number indicates failure, or a situation that some action has -to be taken. Thus negative error codes may be fatal or not. - -Fatal errors terminate the connection immediately and further sends -and receives will be disallowed. An example of a fatal error code is -@code{GNUTLS_E_DECRYPTION_FAILED}. Non-fatal errors may warn about -something, i.e., a warning alert was received, or indicate the some -action has to be taken. This is the case with the error code -@code{GNUTLS_E_REHANDSHAKE} returned by @ref{gnutls_record_recv}. -This error code indicates that the server requests a re-handshake. The -client may ignore this request, or may reply with an alert. You can -test if an error code is a fatal one by using the -@ref{gnutls_error_is_fatal}. - -If any non fatal errors, that require an action, are to be returned by -a function, these error codes will be documented in the function's -reference. @xref{Error Codes}, for all the error codes. - -@node Memory handling -@section Memory Handling - -@acronym{GnuTLS} internally handles heap allocated objects -differently, depending on the sensitivity of the data they -contain. However for performance reasons, the default memory functions -do not overwrite sensitive data from memory, nor protect such objects -from being written to the swap. In order to change the default -behavior the @ref{gnutls_global_set_mem_functions} function is -available which can be used to set other memory handlers than the -defaults. - -The @acronym{Libgcrypt} library on which @acronym{GnuTLS} depends, has -such secure memory allocation functions available. These should be -used in cases where even the system's swap memory is not considered -secure. See the documentation of @acronym{Libgcrypt} for more -information. - -@node Callback functions -@section Callback Functions -@cindex Callback functions - -There are several cases where @acronym{GnuTLS} may need some out of -band input from your program. This is now implemented using some -callback functions, which your program is expected to register. - -An example of this type of functions are the push and pull callbacks -which are used to specify the functions that will retrieve and send -data to the transport layer. - -@itemize - -@item @ref{gnutls_transport_set_push_function} - -@item @ref{gnutls_transport_set_pull_function} - -@end itemize - -Other callback functions such as the one set by -@ref{gnutls_srp_set_server_credentials_function}, may require more -complicated input, including data to be allocated. These callbacks -should allocate and free memory using the functions shown below. - -@itemize - -@item @ref{gnutls_malloc} - -@item @ref{gnutls_free} - -@end itemize - -@node Introduction to TLS -@chapter Introduction to @acronym{TLS} - -@acronym{TLS} stands for ``Transport Layer Security'' and is the -successor of SSL, the Secure Sockets Layer protocol @xcite{SSL3} -designed by Netscape. @acronym{TLS} is an Internet protocol, defined -by @acronym{IETF}@footnote{IETF, or Internet Engineering Task Force, -is a large open international community of network designers, -operators, vendors, and researchers concerned with the evolution of -the Internet architecture and the smooth operation of the Internet. -It is open to any interested individual.}, described in @acronym{RFC} -4346 and also in @xcite{RESCORLA}. The protocol provides -confidentiality, and authentication layers over any reliable transport -layer. The description, below, refers to @acronym{TLS} 1.0 but also -applies to @acronym{TLS} 1.1 @xcite{RFC4346} and @acronym{SSL} 3.0, -since the differences of these protocols are minor. Older protocols -such as @acronym{SSL} 2.0 are not discussed nor implemented in -@acronym{GnuTLS} since they are not considered secure today. GnuTLS -also supports @acronym{X.509} and @acronym{OpenPGP} @xcite{RFC4880}. - -@menu -* TLS layers:: -* The transport layer:: -* The TLS record protocol:: -* The TLS Alert Protocol:: -* The TLS Handshake Protocol:: -* TLS Extensions:: -* Selecting cryptographic key sizes:: -* On SSL 2 and older protocols:: -* On Record Padding:: -* Safe Renegotiation:: -@end menu - -@node TLS layers -@section TLS Layers -@cindex TLS Layers - -@acronym{TLS} is a layered protocol, and consists of the Record -Protocol, the Handshake Protocol and the Alert Protocol. The Record -Protocol is to serve all other protocols and is above the transport -layer. The Record protocol offers symmetric encryption, data -authenticity, and optionally compression. - -The Alert protocol offers some signaling to the other protocols. It -can help informing the peer for the cause of failures and other error -conditions. @xref{The Alert Protocol}, for more information. The -alert protocol is above the record protocol. - -The Handshake protocol is responsible for the security parameters' -negotiation, the initial key exchange and authentication. @xref{The -Handshake Protocol}, for more information about the handshake -protocol. The protocol layering in TLS is shown in the figure below. - -@image{gnutls-layers,12cm,8cm} - -@node The transport layer -@section The Transport Layer -@cindex Transport protocol - -@acronym{TLS} is not limited to one transport layer, it can be used -above any transport layer, as long as it is a reliable one. A set of -functions is provided and their purpose is to load to @acronym{GnuTLS} the -required callbacks to access the transport layer. - -@itemize -@item @ref{gnutls_transport_set_push_function} -@item @ref{gnutls_transport_set_pull_function} -@item @ref{gnutls_transport_set_ptr} -@item @ref{gnutls_transport_set_lowat} -@item @ref{gnutls_transport_set_errno} -@end itemize - -These functions accept a callback function as a parameter. The -callback functions should return the number of bytes written, or -1 on -error and should set @code{errno} appropriately. - -In some environments, setting @code{errno} is unreliable, for example -Windows have several errno variables in different CRTs, or it may be -that errno is not a thread-local variable. If this is a concern to -you, call @code{gnutls_transport_set_errno} with the intended errno -value instead of setting @code{errno} directly. - -@acronym{GnuTLS} currently only interprets the EINTR and EAGAIN errno -values and returns the corresponding @acronym{GnuTLS} error codes -@code{GNUTLS_E_INTERRUPTED} and @code{GNUTLS_E_AGAIN}. These values -are usually returned by interrupted system calls, or when non blocking -IO is used. All @acronym{GnuTLS} functions can be resumed (called -again), if any of these error codes is returned. The error codes -above refer to the system call, not the @acronym{GnuTLS} function, -since signals do not interrupt @acronym{GnuTLS}' functions. - -For non blocking sockets or other custom made pull/push functions -the @ref{gnutls_transport_set_lowat} must be called, with a zero -low water mark value. - -By default, if the transport functions are not set, @acronym{GnuTLS} -will use the Berkeley Sockets functions. In this case -@acronym{GnuTLS} will use some hacks in order for @code{select} to -work, thus making it easy to add @acronym{TLS} support to existing -TCP/IP servers. - -@node The TLS record protocol -@section The TLS Record Protocol -@cindex Record protocol - -The Record protocol is the secure communications provider. Its purpose -is to encrypt, authenticate and ---optionally--- compress packets. -The following functions are available: - -@table @asis - -@item @ref{gnutls_record_send}: -To send a record packet (with application data). - -@item @ref{gnutls_record_recv}: -To receive a record packet (with application data). - -@item @ref{gnutls_record_get_direction}: -To get the direction of the last interrupted function call. -@end table - -As you may have already noticed, the functions which access the Record -protocol, are quite limited, given the importance of this protocol in -@acronym{TLS}. This is because the Record protocol's parameters are -all set by the Handshake protocol. - -The Record protocol initially starts with NULL parameters, which means -no encryption, and no MAC is used. Encryption and authentication begin -just after the handshake protocol has finished. - -@menu -* Encryption algorithms used in the record layer:: -* Compression algorithms used in the record layer:: -* Weaknesses and countermeasures:: -@end menu - -@node Encryption algorithms used in the record layer -@subsection Encryption Algorithms Used in the Record Layer -@cindex Symmetric encryption algorithms - -Confidentiality in the record layer is achieved by using symmetric -block encryption algorithms like @code{3DES}, @code{AES}@footnote{AES, -or Advanced Encryption Standard, is actually the RIJNDAEL algorithm. -This is the algorithm that replaced DES.}, or stream algorithms like -@code{ARCFOUR_128}@footnote{@code{ARCFOUR_128} is a compatible -algorithm with RSA's RC4 algorithm, which is considered to be a trade -secret.}. Ciphers are encryption algorithms that use a single, secret, -key to encrypt and decrypt data. Block algorithms in TLS also provide -protection against statistical analysis of the data. Thus, if you're -using the @acronym{TLS} protocol, a random number of blocks will be -appended to data, to prevent eavesdroppers from guessing the actual -data size. - -Supported cipher algorithms: - -@table @code -@item 3DES_CBC -@code{3DES_CBC} is the DES block cipher algorithm used with triple -encryption (EDE). Has 64 bits block size and is used in CBC mode. - -@item ARCFOUR_128 -ARCFOUR is a fast stream cipher. - -@item ARCFOUR_40 -This is the ARCFOUR cipher that is fed with a 40 bit key, -which is considered weak. - -@item AES_CBC -AES or RIJNDAEL is the block cipher algorithm that replaces the old -DES algorithm. Has 128 bits block size and is used in CBC mode. This -is not officially supported in TLS. -@end table - -Supported MAC algorithms: - -@table @code -@item MAC_MD5 -MD5 is a cryptographic hash algorithm designed by Ron Rivest. Outputs -128 bits of data. - -@item MAC_SHA -SHA is a cryptographic hash algorithm designed by NSA. Outputs 160 -bits of data. - -@end table - -@node Compression algorithms used in the record layer -@subsection Compression Algorithms Used in the Record Layer -@cindex Compression algorithms - -The TLS record layer also supports compression. The algorithms -implemented in @acronym{GnuTLS} can be found in the table below. -All the algorithms except for DEFLATE which is -referenced in @xcite{RFC3749}, should be considered as -@acronym{GnuTLS}' extensions@footnote{You should use -@ref{gnutls_handshake_set_private_extensions} to enable private -extensions.}, and should be advertised only when the peer is known to -have a compliant client, to avoid interoperability problems. - -The included algorithms perform really good when text, or other -compressible data are to be transfered, but offer nothing on already -compressed data, such as compressed images, zipped archives etc. -These compression algorithms, may be useful in high bandwidth TLS -tunnels, and in cases where network usage has to be minimized. As a -drawback, compression increases latency. - -The record layer compression in @acronym{GnuTLS} is implemented based -on the proposal @xcite{RFC3749}. -The supported compression algorithms are: - -@table @code -@item DEFLATE -Zlib compression, using the deflate algorithm. - -@item LZO -LZO is a very fast compression algorithm. This algorithm is only -available if the @acronym{GnuTLS-extra} library has been initialized -and the private extensions are enabled, and if GnuTLS was built with -LZO support. - -@end table - -@node Weaknesses and countermeasures -@subsection Weaknesses and Countermeasures - -Some weaknesses that may affect the security of the Record layer have -been found in @acronym{TLS} 1.0 protocol. These weaknesses can be -exploited by active attackers, and exploit the facts that - -@enumerate - -@item -@acronym{TLS} has separate alerts for ``decryption_failed'' and -``bad_record_mac'' - -@item -The decryption failure reason can be detected by timing the response -time. - -@item -The IV for CBC encrypted packets is the last block of the previous -encrypted packet. - -@end enumerate - -Those weaknesses were solved in @acronym{TLS} 1.1 @xcite{RFC4346} -which is implemented in @acronym{GnuTLS}. For a detailed discussion -see the archives of the TLS Working Group mailing list and the paper -@xcite{CBCATT}. - -@node The TLS Alert Protocol -@section The TLS Alert Protocol -@anchor{The Alert Protocol} -@cindex Alert protocol - -The Alert protocol is there to allow signals to be sent between peers. -These signals are mostly used to inform the peer about the cause of a -protocol failure. Some of these signals are used internally by the -protocol and the application protocol does not have to cope with them -(see @code{GNUTLS_A_CLOSE_NOTIFY}), and others refer to the -application protocol solely (see @code{GNUTLS_A_USER_CANCELLED}). An -alert signal includes a level indication which may be either fatal or -warning. Fatal alerts always terminate the current connection, and -prevent future renegotiations using the current session ID. - -The alert messages are protected by the record protocol, thus the -information that is included does not leak. You must take extreme care -for the alert information not to leak to a possible attacker, via -public log files etc. - -@table @asis -@item @ref{gnutls_alert_send}: -To send an alert signal. - -@item @ref{gnutls_error_to_alert}: -To map a gnutls error number to an alert signal. - -@item @ref{gnutls_alert_get}: -Returns the last received alert. - -@item @ref{gnutls_alert_get_name}: -Returns the name, in a character array, of the given alert. - -@end table - -@node The TLS Handshake Protocol -@section The TLS Handshake Protocol -@anchor{The Handshake Protocol} -@cindex Handshake protocol - -The Handshake protocol is responsible for the ciphersuite negotiation, -the initial key exchange, and the authentication of the two peers. -This is fully controlled by the application layer, thus your program -has to set up the required parameters. Available functions to control -the handshake protocol include: - -@table @asis -@item @ref{gnutls_priority_init}: -To initialize a priority set of ciphers. - -@item @ref{gnutls_priority_deinit}: -To deinitialize a priority set of ciphers. - -@item @ref{gnutls_priority_set}: -To associate a priority set with a @acronym{TLS} session. - -@item @ref{gnutls_priority_set_direct}: -To directly associate a session with a given priority string. - -@item @ref{gnutls_credentials_set}: -To set the appropriate credentials structures. - -@item @ref{gnutls_certificate_server_set_request}: -To set whether client certificate is required or not. - -@item @ref{gnutls_handshake}: -To initiate the handshake. -@end table - -@subsection TLS Cipher Suites - -The Handshake Protocol of @acronym{TLS} negotiates cipher suites of -the form @code{TLS_DHE_RSA_WITH_3DES_CBC_SHA}. The usual cipher -suites contain these parameters: - -@itemize - -@item The key exchange algorithm. -@code{DHE_RSA} in the example. - -@item The Symmetric encryption algorithm and mode -@code{3DES_CBC} in this example. - -@item The MAC@footnote{MAC stands for Message Authentication Code. It can be described as a keyed hash algorithm. See RFC2104.} algorithm used for authentication. -@code{MAC_SHA} is used in the above example. - -@end itemize - -The cipher suite negotiated in the handshake protocol will affect the -Record Protocol, by enabling encryption and data authentication. Note -that you should not over rely on @acronym{TLS} to negotiate the -strongest available cipher suite. Do not enable ciphers and algorithms -that you consider weak. - -The priority functions, dicussed above, allow the application layer to -enable and set priorities on the individual ciphers. It may imply that -all combinations of ciphersuites are allowed, but this is not -true. For several reasons, not discussed here, some combinations were -not defined in the @acronym{TLS} protocol. The supported ciphersuites -are shown in @ref{ciphersuites}. - -@subsection Client Authentication -@cindex Client Certificate authentication - -In the case of ciphersuites that use certificate authentication, the -authentication of the client is optional in @acronym{TLS}. A server -may request a certificate from the client --- using the -@ref{gnutls_certificate_server_set_request} function. If a certificate -is to be requested from the client during the handshake, the server -will send a certificate request message that contains a list of -acceptable certificate signers. In @acronym{GnuTLS} the certificate -signers list is constructed using the trusted Certificate Authorities -by the server. That is the ones set using -@itemize -@item @ref{gnutls_certificate_set_x509_trust_file} -@item @ref{gnutls_certificate_set_x509_trust_mem} -@end itemize - -Sending of the names of the CAs can be controlled using -@ref{gnutls_certificate_send_x509_rdn_sequence}. The client, then, may -send a certificate, signed by one of the server's acceptable signers. - -@subsection Resuming Sessions -@anchor{resume} -@cindex Resuming sessions - -The @ref{gnutls_handshake} function, is expensive since a lot of -calculations are performed. In order to support many fast connections -to the same server a client may use session resuming. @strong{Session -resuming} is a feature of the @acronym{TLS} protocol which allows a -client to connect to a server, after a successful handshake, without -the expensive calculations. This is achieved by using the previously -established keys. @acronym{GnuTLS} supports this feature, and the -example (@pxref{ex:resume-client}) illustrates a typical use of it. - -Keep in mind that sessions are expired after some time, for security -reasons, thus it may be normal for a server not to resume a session -even if you requested that. Also note that you must enable, using the -priority functions, at least the algorithms used in the last session. - -@subsection Resuming Internals - -The resuming capability, mostly in the server side, is one of the -problems of a thread-safe TLS implementations. The problem is that all -threads must share information in order to be able to resume -sessions. The gnutls approach is, in case of a client, to leave all -the burden of resuming to the client. I.e., copy and keep the -necessary parameters. See the functions: - -@itemize - -@item @ref{gnutls_session_get_data} - -@item @ref{gnutls_session_get_id} - -@item @ref{gnutls_session_set_data} - -@end itemize - -The server side is different. A server has to specify some callback -functions which store, retrieve and delete session data. These can be -registered with: - -@itemize - -@item @ref{gnutls_db_set_remove_function} - -@item @ref{gnutls_db_set_store_function} - -@item @ref{gnutls_db_set_retrieve_function} - -@item @ref{gnutls_db_set_ptr} - -@end itemize - -It might also be useful to be able to check for expired sessions in -order to remove them, and save space. The function -@ref{gnutls_db_check_entry} is provided for that reason. - -@node TLS Extensions -@section TLS Extensions -@cindex TLS Extensions - -A number of extensions to the @acronym{TLS} protocol have been -proposed mainly in @xcite{TLSEXT}. The extensions supported -in @acronym{GnuTLS} are: - -@itemize -@item Maximum fragment length negotiation -@item Server name indication -@item Session tickets -@end itemize - -and they will be discussed in the subsections that follow. - -@subsection Maximum Fragment Length Negotiation -@cindex TLS Extensions -@cindex Maximum fragment length - -This extension allows a @acronym{TLS} implementation to negotiate a -smaller value for record packet maximum length. This extension may be -useful to clients with constrained capabilities. See the -@ref{gnutls_record_set_max_size} and the -@ref{gnutls_record_get_max_size} functions. - -@subsection Server Name Indication -@anchor{serverind} -@cindex TLS Extensions -@cindex Server name indication - -A common problem in @acronym{HTTPS} servers is the fact that the -@acronym{TLS} protocol is not aware of the hostname that a client -connects to, when the handshake procedure begins. For that reason the -@acronym{TLS} server has no way to know which certificate to send. - -This extension solves that problem within the @acronym{TLS} protocol, -and allows a client to send the HTTP hostname before the handshake -begins within the first handshake packet. The functions -@ref{gnutls_server_name_set} and @ref{gnutls_server_name_get} can be -used to enable this extension, or to retrieve the name sent by a -client. - -@subsection Session Tickets -@cindex TLS Extensions -@cindex Session Tickets -@cindex Ticket - -To resume a TLS session the server normally store some state. This -complicates deployment, and typical situations the client can cache -information and send it to the server instead. The Session Ticket -extension implements this idea, and it is documented in -RFC 5077 @xcite{TLSTKT}. - -Clients can enable support for TLS tickets with -@ref{gnutls_session_ticket_enable_client} and servers use -@ref{gnutls_session_ticket_key_generate} to generate a key and -@ref{gnutls_session_ticket_enable_server} to enable the extension. -Clients resume sessions using the ticket using the normal session -resume functions, @ref{resume}. - -@node Selecting cryptographic key sizes -@section Selecting Cryptographic Key Sizes -@cindex key sizes - -In TLS, since a lot of algorithms are involved, it is not easy to set -a consistent security level. For this reason this section will -present some correspondance between key sizes of symmetric algorithms -and public key algorithms based on the most conservative values of -@xcite{SELKEY}. Those can be used to generate certificates with -appropriate key sizes as well as parameters for Diffie-Hellman and SRP -authentication. - -@multitable @columnfractions .15 .20 .20 .20 - -@item Year -@tab Symmetric key size -@tab RSA key size, DH and SRP prime size -@tab ECC key size - -@item 1982 -@tab 56 -@tab 417 -@tab 105 - -@item 1988 -@tab 61 -@tab 566 -@tab 114 - -@item 2002 -@tab 72 -@tab 1028 -@tab 139 - -@item 2015 -@tab 82 -@tab 1613 -@tab 173 - -@item 2028 -@tab 92 -@tab 2362 -@tab 210 - -@item 2040 -@tab 101 -@tab 3214 -@tab 244 - -@item 2050 -@tab 109 -@tab 4047 -@tab 272 - -@end multitable - -The first column provides an estimation of the year until these -parameters are considered safe and the rest of the columns list the -parameters for the various algorithms. - -Note however that the values suggested here are nothing more than an -educated guess that is valid today. There are no guarrantees that an -algorithm will remain unbreakable or that these values will remain -constant in time. There could be scientific breakthroughs that cannot -be predicted or total failure of the current public key systems by -quantum computers. On the other hand though the cryptosystems used in -TLS are selected in a conservative way and such catastrophic -breakthroughs or failures are believed to be unlikely. - -NIST publication SP 800-57 @xcite{NISTSP80057} contains a similar -table that extends beyond the key sizes given above. - -@multitable @columnfractions .15 .20 .20 .20 - -@item Bits of security -@tab Symmetric key algorithms -@tab RSA key size, DSA, DH and SRP prime size -@tab ECC key size - -@item 80 -@tab 2TDEA -@tab 1024 -@tab 160-223 - -@item 112 -@tab 3DES -@tab 2048 -@tab 224-255 - -@item 128 -@tab AES-128 -@tab 3072 -@tab 256-383 - -@item 192 -@tab AES-192 -@tab 7680 -@tab 384-511 - -@item 256 -@tab AES-256 -@tab 15360 -@tab 512+ - -@end multitable - -The recommendations are fairly consistent. - -@node On SSL 2 and older protocols -@section On SSL 2 and Older Protocols -@cindex SSL 2 - -One of the initial decisions in the @acronym{GnuTLS} development was -to implement the known security protocols for the transport layer. -Initially @acronym{TLS} 1.0 was implemented since it was the latest at -that time, and was considered to be the most advanced in security -properties. Later the @acronym{SSL} 3.0 protocol was implemented -since it is still the only protocol supported by several servers and -there are no serious security vulnerabilities known. - -One question that may arise is why we didn't implement @acronym{SSL} -2.0 in the library. There are several reasons, most important being -that it has serious security flaws, unacceptable for a modern security -library. Other than that, this protocol is barely used by anyone -these days since it has been deprecated since 1996. The security -problems in @acronym{SSL} 2.0 include: - -@itemize - -@item Message integrity compromised. -The @acronym{SSLv2} message authentication uses the MD5 function, and -is insecure. - -@item Man-in-the-middle attack. -There is no protection of the handshake in @acronym{SSLv2}, which -permits a man-in-the-middle attack. - -@item Truncation attack. -@acronym{SSLv2} relies on TCP FIN to close the session, so the -attacker can forge a TCP FIN, and the peer cannot tell if it was a -legitimate end of data or not. - -@item Weak message integrity for export ciphers. -The cryptographic keys in @acronym{SSLv2} are used for both message -authentication and encryption, so if weak encryption schemes are -negotiated (say 40-bit keys) the message authentication code use the -same weak key, which isn't necessary. - -@end itemize - -@cindex PCT -Other protocols such as Microsoft's @acronym{PCT} 1 and @acronym{PCT} -2 were not implemented because they were also abandoned and deprecated -by @acronym{SSL} 3.0 and later @acronym{TLS} 1.0. - -@node On Record Padding -@section On Record Padding -@cindex Record padding -@cindex Bad record MAC - -The TLS protocol allows for random padding of records, to make it more -difficult to perform analysis on the length of exchanged messages. -(In RFC 4346 this is specified in section 6.2.3.2.) GnuTLS appears to -be one of few implementation that take advantage of this text, and pad -records by a random length. - -The TLS implementation in the Symbian operating system, frequently -used by Nokia and Sony-Ericsson mobile phones, cannot handle -non-minimal record padding. What happens when one of these clients -handshake with a GnuTLS server is that the client will fail to compute -the correct MAC for the record. The client sends a TLS alert -(@code{bad_record_mac}) and disconnects. Typically this will result -in error messages such as 'A TLS fatal alert has been received', 'Bad -record MAC', or both, on the GnuTLS server side. - -GnuTLS implements a work around for this problem. However, it has to -be enabled specifically. It can be enabled by using -@ref{gnutls_record_disable_padding}, or @ref{gnutls_priority_set} with -the @code{%COMPAT} priority string. - -If you implement an application that have a configuration file, we -recommend that you make it possible for users or administrators to -specify a GnuTLS protocol priority string, which is used by your -application via @ref{gnutls_priority_set}. To allow the best -flexibility, make it possible to have a different priority string for -different incoming IP addresses. - -To enable the workaround in the @code{gnutls-cli} client or the -@code{gnutls-serv} server, for testing of other implementations, use -the following parameter: @code{--priority "%COMPAT"}. - -This problem has been discussed on mailing lists and in bug reports. -This section tries to collect all pieces of information that we know -about the problem. If you wish to go back to the old discussions, -here are some links: - -@url{http://bugs.debian.org/390712} - -@url{http://bugs.debian.org/402861} - -@url{http://bugs.debian.org/438137} - -@url{http://thread.gmane.org/gmane.ietf.tls/3079} - -@node Safe Renegotiation -@section Safe Renegotiation -@cindex renegotiation - -Some application protocols and implementations uses the TLS -renegotiation feature in a manner that enables attackers to insert -content of his choice in the beginning of a TLS session. - -One easy to understand vulnerability is HTTPS when servers request -client certificates optionally for certain parts of a web site. The -attack works by having the attacker simulate a client and connect to a -server, with server-only authentication, and send some data intended -to cause harm. When the proper client attempts to contact the server, -the attacker hijacks that connection and uses the TLS renegotiation -feature with the server and splices in the client connection to the -already established connection between the attacker and server. The -attacker will not be able to read the data exchanged between the -client and the server. However, the server will (incorrectly) assume -that the data sent by the attacker was sent by the now authenticated -client. The result is a prefix plain-text injection attack. - -The above is just one example. Other vulnerabilities exists that do -not rely on the TLS renegotiation to change the client's authenticated -status (either TLS or application layer). - -While fixing these application protocols and implementations would be -one natural reaction, an extension to TLS has been designed that -cryptographically binds together any renegotiated handshakes with the -initial negotiation. When the extension is used, the attack is -detected and the session can be terminated. The extension is -specified in @xcite{RFC5746}. - -GnuTLS supports the safe renegotiation extension. The default -behavior is as follows. Clients will attempt to negotiate the safe -renegotiation extension when talking to servers. Servers will accept -the extension when presented by clients. Clients and servers will -permit an initial handshake to complete even when the other side does -not support the safe renegotiation extension. Clients and servers -will refuse renegotiation attempts when the extension has not been -negotiated. - -Note that permitting clients to connect to servers even when the safe -renegotiation extension is not negotiated open up for some attacks. -Changing this default behaviour would prevent interoperability against -the majority of deployed servers out there. We will reconsider this -default behaviour in the future when more servers have been upgraded. -Note that it is easy to configure clients to always require the safe -renegotiation extension from servers (see below on the -%SAFE_RENEGOTIATION priority string). - -To modify the default behaviour, we have introduced some new priority -strings. The priority strings can be used by applications -(@pxref{gnutls_priority_set}) and end users (e.g., @code{--priority} -parameter to @code{gnutls-cli} and @code{gnutls-serv}). - -The @code{%UNSAFE_RENEGOTIATION} priority string permits -(re-)handshakes even when the safe renegotiation extension was not -negotiated. The default behavior is @code{%PARTIAL_RENEGOTIATION} that will -prevent renegotiation with clients and servers not supporting the -extension. This is secure for servers but leaves clients vulnerable -to some attacks, but this is a tradeoff between security and compatibility -with old servers. The @code{%SAFE_RENEGOTIATION} priority string makes -clients and servers require the extension for every handshake. The latter -is the most secure option for clients, at the cost of not being able -to connect to legacy servers. Servers will also deny clients that -do not support the extension from connecting. - -It is possible to disable use of the extension completely, in both -clients and servers, by using the @code{%DISABLE_SAFE_RENEGOTIATION} -priority string however we strongly recommend you to only do this for -debugging and test purposes. - -The default values if the flags above are not specified are: -@table @code - -@item Server: -%PARTIAL_RENEGOTIATION - -@item Client: -%PARTIAL_RENEGOTIATION - -@end table - -For applications we have introduced a new API related to safe -renegotiation. The @ref{gnutls_safe_renegotiation_status} function is -used to check if the extension has been negotiated on a session, and -can be used both by clients and servers. - -@node Authentication methods -@chapter Authentication Methods - -The @acronym{TLS} protocol provides confidentiality and encryption, -but also offers authentication, which is a prerequisite for a secure -connection. The available authentication methods in @acronym{GnuTLS} -are: - -@itemize - -@item Certificate authentication - -@item Anonymous authentication - -@item @acronym{SRP} authentication - -@item @acronym{PSK} authentication - -@end itemize - -@menu -* Certificate authentication:: -* Anonymous authentication:: -* Authentication using SRP:: -* Authentication using PSK:: -* Authentication and credentials:: -* Parameters stored in credentials:: -@end menu - -@node Certificate authentication -@section Certificate Authentication - -@subsection Authentication Using @acronym{X.509} Certificates -@cindex @acronym{X.509} certificates - -@acronym{X.509} certificates contain the public parameters, of a -public key algorithm, and an authority's signature, which proves the -authenticity of the parameters. @xref{The X.509 trust model}, for -more information on @acronym{X.509} protocols. - -@subsection Authentication Using @acronym{OpenPGP} Keys -@cindex @acronym{OpenPGP} Keys - -@acronym{OpenPGP} keys also contain public parameters of a public key -algorithm, and signatures from several other parties. Depending on -whether a signer is trusted the key is considered trusted or not. -@acronym{GnuTLS}'s @acronym{OpenPGP} authentication implementation is -based on the @xcite{TLSPGP} proposal. - -@xref{The OpenPGP trust model}, for more information about the -@acronym{OpenPGP} trust model. For a more detailed introduction to -@acronym{OpenPGP} and @acronym{GnuPG} see @xcite{GPGH}. - -@subsection Using Certificate Authentication - -In @acronym{GnuTLS} both the @acronym{OpenPGP} and @acronym{X.509} -certificates are part of the certificate authentication and thus are -handled using a common API. - -When using certificates the server is required to have at least one -certificate and private key pair. A client may or may not have such a -pair. The certificate and key pair should be loaded, before any -@acronym{TLS} session is initialized, in a certificate credentials -structure. This should be done by using -@ref{gnutls_certificate_set_x509_key_file} or -@ref{gnutls_certificate_set_openpgp_key_file} depending on the -certificate type. In the @acronym{X.509} case, the functions will -also accept and use a certificate list that leads to a trusted -authority. The certificate list must be ordered in such way that every -certificate certifies the one before it. The trusted authority's -certificate need not to be included, since the peer should possess it -already. - -As an alternative, a callback may be used so the server or the client -specify the certificate and the key at the handshake time. That -callback can be set using the functions: - -@itemize - -@item @ref{gnutls_certificate_server_set_retrieve_function} - -@item @ref{gnutls_certificate_client_set_retrieve_function} - -@end itemize - -Clients and servers that will select certificates using callback -functions should select a certificate according the peer's signature -algorithm preferences. To get those preferences use -@ref{gnutls_sign_algorithm_get_requested}. - -Certificate verification is possible by loading the trusted -authorities into the credentials structure by using -@ref{gnutls_certificate_set_x509_trust_file} or -@ref{gnutls_certificate_set_openpgp_keyring_file} for openpgp -keys. Note however that the peer's certificate is not automatically -verified, you should call @ref{gnutls_certificate_verify_peers2}, -after a successful handshake, to verify the signatures of the -certificate. An alternative way, which reports a more detailed -verification output, is to use @ref{gnutls_certificate_get_peers} to -obtain the raw certificate of the peer and verify it using the -functions discussed in @ref{The X.509 trust model}. - -In a handshake, the negotiated cipher suite depends on the -certificate's parameters, so not all key exchange methods will be -available with some certificates. @acronym{GnuTLS} will disable -ciphersuites that are not compatible with the key, or the enabled -authentication methods. For example keys marked as sign-only, will -not be able to access the plain RSA ciphersuites, but only the -@code{DHE_RSA} ones. It is recommended not to use RSA keys for both -signing and encryption. If possible use the same key for the -@code{DHE_RSA} and @code{RSA_EXPORT} ciphersuites, which use signing, -and a different key for the plain RSA ciphersuites, which use -encryption. All the key exchange methods shown below are available in -certificate authentication. - -Note that the DHE key exchange methods are generally -slower@footnote{It really depends on the group used. Primes with -lesser bits are always faster, but also easier to break. Values less -than 768 should not be used today} than plain RSA and require Diffie -Hellman parameters to be generated and associated with a credentials -structure, by the server. The @code{RSA-EXPORT} method also requires -512 bit RSA parameters, that should also be generated and associated -with the credentials structure. See the functions: - -@itemize - -@item @ref{gnutls_dh_params_generate2} - -@item @ref{gnutls_certificate_set_dh_params} - -@item @ref{gnutls_rsa_params_generate2} - -@item @ref{gnutls_certificate_set_rsa_export_params} - -@end itemize - -Sometimes in order to avoid bottlenecks in programs it is usefull to -store and read parameters from formats that can be generated by -external programs such as @code{certtool}. This is possible with -@acronym{GnuTLS} by using the following functions: - -@itemize - -@item @ref{gnutls_dh_params_import_pkcs3} - -@item @ref{gnutls_rsa_params_import_pkcs1} - -@item @ref{gnutls_dh_params_export_pkcs3} - -@item @ref{gnutls_rsa_params_export_pkcs1} - -@end itemize - -Key exchange algorithms for @acronym{OpenPGP} and @acronym{X.509} -certificates: - -@table @code - -@item RSA: -The RSA algorithm is used to encrypt a key and send it to the peer. -The certificate must allow the key to be used for encryption. - -@item RSA_EXPORT: -The RSA algorithm is used to encrypt a key and send it to the peer. -In the EXPORT algorithm, the server signs temporary RSA parameters of -512 bits --- which are considered weak --- and sends them to the -client. - -@item DHE_RSA: -The RSA algorithm is used to sign Ephemeral Diffie-Hellman parameters -which are sent to the peer. The key in the certificate must allow the -key to be used for signing. Note that key exchange algorithms which -use Ephemeral Diffie-Hellman parameters, offer perfect forward -secrecy. That means that even if the private key used for signing is -compromised, it cannot be used to reveal past session data. - -@item DHE_DSS: -The DSS algorithm is used to sign Ephemeral Diffie-Hellman parameters -which are sent to the peer. The certificate must contain DSA -parameters to use this key exchange algorithm. DSS stands for Digital -Signature Standard. - -@end table - -@node Anonymous authentication -@section Anonymous Authentication -@cindex Anonymous authentication - -The anonymous key exchange performs encryption but there is no -indication of the identity of the peer. This kind of authentication -is vulnerable to a man in the middle attack, but this protocol can be -used even if there is no prior communication and trusted parties with -the peer, or when full anonymity is required. Unless really required, -do not use anonymous authentication. Available key exchange methods -are shown below. - -Note that the key exchange methods for anonymous authentication -require Diffie-Hellman parameters to be generated by the server and -associated with an anonymous credentials structure. - -Supported anonymous key exchange algorithms: - -@table @code - -@item ANON_DH: -This algorithm exchanges Diffie-Hellman parameters. - -@end table - -@node Authentication using SRP -@section Authentication using @acronym{SRP} -@cindex @acronym{SRP} authentication - -Authentication via the Secure Remote Password protocol, -@acronym{SRP}@footnote{@acronym{SRP} is described in @xcite{RFC2945}}, -is supported. The @acronym{SRP} key exchange is an extension to the -@acronym{TLS} protocol, and it is a password based authentication -(unlike @acronym{X.509} or @acronym{OpenPGP} that use certificates). -The two peers can be identified using a single password, or there can -be combinations where the client is authenticated using @acronym{SRP} -and the server using a certificate. - -The advantage of @acronym{SRP} authentication, over other proposed -secure password authentication schemes, is that @acronym{SRP} does not -require the server to hold the user's password. This kind of -protection is similar to the one used traditionally in the @emph{UNIX} -@file{/etc/passwd} file, where the contents of this file did not cause -harm to the system security if they were revealed. The @acronym{SRP} -needs instead of the plain password something called a verifier, which -is calculated using the user's password, and if stolen cannot be used -to impersonate the user. Check @xcite{TOMSRP} for a detailed -description of the @acronym{SRP} protocol and the Stanford -@acronym{SRP} libraries, which includes a PAM module that synchronizes -the system's users passwords with the @acronym{SRP} password -files. That way @acronym{SRP} authentication could be used for all the -system's users. - -The implementation in @acronym{GnuTLS} is based on paper -@xcite{TLSSRP}. The supported @acronym{SRP} key exchange methods are: - -@table @code - -@item SRP: -Authentication using the @acronym{SRP} protocol. - -@item SRP_DSS: -Client authentication using the @acronym{SRP} protocol. Server is -authenticated using a certificate with DSA parameters. - -@item SRP_RSA: -Client authentication using the @acronym{SRP} protocol. Server is -authenticated using a certificate with RSA parameters. - -@end table - -If clients supporting @acronym{SRP} know the username and password -before the connection, should initialize the client credentials and -call the function @ref{gnutls_srp_set_client_credentials}. -Alternatively they could specify a callback function by using the -function @ref{gnutls_srp_set_client_credentials_function}. This has -the advantage that allows probing the server for @acronym{SRP} -support. In that case the callback function will be called twice per -handshake. The first time is before the ciphersuite is negotiated, -and if the callback returns a negative error code, the callback will -be called again if @acronym{SRP} has been negotiated. This uses a -special @acronym{TLS}-@acronym{SRP} handshake idiom in order to avoid, -in interactive applications, to ask the user for @acronym{SRP} -password and username if the server does not negotiate an -@acronym{SRP} ciphersuite. - -In server side the default behaviour of @acronym{GnuTLS} is to read -the usernames and @acronym{SRP} verifiers from password files. These -password files are the ones used by the @emph{Stanford srp libraries} -and can be specified using the -@ref{gnutls_srp_set_server_credentials_file}. If a different -password file format is to be used, then the function -@ref{gnutls_srp_set_server_credentials_function}, should be called, -in order to set an appropriate callback. - -Some helper functions such as - -@itemize - -@item @ref{gnutls_srp_verifier} - -@item @ref{gnutls_srp_base64_encode} - -@item @ref{gnutls_srp_base64_decode} - -@end itemize - -are included in @acronym{GnuTLS}, and can be used to generate and -maintain @acronym{SRP} verifiers and password files. A program to -manipulate the required parameters for @acronym{SRP} authentication is -also included. @xref{srptool}, for more information. - - -@node Authentication using PSK -@section Authentication using @acronym{PSK} -@cindex @acronym{PSK} authentication - -Authentication using Pre-shared keys is a method to authenticate using -usernames and binary keys. This protocol avoids making use of public -key infrastructure and expensive calculations, thus it is suitable for -constraint clients. - -The implementation in @acronym{GnuTLS} is based on paper -@xcite{TLSPSK}. The supported @acronym{PSK} key exchange methods are: - -@table @code - -@item PSK: -Authentication using the @acronym{PSK} protocol. - -@item DHE-PSK: -Authentication using the @acronym{PSK} protocol and Diffie-Hellman key -exchange. This method offers perfect forward secrecy. - -@end table - -Clients supporting @acronym{PSK} should supply the username and key -before the connection to the client credentials by calling the -function @ref{gnutls_psk_set_client_credentials}. Alternatively they -could specify a callback function by using the function -@ref{gnutls_psk_set_client_credentials_function}. This has the -advantage that the callback will be called only if @acronym{PSK} has -been negotiated. - -In server side the default behaviour of @acronym{GnuTLS} is to read -the usernames and @acronym{PSK} keys from a password file. The -password file should contain usernames and keys in hexadecimal -format. The name of the password file can be stored to the credentials -structure by calling @ref{gnutls_psk_set_server_credentials_file}. If -a different 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 - -@item @ref{gnutls_hex_encode} - -@item @ref{gnutls_hex_decode} - -@end itemize - -are included in @acronym{GnuTLS}, and may be used to generate and -maintain @acronym{PSK} keys. - - -@node Authentication and credentials -@section Authentication and Credentials - -In @acronym{GnuTLS} every key exchange method is associated with a -credentials type. So in order to enable to enable a specific method, -the corresponding credentials type should be initialized and set using -@ref{gnutls_credentials_set}. A mapping is shown below. - -Key exchange algorithms and the corresponding credential types: - -@multitable @columnfractions .3 .3 .3 - -@headitem Key exchange @tab Client credentials @tab Server credentials - -@item @code{KX_RSA} -@item @code{KX_DHE_RSA} -@item @code{KX_DHE_DSS} -@item @code{KX_RSA_EXPORT} -@tab @code{CRD_CERTIFICATE} -@tab @code{CRD_CERTIFICATE} - -@item @code{KX_SRP_RSA} -@tab @code{CRD_SRP} -@tab @code{CRD_SRP} -@item @code{KX_SRP_DSS} -@tab -@tab @code{CRD_CERTIFICATE} - -@item @code{KX_SRP} -@tab @code{CRD_SRP} -@tab @code{CRD_SRP} - -@item @code{KX_ANON_DH} -@tab @code{CRD_ANON} -@tab @code{CRD_ANON} - -@item @code{KX_PSK} -@tab @code{CRD_PSK} -@tab @code{CRD_PSK} - -@end multitable - -@node Parameters stored in credentials -@section Parameters Stored in Credentials - -Several parameters such as the ones used for Diffie-Hellman -authentication are stored within the credentials structures, so all -sessions can access them. Those parameters are stored in structures -such as @code{gnutls_dh_params_t} and @code{gnutls_rsa_params_t}, and -functions like @ref{gnutls_certificate_set_dh_params} and -@ref{gnutls_certificate_set_rsa_export_params} can be used to -associate those parameters with the given credentials structure. - -Since those parameters need to be renewed from time to time and a -global structure such as the credentials, may not be easy to modify -since it is accessible by all sessions, an alternative interface is -available using a callback function. This can be set using the -@ref{gnutls_certificate_set_params_function}. An example is shown -below. - -@example -#include <gnutls.h> - -gnutls_rsa_params_t rsa_params; -gnutls_dh_params_t dh_params; - -/* This function will be called once a session requests DH - * or RSA parameters. The parameters returned (if any) will - * be used for the first handshake only. - */ -static int get_params( gnutls_session_t session, - gnutls_params_type_t type, - gnutls_params_st *st) -@{ - if (type == GNUTLS_PARAMS_RSA_EXPORT) - st->params.rsa_export = rsa_params; - else if (type == GNUTLS_PARAMS_DH) - st->params.dh = dh_params; - else return -1; - - st->type = type; - /* do not deinitialize those parameters. - */ - st->deinit = 0; - - return 0; -@} - -int main() -@{ - gnutls_certificate_credentials_t cert_cred; - - initialize_params(); - - /* ... - */ - - gnutls_certificate_set_params_function( cert_cred, get_params); -@} -@end example - -@node More on certificate authentication -@chapter More on Certificate Authentication -@anchor{Certificate Authentication} -@cindex Certificate authentication - -@menu -* The X.509 trust model:: -* The OpenPGP trust model:: -* Digital signatures:: -@end menu - -@node The X.509 trust model -@section The @acronym{X.509} Trust Model -@cindex @acronym{X.509} certificates - -The @acronym{X.509} protocols rely on a hierarchical trust model. In -this trust model Certification Authorities (CAs) are used to certify -entities. Usually more than one certification authorities exist, and -certification authorities may certify other authorities to issue -certificates as well, following a hierarchical model. - -@image{gnutls-x509,7cm,9.5cm} - -One needs to trust one or more CAs for his secure communications. In -that case only the certificates issued by the trusted authorities are -acceptable. See the figure above for a typical example. The API for -handling @acronym{X.509} certificates is described at section -@ref{sec:x509api}. Some examples are listed below. - -@menu -* X.509 certificates:: -* Verifying X.509 certificate paths:: -* PKCS #10 certificate requests:: -* PKCS #12 structures:: -@end menu - -@node X.509 certificates -@subsection @acronym{X.509} Certificates - -An @acronym{X.509} certificate usually contains information about the -certificate holder, the signer, a unique serial number, expiration -dates and some other fields @xcite{PKIX} as shown in the table below. - -@table @code - -@item version: -The field that indicates the version of the certificate. - -@item serialNumber: -This field holds a unique serial number per certificate. - -@item issuer: -Holds the issuer's distinguished name. - -@item validity: -The activation and expiration dates. - -@item subject: -The subject's distinguished name of the certificate. - -@item extensions: -The extensions are fields only present in version 3 certificates. - -@end table - -The certificate's @emph{subject or issuer name} is not just a single -string. It is a Distinguished name and in the @acronym{ASN.1} -notation is a sequence of several object IDs with their corresponding -values. Some of available OIDs to be used in an @acronym{X.509} -distinguished name are defined in @file{gnutls/x509.h}. - -The @emph{Version} field in a certificate has values either 1 or 3 for -version 3 certificates. Version 1 certificates do not support the -extensions field so it is not possible to distinguish a CA from a -person, thus their usage should be avoided. - -The @emph{validity} dates are there to indicate the date that the -specific certificate was activated and the date the certificate's key -would be considered invalid. - -Certificate @emph{extensions} are there to include information about -the certificate's subject that did not fit in the typical certificate -fields. Those may be e-mail addresses, flags that indicate whether the -belongs to a CA etc. All the supported @acronym{X.509} version 3 -extensions are shown in the table below. - -@table @code - -@item subject key id (2.5.29.14): -An identifier of the key of the subject. - -@item authority key id (2.5.29.35): -An identifier of the authority's key used to sign the certificate. - -@item subject alternative name (2.5.29.17): -Alternative names to subject's distinguished name. - -@item key usage (2.5.29.15): -Constraints the key's usage of the certificate. - -@item extended key usage (2.5.29.37): -Constraints the purpose of the certificate. - -@item basic constraints (2.5.29.19): -Indicates whether this is a CA certificate or not, and specify the -maximum path lengths of certificate chains. - -@item CRL distribution points (2.5.29.31): -This extension is set by the CA, in order to inform about the issued -CRLs. - -@item Proxy Certification Information (1.3.6.1.5.5.7.1.14): -Proxy Certificates includes this extension that contains the OID of -the proxy policy language used, and can specify limits on the maximum -lengths of proxy chains. Proxy Certificates are specified in -@xcite{RFC3820}. - -@end table - -In @acronym{GnuTLS} the @acronym{X.509} certificate structures are -handled using the @code{gnutls_x509_crt_t} type and the corresponding -private keys with the @code{gnutls_x509_privkey_t} type. All the -available functions for @acronym{X.509} certificate handling have -their prototypes in @file{gnutls/x509.h}. An example program to -demonstrate the @acronym{X.509} parsing capabilities can be found at -section @ref{ex:x509-info}. - -@node Verifying X.509 certificate paths -@subsection Verifying @acronym{X.509} Certificate Paths -@cindex Verifying certificate paths - -Verifying certificate paths is important in @acronym{X.509} -authentication. For this purpose the function -@ref{gnutls_x509_crt_verify} is provided. The output of this function -is the bitwise OR of the elements of the -@code{gnutls_certificate_status_t} enumeration. A detailed -description of these elements can be found in figure below. The -function @ref{gnutls_certificate_verify_peers2} is equivalent to the -previous one, and will verify the peer's certificate in a TLS session. - -@table @code - -@item GNUTLS_CERT_INVALID: -The certificate is not signed by one of the known authorities, or -the signature is invalid. - -@item GNUTLS_CERT_REVOKED: -The certificate has been revoked by its CA. - -@item GNUTLS_CERT_SIGNER_NOT_FOUND: -The certificate's issuer is not known. This is the case when the -issuer is not in the trusted certificates list. - -@item GNUTLS_CERT_SIGNER_NOT_CA: -The certificate's signer was not a CA. This may happen if -this was a version 1 certificate, which is common with some CAs, or -a version 3 certificate without the basic constrains extension. - -@anchor{GNUTLS_CERT_INSECURE_ALGORITHM} -@item GNUTLS_CERT_INSECURE_ALGORITHM: -The certificate was signed using an insecure algorithm such as MD2 or -MD5. These algorithms have been broken and should not be trusted. - -@end table - -There is also to possibility to pass some input to the verification -functions in the form of flags. For @ref{gnutls_x509_crt_verify} the -flags are passed straightforward, but -@ref{gnutls_certificate_verify_peers2} depends on the flags set by -calling @ref{gnutls_certificate_set_verify_flags}. All the available -flags are part of the enumeration -@ref{gnutls_certificate_verify_flags} and are explained in the table -below. - -@anchor{gnutls_certificate_verify_flags} -@tindex gnutls_certificate_verify_flags -@table @code -@item GNUTLS_VERIFY_DISABLE_CA_SIGN: -If set a signer does not have to be a certificate authority. This -flag should normaly be disabled, unless you know what this means. - -@item GNUTLS_VERIFY_ALLOW_X509_V1_CA_CRT: -Allow only trusted CA certificates that have version 1. This is -safer than GNUTLS_VERIFY_ALLOW_ANY_X509_V1_CA_CRT, and should be -used instead. That way only signers in your trusted list will be -allowed to have certificates of version 1. - -@item GNUTLS_VERIFY_ALLOW_ANY_X509_V1_CA_CRT: -Allow CA certificates that have version 1 (both root and -intermediate). This is dangerous since those haven't the -basicConstraints extension. Must be used in combination with -GNUTLS_VERIFY_ALLOW_X509_V1_CA_CRT. - -@item GNUTLS_VERIFY_DO_NOT_ALLOW_SAME: -If a certificate is not signed by anyone trusted but exists in -the trusted CA list do not treat it as trusted. - -@item GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2: -Allow certificates to be signed using the old MD2 algorithm. - -@item GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5: -Allow certificates to be signed using the broken MD5 algorithm. -@end table - -Although the verification of a certificate path indicates that the -certificate is signed by trusted authority, does not reveal anything -about the peer's identity. It is required to verify if the -certificate's owner is the one you expect. For more information -consult @xcite{RFC2818} and section @ref{ex:verify} for an example. - -@node PKCS #10 certificate requests -@subsection @acronym{PKCS} #10 Certificate Requests -@cindex Certificate requests -@cindex @acronym{PKCS} #10 - -A certificate request is a structure, which contain information about -an applicant of a certificate service. It usually contains a private -key, a distinguished name and secondary data such as a challenge -password. @acronym{GnuTLS} supports the requests defined in -@acronym{PKCS} #10 @xcite{RFC2986}. Other certificate request's format -such as PKIX's @xcite{RFC4211} are not currently supported. - -In @acronym{GnuTLS} the @acronym{PKCS} #10 structures are handled -using the @code{gnutls_x509_crq_t} type. An example of a certificate -request generation can be found at section @ref{ex:crq}. - -@node PKCS #12 structures -@subsection @acronym{PKCS} #12 Structures -@cindex @acronym{PKCS} #12 - -A @acronym{PKCS} #12 structure @xcite{PKCS12} usually contains a user's -private keys and certificates. It is commonly used in browsers to -export and import the user's identities. - -In @acronym{GnuTLS} the @acronym{PKCS} #12 structures are handled -using the @code{gnutls_pkcs12_t} type. This is an abstract type that -may hold several @code{gnutls_pkcs12_bag_t} types. The Bag types are -the holders of the actual data, which may be certificates, private -keys or encrypted data. An Bag of type encrypted should be decrypted -in order for its data to be accessed. - -An example of a @acronym{PKCS} #12 structure generation can be found -at section @ref{ex:pkcs12}. - -@node The OpenPGP trust model -@section The @acronym{OpenPGP} Trust Model -@cindex @acronym{OpenPGP} Keys - -The @acronym{OpenPGP} key authentication relies on a distributed trust -model, called the ``web of trust''. The ``web of trust'' uses a -decentralized system of trusted introducers, which are the same as a -CA. @acronym{OpenPGP} allows anyone to sign anyone's else public -key. When Alice signs Bob's key, she is introducing Bob's key to -anyone who trusts Alice. If someone trusts Alice to introduce keys, -then Alice is a trusted introducer in the mind of that observer. - -@image{gnutls-pgp,11cm,9cm} - -For example: If David trusts Alice to be an introducer, and Alice -signed Bob's key, Dave also trusts Bob's key to be the real one. - -There are some key points that are important in that model. In the -example Alice has to sign Bob's key, only if she is sure that the key -belongs to Bob. Otherwise she may also make Dave falsely believe that -this is Bob's key. Dave has also the responsibility to know who to -trust. This model is similar to real life relations. - -Just see how Charlie behaves in the previous example. Although he has -signed Bob's key - because he knows, somehow, that it belongs to Bob - -he does not trust Bob to be an introducer. Charlie decided to trust -only Kevin, for some reason. A reason could be that Bob is lazy -enough, and signs other people's keys without being sure that they -belong to the actual owner. - -@subsection @acronym{OpenPGP} Keys - -In @acronym{GnuTLS} the @acronym{OpenPGP} key structures -@xcite{RFC2440} are handled using the @code{gnutls_openpgp_crt_t} type -and the corresponding private keys with the -@code{gnutls_openpgp_privkey_t} type. All the prototypes for the key -handling functions can be found at @file{gnutls/openpgp.h}. - -@subsection Verifying an @acronym{OpenPGP} Key - -The verification functions of @acronym{OpenPGP} keys, included in -@acronym{GnuTLS}, are simple ones, and do not use the features of the -``web of trust''. For that reason, if the verification needs are -complex, the assistance of external tools like @acronym{GnuPG} and -GPGME (@url{http://www.gnupg.org/related_software/gpgme/}) is -recommended. - -There is one verification function in @acronym{GnuTLS}, the -@ref{gnutls_openpgp_crt_verify_ring}. This checks an -@acronym{OpenPGP} key against a given set of public keys (keyring) and -returns the key status. The key verification status is the same as in -@acronym{X.509} certificates, although the meaning and interpretation -are different. For example an @acronym{OpenPGP} key may be valid, if -the self signature is ok, even if no signers were found. The meaning -of verification status is shown in the figure below. - -@table @code - -@item CERT_INVALID: -A signature on the key is invalid. That means that the key was -modified by somebody, or corrupted during transport. - -@item CERT_REVOKED: -The key has been revoked by its owner. - -@item CERT_SIGNER_NOT_FOUND: -The key was not signed by a known signer. - -@item GNUTLS_CERT_INSECURE_ALGORITHM: -The certificate was signed using an insecure algorithm such as MD2 or -MD5. These algorithms have been broken and should not be trusted. - -@end table - -@node Digital signatures -@section Digital Signatures -@cindex Digital signatures - -In this section we will provide some information about digital -signatures, how they work, and give the rationale for disabling some -of the algorithms used. - -Digital signatures work by using somebody's secret key to sign some -arbitrary data. Then anybody else could use the public key of that -person to verify the signature. Since the data may be arbitrary it is -not suitable input to a cryptographic digital signature algorithm. For -this reason and also for performance cryptographic hash algorithms are -used to preprocess the input to the signature algorithm. This works as -long as it is difficult enough to generate two different messages with -the same hash algorithm output. In that case the same signature could -be used as a proof for both messages. Nobody wants to sign an innocent -message of donating 1 @euro{} to Greenpeace and find out that he -donated 1.000.000 @euro{} to Bad Inc. - -For a hash algorithm to be called cryptographic the following three -requirements must hold: - -@enumerate -@item Preimage resistance. -That means the algorithm must be one way and given the output of the -hash function @math{H(x)}, it is impossible to calculate @math{x}. - -@item 2nd preimage resistance. -That means that given a pair @math{x,y} with @math{y=H(x)} it is -impossible to calculate an @math{x'} such that @math{y=H(x')}. - -@item Collision resistance. -That means that it is impossible to calculate random @math{x} and -@math{x'} such @math{H(x')=H(x)}. -@end enumerate - -The last two requirements in the list are the most important in -digital signatures. These protect against somebody who would like to -generate two messages with the same hash output. When an algorithm is -considered broken usually it means that the Collision resistance of -the algorithm is less than brute force. Using the birthday paradox the -brute force attack takes -@iftex -@math{2^{(\rm{hash\ size}) / 2}} -@end iftex -@ifnottex -@math{2^{((hash size) / 2)}} -@end ifnottex -operations. Today colliding certificates using the MD5 hash algorithm -have been generated as shown in @xcite{WEGER}. - -There has been cryptographic results for the SHA-1 hash algorithms as -well, although they are not yet critical. Before 2004, MD5 had a -presumed collision strength of @math{2^{64}}, but it has been showed -to have a collision strength well under @math{2^{50}}. As of November -2005, it is believed that SHA-1's collision strength is around -@math{2^{63}}. We consider this sufficiently hard so that we still -support SHA-1. We anticipate that SHA-256/386/512 will be used in -publicly-distributed certificates in the future. When @math{2^{63}} -can be considered too weak compared to the computer power available -sometime in the future, SHA-1 will be disabled as well. The collision -attacks on SHA-1 may also get better, given the new interest in tools -for creating them. - -@subsection Trading Security for Interoperability - -If you connect to a server and use GnuTLS' functions to verify the -certificate chain, and get a @ref{GNUTLS_CERT_INSECURE_ALGORITHM} -validation error (@pxref{Verifying X.509 certificate paths}), it means -that somewhere in the certificate chain there is a certificate signed -using @code{RSA-MD2} or @code{RSA-MD5}. These two digital signature -algorithms are considered broken, so GnuTLS fail when attempting to -verify the certificate. In some situations, it may be useful to be -able to verify the certificate chain anyway, assuming an attacker did -not utilize the fact that these signatures algorithms are broken. -This section will give help on how to achieve that. - -First, it is important to know that you do not have to enable any of -the flags discussed here to be able to use trusted root CA -certificates signed using @code{RSA-MD2} or @code{RSA-MD5}. The only -attack today is that it is possible to generate certificates with -colliding signatures (collision resistance); you cannot generate a -certificate that has the same signature as an already existing -signature (2nd preimage resistance). - -If you are using @ref{gnutls_certificate_verify_peers2} to verify the -certificate chain, you can call -@ref{gnutls_certificate_set_verify_flags} with the -@code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2} or -@code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5} flag, as in: - -@example - gnutls_certificate_set_verify_flags (x509cred, - GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5); -@end example - -This will tell the verifier algorithm to enable @code{RSA-MD5} when -verifying the certificates. - -If you are using @ref{gnutls_x509_crt_verify} or -@ref{gnutls_x509_crt_list_verify}, you can pass the -@code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5} parameter directly in the -@code{flags} parameter. - -If you are using these flags, it may also be a good idea to warn the -user when verification failure occur for this reason. The simplest is -to not use the flags by default, and only fall back to using them -after warning the user. If you wish to inspect the certificate chain -yourself, you can use @ref{gnutls_certificate_get_peers} to extract -the raw server's certificate chain, then use -@ref{gnutls_x509_crt_import} to parse each of the certificates, and -then use @ref{gnutls_x509_crt_get_signature_algorithm} to find out the -signing algorithm used for each certificate. If any of the -intermediary certificates are using @code{GNUTLS_SIGN_RSA_MD2} or -@code{GNUTLS_SIGN_RSA_MD5}, you could present a warning. - - - -@node How to use TLS in application protocols -@chapter How To Use @acronym{TLS} in Application Protocols - -This chapter is intended to provide some hints on how to use the -@acronym{TLS} over simple custom made application protocols. The -discussion below mainly refers to the @emph{TCP/IP} transport layer -but may be extended to other ones too. - -@menu -* Separate ports:: -* Upward negotiation:: -@end menu - -@node Separate ports -@section Separate Ports - -Traditionally @acronym{SSL} was used in application protocols by -assigning a new port number for the secure services. That way two -separate ports were assigned, one for the non secure sessions, and one -for the secured ones. This has the benefit that if a user requests a -secure session then the client will try to connect to the secure port -and fail otherwise. The only possible attack with this method is a -denial of service one. The most famous example of this method is the -famous ``HTTP over TLS'' or @acronym{HTTPS} protocol @xcite{RFC2818}. - -Despite its wide use, this method is not as good as it seems. This -approach starts the @acronym{TLS} Handshake procedure just after the -client connects on the ---so called--- secure port. That way the -@acronym{TLS} protocol does not know anything about the client, and -popular methods like the host advertising in HTTP do not -work@footnote{See also the Server Name Indication extension on -@ref{serverind}.}. There is no way for the client to say ``I -connected to YYY server'' before the Handshake starts, so the server -cannot possibly know which certificate to use. - -Other than that it requires two separate ports to run a single -service, which is unnecessary complication. Due to the fact that there -is a limitation on the available privileged ports, this approach was -soon obsoleted. - -@node Upward negotiation -@section Upward Negotiation - -Other application protocols@footnote{See LDAP, IMAP etc.} use a -different approach to enable the secure layer. They use something -called the ``TLS upgrade'' method. This method is quite tricky but it -is more flexible. The idea is to extend the application protocol to -have a ``STARTTLS'' request, whose purpose it to start the TLS -protocols just after the client requests it. This is a really neat -idea and does not require an extra port. - -This method is used by almost all modern protocols and there is even -the @xcite{RFC2817} paper which proposes extensions to HTTP to support -it. - -The tricky part, in this method, is that the ``STARTTLS'' request is -sent in the clear, thus is vulnerable to modifications. A typical -attack is to modify the messages in a way that the client is fooled -and thinks that the server does not have the ``STARTTLS'' capability. -See a typical conversation of a hypothetical protocol: - -@quotation -(client connects to the server) - -CLIENT: HELLO I'M MR. XXX - -SERVER: NICE TO MEET YOU XXX - -CLIENT: PLEASE START TLS - -SERVER: OK - -*** TLS STARTS - -CLIENT: HERE ARE SOME CONFIDENTIAL DATA -@end quotation - -And see an example of a conversation where someone is acting -in between: - -@quotation -(client connects to the server) - -CLIENT: HELLO I'M MR. XXX - -SERVER: NICE TO MEET YOU XXX - -CLIENT: PLEASE START TLS - -(here someone inserts this message) - -SERVER: SORRY I DON'T HAVE THIS CAPABILITY - -CLIENT: HERE ARE SOME CONFIDENTIAL DATA -@end quotation - -As you can see above the client was fooled, and was dummy enough to -send the confidential data in the clear. - -How to avoid the above attack? As you may have already thought this -one is easy to avoid. The client has to ask the user before it -connects whether the user requests @acronym{TLS} or not. If the user -answered that he certainly wants the secure layer the last -conversation should be: - -@quotation -(client connects to the server) - -CLIENT: HELLO I'M MR. XXX - -SERVER: NICE TO MEET YOU XXX - -CLIENT: PLEASE START TLS - -(here someone inserts this message) - -SERVER: SORRY I DON'T HAVE THIS CAPABILITY - -CLIENT: BYE - -(the client notifies the user that the secure connection was not possible) -@end quotation - -This method, if implemented properly, is far better than the -traditional method, and the security properties remain the same, since -only denial of service is possible. The benefit is that the server may -request additional data before the @acronym{TLS} Handshake protocol -starts, in order to send the correct certificate, use the correct -password file@footnote{in @acronym{SRP} authentication}, or anything -else! - -@node How to use GnuTLS in applications -@chapter How To Use @acronym{GnuTLS} in Applications -@anchor{examples} -@cindex Example programs - -@menu -* Preparation:: -* Multi-threaded applications:: -* Client examples:: -* Server examples:: -* Miscellaneous examples:: -* Compatibility with the OpenSSL library:: -* Opaque PRF Input TLS Extension:: -* Keying Material Exporters:: -@end menu - -@node Preparation -@section Preparation - -To use @acronym{GnuTLS}, you have to perform some changes to your -sources and your build system. The necessary changes are explained in -the following subsections. - -@menu -* Headers:: -* Initialization:: -* Version check:: -* Debugging:: -* Building the source:: -@end menu - -@node Headers -@subsection Headers - -All the data types and functions of the @acronym{GnuTLS} library are -defined in the header file @file{gnutls/gnutls.h}. This must be -included in all programs that make use of the @acronym{GnuTLS} -library. - -The extra functionality of the @acronym{GnuTLS-extra} library is -available by including the header file @file{gnutls/extra.h} in your -programs. - -@node Initialization -@subsection Initialization - -GnuTLS must be initialized before it can be used. The library is -initialized by calling @ref{gnutls_global_init}. The resources -allocated by the initialization process can be released if the -application no longer has a need to call GnuTLS functions, this is -done by calling @ref{gnutls_global_deinit}. - -The extra functionality of the @acronym{GnuTLS-extra} library is -available after calling @ref{gnutls_global_init_extra}. - -In order to take advantage of the internationalisation features in -GnuTLS, such as translated error messages, the application must set -the current locale using @code{setlocale} before initializing GnuTLS. - -@node Version check -@subsection Version Check - -It is often desirable to check that the version of `gnutls' used is -indeed one which fits all requirements. Even with binary -compatibility new features may have been introduced but due to problem -with the dynamic linker an old version is actually used. So you may -want to check that the version is okay right after program startup. -See the function @ref{gnutls_check_version}. - -@node Debugging -@subsection Debugging - -In many cases things may not go as expected and further information, -to assist debugging, from @acronym{GnuTLS} is desired. Those are the -case where the @ref{gnutls_global_set_log_level} and -@ref{gnutls_global_set_log_function} are to be used. Those will print -verbose information on the @acronym{GnuTLS} functions internal flow. - -@node Building the source -@subsection Building the Source - -If you want to compile a source file including the -@file{gnutls/gnutls.h} header file, you must make sure that the -compiler can find it in the directory hierarchy. This is accomplished -by adding the path to the directory in which the header file is -located to the compilers include file search path (via the @option{-I} -option). - -However, the path to the include file is determined at the time the -source is configured. To solve this problem, the library uses the -external package @command{pkg-config} that knows the path to the -include file and other configuration options. The options that need -to be added to the compiler invocation at compile time are output by -the @option{--cflags} option to @command{pkg-config gnutls}. The -following example shows how it can be used at the command line: - -@example -gcc -c foo.c `pkg-config gnutls --cflags` -@end example - -Adding the output of @samp{pkg-config gnutls --cflags} to the -compilers command line will ensure that the compiler can find the -@file{gnutls/gnutls.h} header file. - -A similar problem occurs when linking the program with the library. -Again, the compiler has to find the library files. For this to work, -the path to the library files has to be added to the library search -path (via the @option{-L} option). For this, the option -@option{--libs} to @command{pkg-config gnutls} can be used. For -convenience, this option also outputs all other options that are -required to link the program with the libarary (for instance, the -@samp{-ltasn1} option). The example shows how to link @file{foo.o} -with the library to a program @command{foo}. - -@example -gcc -o foo foo.o `pkg-config gnutls --libs` -@end example - -Of course you can also combine both examples to a single command by -specifying both options to @command{pkg-config}: - -@example -gcc -o foo foo.c `pkg-config gnutls --cflags --libs` -@end example - -@node Multi-threaded applications -@section Multi-Threaded Applications - -Although the @acronym{GnuTLS} library is thread safe by design, some -parts of Libgcrypt, such as the random generator, are not. -Applications have to register callback functions to ensure proper -locking in the sensitive parts of @emph{libgcrypt}. - -There are helper macros to help you properly initialize the libraries. -Examples are shown below. - -@itemize - -@item POSIX threads -@example -#include <gnutls.h> -#include <gcrypt.h> -#include <errno.h> -#include <pthread.h> -GCRY_THREAD_OPTION_PTHREAD_IMPL; - -int main() -@{ - /* The order matters. - */ - gcry_control (GCRYCTL_SET_THREAD_CBS, &gcry_threads_pthread); - gnutls_global_init(); -@} -@end example - -@item GNU PTH threads -@example -#include <gnutls.h> -#include <gcrypt.h> -#include <errno.h> -#include <pth.h> -GCRY_THREAD_OPTION_PTH_IMPL; - -int main() -@{ - gcry_control (GCRYCTL_SET_THREAD_CBS, &gcry_threads_pth); - gnutls_global_init(); -@} -@end example - -@item Other thread packages -@example -/* The gcry_thread_cbs structure must have been - * initialized. - */ -static struct gcry_thread_cbs gcry_threads_other = @{ ... @}; - -int main() -@{ - gcry_control (GCRYCTL_SET_THREAD_CBS, &gcry_threads_other); -@} -@end example -@end itemize - -@node Client examples -@section Client Examples - -This section contains examples of @acronym{TLS} and @acronym{SSL} -clients, using @acronym{GnuTLS}. Note that these examples contain -little or no error checking. Some of the examples require functions -implemented by another example. - -@menu -* Simple client example with anonymous authentication:: -* Simple client example with X.509 certificate support:: -* Obtaining session information:: -* Verifying peer's certificate:: -* Using a callback to select the certificate to use:: -* Client with Resume capability example:: -* Simple client example with SRP authentication:: -* Simple client example with TLS/IA support:: -* Simple client example in C++:: -* Helper function for TCP connections:: -@end menu - -@node Simple client example with anonymous authentication -@subsection Simple Client Example with Anonymous Authentication - -The simplest client using TLS is the one that doesn't do any -authentication. This means no external certificates or passwords are -needed to set up the connection. As could be expected, the connection -is vulnerable to man-in-the-middle (active or redirection) attacks. -However, the data is integrity and privacy protected. - -@verbatiminclude examples/ex-client1.c - -@node Simple client example with X.509 certificate support -@subsection Simple Client Example with @acronym{X.509} Certificate Support - -Let's assume now that we want to create a TCP client which -communicates with servers that use @acronym{X.509} or -@acronym{OpenPGP} certificate authentication. The following client is -a very simple @acronym{TLS} client, it does not support session -resuming, not even certificate verification. The TCP functions defined -in this example are used in most of the other examples below, without -redefining them. - -@verbatiminclude examples/ex-client2.c - -@node Obtaining session information -@subsection Obtaining Session Information - -Most of the times it is desirable to know the security properties of -the current established session. This includes the underlying ciphers -and the protocols involved. That is the purpose of the following -function. Note that this function will print meaningful values only -if called after a successful @ref{gnutls_handshake}. - -@verbatiminclude examples/ex-session-info.c - -@node Verifying peer's certificate -@subsection Verifying Peer's Certificate -@anchor{ex:verify} - -A @acronym{TLS} session is not secure just after the handshake -procedure has finished. It must be considered secure, only after the -peer's certificate and identity have been verified. That is, you have -to verify the signature in peer's certificate, the hostname in the -certificate, and expiration dates. Just after this step you should -treat the connection as being a secure one. - -@verbatiminclude examples/ex-rfc2818.c - -An other example is listed below which provides a more detailed -verification output. - -@verbatiminclude examples/ex-verify.c - -@node Using a callback to select the certificate to use -@subsection Using a Callback to Select the Certificate to Use - -There are cases where a client holds several certificate and key -pairs, and may not want to load all of them in the credentials -structure. The following example demonstrates the use of the -certificate selection callback. - -@verbatiminclude examples/ex-cert-select.c - -@subsection Using a Callback to Select a @acronym{PKCS} #11 Certificate - -This example will demonstrate how to load keys and certificates -from a @acronym{PKCS} #11 module, which is typically used -for keys and certificates stored in smart cards. - -@verbatiminclude examples/ex-cert-select-pkcs11.c - -@node Client with Resume capability example -@subsection Client with Resume Capability Example -@anchor{ex:resume-client} - -This is a modification of the simple client example. Here we -demonstrate the use of session resumption. The client tries to connect -once using @acronym{TLS}, close the connection and then try to -establish a new connection using the previously negotiated data. - -@verbatiminclude examples/ex-client-resume.c - -@node Simple client example with SRP authentication -@subsection Simple Client Example with @acronym{SRP} Authentication - -The following client is a very simple @acronym{SRP} @acronym{TLS} -client which connects to a server and authenticates using a -@emph{username} and a @emph{password}. The server may authenticate -itself using a certificate, and in that case it has to be verified. - -@verbatiminclude examples/ex-client-srp.c - -@node Simple client example with TLS/IA support -@subsection Simple Client Example with @acronym{TLS/IA} Support - -The following client is a simple client which uses the -@acronym{TLS/IA} extension to authenticate with the server. - -@verbatiminclude examples/ex-client-tlsia.c - -@node Simple client example in C++ -@subsection Simple Client Example using the C++ API - -The following client is a simple example of a client client utilizing -the GnuTLS C++ API. - -@verbatiminclude examples/ex-cxx.cpp - -@node Helper function for TCP connections -@subsection Helper Function for TCP Connections - -This helper function abstracts away TCP connection handling from the -other examples. It is required to build some examples. - -@verbatiminclude examples/tcp.c - -@node Server examples -@section Server Examples - -This section contains examples of @acronym{TLS} and @acronym{SSL} -servers, using @acronym{GnuTLS}. - -@menu -* Echo Server with X.509 authentication:: -* Echo Server with X.509 authentication II:: -* Echo Server with OpenPGP authentication:: -* Echo Server with SRP authentication:: -* Echo Server with anonymous authentication:: -@end menu - -@node Echo Server with X.509 authentication -@subsection Echo Server with @acronym{X.509} Authentication - -This example is a very simple echo server which supports -@acronym{X.509} authentication, using the RSA ciphersuites. - -@verbatiminclude examples/ex-serv1.c - -@node Echo Server with X.509 authentication II -@subsection Echo Server with @acronym{X.509} Authentication II - -The following example is a server which supports @acronym{X.509} -authentication. This server supports the export-grade cipher suites, -the DHE ciphersuites and session resuming. - -@verbatiminclude examples/ex-serv-export.c - -@node Echo Server with OpenPGP authentication -@subsection Echo Server with @acronym{OpenPGP} Authentication -@cindex @acronym{OpenPGP} Server - -The following example is an echo server which supports -@acronym{@acronym{OpenPGP}} key authentication. You can easily combine -this functionality ---that is have a server that supports both -@acronym{X.509} and @acronym{OpenPGP} certificates--- but we separated -them to keep these examples as simple as possible. - -@verbatiminclude examples/ex-serv-pgp.c - -@node Echo Server with SRP authentication -@subsection Echo Server with @acronym{SRP} Authentication - -This is a server which supports @acronym{SRP} authentication. It is -also possible to combine this functionality with a certificate -server. Here it is separate for simplicity. - -@verbatiminclude examples/ex-serv-srp.c - -@node Echo Server with anonymous authentication -@subsection Echo Server with Anonymous Authentication - -This example server support anonymous authentication, and could be -used to serve the example client for anonymous authentication. - -@verbatiminclude examples/ex-serv-anon.c - -@node Miscellaneous examples -@section Miscellaneous Examples - -@menu -* Checking for an alert:: -* X.509 certificate parsing example:: -* Certificate request generation:: -* PKCS #12 structure generation:: -@end menu - -@node Checking for an alert -@subsection Checking for an Alert - -This is a function that checks if an alert has been received in the -current session. - -@verbatiminclude examples/ex-alert.c - -@node X.509 certificate parsing example -@subsection @acronym{X.509} Certificate Parsing Example -@anchor{ex:x509-info} - -To demonstrate the @acronym{X.509} parsing capabilities an example program is -listed below. That program reads the peer's certificate, and prints -information about it. - -@verbatiminclude examples/ex-x509-info.c - -@node Certificate request generation -@subsection Certificate Request Generation -@anchor{ex:crq} - -The following example is about generating a certificate request, and a -private key. A certificate request can be later be processed by a CA, -which should return a signed certificate. - -@verbatiminclude examples/ex-crq.c - -@node PKCS #12 structure generation -@subsection @acronym{PKCS} #12 Structure Generation -@anchor{ex:pkcs12} - -The following example is about generating a @acronym{PKCS} #12 -structure. - -@verbatiminclude examples/ex-pkcs12.c - -@node Compatibility with the OpenSSL library -@section Compatibility with the OpenSSL Library -@cindex OpenSSL - -To ease @acronym{GnuTLS}' integration with existing applications, a -compatibility layer with the widely used OpenSSL library is included -in the @code{gnutls-openssl} library. This compatibility layer is not -complete and it is not intended to completely reimplement the OpenSSL -API with @acronym{GnuTLS}. It only provides source-level -compatibility. There is currently no attempt to make it -binary-compatible with OpenSSL. - -The prototypes for the compatibility functions are in the -@file{gnutls/openssl.h} header file. - -Current limitations imposed by the compatibility layer include: - -@itemize - -@item Error handling is not thread safe. - -@end itemize - -@node Opaque PRF Input TLS Extension -@section Opaque PRF Input TLS Extension -@cindex Opaque PRF Input - -GnuTLS supports the Opaque PRF Input TLS extension -(@code{draft-rescorla-tls-opaque-prf-input-00.txt}). The API consists -of one API for use in the client, @ref{gnutls_oprfi_enable_client}, -and one API for use in the server, @ref{gnutls_oprfi_enable_server}. -You must invoke both functions before calling @ref{gnutls_handshake}. -The server utilizes a callback function into the application. The -callback can look at the random string provided by the client, and -also set the server string. The string lengths must be equal -according to the protocol. - -@node Keying Material Exporters -@section Keying Material Exporters -@cindex Keying Material Exporters -@cindex Exporting Keying Material - -The TLS PRF can be used by other protocols to derive data. The API to -use is @ref{gnutls_prf}. The function needs to be provided with the -label in the parameter @code{label}, and the extra data to mix in the -@code{extra} parameter. Depending on whether you want to mix in the -client or server random data first, you can set the -@code{server_random_first} parameter. - -For example, after establishing a TLS session using -@ref{gnutls_handshake}, you can invoke the TLS PRF with this call: - -@smallexample -#define MYLABEL "EXPORTER-FOO" -#define MYCONTEXT "some context data" -char out[32]; -rc = gnutls_prf (session, strlen (MYLABEL), MYLABEL, 0, - strlen (MYCONTEXT), MYCONTEXT, 32, out); -@end smallexample - -If you don't want to mix in the client/server random, there is a more -low-level TLS PRF interface called @ref{gnutls_prf_raw}. - -@node Included programs -@chapter Included Programs - -Included with @acronym{GnuTLS} are also a few command line tools that -let you use the library for common tasks without writing an -application. The applications are discussed in this chapter. - -@menu -* Invoking certtool:: -* Invoking gnutls-cli:: -* Invoking gnutls-cli-debug:: -* Invoking gnutls-serv:: -* Invoking psktool:: -* Invoking srptool:: -@end menu - -@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 -@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. - -@item -To create a private key (RSA by default), run: - -@example -$ certtool --generate-privkey --outfile key.pem -@end example - -To create a DSA private key, run: - -@example -$ certtool --dsa --generate-privkey --outfile key-dsa.pem -@end example - -@item -To generate a certificate using the private key, use the command: - -@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 - -@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 - -Some tools (reportedly web browsers) have problems with that file -because it does not contain the CA certificate for the certificate. -To work around that problem in the tool, you can use the -@samp{--load-ca-certificate} parameter as follows: - -@example -$ certtool --load-ca-certificate ca.pem \ - --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" -#dns_name = "www.morethanone.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 preferred 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 - -Simple client program to set up a TLS connection to some other -computer. It sets up a TLS connection and forwards data from the -standard input to the secured socket and vice versa. - -@verbatim -GnuTLS test client -Usage: gnutls-cli [options] hostname - - -d, --debug integer Enable debugging - -r, --resume Connect, establish a session. Connect - again and resume this session. - -s, --starttls Connect, establish a plain session and - start TLS when EOF or a SIGALRM is - received. - --crlf Send CR LF instead of LF. - --x509fmtder Use DER format for certificates to read - from. - -f, --fingerprint Send the openpgp fingerprint, instead - of the key. - --disable-extensions Disable all the TLS extensions. - --print-cert Print the certificate in PEM format. - --recordsize integer The maximum record size to advertize. - -V, --verbose More verbose output. - --ciphers cipher1 cipher2... - Ciphers to enable. - --protocols protocol1 protocol2... - Protocols to enable. - --comp comp1 comp2... Compression methods to enable. - --macs mac1 mac2... MACs to enable. - --kx kx1 kx2... Key exchange methods to enable. - --ctypes certType1 certType2... - Certificate types to enable. - --priority PRIORITY STRING - Priorities string. - --x509cafile FILE Certificate file to use. - --x509crlfile FILE CRL file to use. - --pgpkeyfile FILE PGP Key file to use. - --pgpkeyring FILE PGP Key ring file to use. - --pgpcertfile FILE PGP Public Key (certificate) file to - use. - --pgpsubkey HEX|auto PGP subkey to use. - --x509keyfile FILE X.509 key file to use. - --x509certfile FILE X.509 Certificate file to use. - --srpusername NAME SRP username to use. - --srppasswd PASSWD SRP password to use. - --pskusername NAME PSK username to use. - --pskkey KEY PSK key (in hex) to use. - --opaque-prf-input DATA - Use Opaque PRF Input DATA. - -p, --port PORT The port to connect to. - --insecure Don't abort program if server - certificate can't be validated. - -l, --list Print a list of the supported - algorithms and modes. - -h, --help prints this help - -v, --version prints the program's version number -@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 - -This program was created to assist in debugging @acronym{GnuTLS}, but -it might be useful to extract a @acronym{TLS} server's capabilities. -It's purpose is to connect onto a @acronym{TLS} server, perform some -tests and print the server's capabilities. If called with the `-v' -parameter a more checks will be performed. An example output is: - -@smallexample -crystal:/cvs/gnutls/src$ ./gnutls-cli-debug localhost -p 5556 -Resolving 'localhost'... -Connecting to '127.0.0.1:5556'... -Checking for TLS 1.1 support... yes -Checking fallback from TLS 1.1 to... N/A -Checking for TLS 1.0 support... yes -Checking for SSL 3.0 support... yes -Checking for version rollback bug in RSA PMS... no -Checking for version rollback bug in Client Hello... no -Checking whether we need to disable TLS 1.0... N/A -Checking whether the server ignores the RSA PMS version... no -Checking whether the server can accept Hello Extensions... yes -Checking whether the server can accept cipher suites not in SSL 3.0 spec... yes -Checking whether the server can accept a bogus TLS record version in the client hello... yes -Checking for certificate information... N/A -Checking for trusted CAs... N/A -Checking whether the server understands TLS closure alerts... yes -Checking whether the server supports session resumption... yes -Checking for export-grade ciphersuite support... no -Checking RSA-export ciphersuite info... N/A -Checking for anonymous authentication support... no -Checking anonymous Diffie-Hellman group info... N/A -Checking for ephemeral Diffie-Hellman support... no -Checking ephemeral Diffie-Hellman group info... N/A -Checking for AES cipher support (TLS extension)... yes -Checking for 3DES cipher support... yes -Checking for ARCFOUR 128 cipher support... yes -Checking for ARCFOUR 40 cipher support... no -Checking for MD5 MAC support... yes -Checking for SHA1 MAC support... yes -Checking for ZLIB compression support (TLS extension)... yes -Checking for LZO compression support (GnuTLS extension)... yes -Checking for max record size (TLS extension)... yes -Checking for SRP authentication support (TLS extension)... yes -Checking for OpenPGP authentication support (TLS extension)... no -@end smallexample - -@node Invoking gnutls-serv -@section Invoking gnutls-serv -@cindex gnutls-serv - -Simple server program that listens to incoming TLS connections. - -@verbatim -GnuTLS test server -Usage: gnutls-serv [options] - - -d, --debug integer Enable debugging - -g, --generate Generate Diffie-Hellman Parameters. - -p, --port integer The port to connect to. - -q, --quiet Suppress some messages. - --nodb Does not use the resume database. - --http Act as an HTTP Server. - --echo Act as an Echo Server. - --dhparams FILE DH params file to use. - --x509fmtder Use DER format for certificates - --x509cafile FILE Certificate file to use. - --x509crlfile FILE CRL file to use. - --pgpkeyring FILE PGP Key ring file to use. - --pgpkeyfile FILE PGP Key file to use. - --pgpcertfile FILE PGP Public Key (certificate) file to - use. - --pgpsubkey HEX|auto PGP subkey to use. - --x509keyfile FILE X.509 key file to use. - --x509certfile FILE X.509 Certificate file to use. - --x509dsakeyfile FILE Alternative X.509 key file to use. - --x509dsacertfile FILE Alternative X.509 certificate file to - use. - -r, --require-cert Require a valid certificate. - -a, --disable-client-cert - Disable request for a client - certificate. - --pskpasswd FILE PSK password file to use. - --pskhint HINT PSK identity hint to use. - --srppasswd FILE SRP password file to use. - --srppasswdconf FILE SRP password conf file to use. - --opaque-prf-input DATA - Use Opaque PRF Input DATA. - --ciphers cipher1 cipher2... - Ciphers to enable. - --protocols protocol1 protocol2... - Protocols to enable. - --comp comp1 comp2... Compression methods to enable. - --macs mac1 mac2... MACs to enable. - --kx kx1 kx2... Key exchange methods to enable. - --ctypes certType1 certType2... - Certificate types to enable. - --priority PRIORITY STRING - Priorities string. - -l, --list Print a list of the supported - algorithms and modes. - -h, --help prints this help - -v, --version prints the program's version number -@end verbatim - -@subsection Setting Up a Test HTTPS Server -@cindex HTTPS server -@cindex debug server - -Running your own TLS server based on GnuTLS can be useful when -debugging clients and/or GnuTLS itself. This section describes how to -use @code{gnutls-serv} as a simple HTTPS server. - -The most basic server can be started as: - -@example -gnutls-serv --http -@end example - -It will only support anonymous ciphersuites, which many TLS clients -refuse to use. - -The next step is to add support for X.509. First we generate a CA: - -@example -certtool --generate-privkey > x509-ca-key.pem -echo 'cn = GnuTLS test CA' > ca.tmpl -echo 'ca' >> ca.tmpl -echo 'cert_signing_key' >> ca.tmpl -certtool --generate-self-signed --load-privkey x509-ca-key.pem \ - --template ca.tmpl --outfile x509-ca.pem -... -@end example - -Then generate a server certificate. Remember to change the dns_name -value to the name of your server host, or skip that command to avoid -the field. - -@example -certtool --generate-privkey > x509-server-key.pem -echo 'organization = GnuTLS test server' > server.tmpl -echo 'cn = test.gnutls.org' >> server.tmpl -echo 'tls_www_server' >> server.tmpl -echo 'encryption_key' >> server.tmpl -echo 'signing_key' >> server.tmpl -echo 'dns_name = test.gnutls.org' >> server.tmpl -certtool --generate-certificate --load-privkey x509-server-key.pem \ - --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \ - --template server.tmpl --outfile x509-server.pem -... -@end example - -For use in the client, you may want to generate a client certificate -as well. - -@example -certtool --generate-privkey > x509-client-key.pem -echo 'cn = GnuTLS test client' > client.tmpl -echo 'tls_www_client' >> client.tmpl -echo 'encryption_key' >> client.tmpl -echo 'signing_key' >> client.tmpl -certtool --generate-certificate --load-privkey x509-client-key.pem \ - --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \ - --template client.tmpl --outfile x509-client.pem -... -@end example - -To be able to import the client key/certificate into some -applications, you will need to convert them into a PKCS#12 structure. -This also encrypts the security sensitive key with a password. - -@example -certtool --to-p12 --load-ca-certificate x509-ca.pem --load-privkey x509-client-key.pem --load-certificate x509-client.pem --outder --outfile x509-client.p12 -@end example - -For icing, we'll create a proxy certificate for the client too. - -@example -certtool --generate-privkey > x509-proxy-key.pem -echo 'cn = GnuTLS test client proxy' > proxy.tmpl -certtool --generate-proxy --load-privkey x509-proxy-key.pem \ - --load-ca-certificate x509-client.pem --load-ca-privkey x509-client-key.pem \ - --load-certificate x509-client.pem --template proxy.tmpl \ - --outfile x509-proxy.pem -... -@end example - -Then start the server again: - -@example -gnutls-serv --http \ - --x509cafile x509-ca.pem \ - --x509keyfile x509-server-key.pem \ - --x509certfile x509-server.pem -@end example - -Try connecting to the server using your web browser. Note that the -server listens to port 5556 by default. - -While you are at it, to allow connections using DSA, you can also -create a DSA key and certificate for the server. These credentials -will be used in the final example below. - -@example -certtool --generate-privkey --dsa > x509-server-key-dsa.pem -certtool --generate-certificate --load-privkey x509-server-key-dsa.pem \ - --load-ca-certificate x509-ca.pem --load-ca-privkey x509-ca-key.pem \ - --template server.tmpl --outfile x509-server-dsa.pem -... -@end example - -The next step is to create OpenPGP credentials for the server. - -@example -gpg --gen-key -...enter whatever details you want, use 'test.gnutls.org' as name... -@end example - -Make a note of the OpenPGP key identifier of the newly generated key, -here it was @code{5D1D14D8}. You will need to export the key for -GnuTLS to be able to use it. - -@example -gpg -a --export 5D1D14D8 > openpgp-server.txt -gpg --export 5D1D14D8 > openpgp-server.bin -gpg --export-secret-keys 5D1D14D8 > openpgp-server-key.bin -gpg -a --export-secret-keys 5D1D14D8 > openpgp-server-key.txt -@end example - -Let's start the server with support for OpenPGP credentials: - -@example -gnutls-serv --http \ - --pgpkeyfile openpgp-server-key.txt \ - --pgpcertfile openpgp-server.txt -@end example - -The next step is to add support for SRP authentication. - -@example -srptool --create-conf srp-tpasswd.conf -srptool --passwd-conf srp-tpasswd.conf --username jas --passwd srp-passwd.txt -Enter password: [TYPE "foo"] -@end example - -Start the server with SRP support: - -@example -gnutls-serv --http \ - --srppasswdconf srp-tpasswd.conf \ - --srppasswd srp-passwd.txt -@end example - -Let's also add support for PSK. - -@example -$ psktool --passwd psk-passwd.txt -@end example - -Start the server with PSK support: - -@example -gnutls-serv --http \ - --pskpasswd psk-passwd.txt -@end example - -Finally, we start the server with all the earlier parameters and you -get this command: - -@example -gnutls-serv --http \ - --x509cafile x509-ca.pem \ - --x509keyfile x509-server-key.pem \ - --x509certfile x509-server.pem \ - --x509dsakeyfile x509-server-key-dsa.pem \ - --x509dsacertfile x509-server-dsa.pem \ - --pgpkeyfile openpgp-server-key.txt \ - --pgpcertfile openpgp-server.txt \ - --srppasswdconf srp-tpasswd.conf \ - --srppasswd srp-passwd.txt \ - --pskpasswd psk-passwd.txt -@end example - -@menu -* Example server PSK connection:: -@end menu - -@node Example server PSK connection -@subsection Example server PSK connection -@cindex PSK server - -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. - -@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 - -After this, start the server pointing to the password file. We -disable DHE-PSK. - -@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 - -You can now connect to the server using a PSK client (@pxref{Example -client PSK connection}). - -@node Invoking psktool -@section Invoking psktool -@cindex psktool - -This is a program to manage @acronym{PSK} username and keys. - -@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 - -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 ""}. - -@node Invoking srptool -@section Invoking srptool -@anchor{srptool} -@cindex srptool - -The @file{srptool} is a very simple program that emulates the programs -in the @emph{Stanford SRP libraries}, see -@url{http://srp.stanford.edu/}. 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 @code{tpasswd} -which holds usernames and verifiers, and @code{tpasswd.conf} which -holds generators and primes. - -How to use srptool: - -@itemize - -@item -To create tpasswd.conf which holds the g and n values for -@acronym{SRP} protocol (generator and a large prime), run: - -@example -$ srptool --create-conf /etc/tpasswd.conf -@end example - -@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. - -@example -$ srptool --passwd /etc/tpasswd \ - --passwd-conf /etc/tpasswd.conf -u test -@end example - -@item -This command will check against a password. If the password matches -the one in /etc/tpasswd you will get an ok. - -@example -$ srptool --passwd /etc/tpasswd \ - --passwd-conf /etc/tpasswd.conf --verify -u test -@end example - -@end itemize - -@node Function reference -@chapter Function Reference -@cindex Function reference - -@menu -* Core functions:: -* X.509 certificate functions:: -* GnuTLS-extra functions:: -* OpenPGP functions:: -* TLS Inner Application (TLS/IA) functions:: -* Error codes and descriptions:: -@end menu - -@node Core functions -@section Core Functions - -The prototypes for the following functions lie in -@file{gnutls/gnutls.h}. - -@include gnutls-api.texi - -@node X.509 certificate functions -@section @acronym{X.509} Certificate Functions -@anchor{sec:x509api} -@cindex @acronym{X.509} Functions - -The following functions are to be used for @acronym{X.509} certificate handling. -Their prototypes lie in @file{gnutls/x509.h}. - -@include x509-api.texi - -@node GnuTLS-extra functions -@section @acronym{GnuTLS-extra} Functions -@cindex @acronym{GnuTLS-extra} functions - -These functions are only available in the GPLv3+ version of the -library called @code{gnutls-extra}. The prototypes for this library -lie in @file{gnutls/extra.h}. - -@include extra-api.texi - -@node OpenPGP functions -@section @acronym{OpenPGP} Functions -@cindex @acronym{OpenPGP} functions -@anchor{sec:openpgpapi} - -The following functions are to be used for @acronym{OpenPGP} -certificate handling. Their prototypes lie in -@file{gnutls/openpgp.h}. - -@include pgp-api.texi - -@node TLS Inner Application (TLS/IA) functions -@section @acronym{TLS} Inner Application (@acronym{TLS/IA}) Functions -@cindex @acronym{TLS} Inner Application (@acronym{TLS/IA}) functions -@cindex Inner Application (@acronym{TLS/IA}) functions - -The following functions are used for @acronym{TLS} Inner Application -(@acronym{TLS/IA}). Their prototypes lie in @file{gnutls/extra.h}. -You need to link with @file{libgnutls-extra} to be able to use these -functions (@pxref{GnuTLS-extra functions}). - -The typical control flow in an TLS/IA client (that would not require -an Application Phase for resumed sessions) would be similar to the -following: - -@example -int client_avp (gnuls_session_t *session, void *ptr, - const char *last, size_t lastlen, - char **new, size_t *newlen) -@{ -... -@} -... -int main () -@{ - gnutls_ia_client_credentials_t iacred; -... - gnutls_init (&session, GNUTLS_CLIENT); -... - /* Enable TLS/IA. */ - gnutls_ia_allocate_client_credentials(&iacred); - gnutls_ia_set_client_avp_function(iacred, client_avp); - gnutls_credentials_set (session, GNUTLS_CRD_IA, iacred); -... - ret = gnutls_handshake (session); - // Error handling... -... - if (gnutls_ia_handshake_p (session)) - @{ - ret = gnutls_ia_handshake (session); - // Error handling... -... -@end example - -See below for detailed descriptions of all the functions used above. - -The function @code{client_avp} would have to be implemented by your -application. The function is responsible for handling the AVP data. -See @code{gnutls_ia_set_client_avp_function} below for more -information on how that function should be implemented. - -The control flow in a typical server is similar to the above, use -@code{gnutls_ia_server_credentials_t} instead of -@code{gnutls_ia_client_credentials_t}, and replace the call to the -client functions with the corresponding server functions. - -@include ia-api.texi - -@node Error codes and descriptions -@section Error Codes and Descriptions -@anchor{Error Codes} -@cindex Error codes - -The error codes used throughout the library are described below. The -return code @code{GNUTLS_E_SUCCESS} indicate successful operation, and -is guaranteed to have the value 0, so you can use it in logical -expressions. - -@include error_codes.texi - -@node All the supported ciphersuites in GnuTLS -@chapter All the Supported Ciphersuites in @acronym{GnuTLS} -@anchor{ciphersuites} -@cindex Ciphersuites - -@include algorithms.texi - -Some additional information regarding some of the algorithms: - -@table @code -@item RSA -RSA is public key cryptosystem designed by Ronald Rivest, Adi Shamir -and Leonard Adleman. It can be used with any hash functions. - -@item DSA -DSA is the USA's Digital Signature Standard. It uses only the SHA-1 -hash algorithm. - -@item MD2 -MD2 is a cryptographic hash algorithm designed by Ron Rivest. It is -optimized for 8-bit processors. Outputs 128 bits of data. There are -no known weaknesses of this algorithm but since this algorithm is -rarely used and not really studied it should not be used today. - -@item MD5 -MD5 is a cryptographic hash algorithm designed by Ron Rivest. Outputs -128 bits of data. It is considered to be broken. - -@item SHA-1 -SHA is a cryptographic hash algorithm designed by NSA. Outputs 160 -bits of data. It is also considered to be broken, though no practical -attacks have been found. - -@item RMD160 -RIPEMD is a cryptographic hash algorithm developed in the framework of -the EU project RIPE. Outputs 160 bits of data. - -@end table - -@c -@c Guile Bindings -@c - -@include guile.texi - - -@node Internal architecture of GnuTLS -@chapter Internal Architecture of GnuTLS -@cindex Internal architecture - -This chapter is to give a brief description of the -way @acronym{GnuTLS} works. The focus is to give an idea -to potential developers and those who want to know what -happens inside the black box. - -@menu -* The TLS Protocol:: -* TLS Handshake Protocol:: -* TLS Authentication Methods:: -* TLS Extension Handling:: -* Certificate Handling:: -* Cryptographic Backend:: -@end menu - -@node The TLS Protocol -@section The TLS Protocol -The main needs for the TLS protocol to be used are -shown in the image below. - -@image{gnutls-client-server-use-case,9cm} - -This is being accomplished by the following object diagram. -Note that since @acronym{GnuTLS} is being developed in C -object are just structures with attributes. The operations listed -are functions that require the first parameter to be that object. -@image{gnutls-objects,15cm} - -@node TLS Handshake Protocol -@section TLS Handshake Protocol -The @acronym{GnuTLS} handshake protocol is implemented as a state -machine that waits for input or returns immediately when the non-blocking -transport layer functions are used. The main idea is shown in the following -figure. - -@image{gnutls-handshake-state,9cm} - -Also the way the input is processed varies per ciphersuite. Several -implementations of the internal handlers are available and -@ref{gnutls_handshake} only multiplexes the input to the appropriate -handler. For example a @acronym{PSK} ciphersuite has a different -implementation of the @code{process_client_key_exchange} than a -certificate ciphersuite. - -@image{gnutls-handshake-sequence,12cm} - -@node TLS Authentication Methods -@section TLS Authentication Methods -In @acronym{GnuTLS} authentication methods can be implemented quite -easily. Since the required changes to add a new authentication method -affect only the handshake protocol, a simple interface is used. An -authentication method needs only to implement the functions as seen in -the figure below. - -@image{gnutls-mod_auth_st,12cm} - -The functions that need to be implemented are the ones responsible for -interpreting the handshake protocol messages. It is common for such -functions to read data from one or more @code{credentials_t} -structures@footnote{such as the -@code{gnutls_certificate_credentials_t} structures} and write data, -such as certificates, usernames etc. to @code{auth_info_t} structures. - -Simple examples of existing authentication methods can be seen in -@code{auth_psk.c} for PSK ciphersuites and @code{auth_srp.c} for SRP -ciphersuites. After implementing these functions the structure holding -its pointers has to be registered in @code{gnutls_algorithms.c} in the -@code{_gnutls_kx_algorithms} structure. - -@node TLS Extension Handling -@section TLS Extension Handling -As with authentication methods, the TLS extensions handlers can be -implemented using the following interface. - -@image{gnutls-extensions_st,12cm} - -Here there are two functions, one for receiving the extension data -and one for sending. These functions have to check internally whether -they operate in client or server side. - -A simple example of an extension handler can be seen in -@code{ext_srp.c} After implementing these functions, together with the -extension number they handle, they have to be registered in -@code{gnutls_extensions.c} in the @code{_gnutls_extensions} structure. - -@subsection Adding a New TLS Extension - -Adding support for a new TLS extension is done from time to time, and -the process to do so is not difficult. Here are the steps you need to -follow if you wish to do this yourself. For sake of discussion, let's -consider adding support for the hypothetical TLS extension -@code{foobar}. - -@enumerate - -@item Add @code{configure} option like @code{--enable-foobar} or @code{--disable-foobar}. - -Which to chose depends on whether you intend to make the extension be -enabled by default. Look at existing checks (i.e., SRP, authz) for -how to model the code. For example: - -@example -AC_MSG_CHECKING([whether to disable foobar support]) -AC_ARG_ENABLE(foobar, - AS_HELP_STRING([--disable-foobar], - [disable foobar support]), - ac_enable_foobar=no) -if test x$ac_enable_foobar != xno; then - AC_MSG_RESULT(no) - AC_DEFINE(ENABLE_FOOBAR, 1, [enable foobar]) -else - ac_full=0 - AC_MSG_RESULT(yes) -fi -AM_CONDITIONAL(ENABLE_FOOBAR, test "$ac_enable_foobar" != "no") -@end example - -These lines should go in @code{lib/m4/hooks.m4}. - -@item Add IANA extension value to @code{extensions_t} in @code{gnutls_int.h}. - -A good name for the value would be GNUTLS_EXTENSION_FOOBAR. Check -with @url{http://www.iana.org/assignments/tls-extensiontype-values} -for allocated values. For experiments, you could pick a number but -remember that some consider it a bad idea to deploy such modified -version since it will lead to interoperability problems in the future -when the IANA allocates that number to someone else, or when the -foobar protocol is allocated another number. - -@item Add an entry to @code{_gnutls_extensions} in @code{gnutls_extensions.c}. - -A typical entry would be: - -@example - int ret; - - /* ... - */ - -#if ENABLE_FOOBAR - ret = gnutls_ext_register (GNUTLS_EXTENSION_FOOBAR, - "FOOBAR", - GNUTLS_EXT_TLS, - _gnutls_foobar_recv_params, - _gnutls_foobar_send_params); - if (ret != GNUTLS_E_SUCCESS) - return ret; -#endif -@end example - -The GNUTLS_EXTENSION_FOOBAR is the integer value you added to -@code{gnutls_int.h} earlier. The two functions are new functions that -you will need to implement, most likely you'll need to add an -@code{#include "ext_foobar.h"} as well. - -@item Add new files @code{ext_foobar.c} and @code{ext_foobar.h} that implements the extension. - -The functions you are responsible to add are those mentioned in the -previous step. As a starter, you could add this: - -@example -int -_gnutls_foobar_recv_params (gnutls_session_t session, - const opaque * data, - size_t data_size) -@{ - return 0; -@} - -int -_gnutls_foobar_send_params (gnutls_session_t session, - opaque * data, - size_t _data_size) -@{ - return 0; -@} -@end example - -The @code{_gnutls_foobar_recv_params} function is responsible for -parsing incoming extension data (both in the client and server). - -The @code{_gnutls_foobar_send_params} function is responsible for -sending extension data (both in the client and server). - -If you receive length fields that doesn't match, return -@code{GNUTLS_E_UNEXPECTED_PACKET_LENGTH}. If you receive invalid -data, return @code{GNUTLS_E_RECEIVED_ILLEGAL_PARAMETER}. You can use -other error codes too. Return 0 on success. - -The function typically store some information in the @code{session} -variable for later usage. If you need to add new fields there, check -@code{tls_ext_st} in @code{gnutls_int.h} and compare with existing TLS -extension specific variables. - -Recall that both the client and server both send and receives -parameters, and your code most likely will need to do different things -depending on which mode it is in. It may be useful to make this -distinction explicit in the code. Thus, for example, a better -template than above would be: - -@example -int -_gnutls_foobar_recv_params (gnutls_session_t session, - const opaque * data, - size_t data_size) -@{ - if (session->security_parameters.entity == GNUTLS_CLIENT) - return foobar_recv_client (session, data, data_size); - else - return foobar_recv_server (session, data, data_size); -@} - -int -_gnutls_foobar_send_params (gnutls_session_t session, - opaque * data, - size_t data_size) -@{ - if (session->security_parameters.entity == GNUTLS_CLIENT) - return foobar_send_client (session, data, data_size); - else - return foobar_send_server (session, data, data_size); -@} -@end example - -The functions used would be declared as @code{static} functions, of -the appropriate prototype, in the same file. - -When adding the files, you'll need to add them to @code{Makefile.am} -as well, for example: - -@example -if ENABLE_FOOBAR -COBJECTS += ext_foobar.c -HFILES += ext_foobar.h -endif -@end example - -@item Add API functions to enable/disable the extension. - -Normally the client will have one API to request use of the extension, -and setting some extension specific data. The server will have one -API to let the library know that it is willing to accept the -extension, often this is implemented through a callback but it doesn't -have to. - -The APIs need to be added to @code{includes/gnutls/gnutls.h} or -@code{includes/gnutls/extra.h} as appropriate. It is recommended that -if you don't have a requirement to use the LGPLv2.1+ license for your -extension, that you place your work under the GPLv3+ license and thus -in the libgnutls-extra library. - -You can implement the API function in the @code{ext_foobar.c} file, or -if that file ends up becoming rather larger, add a -@code{gnutls_foobar.c} file. - -To make the API available in the shared library you need to add the -symbol in @code{lib/libgnutls.map} or -@code{libextra/libgnutls-extra.map} as appropriate, so that the symbol -is exported properly. - -When writing GTK-DOC style documentation for your new APIs, don't -forget to add @code{Since:} tags to indicate the GnuTLS version the -API was introduced in. - -@end enumerate - -@node Certificate Handling -@section Certificate Handling -What is provided by the certificate handling functions -is summarized in the following diagram. - -@image{gnutls-certificate-user-use-case,12cm} - -@node Cryptographic Backend -@section Cryptographic Backend -Several new systems provide hardware assisted cryptographic algorithm -implementations that offer implementations some orders of magnitude -faster than the software. For this reason GnuTLS supports by default -the /dev/crypto device usually found in FreeBSD and OpenBSD system, to -take advantage of installed hardware. - -In addition it is possible to override parts of the crypto backend or the -whole. It is possible to override them both at runtime and compile -time, however here we will discuss the runtime possibility. The API -available for this functionality is in @code{gnutls/crypto.h} header -file. - -@subsection Override specific algorithms -When an optimized implementation of a single algorithm is available, -say a hardware assisted version of @acronym{AES-CBC} then the -following functions can be used to register those algorithms. - -@itemize - -@item @ref{gnutls_crypto_single_cipher_register2} -To register a cipher algorithm. - -@ref{gnutls_crypto_single_digest_register2} -To register a hash (digest) or MAC algorithm. - -@end itemize - -Those registration functions will only replace the specified algorithm -and leave the rest of subsystem intact. - -@subsection Override parts of the backend -In some systems, such as embedded ones, it might be desirable to -override big parts of the cryptographic backend, or even all of -them. For this reason the following functions are provided. - -@itemize - -@item @ref{gnutls_crypto_cipher_register2} -To override the cryptographic algorithms backend. - -@item @ref{gnutls_crypto_digest_register2} -To override the digest algorithms backend. - -@item @ref{gnutls_crypto_rnd_register2} -To override the random number generator backend. - -@item @ref{gnutls_crypto_bigint_register2} -To override the big number number operations backend. - -@item @ref{gnutls_crypto_pk_register2} -To override the public key encryption backend. This is tight to the -big number operations so either both of them should be updated or care -must be taken to use the same format. - -@end itemize - -If all of them are used then GnuTLS will no longer use libgcrypt. - -@node Copying Information -@appendix Copying Information - -@menu -* GNU Free Documentation License:: License for copying this manual. -* GNU LGPL:: License for copying the core GnuTLS library. -* GNU GPL:: License for copying GnuTLS-extra and tools. -@end menu - -@node GNU Free Documentation License -@appendixsec GNU Free Documentation License - -@cindex FDL, GNU Free Documentation License - -@include fdl-1.3.texi - -@node GNU LGPL -@appendixsec GNU Lesser General Public License -@cindex LGPL, GNU Lesser General Public License -@cindex License, GNU LGPL - -@include lgpl-2.1.texi - -@node GNU GPL -@appendixsec GNU General Public License -@cindex GPL, GNU General Public License -@cindex License, GNU GPL - -@include gpl-3.0.texi - -@node Bibliography -@unnumbered Bibliography - -@table @asis - -@item @anchor{CBCATT}[CBCATT] -Bodo Moeller, "Security of CBC Ciphersuites in SSL/TLS: Problems and -Countermeasures", 2002, available from -@url{http://www.openssl.org/~bodo/tls-cbc.txt}. - -@item @anchor{GPGH}[GPGH] -Mike Ashley, "The GNU Privacy Handbook", 2002, available from -@url{http://www.gnupg.org/gph/en/manual.pdf}. - -@item @anchor{GUTPKI}[GUTPKI] -Peter Gutmann, "Everything you never wanted to know about PKI but were -forced to find out", Available from -@url{http://www.cs.auckland.ac.nz/~pgut001/}. - -@item @anchor{NISTSP80057}[NISTSP80057] -NIST Special Publication 800-57, "Recommendation for Key Management - -Part 1: General (Revised)", March 2007, available from -@url{http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57-Part1-revised2_Mar08-2007.pdf}. - -@item @anchor{RFC2246}[RFC2246] -Tim Dierks and Christopher Allen, "The TLS Protocol Version 1.0", -January 1999, Available from -@url{http://www.ietf.org/rfc/rfc2246.txt}. - -@item @anchor{RFC4346}[RFC4346] -Tim Dierks and Eric Rescorla, "The TLS Protocol Version 1.1", Match -2006, Available from @url{http://www.ietf.org/rfc/rfc4346.txt}. - -@item @anchor{RFC2440}[RFC2440] -Jon Callas, Lutz Donnerhacke, Hal Finney and Rodney Thayer, "OpenPGP -Message Format", November 1998, Available from -@url{http://www.ietf.org/rfc/rfc2440.txt}. - -@item @anchor{RFC4880}[RFC4880] -Jon Callas, Lutz Donnerhacke, Hal Finney, David Shaw and Rodney -Thayer, "OpenPGP Message Format", November 2007, Available from -@url{http://www.ietf.org/rfc/rfc4880.txt}. - -@item @anchor{RFC4211}[RFC4211] -J. Schaad, "Internet X.509 Public Key Infrastructure Certificate -Request Message Format (CRMF)", September 2005, Available from -@url{http://www.ietf.org/rfc/rfc4211.txt}. - -@item @anchor{RFC2817}[RFC2817] -Rohit Khare and Scott Lawrence, "Upgrading to TLS Within HTTP/1.1", -May 2000, Available from @url{http://www.ietf.org/rfc/rfc2817.txt} - -@item @anchor{RFC2818}[RFC2818] -Eric Rescorla, "HTTP Over TLS", May 2000, Available from -@url{http://www.ietf/rfc/rfc2818.txt}. - -@item @anchor{RFC2945}[RFC2945] -Tom Wu, "The SRP Authentication and Key Exchange System", September -2000, Available from @url{http://www.ietf.org/rfc/rfc2945.txt}. - -@item @anchor{RFC2986}[RFC2986] -Magnus Nystrom and Burt Kaliski, "PKCS 10 v1.7: Certification Request -Syntax Specification", November 2000, Available from -@url{http://www.ietf.org/rfc/rfc2986.txt}. - -@item @anchor{PKIX}[PKIX] -D. Cooper, S. Santesson, S. Farrel, S. Boeyen, R. Housley, W. Polk, -"Internet X.509 Public Key Infrastructure Certificate and Certificate -Revocation List (CRL) Profile", May 2008, available from -@url{http://www.ietf.org/rfc/rfc5280.txt}. - -@item @anchor{RFC3749}[RFC3749] -Scott Hollenbeck, "Transport Layer Security Protocol Compression -Methods", May 2004, available from -@url{http://www.ietf.org/rfc/rfc3749.txt}. - -@item @anchor{RFC3820}[RFC3820] -Steven Tuecke, Von Welch, Doug Engert, Laura Pearlman, and Mary -Thompson, "Internet X.509 Public Key Infrastructure (PKI) Proxy -Certificate Profile", June 2004, available from -@url{http://www.ietf.org/rfc/rfc3820}. - -@item @anchor{RFC5746}[RFC5746] -E. Rescorla, M. Ray, S. Dispensa, and N. Oskov, "Transport Layer -Security (TLS) Renegotiation Indication Extension", February 2010, -available from @url{http://www.ietf.org/rfc/rfc5746}. - -@item @anchor{TLSTKT}[TLSTKT] -Joseph Salowey, Hao Zhou, Pasi Eronen, Hannes Tschofenig, "Transport -Layer Security (TLS) Session Resumption without Server-Side State", -January 2008, available from @url{http://www.ietf.org/rfc/rfc5077}. - -@item @anchor{PKCS12}[PKCS12] -RSA Laboratories, "PKCS 12 v1.0: Personal Information Exchange -Syntax", June 1999, Available from @url{http://www.rsa.com}. - -@item @anchor{RESCORLA}[RESCORLA] -Eric Rescorla, "SSL and TLS: Designing and Building Secure Systems", -2001 - -@item @anchor{SELKEY}[SELKEY] -Arjen Lenstra and Eric Verheul, "Selecting Cryptographic Key Sizes", -2003, available from @url{http://www.win.tue.nl/~klenstra/key.pdf}. - -@item @anchor{SSL3}[SSL3] -Alan Freier, Philip Karlton and Paul Kocher, "The SSL Protocol Version -3.0", November 1996, Available from -@url{http://wp.netscape.com/eng/ssl3/draft302.txt}. - -@item @anchor{STEVENS}[STEVENS] -Richard Stevens, "UNIX Network Programming, Volume 1", Prentice Hall -PTR, January 1998 - -@item @anchor{TLSEXT}[TLSEXT] -Simon Blake-Wilson, Magnus Nystrom, David Hopwood, Jan Mikkelsen and -Tim Wright, "Transport Layer Security (TLS) Extensions", June 2003, -Available from @url{http://www.ietf.org/rfc/rfc3546.txt}. - -@item @anchor{TLSPGP}[TLSPGP] -Nikos Mavrogiannopoulos, "Using OpenPGP keys for TLS authentication", -April 2004, November 2007. Available from -@url{http://www.ietf.org/rfc/rfc5081.txt}. +@include cha-programs.texi -@item @anchor{TLSSRP}[TLSSRP] -David Taylor, Trevor Perrin, Tom Wu and Nikos Mavrogiannopoulos, -"Using SRP for TLS Authentication", November 2007. Available from -@url{http://www.ietf.org/rfc/rfc5054.txt}. +@include cha-functions.texi -@item @anchor{TLSPSK}[TLSPSK] -Pasi Eronen and Hannes Tschofenig, "Pre-shared key Ciphersuites for -TLS", December 2005, Available from -@url{http://www.ietf.org/rfc/rfc4279.txt}. +@include cha-ciphersuites.texi -@item @anchor{TOMSRP}[TOMSRP] -Tom Wu, "The Stanford SRP Authentication Project", Available at -@url{http://srp.stanford.edu/}. +@include cha-internals.texi -@item @anchor{WEGER}[WEGER] -Arjen Lenstra and Xiaoyun Wang and Benne de Weger, "Colliding X.509 -Certificates", Cryptology ePrint Archive, Report 2005/067, Available -at @url{http://eprint.iacr.org/}. +@include cha-copying.texi -@end table +@include cha-bib.texi @node Function and Data Index @unnumbered Function and Data Index diff --git a/lib/includes/gnutls/pkcs11.h b/lib/includes/gnutls/pkcs11.h index 1064c5e2cc..40bda70771 100644 --- a/lib/includes/gnutls/pkcs11.h +++ b/lib/includes/gnutls/pkcs11.h @@ -147,14 +147,6 @@ int gnutls_pkcs11_copy_x509_privkey(const char* token_url, gnutls_x509_privkey_t crt, const char* label, unsigned int key_usage /*GNUTLS_KEY_* */); int gnutls_pkcs11_delete_url(const char* object_url); -/** - * @brief Release array of certificate references. - * @param certificates Array to free. - * @param ncertificates Array size. - * @return gnutls status. - */ -int gnutls_pkcs11_obj_list_deinit (gnutls_pkcs11_obj_t * , const unsigned int nobjs); - typedef enum { GNUTLS_PKCS11_OBJ_ID_HEX=1, GNUTLS_PKCS11_OBJ_LABEL, diff --git a/lib/libgnutls.map b/lib/libgnutls.map index 950ac59590..2acda43b54 100644 --- a/lib/libgnutls.map +++ b/lib/libgnutls.map @@ -615,7 +615,6 @@ GNUTLS_2_11 gnutls_pkcs11_obj_import_url; gnutls_pkcs11_obj_export_url; gnutls_pkcs11_obj_deinit; - gnutls_pkcs11_obj_list_deinit; gnutls_pkcs11_obj_list_import_url; gnutls_x509_crt_import_pkcs11; gnutls_pkcs11_obj_get_type; diff --git a/lib/pkcs11.c b/lib/pkcs11.c index 6b658b9b4f..e35dcc1cec 100644 --- a/lib/pkcs11.c +++ b/lib/pkcs11.c @@ -2140,8 +2140,20 @@ int gnutls_x509_crt_import_pkcs11( gnutls_x509_crt_t crt, gnutls_pkcs11_obj_t pk return gnutls_x509_crt_import(crt, &pkcs11_crt->raw, GNUTLS_X509_FMT_DER); } +/** + * gnutls_x509_crt_list_import_pkcs11: + * @cert: A list of certificates of type #gnutls_x509_crt_t + * @cert_max: The maximum size of the list + * @objs: A list of PKCS 11 objects + * + * This function will import a PKCS 11 certificate list to a list of + * #gnutls_x509_crt_t structure. These must not be initialized. + * + * Returns: On success, %GNUTLS_E_SUCCESS is returned, otherwise a + * negative error value. + **/ int gnutls_x509_crt_list_import_pkcs11 (gnutls_x509_crt_t * certs, - unsigned int cert_max, gnutls_pkcs11_obj_t * const pkcs11_certs, + unsigned int cert_max, gnutls_pkcs11_obj_t * const objs, unsigned int flags) { int i, j; @@ -2154,7 +2166,7 @@ int gnutls_x509_crt_list_import_pkcs11 (gnutls_x509_crt_t * certs, goto cleanup; } - ret = gnutls_x509_crt_import_pkcs11( certs[i], pkcs11_certs[i]); + ret = gnutls_x509_crt_import_pkcs11( certs[i], objs[i]); if (ret < 0) { gnutls_assert(); goto cleanup; |