[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[SCM] GNU gnutls branch, master, updated. gnutls_3_0_8-6-g54e3f5b
|
From: |
Nikos Mavrogiannopoulos |
|
Subject: |
[SCM] GNU gnutls branch, master, updated. gnutls_3_0_8-6-g54e3f5b |
|
Date: |
Mon, 14 Nov 2011 15:57:13 +0000 |
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU gnutls".
http://git.savannah.gnu.org/cgit/gnutls.git/commit/?id=54e3f5b50c173083ef8e870d1b29321f06cc8873
The branch, master has been updated
via 54e3f5b50c173083ef8e870d1b29321f06cc8873 (commit)
from 06010f7310003259e617ada2a7275900553b9e99 (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 54e3f5b50c173083ef8e870d1b29321f06cc8873
Author: Nikos Mavrogiannopoulos <address@hidden>
Date: Sun Nov 13 21:25:55 2011 +0100
reorganized documentation
-----------------------------------------------------------------------
Summary of changes:
doc/Makefile.am | 5 +-
doc/cha-auth.texi | 498 -------------------------
doc/cha-cert-auth.texi | 885 +-------------------------------------------
doc/cha-cert-auth2.texi | 823 ++++++++++++++++++++++++++++++++++++++++
doc/cha-gtls-app.texi | 759 +++++++++++++++++++++++--------------
doc/cha-gtls-examples.texi | 221 +++++++++++
doc/cha-intro-tls.texi | 288 ++++++++-------
doc/cha-library.texi | 177 +--------
doc/cha-shared-key.texi | 202 ++++++++++
doc/gnutls.texi | 14 +-
doc/latex/.gitignore | 3 +
doc/latex/Makefile.am | 14 +-
doc/latex/gnutls.tex | 8 +-
doc/scripts/mytexi2latex | 1 +
14 files changed, 1927 insertions(+), 1971 deletions(-)
delete mode 100644 doc/cha-auth.texi
create mode 100644 doc/cha-cert-auth2.texi
create mode 100644 doc/cha-gtls-examples.texi
create mode 100644 doc/cha-shared-key.texi
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 1625209..9907daf 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -31,11 +31,12 @@ endif
info_TEXINFOS = gnutls.texi gnutls-guile.texi
gnutls_TEXINFOS = gnutls.texi fdl-1.3.texi lgpl-2.1.texi gpl-3.0.texi \
- cha-auth.texi cha-bib.texi cha-cert-auth.texi \
+ cha-bib.texi cha-cert-auth.texi \
cha-ciphersuites.texi cha-copying.texi cha-functions.texi \
cha-gtls-app.texi cha-internals.texi cha-intro-tls.texi \
cha-library.texi cha-preface.texi cha-programs.texi \
- sec-tls-app.texi cha-errors.texi cha-support.texi
+ sec-tls-app.texi cha-errors.texi cha-support.texi \
+ cha-shared-key.texi
# Examples.
gnutls_TEXINFOS += examples/ex-client1.c \
diff --git a/doc/cha-auth.texi b/doc/cha-auth.texi
deleted file mode 100644
index 7315389..0000000
--- a/doc/cha-auth.texi
+++ /dev/null
@@ -1,498 +0,0 @@
address@hidden Authentication methods
address@hidden 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:
-
address@hidden
-
address@hidden Certificate authentication: Authenticated key exchange using
public key infrastructure and certificates (X.509 or OpenPGP).
-
address@hidden @acronym{SRP} authentication: Authenticated key exchange using a
password.
-
address@hidden @acronym{PSK} authentication: Authenticated key exchange using a
pre-shared key.
-
address@hidden Anonymous authentication: Key exchange without peer
authentication.
-
address@hidden itemize
-
-The rule for each method is to allocate a credentials
-structure containing data required for authentication and
-associate that structure with the session using
address@hidden Various authentication methods might
-require additional data to be stored in the credential structures,
-such as ephemeral Diffie-Hellman parameters etc.
-In the next paragraphs
-we elaborate on supported authentication methods.
-
address@hidden
-
address@hidden
-* Certificate authentication::
-* Anonymous authentication::
-* SRP authentication::
-* PSK authentication::
-* Authentication and credentials::
address@hidden menu
-
address@hidden Certificate authentication
address@hidden Certificate authentication
-
address@hidden Authentication using @acronym{X.509} certificates
address@hidden X.509 certificates
-
address@hidden certificates contain the public parameters, of a
-public key algorithm, and an authority's signature, which proves the
-authenticity of the parameters. See @ref{X.509 certificates}, for
-more information on @acronym{X.509} protocols.
-
address@hidden Authentication using @acronym{OpenPGP} keys
address@hidden OpenPGP keys
-
address@hidden 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.
address@hidden's @acronym{OpenPGP} authentication implementation is
-based on the @xcite{TLSPGP} proposal.
-
-More information on the @acronym{OpenPGP} trusted model is provided in
@ref{OpenPGP certificates}.
-For a more detailed introduction to @acronym{OpenPGP} and @acronym{GnuPG} see
@xcite{GPGH}.
-
address@hidden 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.
-
address@hidden,gnutls_certificate_free_credentials}
-
-After the credentials structures are initialized using the functions
-above, the certificate and key pair should be loaded. This should
-occur before any @acronym{TLS} session is initialized.
-Depending on the certificate type different loading functions
-are available, and are shown below.
-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.
-
address@hidden,gnutls_certificate_set_openpgp_key,gnutls_certificate_set_openpgp_key_file,gnutls_certificate_set_openpgp_key_mem}
address@hidden,gnutls_certificate_set_key}
-
address@hidden
-
-As an alternative to loading from files, a callback may be used so that the
-server or the client can specify the certificate and the key at the handshake
time.
-In that case a certificate should be selected according the peer's signature
-algorithm preferences. To get those preferences use
address@hidden Both functions are shown below.
-
address@hidden
-
address@hidden
-
-
-Certificate verification is possible by loading the trusted
-authorities into the credentials structure by using
-the following functions, applicable to X.509 and OpenPGP certificates.
-
address@hidden,gnutls_certificate_set_openpgp_keyring_file}
-
-Note however that the peer's certificate is not automatically
-verified, you should call @funcref{gnutls_certificate_verify_peers2},
-after a successful handshake or during if
@funcref{gnutls_certificate_set_verify_function}
-has been used, to verify the certificate's signature.
-An alternative way, which reports a more detailed
-verification output, is to use @funcref{gnutls_certificate_get_peers} to
-obtain the raw certificate of the peer and verify it using the
-functions discussed in @ref{X.509 certificates}.
-
address@hidden
-
-In a handshake, the negotiated cipher suite also depends on the
-certificate's parameters, so some key exchange methods might not 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, that require
-decryption. It is not recommended to use RSA keys for both
-signing and encryption. If possible use a different key for the
address@hidden which uses signing and @code{RSA} that requires decryption.
-All the key exchange methods shown in @ref{tab:key-exchange} are
-available in certificate authentication.
-
address@hidden
-
-Note that the DHE key exchange methods are generally
address@hidden depends on the group used. Primes with
-lesser bits are always faster, but also easier to break. See @ref{Selecting
cryptographic key sizes}
-for the acceptable security levels.} than the elliptic curves counterpart
-(ECDHE). Moreover the plain Diffie-Hellman key exchange
-requires parameters to be generated and associated with a credentials
-structure by the server (see @ref{Parameter generation}).
-
address@hidden Table,tab:key-exchange
address@hidden @columnfractions .2 .7
-
address@hidden Key exchange @tab Description
-
address@hidden RSA @tab
-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.
-
address@hidden RSA_EXPORT @tab
-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.
-
address@hidden DHE_RSA @tab
-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.
-
address@hidden ECDHE_RSA @tab
-The RSA algorithm is used to sign ephemeral elliptic curve Diffie-Hellman
-parameters which are sent to the peer. The key in the certificate must allow
-the key to be used for signing. It also offers 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.
-
address@hidden DHE_DSS @tab
-The DSA 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. DSA is the algorithm
-of the Digital Signature Standard (DSS).
-
address@hidden ECDHE_ECDSA @tab
-The Elliptic curve DSA algorithm is used to sign ephemeral elliptic
-curve Diffie-Hellman parameters which are sent to the peer. The
-certificate must contain ECDSA parameters to use this key exchange
-algorithm.
-
address@hidden multitable
address@hidden key exchange algorithms.}
address@hidden float
-
address@hidden Anonymous authentication
address@hidden Anonymous authentication
address@hidden anonymous authentication
-
-The anonymous key exchange offers encryption without any
-indication of the peer's identity. This kind of authentication
-is vulnerable to a man in the middle attack, but can be
-used even if there is no prior communication or shared trusted parties
-with the peer. Moreover it is useful when complete anonymity is required.
-Unless in one of the above cases, do not use anonymous authentication.
-
-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. Check
address@hidden generation} for more information.
-
-The initialization functions for the credentials are shown below.
-
address@hidden,gnutls_anon_allocate_client_credentials,gnutls_anon_free_server_credentials,gnutls_anon_free_client_credentials}
-
-
-The available key exchange algorithms for anonymous authentication are
-shown below.
-
address@hidden @code
-
address@hidden ANON_DH:
-This algorithm exchanges Diffie-Hellman parameters.
-
address@hidden ANON_ECDH:
-This algorithm exchanges elliptic curve Diffie-Hellman parameters. It is more
-efficient than ANON_DH on equivalent security levels.
-
address@hidden table
-
address@hidden SRP authentication
address@hidden SRP authentication
-
address@hidden
-* Authentication using SRP::
-* Invoking srptool::
address@hidden menu
-
address@hidden Authentication using SRP
address@hidden Authentication using @acronym{SRP}
address@hidden SRP authentication
-
address@hidden supported authentication via the Secure Remote Password
-or @acronym{SRP} protocol (see @xcite{RFC2945,TOMSRP} for a description).
-The @acronym{SRP} key exchange is an extension to the
address@hidden protocol, and it provided an authenticated with a
-password key exchange. The 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} is not
-susceptible to off-line dictionary attacks.
-Moreover, 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
@acronym{UNIX}
address@hidden/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.
-The Stanford @acronym{SRP} libraries, include 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 users
-of a system.
-
-The implementation in @acronym{GnuTLS} is based on @xcite{TLSSRP}. The
-supported key exchange methods are shown below.
-
address@hidden @code
-
address@hidden SRP:
-Authentication using the @acronym{SRP} protocol.
-
address@hidden SRP_DSS:
-Client authentication using the @acronym{SRP} protocol. Server is
-authenticated using a certificate with DSA parameters.
-
address@hidden SRP_RSA:
-Client authentication using the @acronym{SRP} protocol. Server is
-authenticated using a certificate with RSA parameters.
-
address@hidden table
-
-The initialization functions in SRP credentials differ between
-client and server.
-
address@hidden,gnutls_srp_allocate_client_credentials,gnutls_srp_free_server_credentials,gnutls_srp_free_client_credentials}
-
-Clients supporting @acronym{SRP} should set the username and password
-prior to connection, to the credentials structure.
-Alternatively @funcref{gnutls_srp_set_client_credentials_function}
-may be used instead, to specify a callback function that should return the
-SRP username and password.
-The callback is called once during the @acronym{TLS} handshake.
-
address@hidden
-
address@hidden
-
-In server side the default behavior of @acronym{GnuTLS} is to read
-the usernames and @acronym{SRP} verifiers from password files. These
-password file format is compatible the with the @emph{Stanford srp libraries}
-format. If a different password file format is to be used, then
address@hidden should be called,
-to set an appropriate callback.
-
address@hidden
-
address@hidden
-
-Other helper functions are included in @acronym{GnuTLS}, 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. See @ref{srptool}, for more information.
-
address@hidden
-
address@hidden,gnutls_srp_base64_decode}
-
address@hidden Invoking srptool
address@hidden Invoking srptool
address@hidden
address@hidden srptool
-
-The @file{srptool} is a very simple program that emulates the programs
-in the @emph{Stanford SRP address@hidden
address@hidden://srp.stanford.edu/}.}. It requires two files,
-one called @code{tpasswd} which holds usernames and verifiers,
-and @code{tpasswd.conf} which holds generators and primes.
-
-To create tpasswd.conf which holds the generator and prime values for
-the @acronym{SRP} protocol, run:
-
address@hidden
-$ srptool --create-conf /etc/tpasswd.conf
address@hidden smallexample
-
-This command will create /etc/tpasswd and will add user 'test' (you
-will also be prompted for a password). Verifiers are stored in a way that
-is compatible with libsrp.
-
address@hidden
-$ srptool --passwd /etc/tpasswd \
- --passwd-conf /etc/tpasswd.conf -u test
address@hidden smallexample
-
-This command will check against a password. If the password matches
-the one in /etc/tpasswd you will get an ok.
-
address@hidden
-$ srptool --passwd /etc/tpasswd \
- --passwd-conf /etc/tpasswd.conf --verify -u test
address@hidden smallexample
-
address@hidden PSK authentication
address@hidden PSK authentication
-
address@hidden
-* Authentication using PSK::
-* Invoking psktool::
address@hidden menu
-
address@hidden Authentication using PSK
address@hidden Authentication using @acronym{PSK}
address@hidden 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 @xcite{TLSPSK}.
-The supported @acronym{PSK} key exchange methods are:
-
address@hidden @code
-
address@hidden PSK:
-Authentication using the @acronym{PSK} protocol.
-
address@hidden DHE-PSK:
-Authentication using the @acronym{PSK} protocol and Diffie-Hellman key
-exchange. This method offers perfect forward secrecy.
-
address@hidden ECDHE-PSK:
-Authentication using the @acronym{PSK} protocol and Elliptic curve
Diffie-Hellman key
-exchange. This method offers perfect forward secrecy.
-
address@hidden table
-
-The initialization functions in PSK credentials differ between
-client and server.
-
address@hidden,gnutls_psk_allocate_client_credentials,gnutls_psk_free_server_credentials,gnutls_psk_free_client_credentials}
-
-Clients supporting @acronym{PSK} should supply the username and key
-before a TLS session is established. Alternatively
address@hidden can be used to
-specify a callback function. This has the
-advantage that the callback will be called only if @acronym{PSK} has
-been negotiated.
-
address@hidden
-
address@hidden
-
-In server side the default behavior 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 @funcref{gnutls_psk_set_server_credentials_file}. If
-a different password file format is to be used, then
-a callback should be set instead by
@funcref{gnutls_psk_set_server_credentials_function}.
-
-The server can help the client chose a suitable username and password,
-by sending a hint. Note that there is no common profile for the PSK hint and
applications
-are discouraged to use it.
-A server, may specify the hint by calling
address@hidden The client can retrieve
-the hint, for example in the callback function, using
address@hidden
-
address@hidden
-
address@hidden,gnutls_psk_set_server_credentials_hint,gnutls_psk_client_get_hint}
-
-Helper functions to generate and maintain @acronym{PSK} keys are also included
-in @acronym{GnuTLS}.
-
address@hidden,gnutls_hex_encode,gnutls_hex_decode}
-
address@hidden Invoking psktool
address@hidden Invoking psktool
address@hidden psktool
-
-This is a program to manage @acronym{PSK} username and keys.
-It will generate random keys for the indicated username,
-using a simple password file format.
-
address@hidden
-PSKtool help
-Usage : psktool [options]
- -u, --username username
- specify username.
- -p, --passwd FILE specify a password file.
- -s, --keysize SIZE specify the key size in bytes.
- -v, --version prints the program's version number
- -h, --help shows this help text
address@hidden smallexample
-
-The generation of a PSK password file is illustrated in the example below.
-The password is provided in the prompt.
-
address@hidden
-$ ./psktool -u psk_identity -p psks.txt
-Generating a random key for user 'psk_identity'
-Key stored to psks.txt
-$ cat psks.txt
-psk_identity:88f3824b3e5659f52d00e959bacab954b6540344
-$
address@hidden smallexample
-
address@hidden Authentication and credentials
address@hidden Authentication and credentials
-
-In @acronym{GnuTLS} every key exchange method is associated with a
-credentials type. For a key exchange method to be available it
-must be listed as a priority string (see @ref{Priority Strings}) and
-the corresponding credentials type should be initialized and set using
address@hidden A mapping of the key exchange methods
-with the credential types is shown in @ref{tab:key-exchange-cred}.
-
address@hidden Table,tab:key-exchange-cred
address@hidden @columnfractions .4 .25 .25
-
address@hidden Key exchange @tab Client credentials @tab Server credentials
-
address@hidden @code{KX_RSA},
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden
address@hidden @code{CRD_CERTIFICATE}
address@hidden @code{CRD_CERTIFICATE}
-
address@hidden @code{KX_SRP_RSA}, @code{KX_SRP_DSS}
address@hidden @code{CRD_SRP}
address@hidden @code{CRD_CERTIFICATE}, @code{CRD_SRP}
-
address@hidden @code{KX_SRP}
address@hidden @code{CRD_SRP}
address@hidden @code{CRD_SRP}
-
address@hidden @code{KX_ANON_DH},
address@hidden
address@hidden @code{CRD_ANON}
address@hidden @code{CRD_ANON}
-
address@hidden @code{KX_PSK},
address@hidden, @code{KX_ECDHE_PSK}
address@hidden @code{CRD_PSK}
address@hidden @code{CRD_PSK}
-
address@hidden multitable
address@hidden exchange algorithms and the corresponding credential types.}
address@hidden float
-
diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi
index ad35254..df9d388 100644
--- a/doc/cha-cert-auth.texi
+++ b/doc/cha-cert-auth.texi
@@ -1,16 +1,23 @@
address@hidden More on certificate authentication
address@hidden More on certificate authentication
address@hidden Certificate authentication
address@hidden Certificate authentication
@cindex certificate authentication
@menu
+* Introduction::
* X.509 certificates::
* OpenPGP certificates::
-* The certtool application::
-* Hardware tokens::
-* Abstract key types::
* Digital signatures::
@end menu
address@hidden Introduction
address@hidden Introduction
+
+The most known authentication method of @acronym{TLS} are certificates.
+The PKIX @xcite{PKIX} public key infrastructure is daily used by anyone
+using a browser today. @acronym{GnuTLS} supports both
address@hidden certificates @xcite{PKIX} and @acronym{OpenPGP}
+certificates using a common API.
+
@node X.509 certificates
@section @acronym{X.509} certificates
@cindex X.509 certificates
@@ -34,9 +41,6 @@ acceptable. The framework is illustrated on @ref{fig:x509}.
* X.509 certificate structure::
* Verifying X.509 certificate paths::
* Verifying a certificate in the context of TLS session::
-* Certificate requests::
-* Certificate revocation lists::
-* PKCS 12 structures::
@end menu
@node X.509 certificate structure
@@ -151,8 +155,6 @@ Verifying certificate paths is important in @acronym{X.509}
authentication. For this purpose the following functions are
provided.
address@hidden,gnutls_x509_trust_list_deinit}
-
@showfuncdesc{gnutls_x509_trust_list_add_cas}
@showfuncdesc{gnutls_x509_trust_list_add_named_crt}
@showfuncdesc{gnutls_x509_trust_list_add_crls}
@@ -200,159 +202,6 @@ 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.
address@hidden Certificate requests
address@hidden @acronym{PKCS} #10 certificate requests
address@hidden certificate requests
address@hidden 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
address@hidden #10 @xcite{RFC2986}. Other formats of certificate requests
-are not currently supported.
-
address@hidden,gnutls_x509_crq_deinit}
-
address@hidden
-
address@hidden
-
-A certificate request can be generated by
-associating it with a private key, setting the
-subject's information and finally self signing it.
-The last step ensures that the requester is in
-possession of the private key.
-
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
-
-The @funcref{gnutls_x509_crq_set_key} and @funcref{gnutls_x509_crq_sign2}
-functions associate the request with a private key and sign it. If a
-request is to be signed with a key residing in a PKCS #11 token it is
recommended to use
-the signing functions shown in @ref{Abstract key types}.
-
address@hidden
address@hidden
-
-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.
-
address@hidden:crq}
address@hidden examples/ex-crq.c
-
address@hidden Certificate revocation lists
address@hidden Certificate revocation lists
address@hidden certificate revocation lists
address@hidden CRL
-
-A certificate revocation list (CRL) is a structure issued by an authority
-periodically containing a list of revoked certificates serial numbers.
-The CRL structure is signed with the issuing authorities' keys. A typical
-CRL contains the fields as shown in @ref{tab:crl}.
-Certificate revocation lists are used to complement the expiration date of a
certificate,
-in order to account for other reasons of revocation, such as compromised keys,
etc.
-
address@hidden,gnutls_x509_crl_deinit}
address@hidden,gnutls_x509_crl_export}
-
-A certificate request can be generated by
-associating it with a private key, setting the
-subject's information and finally self signing it.
-The last step ensures that the requester is in
-possession of the private key. Each CRL is valid for limited amount of
-time and is required to provide, except for the current issuing time, also
-the issuing time of the next update.
-
address@hidden Table,tab:crl
address@hidden @columnfractions .2 .7
-
address@hidden Field @tab Description
-
address@hidden version @tab
-The field that indicates the version of the CRL structure.
-
address@hidden signature @tab
-A signature by the issuing authority.
-
address@hidden issuer @tab
-Holds the issuer's distinguished name.
-
address@hidden thisUpdate @tab
-The issuing time of the revocation list.
-
address@hidden nextUpdate @tab
-The issuing time of the revocation list that will update that one.
-
address@hidden revokedCertificates @tab
-List of revoked certificates serial numbers.
-
address@hidden extensions @tab
-Optional CRL structure extensions.
-
address@hidden multitable
address@hidden revocation list fields.}
address@hidden float
-
-
address@hidden
address@hidden
-
address@hidden,gnutls_x509_crl_set_next_update,gnutls_x509_crl_set_this_update}
-
-The @funcref{gnutls_x509_crl_sign2} and @funcref{gnutls_x509_crl_privkey_sign}
-functions sign the revocation list with a private key. The latter function
-can be used to sign with a key residing in a PKCS #11 token.
-
address@hidden
address@hidden
-
-Few extensions on the CRL structure are supported, including the
-CRL number extension and the authority key identifier.
-
address@hidden,gnutls_x509_crl_set_authority_key_id}
-
address@hidden PKCS 12 structures
address@hidden @acronym{PKCS} #12 structures
address@hidden 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. A bag of type encrypted should be decrypted
-in order for its data to be accessed.
-
address@hidden,gnutls_pkcs12_deinit}
-
-The following functions are available to read a @acronym{PKCS} #12
-structure.
-
address@hidden
address@hidden
address@hidden
address@hidden
-
address@hidden,gnutls_pkcs12_bag_deinit,gnutls_pkcs12_bag_get_count,gnutls_pkcs12_bag_get_data,gnutls_pkcs12_bag_get_key_id,gnutls_pkcs12_bag_get_friendly_name}
-
-The functions below are used to generate a PKCS #12 structure. An example
-of their usage is also shown.
-
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden,gnutls_pkcs12_bag_set_crl,gnutls_pkcs12_bag_set_crt,gnutls_pkcs12_bag_set_key_id,gnutls_pkcs12_bag_set_friendly_name}
-
address@hidden examples/ex-pkcs12.c
@node OpenPGP certificates
@@ -428,717 +277,7 @@ to verify the signatures in the certificate sent by the
peer.
@showfuncdesc{gnutls_certificate_set_openpgp_keyring_file}
address@hidden The certtool application
address@hidden The certtool application
address@hidden certtool
-
-This is a program to generate @acronym{X.509} certificates, certificate
-requests, CRLs and private keys.
-
address@hidden
-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 Verify a PEM encoded certificate chain.
- CA certificates must be loaded with
- --load-ca-certificate.
- --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-pubkey FILE Public 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.
- --certificate-pubkey Print certificate public key.
- --pgp-certificate-info Print information on a OpenPGP
- certificate.
- --pgp-ring-info Print information on a keyring
- structure.
- -l, --crl-info Print information on a CRL.
- --crq-info Print information on a Certificate
- Request.
- --no-crq-extensions Do not use extensions in certificate
- requests.
- --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.
- --pgp-key-info Print information on a OpenPGP private
- key.
- --pubkey-info Print information on a public key.
- --fix-key Regenerate the parameters in a private
- key.
- --v1 Generate an X.509 version 1 certificate
- (no extensions).
- --to-p12 Generate a PKCS #12 structure.
- --to-p8 Generate a PKCS #8 key structure.
- -8, --pkcs8 Use PKCS #8 format for private keys.
- --dsa Use DSA keys.
- --ecc Use ECC (ECDSA) keys.
- --hash STR Hash algorithm to use for signing
- (MD5,SHA1,RMD160,SHA256,SHA384,SHA512).
- --export-ciphers Use weak encryption algorithms.
- --inder Use DER format for input certificates
- and private keys.
- --inraw Use RAW/DER format for input
- certificates and private keys.
- --outder Use DER format for output certificates
- and private keys.
- --outraw Use RAW/DER format for output
- certificates and private keys.
- --bits BITS specify the number of bits for key
- generation.
- --sec-param PARAM specify the security level
- [low|normal|high|ultra].
- --disable-quick-random Use /dev/random for key generationg,
- thus increasing the quality of
- randomness used.
- --outfile FILE Output file.
- --infile FILE Input file.
- --template FILE Template file to use for non
- interactive operation.
- --pkcs-cipher CIPHER Cipher to use for pkcs operations
- (3des,3des-pkcs12,aes-128,aes-192,aes-25
- 6,rc2-40,arcfour).
- -d, --debug LEVEL specify the debug level. Default is 1.
- -h, --help shows this help text
- -v, --version shows the program's version
address@hidden example
-
-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.
-
address@hidden Diffie-Hellman parameter generation
-To generate parameters for Diffie-Hellman key exchange, use the command:
address@hidden
-$ certtool --generate-dh-params --outfile dh.pem
address@hidden smallexample
-
address@hidden Self-signed certificate generation
-
-To create a self signed certificate, use the command:
address@hidden
-$ certtool --generate-privkey --outfile ca-key.pem
-$ certtool --generate-self-signed --load-privkey ca-key.pem \
- --outfile ca-cert.pem
address@hidden smallexample
-
-Note that a self-signed certificate usually belongs to a certificate
-authority, that signs other certificates.
-
address@hidden Private key generation
-To create a private key (RSA by default), run:
-
address@hidden
-$ certtool --generate-privkey --outfile key.pem
address@hidden smallexample
-
-To create a DSA or elliptic curves (ECDSA) private key use the
-above command combined with @code{--dsa} or @code{--ecc} options.
-
address@hidden Certificate generation
-To generate a certificate using the private key, use the command:
-
address@hidden
-$ certtool --generate-certificate --load-privkey key.pem \
- --outfile cert.pem --load-ca-certificate ca-cert.pem \
- --load-ca-privkey ca-key.pem
address@hidden smallexample
-
-Alternatively you may create a certificate request, which is needed
-when the certificate will be signed by a third party authority.
-
address@hidden
-$ certtool --generate-request --load-privkey key.pem \
- --outfile request.pem
address@hidden smallexample
-
-If the private key is stored in a smart card you can generate
-a request by specifying the private key object URL (see @ref{The p11tool
application}
-on how to obtain the URL).
-
address@hidden
-$ certtool --generate-request --load-privkey pkcs11:(PRIVKEY URL) \
- --load-pubkey pkcs11:(PUBKEY URL) --outfile request.pem
address@hidden smallexample
-
-To generate a certificate using the previous request, use the command:
-
address@hidden
-$ certtool --generate-certificate --load-request request.pem \
- --outfile cert.pem \
- --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem
address@hidden smallexample
-
address@hidden Certificate information
-To view the certificate information, use:
-
address@hidden
-$ certtool --certificate-info --infile cert.pem
address@hidden smallexample
-
address@hidden @acronym{PKCS} #12 structure generation
-To generate a @acronym{PKCS} #12 structure using the previous key and
-certificate, use the command:
-
address@hidden
-$ certtool --load-certificate cert.pem --load-privkey key.pem \
- --to-p12 --outder --outfile key.p12
address@hidden smallexample
-
-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
---load-ca-certificate parameter as follows:
-
address@hidden
-$ certtool --load-ca-certificate ca.pem \
- --load-certificate cert.pem --load-privkey key.pem \
- --to-p12 --outder --outfile key.p12
address@hidden smallexample
-
address@hidden Proxy certificate generation
-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:
-
address@hidden
-$ 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
address@hidden smallexample
-
address@hidden Certificate revocation list generation
-To create an empty Certificate Revocation List (CRL) do:
-
address@hidden
-$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
- --load-ca-certificate x509-ca.pem
address@hidden smallexample
-
-To create a CRL that contains some revoked certificates, place the
-certificates in a file and use @code{--load-certificate} as follows:
-
address@hidden
-$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
- --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem
address@hidden smallexample
-
-To verify a Certificate Revocation List (CRL) do:
-
address@hidden
-$ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem
address@hidden smallexample
-
-
-
address@hidden Certtool's template file format:
-A template file can be used to avoid the interactive questions of
-certtool. Initially create a file named 'cert.cfg' that contains the
information
-about the certificate. The template can be used as below:
-
address@hidden
-$ certtool --generate-certificate cert.pem --load-privkey key.pem \
- --template cert.cfg \
- --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem
address@hidden smallexample
-
-An example certtool template file:
-
address@hidden
-# 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
-
-# Whether this key will be used for IPsec IKE operations.
-#ipsec_ike_key
address@hidden example
-
-
-
address@hidden Hardware tokens
address@hidden Hardware tokens
address@hidden PKCS #11 tokens
address@hidden hardware tokens
address@hidden smart cards
-
address@hidden
-* Introduction::
-* PKCS11 Initialization::
-* Reading objects::
-* Writing objects::
-* Using a PKCS11 token with TLS::
-* The p11tool application::
address@hidden menu
-
address@hidden Introduction
address@hidden Introduction
-This section copes with hardware token support in @acronym{GnuTLS} using
address@hidden #11 @xcite{PKCS11}.
address@hidden #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 and a trusted platform module
(TPM),
-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}.
Its
-main advantage is that it allows operations on private key objects such as
decryption
-and signing without exposing the key.
-
-A @acronym{PKCS} #11 module to access smart cards is provided by the
address@hidden@url{http://www.opensc-project.org}} project, and a
-module to access the TPM chip on a PC is available from the
address@hidden@url{http://trousers.sourceforge.net/}}
-project.
-
-Moreover @acronym{PKCS} #11 can be (ab)used to allow all applications in the
same operating system to access
-shared cryptographic keys and certificates in a uniform way, as in
@ref{fig:pkcs11-vision}.
-That way applications could load their trusted certificate list, as well as
user
-certificates from a common PKCS #11 module. Such a provider exists in the
@acronym{Gnome}
-system, being the @acronym{Gnome Keyring}.
-
address@hidden Figure,fig:pkcs11-vision
address@hidden,9cm}
address@hidden #11 module usage.}
address@hidden float
-
address@hidden PKCS11 Initialization
address@hidden Initialization
-To allow all the @acronym{GnuTLS} applications to access @acronym{PKCS} #11
tokens
-you can use a configuration per module, stored in @code{/etc/pkcs11/modules/}.
-These are the configuration files of
@address@hidden@url{http://p11-glue.freedesktop.org/}}.
-For example a file that will load the @acronym{OpenSC} module, could be named
address@hidden/etc/pkcs11/modules/opensc} and contain the following:
-
address@hidden
-module: /usr/lib/opensc-pkcs11.so
address@hidden smallexample
-
-If you use this file, then there is no need for other initialization in
address@hidden, except for the PIN and token functions. Those allow retrieving
a PIN
-when accessing a protected object, such as a private key, as well as probe
-the user to insert the token. All the initialization functions are below.
-
address@hidden
address@hidden
-
address@hidden
address@hidden
address@hidden
-
-Note that due to limitations of @acronym{PKCS} #11 there are issues when
multiple libraries
-are sharing a module. To avoid this problem GnuTLS uses @acronym{p11-kit}
-that provides a middleware to control access to resources over the
-multiple users.
-
address@hidden Reading objects
address@hidden Reading objects
-
-All @acronym{PKCS} #11 objects are referenced by @acronym{GnuTLS} functions by
-URLs as described in @xcite{PKCS11URI}.
-This allows for a consistent naming of objects across systems and applications
-in the same system. For example a public
-key on a smart card may be referenced as:
-
address@hidden
-pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315; \
-manufacturer=EnterSafe;object=test1;objecttype=public;\
-id=32f153f3e37990b08624141077ca5dec2d15faed
address@hidden smallexample
-
-while the smart card itself can be referenced as:
address@hidden
-pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315;manufacturer=EnterSafe
address@hidden smallexample
-
-Objects stored in a @acronym{PKCS} #11 token can be extracted
-if they are not marked as sensitive. Usually only private keys are marked as
-sensitive and cannot be extracted, while certificates and other data can
-be retrieved. The functions that can be used to access objects
-are shown below.
-
address@hidden,gnutls_pkcs11_obj_deinit}
-
address@hidden
-
address@hidden
-
address@hidden
-
address@hidden
-
address@hidden
-
address@hidden,gnutls_x509_crt_import_pkcs11_url,gnutls_x509_crt_list_import_pkcs11}
-
-Properties of the physical token can also be accessed and altered with
@acronym{GnuTLS}.
-For example data in a token can be erased (initialized), PIN can be altered,
etc.
-
address@hidden,gnutls_pkcs11_token_get_url,gnutls_pkcs11_token_get_info,gnutls_pkcs11_token_get_flags}
address@hidden
-
-The following examples demonstrate the usage of the API. The first example
-will list all available PKCS #11 tokens in a system and the latter will
-list all certificates in a token that have a corresponding private key.
-
address@hidden
-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_free(url);
- @}
-gnutls_global_deinit();
address@hidden example
-
address@hidden examples/ex-pkcs11-list.c
-
address@hidden Writing objects
address@hidden Writing objects
-
-With @acronym{GnuTLS} you can copy existing private keys and certificates
-to a token. Note that when copying private keys it is recommended to mark
-them as sensitive using the @address@hidden@address@hidden@-SENSITIVE}
-to prevent its extraction. An object can be marked as private using the flag
address@hidden@address@hidden@address@hidden, to require PIN to be
-entered before accessing the object (for operations or otherwise).
-
address@hidden
-
address@hidden
address@hidden
-
-
address@hidden Using a PKCS11 token with TLS
address@hidden Using a @acronym{PKCS} #11 token with TLS
-
-It is possible to use a @acronym{PKCS} #11 token to a TLS
-session, as shown in @ref{ex:pkcs11-client}. In addition
-the following functions can be used to load PKCS #11 key and
-certificates by specifying a PKCS #11 URL instead of a filename.
-
address@hidden,gnutls_certificate_set_x509_key_file}
-
address@hidden The p11tool application
address@hidden The p11tool application
address@hidden
address@hidden p11tool
-
-p11tool is a program that is used to access tokens
-and security modules that support the PKCS #11 API. It requires
-individual PKCS #11 modules to be loaded either with the
address@hidden option, or by setting up the GnuTLS configuration
-file for PKCS #11 as in @ref{Hardware tokens}.
-
address@hidden
-p11tool help
-Usage: p11tool [options]
-Usage: p11tool --list-tokens
-Usage: p11tool --list-all
-Usage: p11tool --export 'pkcs11:...'
-
- --export URL Export an object specified by a pkcs11
- URL
- --list-tokens List all available tokens
- --list-mechanisms URL List all available mechanisms in token.
- --list-all List all objects specified by a PKCS#11
- URL
- --list-all-certs List all certificates specified by a
- PKCS#11 URL
- --list-certs List certificates that have a private
- key specified by a PKCS#11 URL
- --list-privkeys List private keys specified by a
- PKCS#11 URL
- --list-trusted List certificates marked as trusted,
- specified by a PKCS#11 URL
- --initialize URL Initializes a PKCS11 token.
- --write URL Writes loaded certificates, private or
- secret keys to a PKCS11 token.
- --delete URL Deletes objects matching the URL.
- --label label Sets a label for the write operation.
- --trusted Marks the certificate to be written as
- trusted.
- --private Marks the object to be written as
- private (requires PIN).
- --no-private Marks the object to be written as not
- private.
- --login Force login to token
- --detailed-url Export detailed URLs.
- --no-detailed-url Export less detailed URLs.
- --secret-key HEX_KEY Provide a hex encoded secret key.
- --load-privkey FILE Private key file to use.
- --load-pubkey FILE Private key file to use.
- --load-certificate FILE
- Certificate file to use.
- -8, --pkcs8 Use PKCS #8 format for private keys.
- --inder Use DER format for input certificates
- and private keys.
- --inraw Use RAW/DER format for input
- certificates and private keys.
- --provider Library Specify the pkcs11 provider library
- --outfile FILE Output file.
- -d, --debug LEVEL specify the debug level. Default is 1.
- -h, --help shows this help text
address@hidden example
-
-After being provided the available PKCS #11 modules, it can list all tokens
-available in your system, the objects on the tokens, and perform operations
-on them.
-
-Some examples on how to use p11tool are illustrated in the following
paragraphs.
-
address@hidden List all tokens
address@hidden
-$ p11tool --list-tokens
address@hidden smallexample
-
address@hidden List all objects
-The following command will list all objects in a token. The @code{--login}
-is required to show objects marked as private.
address@hidden
-$ p11tool --login --list-all
address@hidden smallexample
-
address@hidden Exporting an object
-To retrieve an object stored in the card use the following command.
-Note however that objects marked as sensitive (typically PKCS #11 private
keys)
-are not allowed to be extracted from the token.
address@hidden
-$ p11tool --login --export [OBJECT URL]
address@hidden smallexample
-
address@hidden Copy an object to a token
-To copy an object, such as a certificate or private key to a token
-use the following command.
address@hidden
-$ p11tool --login --write [TOKEN URL] \
- --load-certificate cert.pem --label "my_cert"
address@hidden smallexample
-
-
-
address@hidden Abstract key types
address@hidden Abstract key types
address@hidden abstract types
-
-Since there are many forms of a public or private keys supported by
@acronym{GnuTLS} such as
address@hidden, @acronym{OpenPGP}, or @acronym{PKCS} #11 it is desirable to
allow common operations
-on them. For these reasons the abstract @code{gnutls_privkey_t} and
@code{gnutls_pubkey_t} were
-introduced in @code{gnutls/abstract.h} header. Those types are initialized
using a specific type of
-key and then can be used to perform operations in an abstract way. For example
in order
-to sign an X.509 certificate with a key that resides in a token the following
steps must be
-used.
-
address@hidden
-#inlude <gnutls/abstract.h>
-#inlude <gnutls/pkcs11.h>
-
-void sign_cert( gnutls_x509_crt_t to_be_signed)
address@hidden
-gnutls_pkcs11_privkey_t ca_key;
-gnutls_x509_crt_t ca_cert;
-gnutls_privkey_t abs_key;
-
- /* load the PKCS #11 key and certificates */
- gnutls_pkcs11_privkey_init(&ca_key);
- gnutls_pkcs11_privkey_import_url(ca_key, key_url);
-
- gnutls_x509_crt_init(&ca_cert);
- gnutls_x509_crt_import_pkcs11_url(&ca_cert, cert_url);
-
- /* initialize the abstract key */
- gnutls_privkey_init(&abs_key);
- gnutls_privkey_import_pkcs11(abs_key, ca_key);
-
- /* sign the certificate to be signed */
- gnutls_x509_crt_privkey_sign(to_be_signed, ca_cert, ca_key,
- GNUTLS_DIG_SHA256, 0);
address@hidden
address@hidden example
-
address@hidden Public keys
-An abstract @code{gnutls_pubkey_t} can be initialized
-using the functions below. It can be imported through
-an existing structure like @code{gnutls_x509_crt_t},
-or through an ASN.1 encoding of the X.509 @code{SubjectPublicKeyInfo}
-sequence.
-
address@hidden,gnutls_pubkey_deinit}
-
address@hidden
-
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
address@hidden
-
-Additional functions are available that will return
-information over a public key.
-
address@hidden
-
address@hidden
address@hidden
-
address@hidden Private keys
-An abstract @code{gnutls_privkey_t} can be initialized
-using the functions below. It can be imported through
-an existing structure like @code{gnutls_x509_privkey_t},
-but unlike public keys it cannot be exported. That is
-to allow abstraction over @acronym{PKCS} #11 keys that
-are not extractable.
-
address@hidden,gnutls_privkey_deinit}
-
address@hidden
-
address@hidden,gnutls_privkey_import_pkcs11,gnutls_privkey_import_ext}
address@hidden
address@hidden
-
address@hidden Operations
-The abstract key types can be used to access signing and
-signature verification operations with the underlying keys.
-
address@hidden
address@hidden
address@hidden
address@hidden
-
-Signing existing structures, such as certificates, CRLs,
-or certificate requests, as well as associating public
-keys with structures is also possible using the
-key abstractions.
address@hidden
address@hidden
address@hidden,gnutls_x509_crl_privkey_sign,gnutls_x509_crq_privkey_sign}
@node Digital signatures
@section Digital signatures
diff --git a/doc/cha-cert-auth2.texi b/doc/cha-cert-auth2.texi
new file mode 100644
index 0000000..93a771a
--- /dev/null
+++ b/doc/cha-cert-auth2.texi
@@ -0,0 +1,823 @@
address@hidden More on certificate authentication
address@hidden More on certificate authentication
address@hidden certificate authentication
+
address@hidden
+* PKCS 10 certificate requests::
+* PKIX certificate revocation lists::
+* PKCS 12 structures::
+* The certtool application::
+* Hardware tokens::
+* Abstract key types::
address@hidden menu
+
address@hidden PKCS 10 certificate requests
address@hidden @acronym{PKCS} #10 certificate requests
address@hidden certificate requests
address@hidden 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
address@hidden #10 @xcite{RFC2986}. Other formats of certificate requests
+are not currently supported.
+
+A certificate request can be generated by
+associating it with a private key, setting the
+subject's information and finally self signing it.
+The last step ensures that the requester is in
+possession of the private key.
+
address@hidden,gnutls_x509_crq_set_dn_by_oid,gnutls_x509_crq_set_key_usage,gnutls_x509_crq_set_key_purpose_oid,gnutls_x509_crq_set_basic_constraints}
+
+The @funcref{gnutls_x509_crq_set_key} and @funcref{gnutls_x509_crq_sign2}
+functions associate the request with a private key and sign it. If a
+request is to be signed with a key residing in a PKCS #11 token it is
recommended to use
+the signing functions shown in @ref{Abstract key types}.
+
address@hidden
address@hidden
+
+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.
+
address@hidden:crq}
address@hidden examples/ex-crq.c
+
address@hidden PKIX certificate revocation lists
address@hidden PKIX certificate revocation lists
address@hidden certificate revocation lists
address@hidden CRL
+
+A certificate revocation list (CRL) is a structure issued by an authority
+periodically containing a list of revoked certificates serial numbers.
+The CRL structure is signed with the issuing authorities' keys. A typical
+CRL contains the fields as shown in @ref{tab:crl}.
+Certificate revocation lists are used to complement the expiration date of a
certificate,
+in order to account for other reasons of revocation, such as compromised keys,
etc.
+
+A certificate request can be generated by
+associating it with a private key, setting the
+subject's information and finally self signing it.
+The last step ensures that the requester is in
+possession of the private key. Each CRL is valid for limited amount of
+time and is required to provide, except for the current issuing time, also
+the issuing time of the next update.
+
address@hidden Table,tab:crl
address@hidden @columnfractions .2 .7
+
address@hidden Field @tab Description
+
address@hidden version @tab
+The field that indicates the version of the CRL structure.
+
address@hidden signature @tab
+A signature by the issuing authority.
+
address@hidden issuer @tab
+Holds the issuer's distinguished name.
+
address@hidden thisUpdate @tab
+The issuing time of the revocation list.
+
address@hidden nextUpdate @tab
+The issuing time of the revocation list that will update that one.
+
address@hidden revokedCertificates @tab
+List of revoked certificates serial numbers.
+
address@hidden extensions @tab
+Optional CRL structure extensions.
+
address@hidden multitable
address@hidden revocation list fields.}
address@hidden float
+
+
address@hidden,gnutls_x509_crl_set_crt_serial,gnutls_x509_crl_set_crt,gnutls_x509_crl_set_next_update,gnutls_x509_crl_set_this_update}
+
+The @funcref{gnutls_x509_crl_sign2} and @funcref{gnutls_x509_crl_privkey_sign}
+functions sign the revocation list with a private key. The latter function
+can be used to sign with a key residing in a PKCS #11 token.
+
address@hidden
address@hidden
+
+Few extensions on the CRL structure are supported, including the
+CRL number extension and the authority key identifier.
+
address@hidden,gnutls_x509_crl_set_authority_key_id}
+
address@hidden PKCS 12 structures
address@hidden @acronym{PKCS} #12 structures
address@hidden 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. A bag of type encrypted should be decrypted
+in order for its data to be accessed.
+
+The following functions are available to read a @acronym{PKCS} #12
+structure.
+
address@hidden,gnutls_pkcs12_verify_mac,gnutls_pkcs12_bag_decrypt}
+
address@hidden,gnutls_pkcs12_bag_get_data,gnutls_pkcs12_bag_get_key_id,gnutls_pkcs12_bag_get_friendly_name}
+
+The functions below are used to generate a PKCS #12 structure. An example
+of their usage is also shown.
+
address@hidden,gnutls_pkcs12_bag_encrypt,gnutls_pkcs12_generate_mac}
address@hidden,gnutls_pkcs12_bag_set_crl,gnutls_pkcs12_bag_set_crt,gnutls_pkcs12_bag_set_key_id,gnutls_pkcs12_bag_set_friendly_name}
+
address@hidden examples/ex-pkcs12.c
+
address@hidden The certtool application
address@hidden The certtool application
address@hidden certtool
+
+This is a program to generate @acronym{X.509} certificates, certificate
+requests, CRLs and private keys.
+
address@hidden
+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 Verify a PEM encoded certificate chain.
+ CA certificates must be loaded with
+ --load-ca-certificate.
+ --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-pubkey FILE Public 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.
+ --certificate-pubkey Print certificate public key.
+ --pgp-certificate-info Print information on a OpenPGP
+ certificate.
+ --pgp-ring-info Print information on a keyring
+ structure.
+ -l, --crl-info Print information on a CRL.
+ --crq-info Print information on a Certificate
+ Request.
+ --no-crq-extensions Do not use extensions in certificate
+ requests.
+ --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.
+ --pgp-key-info Print information on a OpenPGP private
+ key.
+ --pubkey-info Print information on a public key.
+ --fix-key Regenerate the parameters in a private
+ key.
+ --v1 Generate an X.509 version 1 certificate
+ (no extensions).
+ --to-p12 Generate a PKCS #12 structure.
+ --to-p8 Generate a PKCS #8 key structure.
+ -8, --pkcs8 Use PKCS #8 format for private keys.
+ --dsa Use DSA keys.
+ --ecc Use ECC (ECDSA) keys.
+ --hash STR Hash algorithm to use for signing
+ (MD5,SHA1,RMD160,SHA256,SHA384,SHA512).
+ --export-ciphers Use weak encryption algorithms.
+ --inder Use DER format for input certificates
+ and private keys.
+ --inraw Use RAW/DER format for input
+ certificates and private keys.
+ --outder Use DER format for output certificates
+ and private keys.
+ --outraw Use RAW/DER format for output
+ certificates and private keys.
+ --bits BITS specify the number of bits for key
+ generation.
+ --sec-param PARAM specify the security level
+ [low|normal|high|ultra].
+ --disable-quick-random Use /dev/random for key generationg,
+ thus increasing the quality of
+ randomness used.
+ --outfile FILE Output file.
+ --infile FILE Input file.
+ --template FILE Template file to use for non
+ interactive operation.
+ --pkcs-cipher CIPHER Cipher to use for pkcs operations
+ (3des,3des-pkcs12,aes-128,aes-192,aes-25
+ 6,rc2-40,arcfour).
+ -d, --debug LEVEL specify the debug level. Default is 1.
+ -h, --help shows this help text
+ -v, --version shows the program's version
address@hidden example
+
+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.
+
address@hidden Diffie-Hellman parameter generation
+To generate parameters for Diffie-Hellman key exchange, use the command:
address@hidden
+$ certtool --generate-dh-params --outfile dh.pem
address@hidden smallexample
+
address@hidden Self-signed certificate generation
+
+To create a self signed certificate, use the command:
address@hidden
+$ certtool --generate-privkey --outfile ca-key.pem
+$ certtool --generate-self-signed --load-privkey ca-key.pem \
+ --outfile ca-cert.pem
address@hidden smallexample
+
+Note that a self-signed certificate usually belongs to a certificate
+authority, that signs other certificates.
+
address@hidden Private key generation
+To create a private key (RSA by default), run:
+
address@hidden
+$ certtool --generate-privkey --outfile key.pem
address@hidden smallexample
+
+To create a DSA or elliptic curves (ECDSA) private key use the
+above command combined with @code{--dsa} or @code{--ecc} options.
+
address@hidden Certificate generation
+To generate a certificate using the private key, use the command:
+
address@hidden
+$ certtool --generate-certificate --load-privkey key.pem \
+ --outfile cert.pem --load-ca-certificate ca-cert.pem \
+ --load-ca-privkey ca-key.pem
address@hidden smallexample
+
+Alternatively you may create a certificate request, which is needed
+when the certificate will be signed by a third party authority.
+
address@hidden
+$ certtool --generate-request --load-privkey key.pem \
+ --outfile request.pem
address@hidden smallexample
+
+If the private key is stored in a smart card you can generate
+a request by specifying the private key object URL (see @ref{The p11tool
application}
+on how to obtain the URL).
+
address@hidden
+$ certtool --generate-request --load-privkey pkcs11:(PRIVKEY URL) \
+ --load-pubkey pkcs11:(PUBKEY URL) --outfile request.pem
address@hidden smallexample
+
+To generate a certificate using the previous request, use the command:
+
address@hidden
+$ certtool --generate-certificate --load-request request.pem \
+ --outfile cert.pem \
+ --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem
address@hidden smallexample
+
address@hidden Certificate information
+To view the certificate information, use:
+
address@hidden
+$ certtool --certificate-info --infile cert.pem
address@hidden smallexample
+
address@hidden @acronym{PKCS} #12 structure generation
+To generate a @acronym{PKCS} #12 structure using the previous key and
+certificate, use the command:
+
address@hidden
+$ certtool --load-certificate cert.pem --load-privkey key.pem \
+ --to-p12 --outder --outfile key.p12
address@hidden smallexample
+
+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
+--load-ca-certificate parameter as follows:
+
address@hidden
+$ certtool --load-ca-certificate ca.pem \
+ --load-certificate cert.pem --load-privkey key.pem \
+ --to-p12 --outder --outfile key.p12
address@hidden smallexample
+
address@hidden Proxy certificate generation
+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:
+
address@hidden
+$ 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
address@hidden smallexample
+
address@hidden Certificate revocation list generation
+To create an empty Certificate Revocation List (CRL) do:
+
address@hidden
+$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
+ --load-ca-certificate x509-ca.pem
address@hidden smallexample
+
+To create a CRL that contains some revoked certificates, place the
+certificates in a file and use @code{--load-certificate} as follows:
+
address@hidden
+$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
+ --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem
address@hidden smallexample
+
+To verify a Certificate Revocation List (CRL) do:
+
address@hidden
+$ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem
address@hidden smallexample
+
+
+
address@hidden Certtool's template file format:
+A template file can be used to avoid the interactive questions of
+certtool. Initially create a file named 'cert.cfg' that contains the
information
+about the certificate. The template can be used as below:
+
address@hidden
+$ certtool --generate-certificate cert.pem --load-privkey key.pem \
+ --template cert.cfg \
+ --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem
address@hidden smallexample
+
+An example certtool template file:
+
address@hidden
+# 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
+
+# Whether this key will be used for IPsec IKE operations.
+#ipsec_ike_key
address@hidden example
+
+
address@hidden Hardware tokens
address@hidden Hardware tokens
address@hidden PKCS #11 tokens
address@hidden hardware tokens
address@hidden smart cards
+
address@hidden
+* Introduction on hardware tokens::
+* PKCS11 Initialization::
+* Reading objects::
+* Writing objects::
+* Using a PKCS11 token with TLS::
+* The p11tool application::
address@hidden menu
+
address@hidden Introduction on hardware tokens
address@hidden Introduction
+This section copes with hardware token support in @acronym{GnuTLS} using
address@hidden #11 @xcite{PKCS11}.
address@hidden #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 and a trusted platform module
(TPM),
+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}.
Its
+main advantage is that it allows operations on private key objects such as
decryption
+and signing without exposing the key.
+
+A @acronym{PKCS} #11 module to access smart cards is provided by the
address@hidden@url{http://www.opensc-project.org}} project, and a
+module to access the TPM chip on a PC is available from the
address@hidden@url{http://trousers.sourceforge.net/}}
+project.
+
+Moreover @acronym{PKCS} #11 can be (ab)used to allow all applications in the
same operating system to access
+shared cryptographic keys and certificates in a uniform way, as in
@ref{fig:pkcs11-vision}.
+That way applications could load their trusted certificate list, as well as
user
+certificates from a common PKCS #11 module. Such a provider exists in the
@acronym{Gnome}
+system, being the @acronym{Gnome Keyring}.
+
address@hidden Figure,fig:pkcs11-vision
address@hidden,9cm}
address@hidden #11 module usage.}
address@hidden float
+
address@hidden PKCS11 Initialization
address@hidden Initialization
+To allow all the @acronym{GnuTLS} applications to access @acronym{PKCS} #11
tokens
+you can use a configuration per module, stored in @code{/etc/pkcs11/modules/}.
+These are the configuration files of
@address@hidden@url{http://p11-glue.freedesktop.org/}}.
+For example a file that will load the @acronym{OpenSC} module, could be named
address@hidden/etc/pkcs11/modules/opensc} and contain the following:
+
address@hidden
+module: /usr/lib/opensc-pkcs11.so
address@hidden smallexample
+
+If you use this file, then there is no need for other initialization in
address@hidden, except for the PIN and token functions. Those allow retrieving
a PIN
+when accessing a protected object, such as a private key, as well as probe
+the user to insert the token. All the initialization functions are below.
+
address@hidden
address@hidden,gnutls_pkcs11_set_pin_function,gnutls_pkcs11_add_provider}
+
+Note that due to limitations of @acronym{PKCS} #11 there are issues when
multiple libraries
+are sharing a module. To avoid this problem GnuTLS uses @acronym{p11-kit}
+that provides a middleware to control access to resources over the
+multiple users.
+
address@hidden Reading objects
address@hidden Reading objects
+
+All @acronym{PKCS} #11 objects are referenced by @acronym{GnuTLS} functions by
+URLs as described in @xcite{PKCS11URI}.
+This allows for a consistent naming of objects across systems and applications
+in the same system. For example a public
+key on a smart card may be referenced as:
+
address@hidden
+pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315; \
+manufacturer=EnterSafe;object=test1;objecttype=public;\
+id=32f153f3e37990b08624141077ca5dec2d15faed
address@hidden smallexample
+
+while the smart card itself can be referenced as:
address@hidden
+pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315;manufacturer=EnterSafe
address@hidden smallexample
+
+Objects stored in a @acronym{PKCS} #11 token can be extracted
+if they are not marked as sensitive. Usually only private keys are marked as
+sensitive and cannot be extracted, while certificates and other data can
+be retrieved. The functions that can be used to access objects
+are shown below.
+
address@hidden,gnutls_pkcs11_obj_export_url}
+
address@hidden
+
address@hidden,gnutls_x509_crt_import_pkcs11_url,gnutls_x509_crt_list_import_pkcs11}
+
+Properties of the physical token can also be accessed and altered with
@acronym{GnuTLS}.
+For example data in a token can be erased (initialized), PIN can be altered,
etc.
+
address@hidden,gnutls_pkcs11_token_get_url,gnutls_pkcs11_token_get_info,gnutls_pkcs11_token_get_flags,gnutls_pkcs11_token_set_pin}
+
+The following examples demonstrate the usage of the API. The first example
+will list all available PKCS #11 tokens in a system and the latter will
+list all certificates in a token that have a corresponding private key.
+
address@hidden
+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_free(url);
+ @}
+gnutls_global_deinit();
address@hidden example
+
address@hidden examples/ex-pkcs11-list.c
+
address@hidden Writing objects
address@hidden Writing objects
+
+With @acronym{GnuTLS} you can copy existing private keys and certificates
+to a token. Note that when copying private keys it is recommended to mark
+them as sensitive using the @address@hidden@address@hidden@-SENSITIVE}
+to prevent its extraction. An object can be marked as private using the flag
address@hidden@address@hidden@address@hidden, to require PIN to be
+entered before accessing the object (for operations or otherwise).
+
address@hidden
+
address@hidden
address@hidden
+
+
address@hidden Using a PKCS11 token with TLS
address@hidden Using a @acronym{PKCS} #11 token with TLS
+
+It is possible to use a @acronym{PKCS} #11 token to a TLS
+session, as shown in @ref{ex:pkcs11-client}. In addition
+the following functions can be used to load PKCS #11 key and
+certificates by specifying a PKCS #11 URL instead of a filename.
+
address@hidden,gnutls_certificate_set_x509_key_file}
+
address@hidden The p11tool application
address@hidden The p11tool application
address@hidden
address@hidden p11tool
+
+p11tool is a program that is used to access tokens
+and security modules that support the PKCS #11 API. It requires
+individual PKCS #11 modules to be loaded either with the
address@hidden option, or by setting up the GnuTLS configuration
+file for PKCS #11 as in @ref{Hardware tokens}.
+
address@hidden
+p11tool help
+Usage: p11tool [options]
+Usage: p11tool --list-tokens
+Usage: p11tool --list-all
+Usage: p11tool --export 'pkcs11:...'
+
+ --export URL Export an object specified by a pkcs11
+ URL
+ --list-tokens List all available tokens
+ --list-mechanisms URL List all available mechanisms in token.
+ --list-all List all objects specified by a PKCS#11
+ URL
+ --list-all-certs List all certificates specified by a
+ PKCS#11 URL
+ --list-certs List certificates that have a private
+ key specified by a PKCS#11 URL
+ --list-privkeys List private keys specified by a
+ PKCS#11 URL
+ --list-trusted List certificates marked as trusted,
+ specified by a PKCS#11 URL
+ --initialize URL Initializes a PKCS11 token.
+ --write URL Writes loaded certificates, private or
+ secret keys to a PKCS11 token.
+ --delete URL Deletes objects matching the URL.
+ --label label Sets a label for the write operation.
+ --trusted Marks the certificate to be written as
+ trusted.
+ --private Marks the object to be written as
+ private (requires PIN).
+ --no-private Marks the object to be written as not
+ private.
+ --login Force login to token
+ --detailed-url Export detailed URLs.
+ --no-detailed-url Export less detailed URLs.
+ --secret-key HEX_KEY Provide a hex encoded secret key.
+ --load-privkey FILE Private key file to use.
+ --load-pubkey FILE Private key file to use.
+ --load-certificate FILE
+ Certificate file to use.
+ -8, --pkcs8 Use PKCS #8 format for private keys.
+ --inder Use DER format for input certificates
+ and private keys.
+ --inraw Use RAW/DER format for input
+ certificates and private keys.
+ --provider Library Specify the pkcs11 provider library
+ --outfile FILE Output file.
+ -d, --debug LEVEL specify the debug level. Default is 1.
+ -h, --help shows this help text
address@hidden example
+
+After being provided the available PKCS #11 modules, it can list all tokens
+available in your system, the objects on the tokens, and perform operations
+on them.
+
+Some examples on how to use p11tool are illustrated in the following
paragraphs.
+
address@hidden List all tokens
address@hidden
+$ p11tool --list-tokens
address@hidden smallexample
+
address@hidden List all objects
+The following command will list all objects in a token. The @code{--login}
+is required to show objects marked as private.
address@hidden
+$ p11tool --login --list-all
address@hidden smallexample
+
address@hidden Exporting an object
+To retrieve an object stored in the card use the following command.
+Note however that objects marked as sensitive (typically PKCS #11 private
keys)
+are not allowed to be extracted from the token.
address@hidden
+$ p11tool --login --export [OBJECT URL]
address@hidden smallexample
+
address@hidden Copy an object to a token
+To copy an object, such as a certificate or private key to a token
+use the following command.
address@hidden
+$ p11tool --login --write [TOKEN URL] \
+ --load-certificate cert.pem --label "my_cert"
address@hidden smallexample
+
+
address@hidden Abstract key types
address@hidden Abstract key types
address@hidden abstract types
+
+Since there are many forms of a public or private keys supported by
@acronym{GnuTLS} such as
address@hidden, @acronym{OpenPGP}, or @acronym{PKCS} #11 it is desirable to
allow common operations
+on them. For these reasons the abstract @code{gnutls_privkey_t} and
@code{gnutls_pubkey_t} were
+introduced in @code{gnutls/abstract.h} header. Those types are initialized
using a specific type of
+key and then can be used to perform operations in an abstract way. For example
in order
+to sign an X.509 certificate with a key that resides in a token the following
steps must be
+used.
+
address@hidden
+#inlude <gnutls/abstract.h>
+#inlude <gnutls/pkcs11.h>
+
+void sign_cert( gnutls_x509_crt_t to_be_signed)
address@hidden
+gnutls_pkcs11_privkey_t ca_key;
+gnutls_x509_crt_t ca_cert;
+gnutls_privkey_t abs_key;
+
+ /* load the PKCS #11 key and certificates */
+ gnutls_pkcs11_privkey_init(&ca_key);
+ gnutls_pkcs11_privkey_import_url(ca_key, key_url);
+
+ gnutls_x509_crt_init(&ca_cert);
+ gnutls_x509_crt_import_pkcs11_url(&ca_cert, cert_url);
+
+ /* initialize the abstract key */
+ gnutls_privkey_init(&abs_key);
+ gnutls_privkey_import_pkcs11(abs_key, ca_key);
+
+ /* sign the certificate to be signed */
+ gnutls_x509_crt_privkey_sign(to_be_signed, ca_cert, ca_key,
+ GNUTLS_DIG_SHA256, 0);
address@hidden
address@hidden example
+
address@hidden Public keys
+An abstract @code{gnutls_pubkey_t} can be initialized
+using the functions below. It can be imported through
+an existing structure like @code{gnutls_x509_crt_t},
+or through an ASN.1 encoding of the X.509 @code{SubjectPublicKeyInfo}
+sequence.
+
address@hidden
address@hidden,gnutls_pubkey_import_pkcs11,gnutls_pubkey_import_pkcs11_url,gnutls_pubkey_import_privkey}
+
+Additional functions are available that will return
+information over a public key.
+
address@hidden,gnutls_pubkey_get_preferred_hash_algorithm,gnutls_pubkey_get_key_id}
+
address@hidden Private keys
+An abstract @code{gnutls_privkey_t} can be initialized
+using the functions below. It can be imported through
+an existing structure like @code{gnutls_x509_privkey_t},
+but unlike public keys it cannot be exported. That is
+to allow abstraction over @acronym{PKCS} #11 keys that
+are not extractable.
+
address@hidden,gnutls_privkey_import_openpgp,gnutls_privkey_import_pkcs11,gnutls_privkey_import_ext}
address@hidden,gnutls_privkey_get_type}
+
address@hidden Operations
+The abstract key types can be used to access signing and
+signature verification operations with the underlying keys.
+
address@hidden
address@hidden
address@hidden
address@hidden
+
+Signing existing structures, such as certificates, CRLs,
+or certificate requests, as well as associating public
+keys with structures is also possible using the
+key abstractions.
+
address@hidden
address@hidden
address@hidden,gnutls_x509_crl_privkey_sign,gnutls_x509_crq_privkey_sign}
diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index a8b8dcc..d9cba25 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -1,20 +1,179 @@
@node How to use GnuTLS in applications
@chapter How to use @acronym{GnuTLS} in applications
address@hidden
address@hidden example programs
address@hidden examples
@menu
+* Introduction to the library::
* Preparation::
-* TLS and DTLS sessions::
+* Session initialization::
+* Setting up the transport layer::
+* TLS handshake::
+* Data transfer and termination::
* Priority Strings::
-* Client examples::
-* Server examples::
-* Miscellaneous examples::
* Advanced and other topics::
* Using the cryptographic library::
+* Selecting cryptographic key sizes::
@end menu
address@hidden Introduction to the library
address@hidden Introduction
+
address@hidden
+* General idea::
+* Error handling::
+* Debugging and auditing::
+* Thread safety::
+* Callback functions::
address@hidden menu
+
address@hidden General idea
address@hidden General idea
+
+A brief description of how @acronym{GnuTLS} works internally is shown
+at @ref{fig:gnutls-design}. This section may become more clear after
+having read the rest of this section.
+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 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 allocated memory
+and is called after the program has permanently
+finished using @acronym{GnuTLS}.
+
address@hidden Figure,fig:gnutls-design
address@hidden,12cm}
address@hidden level design of GnuTLS.}
address@hidden float
+
+The credentials structures are used by the authentication methods, such
+as certificate authentication. They store certificates, privates keys,
+and other information that is needed to prove the identity to the peer,
+and/or verify the indentity of the peer. The information stored in
+the credentials structures is initialized once and then can be
+shared by many @acronym{TLS} sessions.
+
+A @acronym{GnuTLS} session contains all the required information
+to handle one secure connection. The session communicates with the
+peers using the provided functions of the transport layer.
+Every session has a unique session ID shared with the peer.
+
+Since TLS sessions can be resumed, servers need a
+database back-end to hold the session's parameters. Every
address@hidden session after a successful handshake calls the
+appropriate back-end function (see @ref{resume})
+to store the newly negotiated session. The session
+database is examined by the server just after having received the
+client address@hidden 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.
+
address@hidden Error handling
address@hidden 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. Such an example is
address@hidden@address@hidden@-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
address@hidden@address@hidden returned by @funcref{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
address@hidden
+
+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. See @ref{Error codes}, for a description of the available
+error codes.
+
address@hidden Debugging and auditing
address@hidden Debugging and auditing
+
+In many cases things may not go as expected and further information,
+to assist debugging, from @acronym{GnuTLS} is desired.
+Those are the cases where the @funcref{gnutls_global_set_log_level} and
address@hidden are to be used. Those will print
+verbose information on the @acronym{GnuTLS} functions internal flow.
+
address@hidden,gnutls_global_set_log_function}
+
+When debugging is not required, important issues, such as detected
+attacks on the protocol still need to be logged. This is provided
+by the logging function set by
address@hidden The provided function
+will receive an message and the corresponding
+TLS session. The session information might be used to derive IP addresses
+or other information about the peer involved.
+
address@hidden
+
address@hidden Thread safety
address@hidden Thread safety
address@hidden thread safety
+
+The @acronym{GnuTLS} library is thread safe by design, meaning that
+objects of the library such as TLS sessions, can be safely divided across
+threads as long as a single thread accesses a single object. This is
+sufficient to support a server which handles several sessions per thread.
+If, however, an object needs to be shared across threads then access must be
+protected with a mutex. Read-only access to objects, for example the
+credentials holding structures (see @ref{Authentication}), is also
thread-safe.
+
+The random generator of the cryptographic back-end, is not thread safe and
requires
+mutex locks which are setup by @acronym{GnuTLS}.
+Applications can either call @funcref{gnutls_global_init} which will
initialize the default
+operating system provided locks (i.e. @code{pthreads} on GNU/Linux and
address@hidden on Windows), or specify manually the locking system using
+the function @funcref{gnutls_global_set_mutex} before calling
@funcref{gnutls_global_init}.
+Setting manually mutexes is recommended
+only to applications that have full control of the underlying libraries. If
this
+is not the case, the use of the operating system defaults is recommended. An
example of
+non-native thread usage is shown below.
+
address@hidden
+#include <gnutls.h>
+
+/* Other thread packages
+ */
+
+int main()
address@hidden
+ gnutls_global_set_mutex (mutex_init, mutex_deinit,
+ mutex_lock, mutex_unlock);
+ gnutls_global_init();
address@hidden
address@hidden example
+
address@hidden
+
address@hidden Callback functions
address@hidden Callback functions
address@hidden callback functions
+
+There are several cases where @acronym{GnuTLS} may need 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.
+
address@hidden,gnutls_transport_set_pull_function}
+
+Other callback functions may require more complicated input and data
+to be allocated. Such an example is
address@hidden
+All callbacks should allocate and free memory using the functions shown below.
+
address@hidden,gnutls_free}
+
+
@node Preparation
@section Preparation
@@ -107,13 +266,12 @@ specifying both options to @command{pkg-config}:
gcc -o foo foo.c `pkg-config gnutls --cflags --libs`
@end smallexample
address@hidden TLS and DTLS sessions
address@hidden TLS and DTLS sessions
address@hidden Session initialization
address@hidden Session initialization
address@hidden Session initialization
In the previous sections we have discussed the global initialization
required for GnuTLS as well as the initialization required for each
-authentication method's credentials (see @ref{Authentication methods}).
+authentication method's credentials (see @ref{Authentication}).
In this section we elaborate on the TLS or DTLS session initiation.
Each session is initialized using @funcref{gnutls_init} which among
others is used to specify the type of the connection (server or client),
@@ -127,9 +285,160 @@ such as @funcref{gnutls_priority_set_direct}. We
elaborate on them
in @ref{Priority Strings}.
The credentials used for the key exchange method, such as certificates
or usernames and passwords should also be associated with the session
-current session using @funcref{gnutls_credentials_set} (see
@ref{Authentication methods}).
+current session using @funcref{gnutls_credentials_set}.
+
address@hidden
+
address@hidden Associating the credentials
address@hidden Certificates
+
+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.
+
address@hidden,gnutls_certificate_free_credentials}
+
+After the credentials structures are initialized using the functions
+above, the certificate and key pair should be loaded. This should
+occur before any @acronym{TLS} session is initialized.
+Depending on the certificate type different loading functions
+are available, and are shown below.
+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.
+
address@hidden,gnutls_certificate_set_x509_key,gnutls_certificate_set_x509_key_file}
+
address@hidden,gnutls_certificate_set_openpgp_key,gnutls_certificate_set_openpgp_key_file,gnutls_certificate_set_key}
+
+As an alternative to loading from files, a callback may be used so that the
+server or the client can specify the certificate and the key at the handshake
time.
+In that case a certificate should be selected according the peer's signature
+algorithm preferences. To get those preferences use
address@hidden Both functions are shown below.
+
address@hidden,gnutls_sign_algorithm_get_requested}
+
+
+Certificate verification is possible by loading the trusted
+authorities into the credentials structure by using
+the following functions, applicable to X.509 and OpenPGP certificates.
+
address@hidden,gnutls_certificate_set_openpgp_keyring_file}
+
+Note however that the peer's certificate is not automatically
+verified, you should call @funcref{gnutls_certificate_verify_peers2},
+after a successful handshake or during if
@funcref{gnutls_certificate_set_verify_function}
+has been used, to verify the certificate's signature.
+An alternative way, which reports a more detailed
+verification output, is to use @funcref{gnutls_certificate_get_peers} to
+obtain the raw certificate of the peer and verify it using the
+functions discussed in @ref{X.509 certificates}.
+
address@hidden
+
+In a handshake, the negotiated cipher suite also depends on the
+certificate's parameters, so some key exchange methods might not 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, that require
+decryption. It is not recommended to use RSA keys for both
+signing and encryption. If possible use a different key for the
address@hidden which uses signing and @code{RSA} that requires decryption.
+All the key exchange methods shown in @ref{tab:key-exchange} are
+available in certificate authentication.
+
address@hidden
+
+Note that the DHE key exchange methods are generally
address@hidden depends on the group used. Primes with
+lesser bits are always faster, but also easier to break. See @ref{Selecting
cryptographic key sizes}
+for the acceptable security levels.} than the elliptic curves counterpart
+(ECDHE). Moreover the plain Diffie-Hellman key exchange
+requires parameters to be generated and associated with a credentials
+structure by the server (see @ref{Parameter generation}).
+
address@hidden SRP
address@hidden Setting up the transport layer
+The initialization functions in SRP credentials differ between
+client and server.
+Clients supporting @acronym{SRP} should set the username and password
+prior to connection, to the credentials structure.
+Alternatively @funcref{gnutls_srp_set_client_credentials_function}
+may be used instead, to specify a callback function that should return the
+SRP username and password.
+The callback is called once during the @acronym{TLS} handshake.
+
address@hidden,gnutls_srp_allocate_client_credentials,gnutls_srp_free_server_credentials,gnutls_srp_free_client_credentials,gnutls_srp_set_client_credentials}
+
address@hidden
+
+In server side the default behavior of @acronym{GnuTLS} is to read
+the usernames and @acronym{SRP} verifiers from password files. These
+password file format is compatible the with the @emph{Stanford srp libraries}
+format. If a different password file format is to be used, then
address@hidden should be called,
+to set an appropriate callback.
+
address@hidden
+
address@hidden
+
+
address@hidden PSK
+The initialization functions in PSK credentials differ between
+client and server.
+
address@hidden,gnutls_psk_allocate_client_credentials,gnutls_psk_free_server_credentials,gnutls_psk_free_client_credentials}
+
+Clients supporting @acronym{PSK} should supply the username and key
+before a TLS session is established. Alternatively
address@hidden can be used to
+specify a callback function. This has the
+advantage that the callback will be called only if @acronym{PSK} has
+been negotiated.
+
address@hidden
+
address@hidden
+
+In server side the default behavior 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 @funcref{gnutls_psk_set_server_credentials_file}. If
+a different password file format is to be used, then
+a callback should be set instead by
@funcref{gnutls_psk_set_server_credentials_function}.
+
+The server can help the client chose a suitable username and password,
+by sending a hint. Note that there is no common profile for the PSK hint and
applications
+are discouraged to use it.
+A server, may specify the hint by calling
address@hidden The client can retrieve
+the hint, for example in the callback function, using
address@hidden
+
address@hidden
+
address@hidden,gnutls_psk_set_server_credentials_hint,gnutls_psk_client_get_hint}
+
address@hidden Anonymous
+The initialization functions for the credentials are shown below.
+
address@hidden,gnutls_anon_allocate_client_credentials,gnutls_anon_free_server_credentials,gnutls_anon_free_client_credentials}
+
+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. Check
address@hidden generation} for more information.
+
+
address@hidden Setting up the transport layer
address@hidden Setting up the transport layer
The next step is to setup the underlying transport layer details. The
Berkeley sockets are implicitly used by GnuTLS, thus a
@@ -176,8 +485,66 @@ message. This requires the
@funcref{gnutls_transport_set_pull_timeout_function}
@showfuncdesc{gnutls_transport_set_pull_timeout_function}
address@hidden Asynchronous operation
address@hidden can be used with asynchronous socket or event-driven programming.
+During a TLS protocol session @acronym{GnuTLS} does not block for anything
except
+calculations. The only blocking operations are due to the transport layer
(sockets) functions.
+Those, however, in an asynchronous scenario are typically set to
+non-blocking mode, which forces them to return @code{EAGAIN} error code
instead of blocking.
+In that case @acronym{GnuTLS} functions
+will return the @code{GNUTLS_E_AGAIN} error code and can be resumed the
+same way as a system call would. The only exception is
@funcref{gnutls_record_send},
+which if interrupted subsequent calls need not to include the data to be
+sent (can be called with NULL argument).
address@hidden Handshake
+The @funcintref{select} system call can also be used in combination with the
address@hidden functions. @funcintref{select} allows monitoring of sockets
+and notifies on them being ready for reading or writing data. Note however
+that this system call cannot notify on data present in @acronym{GnuTLS}
+read buffers, it is only applicable to the kernel sockets API. Thus if
+you are using it for reading from a @acronym{GnuTLS} session, make sure
+the session is read completely. That can be achieved by checking there
+are no data waiting to be read (using @funcref{gnutls_record_check_pending}),
+either before the @funcintref{select} system call, or after a call to
address@hidden @acronym{GnuTLS} does not keep a write buffer,
+thus when writing @funcintref{select} need only to be consulted.
+
+In the DTLS, however, @acronym{GnuTLS} might block due to timers
+required by the protocol. To prevent those timers from blocking a DTLS
handshake,
+the @funcref{gnutls_init} should be called with the
address@hidden flag (see @ref{Session initialization}).
+
address@hidden DTLS sessions
+
+Because datagram TLS can operate over connections where the peer
+of a server cannot be reliably verified, functionality is available to prevent
+denial of service attacks. @acronym{GnuTLS} requires a server
+to generate a secret key that is used to sign a address@hidden key of 128 bits
or 16 bytes should be sufficient for this purpose.}.
+That cookie is sent to the client using @funcref{gnutls_dtls_cookie_send}, and
+the client must reply using the correct cookie. The server side
+should verify the initial message sent by client using
@funcref{gnutls_dtls_cookie_verify}.
+If successful the session should be initialized and associated with
+the cookie using @funcref{gnutls_dtls_prestate_set}, before proceeding to
+the handshake.
+
address@hidden,gnutls_dtls_cookie_send,gnutls_dtls_cookie_verify,gnutls_dtls_prestate_set}
+
+Note that the above apply to server side only and they are not mandatory to be
+used. Not using them, however, allows denial of service attacks.
+The client side cookie handling is part of @funcref{gnutls_handshake}.
+
+Datagrams are typically restricted by a maximum transfer unit (MTU). For that
+both client and server side should set the correct maximum transfer unit for
+the layer underneath @acronym{GnuTLS}. This will allow proper fragmentation
+of DTLS messages and prevent messages from being silently discarded by the
+transport layer. The ``correct'' maximum transfer unit can be obtained through
+a path MTU discovery mechanism @xcite{RFC4821}.
+
address@hidden,gnutls_dtls_get_mtu,gnutls_dtls_get_data_mtu}
+
+
address@hidden TLS handshake
address@hidden TLS handshake
Once a session has been initialized and a network
connection has been set up, TLS and DTLS protocols
perform a handshake. The handshake is the actual key
@@ -195,8 +562,8 @@ for more information).
@showfuncA{gnutls_certificate_verify_peers2}
-
address@hidden Data transfer and termination
address@hidden Data transfer and termination
address@hidden Data transfer and termination
Once the handshake is complete and peer's identity
has been verified data can be exchanged. The available
functions resemble the POSIX @code{recv} and @code{send}
@@ -224,6 +591,7 @@ i.e., @funcref{gnutls_record_check_pending} reports no data
to be read, @code{se
should be called to check for data in the network buffers.
@showfuncdesc{gnutls_record_check_pending}
address@hidden
Once a TLS or DTLS session is no longer needed, it is
recommended to use @funcref{gnutls_bye} to terminate the
@@ -235,62 +603,6 @@ A session can be deinitialized with the
@funcref{gnutls_deinit} function.
@showfuncdesc{gnutls_bye}
@showfuncdesc{gnutls_deinit}
address@hidden Asynchronous operation
address@hidden can be used with asynchronous socket or event-driven programming.
-During a TLS protocol session @acronym{GnuTLS} does not block for anything
except
-calculations. The only blocking operations are due to the transport layer
(sockets) functions.
-Those, however, in an asynchronous scenario are typically set to
-non-blocking mode, which forces them to return @code{EAGAIN} error code
instead of blocking.
-In that case @acronym{GnuTLS} functions
-will return the @code{GNUTLS_E_AGAIN} error code and can be resumed the
-same way as a system call would. The only exception is
@funcref{gnutls_record_send},
-which if interrupted subsequent calls need not to include the data to be
-sent (can be called with NULL argument).
-
-The @funcintref{select} system call can also be used in combination with the
address@hidden functions. @funcintref{select} allows monitoring of sockets
-and notifies on them being ready for reading or writing data. Note however
-that this system call cannot notify on data present in @acronym{GnuTLS}
-read buffers, it is only applicable to the kernel sockets API. Thus if
-you are using it for reading from a @acronym{GnuTLS} session, make sure
-the session is read completely. That can be achieved by checking there
-are no data waiting to be read (using @funcref{gnutls_record_check_pending}),
-either before the @funcintref{select} system call, or after a call to
address@hidden @acronym{GnuTLS} does not keep a write buffer,
-thus when writing @funcintref{select} need only to be consulted.
-
-In the DTLS, however, @acronym{GnuTLS} might block due to timers
-required by the protocol. To prevent those timers from blocking a DTLS
handshake,
-the @funcref{gnutls_init} should be called with the
address@hidden flag (see @ref{TLS and DTLS sessions}).
-
address@hidden DTLS sessions
-
-Because datagram TLS can operate over connections where the peer
-of a server cannot be reliably verified, functionality is available to prevent
-denial of service attacks. @acronym{GnuTLS} requires a server
-to generate a secret key that is used to sign a address@hidden key of 128 bits
or 16 bytes should be sufficient for this purpose.}.
-That cookie is sent to the client using @funcref{gnutls_dtls_cookie_send}, and
-the client must reply using the correct cookie. The server side
-should verify the initial message sent by client using
@funcref{gnutls_dtls_cookie_verify}.
-If successful the session should be initialized and associated with
-the cookie using @funcref{gnutls_dtls_prestate_set}, before proceeding to
-the handshake.
-
address@hidden,gnutls_dtls_cookie_send,gnutls_dtls_cookie_verify,gnutls_dtls_prestate_set}
-
-Note that the above apply to server side only and they are not mandatory to be
-used. Not using them, however, allows denial of service attacks.
-The client side cookie handling is part of @funcref{gnutls_handshake}.
-
-Datagrams are typically restricted by a maximum transfer unit (MTU). For that
-both client and server side should set the correct maximum transfer unit for
-the layer underneath @acronym{GnuTLS}. This will allow proper fragmentation
-of DTLS messages and prevent messages from being silently discarded by the
-transport layer. The ``correct'' maximum transfer unit can be obtained through
-a path MTU discovery mechanism @xcite{RFC4821}.
-
address@hidden,gnutls_dtls_get_mtu,gnutls_dtls_get_data_mtu}
@node Priority Strings
@section Priority strings
@@ -302,7 +614,7 @@ That string may contain a high level keyword such as
in @ref{tab:prio-keywords} or combination of a high level
keyword, additional algorithm keywords and special keywords.
address@hidden,gnutls_priority_init,gnutls_priority_deinit,gnutls_priority_set}
address@hidden,gnutls_priority_set}
@float Table,tab:prio-keywords
@multitable @columnfractions .20 .70
@@ -469,215 +781,6 @@ will allow V1 CAs in chains.
@end float
address@hidden Client examples
address@hidden 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.
-
address@hidden
-* Simple client example with anonymous authentication::
-* Simple client example with X.509 certificate support::
-* Simple Datagram TLS client example::
-* Obtaining session information::
-* Using a callback to select the certificate to use::
-* Verifying a certificate::
-* Client using a PKCS 11 token with TLS::
-* Client with Resume capability example::
-* Simple client example with SRP authentication::
-* Simple client example in C++::
-* Helper function for TCP connections::
address@hidden menu
-
address@hidden Simple client example with anonymous authentication
address@hidden 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.
-
address@hidden examples/ex-client1.c
-
address@hidden Simple client example with X.509 certificate support
address@hidden Simple client example with @acronym{X.509} certificate support
address@hidden:verify}
-
-Let's assume now that we want to create a TCP client which
-communicates with servers that use @acronym{X.509} or
address@hidden certificate authentication. The following client is
-a very simple @acronym{TLS} client, which uses the high level verification
-functions for certificates, but does not support session
-resumption. The TCP functions defined in this example are used
-in most of the other examples below, without redefining them.
-
address@hidden examples/ex-rfc2818.c
-
address@hidden Simple Datagram TLS client example
address@hidden Simple datagram @acronym{TLS} client example
-
-This is a client that uses @acronym{UDP} to connect to a
-server. This is the @acronym{DTLS} equivalent to the example
-in @ref{Simple client example with X.509 certificate support}.
-
address@hidden examples/ex-client-udp.c
-
address@hidden Obtaining session information
address@hidden 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 @funcref{gnutls_handshake}.
-
address@hidden examples/ex-session-info.c
-
address@hidden Using a callback to select the certificate to use
address@hidden 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.
-
address@hidden examples/ex-cert-select.c
-
address@hidden Verifying a certificate
address@hidden Verifying a certificate
address@hidden:verify2}
-
-An example is listed below which uses the high level verification
-functions to verify a given certificate list.
-
address@hidden examples/ex-verify.c
-
address@hidden Client using a PKCS 11 token with TLS
address@hidden Using a @acronym{PKCS} #11 token with TLS
address@hidden:pkcs11-client}
-
-This example will demonstrate how to load keys and certificates
-from a @acronym{PKCS} #11 token, and use it with a TLS connection.
-
address@hidden examples/ex-cert-select-pkcs11.c
-
-
address@hidden Client with Resume capability example
address@hidden Client with resume capability example
address@hidden: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.
-
address@hidden examples/ex-client-resume.c
-
-
address@hidden Simple client example with SRP authentication
address@hidden 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
address@hidden and a @emph{password}. The server may authenticate
-itself using a certificate, and in that case it has to be verified.
-
address@hidden examples/ex-client-srp.c
-
address@hidden Simple client example in C++
address@hidden Simple client example using the C++ API
-
-The following client is a simple example of a client client utilizing
-the GnuTLS C++ API.
-
address@hidden examples/ex-cxx.cpp
-
address@hidden Helper function for TCP connections
address@hidden Helper function for TCP connections
-
-This helper function abstracts away TCP connection handling from the
-other examples. It is required to build some examples.
-
address@hidden examples/tcp.c
-
address@hidden Server examples
address@hidden Server examples
-
-This section contains examples of @acronym{TLS} and @acronym{SSL}
-servers, using @acronym{GnuTLS}.
-
address@hidden
-* Echo Server with X.509 authentication::
-* Echo Server with OpenPGP authentication::
-* Echo Server with SRP authentication::
-* Echo Server with anonymous authentication::
address@hidden menu
-
address@hidden Echo Server with X.509 authentication
address@hidden Echo server with @acronym{X.509} authentication
-
-This example is a very simple echo server which supports
address@hidden authentication, using the RSA ciphersuites.
-
address@hidden examples/ex-serv1.c
-
address@hidden Echo Server with OpenPGP authentication
address@hidden Echo server with @acronym{OpenPGP} authentication
address@hidden OpenPGP server
-
-The following example is an echo server which supports
address@hidden key authentication. You can easily combine
-this functionality ---that is have a server that supports both
address@hidden and @acronym{OpenPGP} certificates--- but we separated
-them to keep these examples as simple as possible.
-
address@hidden examples/ex-serv-pgp.c
-
address@hidden Echo Server with SRP authentication
address@hidden 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.
-
address@hidden examples/ex-serv-srp.c
-
address@hidden Echo Server with anonymous authentication
address@hidden Echo Server with anonymous authentication
-
-This example server support anonymous authentication, and could be
-used to serve the example client for anonymous authentication.
-
address@hidden examples/ex-serv-anon.c
-
address@hidden Miscellaneous examples
address@hidden Miscellaneous examples
-
address@hidden
-* Checking for an alert::
-* X.509 certificate parsing example::
address@hidden menu
-
address@hidden Checking for an alert
address@hidden Checking for an alert
-
-This is a function that checks if an alert has been received in the
-current session.
-
address@hidden examples/ex-alert.c
-
address@hidden X.509 certificate parsing example
address@hidden @acronym{X.509} certificate parsing example
address@hidden: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.
-
address@hidden examples/ex-x509-info.c
@node Advanced and other topics
@section Advanced and other topics
@@ -689,7 +792,6 @@ information about it.
* Compatibility with the OpenSSL library::
@end menu
-
@node Parameter generation
@subsection Parameter generation
@cindex parameter generation
@@ -705,8 +807,6 @@ The parameters can be used in a @acronym{TLS} session by
calling
@funcref{gnutls_certificate_set_dh_params} or
@funcref{gnutls_anon_set_server_dh_params} for anonymous sessions.
address@hidden,gnutls_dh_params_deinit}
-
@showfuncD{gnutls_dh_params_generate2,gnutls_dh_params_import_pkcs3,gnutls_certificate_set_dh_params,gnutls_anon_set_server_dh_params}
Due to the time-consuming calculations required for the generation
@@ -725,8 +825,6 @@ requires 512-bit RSA keys to be generated. It is
recommended those
parameters to be refreshed (regenerated) in short intervals. The
following functions can be used for these parameters.
address@hidden,gnutls_rsa_params_deinit}
-
@showfuncD{gnutls_rsa_params_generate2,gnutls_certificate_set_rsa_export_params,gnutls_rsa_params_import_pkcs1,gnutls_rsa_params_export_pkcs1}
To allow renewal of the parameters within an application without
@@ -879,3 +977,90 @@ function. It allows obtaining random data of various
levels.
@showenumdesc{gnutls_rnd_level_t,The random number levels.}
@showfuncdesc{gnutls_rnd}
+
address@hidden Selecting cryptographic key sizes
address@hidden Selecting cryptographic key sizes
address@hidden key sizes
+
+Because many algorithms are involved in TLS, it is not easy to set
+a consistent security level. For this reason in @ref{tab:key-sizes} we
+present some correspondence between key sizes of symmetric algorithms
+and public key algorithms based on @xcite{ECRYPT}.
+Those can be used to generate certificates with
+appropriate key sizes as well as select parameters for Diffie-Hellman and SRP
+authentication.
+
address@hidden Table,tab:key-sizes
address@hidden @columnfractions .10 .12 .10 .20 .32
+
address@hidden Security bits @tab RSA, DH and SRP parameter size @tab ECC key
size @tab Security parameter @tab Description
+
address@hidden 64
address@hidden 816
address@hidden 128
address@hidden @code{WEAK}
address@hidden Very short term protection against small organizations
+
address@hidden 80
address@hidden 1248
address@hidden 160
address@hidden @code{LOW}
address@hidden Very short term protection against agencies
+
address@hidden 112
address@hidden 2432
address@hidden 224
address@hidden @code{NORMAL}
address@hidden Medium-term protection
+
address@hidden 128
address@hidden 3248
address@hidden 256
address@hidden @code{HIGH}
address@hidden Long term protection
+
address@hidden 256
address@hidden 15424
address@hidden 512
address@hidden @code{ULTRA}
address@hidden Foreseeable future
+
address@hidden multitable
address@hidden sizes and security parameters.}
address@hidden float
+
+The first column provides a security parameter in a number of bits. This
+gives an indication of the number of combinations to be tried by an adversary
+to brute force a key. For example to test all possible keys in a 112 bit
security parameter
address@hidden combinations have to be tried. For today's technology this is
infeasible.
+The next two columns correlate the security
+parameter with actual bit sizes of parameters for DH, RSA, SRP and ECC
algorithms.
+A mapping to @code{gnutls_sec_param_t} value is given for each security
parameter, on
+the next column, and finally a brief description of the level.
+
address@hidden @showenumdesc{gnutls_sec_param_t,The @address@hidden
enumeration.}
+
+Note, however, that the values suggested here are nothing more than an
+educated guess that is valid today. There are no guarantees 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.
+The NIST publication SP 800-57 @xcite{NISTSP80057} contains a similar
+table.
+
+When using @acronym{GnuTLS} and a decision on bit sizes for a public
+key algorithm is required, use of the following functions is
+recommended:
+
address@hidden
+
address@hidden
+
+Those functions will convert a human understandable security parameter
+of @code{gnutls_sec_param_t} type, to a number of bits suitable for a public
+key algorithm.
+
+
diff --git a/doc/cha-gtls-examples.texi b/doc/cha-gtls-examples.texi
new file mode 100644
index 0000000..3f9fb6b
--- /dev/null
+++ b/doc/cha-gtls-examples.texi
@@ -0,0 +1,221 @@
address@hidden GnuTLS application examples
address@hidden GnuTLS application examples
address@hidden
address@hidden example programs
address@hidden examples
+
address@hidden
+* Client examples::
+* Server examples::
+* Miscellaneous examples::
address@hidden menu
+
address@hidden Client examples
address@hidden 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.
+
address@hidden
+* Simple client example with anonymous authentication::
+* Simple client example with X.509 certificate support::
+* Simple Datagram TLS client example::
+* Obtaining session information::
+* Using a callback to select the certificate to use::
+* Verifying a certificate::
+* Client using a PKCS 11 token with TLS::
+* Client with Resume capability example::
+* Simple client example with SRP authentication::
+* Simple client example in C++::
+* Helper function for TCP connections::
address@hidden menu
+
address@hidden Simple client example with anonymous authentication
address@hidden 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.
+
address@hidden examples/ex-client1.c
+
address@hidden Simple client example with X.509 certificate support
address@hidden Simple client example with @acronym{X.509} certificate support
address@hidden:verify}
+
+Let's assume now that we want to create a TCP client which
+communicates with servers that use @acronym{X.509} or
address@hidden certificate authentication. The following client is
+a very simple @acronym{TLS} client, which uses the high level verification
+functions for certificates, but does not support session
+resumption. The TCP functions defined in this example are used
+in most of the other examples below, without redefining them.
+
address@hidden examples/ex-rfc2818.c
+
address@hidden Simple Datagram TLS client example
address@hidden Simple datagram @acronym{TLS} client example
+
+This is a client that uses @acronym{UDP} to connect to a
+server. This is the @acronym{DTLS} equivalent to the example
+in @ref{Simple client example with X.509 certificate support}.
+
address@hidden examples/ex-client-udp.c
+
address@hidden Obtaining session information
address@hidden 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 @funcref{gnutls_handshake}.
+
address@hidden examples/ex-session-info.c
+
address@hidden Using a callback to select the certificate to use
address@hidden 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.
+
address@hidden examples/ex-cert-select.c
+
address@hidden Verifying a certificate
address@hidden Verifying a certificate
address@hidden:verify2}
+
+An example is listed below which uses the high level verification
+functions to verify a given certificate list.
+
address@hidden examples/ex-verify.c
+
address@hidden Client using a PKCS 11 token with TLS
address@hidden Using a @acronym{PKCS} #11 token with TLS
address@hidden:pkcs11-client}
+
+This example will demonstrate how to load keys and certificates
+from a @acronym{PKCS} #11 token, and use it with a TLS connection.
+
address@hidden examples/ex-cert-select-pkcs11.c
+
+
address@hidden Client with Resume capability example
address@hidden Client with resume capability example
address@hidden: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.
+
address@hidden examples/ex-client-resume.c
+
+
address@hidden Simple client example with SRP authentication
address@hidden 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
address@hidden and a @emph{password}. The server may authenticate
+itself using a certificate, and in that case it has to be verified.
+
address@hidden examples/ex-client-srp.c
+
address@hidden Simple client example in C++
address@hidden Simple client example using the C++ API
+
+The following client is a simple example of a client client utilizing
+the GnuTLS C++ API.
+
address@hidden examples/ex-cxx.cpp
+
address@hidden Helper function for TCP connections
address@hidden Helper function for TCP connections
+
+This helper function abstracts away TCP connection handling from the
+other examples. It is required to build some examples.
+
address@hidden examples/tcp.c
+
address@hidden Server examples
address@hidden Server examples
+
+This section contains examples of @acronym{TLS} and @acronym{SSL}
+servers, using @acronym{GnuTLS}.
+
address@hidden
+* Echo Server with X.509 authentication::
+* Echo Server with OpenPGP authentication::
+* Echo Server with SRP authentication::
+* Echo Server with anonymous authentication::
address@hidden menu
+
address@hidden Echo Server with X.509 authentication
address@hidden Echo server with @acronym{X.509} authentication
+
+This example is a very simple echo server which supports
address@hidden authentication, using the RSA ciphersuites.
+
address@hidden examples/ex-serv1.c
+
address@hidden Echo Server with OpenPGP authentication
address@hidden Echo server with @acronym{OpenPGP} authentication
address@hidden OpenPGP server
+
+The following example is an echo server which supports
address@hidden key authentication. You can easily combine
+this functionality ---that is have a server that supports both
address@hidden and @acronym{OpenPGP} certificates--- but we separated
+them to keep these examples as simple as possible.
+
address@hidden examples/ex-serv-pgp.c
+
address@hidden Echo Server with SRP authentication
address@hidden 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.
+
address@hidden examples/ex-serv-srp.c
+
address@hidden Echo Server with anonymous authentication
address@hidden Echo Server with anonymous authentication
+
+This example server support anonymous authentication, and could be
+used to serve the example client for anonymous authentication.
+
address@hidden examples/ex-serv-anon.c
+
address@hidden Miscellaneous examples
address@hidden Miscellaneous examples
+
address@hidden
+* Checking for an alert::
+* X.509 certificate parsing example::
address@hidden menu
+
address@hidden Checking for an alert
address@hidden Checking for an alert
+
+This is a function that checks if an alert has been received in the
+current session.
+
address@hidden examples/ex-alert.c
+
address@hidden X.509 certificate parsing example
address@hidden @acronym{X.509} certificate parsing example
address@hidden: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.
+
address@hidden examples/ex-x509-info.c
diff --git a/doc/cha-intro-tls.texi b/doc/cha-intro-tls.texi
index c25cfe1..64b4888 100644
--- a/doc/cha-intro-tls.texi
+++ b/doc/cha-intro-tls.texi
@@ -11,13 +11,12 @@ the Internet architecture and the smooth operation of the
Internet.
It is open to any interested individual.}, described in @xcite{RFC5246}.
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.2 @xcite{RFC5246} and @acronym{SSL} 3.0,
-since the differences of these protocols are not major.
+layer. The description, above, refers to @acronym{TLS} 1.0 but applies
+to all other TLS versions as the differences between the protocols are not
major.
The @acronym{DTLS} protocol, or ``Datagram @acronym{TLS}'' @xcite{RFC4347} is a
protocol with identical goals as @acronym{TLS}, but can operate
-under unreliable transport layers, such as @acronym{UDP}. The
+under unreliable transport layers such as @acronym{UDP}. The
discussions below apply to this protocol as well, except when
noted otherwise.
@@ -28,7 +27,6 @@ noted otherwise.
* The TLS Alert Protocol::
* The TLS Handshake Protocol::
* TLS Extensions::
-* Selecting cryptographic key sizes::
* How to use TLS in application protocols::
* On SSL 2 and older protocols::
@end menu
@@ -68,7 +66,7 @@ can be used over reliable and unreliable transport layers.
@acronym{GnuTLS} supports TCP and UDP layers transparently using
the Berkeley sockets API. However, any transport layer can be used
by providing callbacks for @acronym{GnuTLS} to access the transport layer
-(for details see @ref{TLS and DTLS sessions}).
+(for details see @ref{Setting up the transport layer}).
@node The TLS record protocol
@section The TLS record protocol
@@ -82,20 +80,18 @@ or send data. In @acronym{DTLS} however, due to
re-transmission
timers used in the handshake out-of-order handshake data might
be received for some time (maximum 60 seconds) after the handshake
process is finished. For this reason programs using @acronym{DTLS}
-should call @funcref{gnutls_record_recv} or @funcref{gnutls_record_recv_seq}
-for every packet received by the peer, even if no data were
-expected.
-
-As you may have already noticed, the functions which access the record
-protocol, are quite limited, given the importance of this protocol in
address@hidden This is because the record protocol's parameters are
-all set by the handshake protocol.
+should call the receive functions for every packet received by
+the peer, even if no data were expected.
+
+The functions to access the record protocol are limited to send
+and receive functions, which might, given
+the importance of this protocol in @acronym{TLS}, seem awkward. 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.
@showfuncC{gnutls_record_send,gnutls_record_recv,gnutls_record_recv_seq}
address@hidden,gnutls_record_get_direction}
@menu
* Encryption algorithms used in the record layer::
@@ -112,7 +108,7 @@ Confidentiality in the record layer is achieved by using
symmetric
block encryption algorithms like @code{3DES}, @code{AES}
or stream algorithms like @code{ARCFOUR_128}.
Ciphers are encryption algorithms that use a single, secret,
-key to encrypt and decrypt data. Block algorithms in TLS also provide
+key to encrypt and decrypt data. Block algorithms in CBC mode 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
@@ -193,7 +189,7 @@ tunnels, and in cases where network usage has to be
minimized. It
should be noted however that compression increases latency.
The record layer compression in @acronym{GnuTLS} is implemented based
-on the proposal @xcite{RFC3749}. The supported algorithms are shown in
+on @xcite{RFC3749}. The supported algorithms are shown in
@ref{gnutls_compression_method_t}.
@showenumdesc{gnutls_compression_method_t,Supported compression algorithms}
@@ -222,15 +218,17 @@ 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 @xcite{CBCATT}.
+which is implemented in @acronym{GnuTLS}. For this reason we suggest
+to always negotiate the highest supported TLS version with the peer.
+For a detailed discussion of the issues see the archives of the TLS
+Working Group mailing list and @xcite{CBCATT}.
@node On Record Padding
@subsection On record padding
@cindex record padding
@cindex bad_record_mac
-The TLS protocol allows for random padding of records, to prevent
+The TLS protocol allows for random padding of records in CBC ciphers, to
prevent
statistical analysis based on the length of exchanged messages (see
@xcite{RFC5246} 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.
@@ -303,11 +301,13 @@ the handshake protocol, i.e., the ciphersuite negotiation.
@menu
* TLS Cipher Suites:: TLS session parameters.
+* Authentication:: TLS authentication.
* Client Authentication:: Requesting a certificate from the client.
* Resuming Sessions:: Reusing previously established keys.
* Interoperability:: About interoperability with other
implementations.
@end menu
+
@node TLS Cipher Suites
@subsection TLS ciphersuites
@@ -336,6 +336,117 @@ that you consider weak.
All the supported ciphersuites are listed in @ref{ciphersuites}.
address@hidden Authentication
address@hidden Authentication
+
+The key exchange algorithms of the @acronym{TLS} protocol offer
+authentication, which is a prerequisite for a secure connection.
+The available authentication methods in @acronym{GnuTLS} follow.
+
address@hidden
+
address@hidden Certificate authentication: Authenticated key exchange using
public key infrastructure and certificates (X.509 or OpenPGP).
address@hidden @acronym{SRP} authentication: Authenticated key exchange using a
password.
address@hidden @acronym{PSK} authentication: Authenticated key exchange using a
pre-shared key.
address@hidden Anonymous authentication: Key exchange without peer
authentication.
+
address@hidden itemize
+
address@hidden Table,tab:key-exchange
address@hidden @columnfractions .2 .7
+
address@hidden Key exchange @tab Description
+
address@hidden RSA @tab
+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.
+
address@hidden RSA_EXPORT @tab
+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.
+
address@hidden DHE_RSA @tab
+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.
+
address@hidden ECDHE_RSA @tab
+The RSA algorithm is used to sign ephemeral elliptic curve Diffie-Hellman
+parameters which are sent to the peer. The key in the certificate must allow
+the key to be used for signing. It also offers 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.
+
address@hidden DHE_DSS @tab
+The DSA 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. DSA is the algorithm
+of the Digital Signature Standard (DSS).
+
address@hidden ECDHE_ECDSA @tab
+The Elliptic curve DSA algorithm is used to sign ephemeral elliptic
+curve Diffie-Hellman parameters which are sent to the peer. The
+certificate must contain ECDSA parameters to use this key exchange
+algorithm.
+
address@hidden multitable
address@hidden key exchange algorithms.}
address@hidden float
+
+Each authentication method is associated with a key exchange method, shown
+in @ref{tab:key-exchange}, and a credentials type.
+The contents of the credentials is method-dependent, e.g. certificates
+for certificate authentication and should be initialized and associated
+with a session (see @funcref{gnutls_credentials_set}). A mapping of the key
exchange methods
+with the credential types is shown in @ref{tab:key-exchange-cred}.
+
address@hidden Table,tab:key-exchange-cred
address@hidden @columnfractions .25 .25 .2 .2
+
address@hidden Authentication method @tab Key exchange @tab Client credentials
@tab Server credentials
+
address@hidden Certificate
address@hidden @code{KX_RSA},
address@hidden,
address@hidden,
address@hidden,
address@hidden,
address@hidden
address@hidden @code{CRD_CERTIFICATE}
address@hidden @code{CRD_CERTIFICATE}
+
address@hidden Password and certificate
address@hidden @code{KX_SRP_RSA}, @code{KX_SRP_DSS}
address@hidden @code{CRD_SRP}
address@hidden @code{CRD_CERTIFICATE}, @code{CRD_SRP}
+
address@hidden Password
address@hidden @code{KX_SRP}
address@hidden @code{CRD_SRP}
address@hidden @code{CRD_SRP}
+
address@hidden Anonymous
address@hidden @code{KX_ANON_DH},
address@hidden
address@hidden @code{CRD_ANON}
address@hidden @code{CRD_ANON}
+
address@hidden Pre-shared key
address@hidden @code{KX_PSK},
address@hidden, @code{KX_ECDHE_PSK}
address@hidden @code{CRD_PSK}
address@hidden @code{CRD_PSK}
+
address@hidden multitable
address@hidden exchange algorithms and the corresponding credential types.}
address@hidden float
+
+
@node Client Authentication
@subsection Client authentication
@cindex client certificate authentication
@@ -347,7 +458,7 @@ may request a certificate from the client using the
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
+signers list is constructed using the trusted certificate authorities
by the server. That is the ones set using the following functions.
@showfuncB{gnutls_certificate_set_x509_trust_file,gnutls_certificate_set_x509_trust_mem}
@@ -368,11 +479,11 @@ signed by server's acceptable signers.
@cindex resuming sessions
@cindex session resuming
-The @funcref{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. 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 TLS handshake process performs expensive calculations
+and a busy server might easily be put under load. To
+reduce the load, clients may use session resumption. Session
+resumption 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 re-using the previously
established keys. @acronym{GnuTLS} supports this feature, and the
example in @ref{ex:resume-client} illustrates a typical use of it.
@@ -387,39 +498,29 @@ 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. That is, copy and keep the
+the burden of resuming to the client, i.e., copy and keep the
necessary parameters. The relevant functions are listed below.
address@hidden
-
address@hidden
-
address@hidden
address@hidden,gnutls_session_get_id,gnutls_session_set_data}
Server side is different. A server needs to specify callback
functions which store, retrieve and delete session data. These can be
registered with the functions shown below.
address@hidden
-
address@hidden
-
address@hidden,gnutls_db_set_remove_function}
address@hidden,gnutls_db_set_store_function,gnutls_db_set_ptr,gnutls_db_set_remove_function}
It might also be useful to be able to check for expired sessions in
order to remove them, and save space. The function
@funcref{gnutls_db_check_entry} is provided for that reason.
address@hidden
address@hidden
@node Interoperability
@subsection Interoperability
-The @acronym{TLS} handshake is a complex procedure that negotiates all
-required parameters for a secure session. @acronym{GnuTLS} supports
-several @acronym{TLS} extensions, as well as the latest @acronym{TLS} protocol
-version 1.2. However few implementations are not able to
-properly interoperate once faced with extensions or version protocols
+The @acronym{TLS} protocols support many ciphersuites, extensions and version
+numbers. As a result, few implementations are
+not able to properly interoperate once faced with extensions or version
protocols
they do not support and understand. The @acronym{TLS} protocol allows for a
graceful downgrade to the commonly supported options, but practice shows
it is not always implemented correctly.
@@ -438,7 +539,7 @@ This priority string will only enable SSL 3.0 and TLS 1.0
as protocols and
will disable, via the @code{%COMPAT} keyword, several @acronym{TLS} protocol
options that are known to cause compatibility problems. Note however that
there are known attacks against those protocol versions and
-if mode is used security is traded for compatibility.
+this mode trades security for compatibility.
@node TLS Extensions
@section TLS extensions
@@ -466,9 +567,7 @@ smaller value for record packet maximum length. This
extension may be
useful to clients with constrained capabilities. The functions shown
below can be used to control this extension.
address@hidden
-
address@hidden
address@hidden,gnutls_record_set_max_size}
@subsection Server name indication
@anchor{serverind}
@@ -487,9 +586,7 @@ begins within the first handshake packet. The functions
used to enable this extension, or to retrieve the name sent by a
client.
address@hidden
-
address@hidden
address@hidden,gnutls_server_name_get}
@subsection Session tickets
@cindex TLS extensions
@@ -508,11 +605,7 @@ Clients can enable support for TLS tickets with
@funcref{gnutls_session_ticket_enable_server} to enable the extension.
Clients resume sessions using the normal session resumption procedure (see
@ref{resume}).
address@hidden
-
address@hidden
-
address@hidden
address@hidden,gnutls_session_ticket_enable_server,gnutls_session_ticket_enable_client}
@subsection Safe renegotiation
@cindex renegotiation
@@ -612,91 +705,6 @@ renegotiation. The
@funcref{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.
address@hidden Selecting cryptographic key sizes
address@hidden Selecting cryptographic key sizes
address@hidden key sizes
-
-Because many algorithms are involved in TLS, it is not easy to set
-a consistent security level. For this reason in @ref{tab:key-sizes} we
-present some correspondence between key sizes of symmetric algorithms
-and public key algorithms based on @xcite{ECRYPT}.
-Those can be used to generate certificates with
-appropriate key sizes as well as select parameters for Diffie-Hellman and SRP
-authentication.
-
address@hidden Table,tab:key-sizes
address@hidden @columnfractions .10 .12 .10 .20 .32
-
address@hidden Security bits @tab RSA, DH and SRP parameter size @tab ECC key
size @tab Security parameter @tab Description
-
address@hidden 64
address@hidden 816
address@hidden 128
address@hidden @code{WEAK}
address@hidden Very short term protection against small organizations
-
address@hidden 80
address@hidden 1248
address@hidden 160
address@hidden @code{LOW}
address@hidden Very short term protection against agencies
-
address@hidden 112
address@hidden 2432
address@hidden 224
address@hidden @code{NORMAL}
address@hidden Medium-term protection
-
address@hidden 128
address@hidden 3248
address@hidden 256
address@hidden @code{HIGH}
address@hidden Long term protection
-
address@hidden 256
address@hidden 15424
address@hidden 512
address@hidden @code{ULTRA}
address@hidden Foreseeable future
-
address@hidden multitable
address@hidden sizes and security parameters.}
address@hidden float
-
-The first column provides a security parameter in a number of bits. This
-gives an indication of the number of combinations to be tried by an adversary
-to brute force a key. For example to test all possible keys in a 112 bit
security parameter
address@hidden combinations have to be tried. For today's technology this is
infeasible.
-The next two columns correlate the security
-parameter with actual bit sizes of parameters for DH, RSA, SRP and ECC
algorithms.
-A mapping to @code{gnutls_sec_param_t} value is given for each security
parameter, on
-the next column, and finally a brief description of the level.
-
address@hidden @showenumdesc{gnutls_sec_param_t,The @address@hidden
enumeration.}
-
-Note, however, that the values suggested here are nothing more than an
-educated guess that is valid today. There are no guarantees 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.
-The NIST publication SP 800-57 @xcite{NISTSP80057} contains a similar
-table.
-
-When using @acronym{GnuTLS} and a decision on bit sizes for a public
-key algorithm is required, use of the following functions is
-recommended:
-
address@hidden
-
address@hidden
-
-Those functions will convert a human understandable security parameter
-of @code{gnutls_sec_param_t} type, to a number of bits suitable for a public
-key algorithm.
-
@include sec-tls-app.texi
@node On SSL 2 and older protocols
diff --git a/doc/cha-library.texi b/doc/cha-library.texi
index de34820..2f751b3 100644
--- a/doc/cha-library.texi
+++ b/doc/cha-library.texi
@@ -1,5 +1,7 @@
address@hidden The Library
address@hidden The Library
address@hidden Introduction to GnuTLS
address@hidden Introduction to GnuTLS
+
address@hidden Introduction
In brief @acronym{GnuTLS} can be described as a library which offers an API
to access secure communication protocols. These protocols provide
@@ -19,9 +21,7 @@ include:
@item Support for Datagram TLS 1.0.
address@hidden Support for both @acronym{X.509} and @acronym{OpenPGP}
certificates.
-
address@hidden Support for handling and verification of certificates.
address@hidden Support for handling and verification of @acronym{X.509} and
@acronym{OpenPGP} certificates.
@item Support for password authentication using @acronym{TLS-SRP}.
@@ -41,15 +41,7 @@ functionality from the
address@hidden@url{http://www.gnu.org/software/libtasn1/}} library.
The ``Cryptographic back-end'' is provided by the
address@hidden@url{http://www.lysator.liu.se/~nisse/nettle/}}
library.
address@hidden
-* Downloading and installing::
-* General idea::
-* Error handling::
-* Thread safety::
-* Callback functions::
address@hidden menu
-
address@hidden Downloading and installing
+
@section Downloading and installing
@cindex installation
@cindex download
@@ -101,150 +93,13 @@ to create a smaller library with only the required
features.
For the complete list, refer to the output from @code{configure --help}.
address@hidden General idea
address@hidden General idea
-
-A brief description of how @acronym{GnuTLS} works internally is shown
-at @ref{fig:gnutls-design}. This section may be easier to understand after
-having seen the examples at @ref{examples}.
-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 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 allocated memory
-and is called after the program has permanently
-finished using @acronym{GnuTLS}.
-
address@hidden Figure,fig:gnutls-design
address@hidden,12cm}
address@hidden level design of GnuTLS.}
address@hidden float
-
-The credentials structures are used by the authentication methods, such
-as certificate authentication. They store certificates, privates keys,
-and other information that is needed to prove the identity to the peer,
-and/or verify the indentity of the peer. The information stored in
-the credentials structures is initialized once and then can be
-shared by many @acronym{TLS} sessions.
-
-A @acronym{GnuTLS} session contains all the required information
-to handle one secure connection. The session communicates with the
-peers using the provided functions of the transport layer.
-Every session has a unique session ID shared with the peer.
-
-Since TLS sessions can be resumed, servers need a
-database back-end to hold the session's parameters. Every
address@hidden session after a successful handshake calls the
-appropriate back-end function (see @ref{resume})
-to store the newly negotiated session. The session
-database is examined by the server just after having received the
-client address@hidden 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.
-
address@hidden Error handling
address@hidden Error handling
address@hidden Conventions
-
-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. Such an example is
address@hidden@address@hidden@-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
address@hidden@address@hidden returned by @funcref{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
address@hidden
-
-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. See @ref{Error codes}, for a description of the available
-error codes.
-
address@hidden Debugging and auditing
-
-In many cases things may not go as expected and further information,
-to assist debugging, from @acronym{GnuTLS} is desired.
-Those are the cases where the @funcref{gnutls_global_set_log_level} and
address@hidden are to be used. Those will print
-verbose information on the @acronym{GnuTLS} functions internal flow.
-
address@hidden,gnutls_global_set_log_function}
-
-When debugging is not required, important issues, such as detected
-attacks on the protocol still need to be logged. This is provided
-by the logging function set by
address@hidden The provided function
-will receive an message and the corresponding
-TLS session. The session information might be used to derive IP addresses
-or other information about the peer involved.
-
address@hidden
-
address@hidden Thread safety
address@hidden Thread safety
-
-The @acronym{GnuTLS} library is thread safe by design, meaning that
-objects of the library such as TLS sessions, can be safely divided across
-threads as long as a single thread accesses a single object. This is
-sufficient to support a server which handles several sessions per thread.
-If, however, an object needs to be shared across threads then access must be
-protected with a mutex. Read-only access to objects, for example the
-credentials holding structures (see @ref{Authentication methods}), is also
thread-safe.
-
-The random generator of the cryptographic back-end, is not thread safe and
requires
-mutex locks which are setup by @acronym{GnuTLS}.
-Applications can either call @funcref{gnutls_global_init} which will
initialize the default
-operating system provided locks (i.e. @code{pthreads} on GNU/Linux and
address@hidden on Windows), or specify manually the locking system using
-the function @funcref{gnutls_global_set_mutex} before calling
@funcref{gnutls_global_init}.
-Setting manually mutexes is recommended
-only to applications that have full control of the underlying libraries. If
this
-is not the case, the use of the operating system defaults is recommended. An
example of
-non-native thread usage is shown below.
-
address@hidden
-#include <gnutls.h>
-
-/* Other thread packages
- */
-
-int main()
address@hidden
- gnutls_global_set_mutex (mutex_init, mutex_deinit,
- mutex_lock, mutex_unlock);
- gnutls_global_init();
address@hidden
address@hidden example
-
address@hidden
-
address@hidden Callback functions
address@hidden Callback functions
address@hidden callback functions
-
-There are several cases where @acronym{GnuTLS} may need 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.
-
address@hidden,gnutls_transport_set_pull_function}
-
-Other callback functions may require more complicated input and data
-to be allocated. Such an example is
address@hidden
-All callbacks should allocate and free memory using the functions shown below.
-
address@hidden,gnutls_free}
-
address@hidden Overview
+In this document we present an overview of the supported security protocols in
@ref{Introduction to TLS}, and
+continue by providing more information on the certificate authentication in
@ref{Certificate authentication},
+and shared-key as well anonymous authentication in @ref{Shared-key and
anonymous authentication}. We
+elaborate on certificate authentication by demonstrating advanced usage of the
API in @ref{More on certificate authentication}.
+The core of the TLS library is presented in @ref{How to use GnuTLS in
applications} and example
+applications are listed in @ref{GnuTLS application examples}.
+In @ref{Other included programs} the usage of few included programs that
+may assist debugging is presented. The last chapter is @ref{Internal
architecture of GnuTLS} that
+provides a short introduction to GnuTLS' internal architecture.
diff --git a/doc/cha-shared-key.texi b/doc/cha-shared-key.texi
new file mode 100644
index 0000000..50f4585
--- /dev/null
+++ b/doc/cha-shared-key.texi
@@ -0,0 +1,202 @@
address@hidden Shared-key and anonymous authentication
address@hidden Shared-key and anonymous authentication
+
address@hidden
+* SRP authentication::
+* PSK authentication::
+* Anonymous authentication::
address@hidden menu
+
address@hidden SRP authentication
address@hidden SRP authentication
+
address@hidden
+* Authentication using SRP::
+* Invoking srptool::
address@hidden menu
+
address@hidden Authentication using SRP
address@hidden Authentication using @acronym{SRP}
address@hidden SRP authentication
+
address@hidden supports authentication via the Secure Remote Password
+or @acronym{SRP} protocol (see @xcite{RFC2945,TOMSRP} for a description).
+The @acronym{SRP} key exchange is an extension to the
address@hidden protocol, and it provides an authenticated with a
+password key exchange. The 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} is not
+susceptible to off-line dictionary attacks.
+Moreover, 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
@acronym{UNIX}
address@hidden/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.
+The Stanford @acronym{SRP} libraries, include 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 users
+of a system.
+
+The implementation in @acronym{GnuTLS} is based on @xcite{TLSSRP}. The
+supported key exchange methods are shown below.
+
address@hidden @code
+
address@hidden SRP:
+Authentication using the @acronym{SRP} protocol.
+
address@hidden SRP_DSS:
+Client authentication using the @acronym{SRP} protocol. Server is
+authenticated using a certificate with DSA parameters.
+
address@hidden SRP_RSA:
+Client authentication using the @acronym{SRP} protocol. Server is
+authenticated using a certificate with RSA parameters.
+
address@hidden table
+
+Helper functions are included in @acronym{GnuTLS}, 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. See @ref{srptool}, for more information.
+
address@hidden
+
address@hidden,gnutls_srp_base64_decode}
+
address@hidden Invoking srptool
address@hidden Invoking srptool
address@hidden
address@hidden srptool
+
+The @file{srptool} is a very simple program that emulates the programs
+in the @emph{Stanford SRP address@hidden
address@hidden://srp.stanford.edu/}.}. It requires two files,
+one called @code{tpasswd} which holds usernames and verifiers,
+and @code{tpasswd.conf} which holds generators and primes.
+
+To create tpasswd.conf which holds the generator and prime values for
+the @acronym{SRP} protocol, run:
+
address@hidden
+$ srptool --create-conf /etc/tpasswd.conf
address@hidden smallexample
+
+This command will create /etc/tpasswd and will add user 'test' (you
+will also be prompted for a password). Verifiers are stored in a way that
+is compatible with libsrp.
+
address@hidden
+$ srptool --passwd /etc/tpasswd \
+ --passwd-conf /etc/tpasswd.conf -u test
address@hidden smallexample
+
+This command will check against a password. If the password matches
+the one in /etc/tpasswd you will get an ok.
+
address@hidden
+$ srptool --passwd /etc/tpasswd \
+ --passwd-conf /etc/tpasswd.conf --verify -u test
address@hidden smallexample
+
address@hidden PSK authentication
address@hidden PSK authentication
+
address@hidden
+* Authentication using PSK::
+* Invoking psktool::
address@hidden menu
+
address@hidden Authentication using PSK
address@hidden Authentication using @acronym{PSK}
address@hidden 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 @xcite{TLSPSK}.
+The supported @acronym{PSK} key exchange methods are:
+
address@hidden @code
+
address@hidden PSK:
+Authentication using the @acronym{PSK} protocol.
+
address@hidden DHE-PSK:
+Authentication using the @acronym{PSK} protocol and Diffie-Hellman key
+exchange. This method offers perfect forward secrecy.
+
address@hidden ECDHE-PSK:
+Authentication using the @acronym{PSK} protocol and Elliptic curve
Diffie-Hellman key
+exchange. This method offers perfect forward secrecy.
+
address@hidden table
+
+
+Helper functions to generate and maintain @acronym{PSK} keys are also included
+in @acronym{GnuTLS}.
+
address@hidden,gnutls_hex_encode,gnutls_hex_decode}
+
address@hidden Invoking psktool
address@hidden Invoking psktool
address@hidden psktool
+
+This is a program to manage @acronym{PSK} username and keys.
+It will generate random keys for the indicated username,
+using a simple password file format.
+
address@hidden
+PSKtool help
+Usage : psktool [options]
+ -u, --username username
+ specify username.
+ -p, --passwd FILE specify a password file.
+ -s, --keysize SIZE specify the key size in bytes.
+ -v, --version prints the program's version number
+ -h, --help shows this help text
address@hidden smallexample
+
+The generation of a PSK password file is illustrated in the example below.
+The password is provided in the prompt.
+
address@hidden
+$ ./psktool -u psk_identity -p psks.txt
+Generating a random key for user 'psk_identity'
+Key stored to psks.txt
+$ cat psks.txt
+psk_identity:88f3824b3e5659f52d00e959bacab954b6540344
+$
address@hidden smallexample
+
address@hidden Anonymous authentication
address@hidden Anonymous authentication
address@hidden anonymous authentication
+
+The anonymous key exchange offers encryption without any
+indication of the peer's identity. This kind of authentication
+is vulnerable to a man in the middle attack, but can be
+used even if there is no prior communication or shared trusted parties
+with the peer. Moreover it is useful when complete anonymity is required.
+Unless in one of the above cases, do not use anonymous authentication.
+
+The available key exchange algorithms for anonymous authentication are
+shown below.
+
address@hidden @code
+
address@hidden ANON_DH:
+This algorithm exchanges Diffie-Hellman parameters.
+
address@hidden ANON_ECDH:
+This algorithm exchanges elliptic curve Diffie-Hellman parameters. It is more
+efficient than ANON_DH on equivalent security levels.
+
address@hidden table
diff --git a/doc/gnutls.texi b/doc/gnutls.texi
index fd4bf1f..8f4e13f 100644
--- a/doc/gnutls.texi
+++ b/doc/gnutls.texi
@@ -147,11 +147,13 @@ Documentation License''.
@menu
* Preface::
-* The Library::
+* Introduction to GnuTLS::
* Introduction to TLS::
-* Authentication methods::
+* Certificate authentication::
+* Shared-key and anonymous authentication::
* More on certificate authentication::
* How to use GnuTLS in applications::
+* GnuTLS application examples::
* Other included programs::
* Internal architecture of GnuTLS::
* Support::
@@ -171,12 +173,16 @@ Documentation License''.
@include cha-intro-tls.texi
address@hidden cha-auth.texi
-
@include cha-cert-auth.texi
address@hidden cha-shared-key.texi
+
address@hidden cha-cert-auth2.texi
+
@include cha-gtls-app.texi
address@hidden cha-gtls-examples.texi
+
@include cha-programs.texi
@include cha-internals.texi
diff --git a/doc/latex/.gitignore b/doc/latex/.gitignore
index 6d679f3..ab0ce42 100644
--- a/doc/latex/.gitignore
+++ b/doc/latex/.gitignore
@@ -35,3 +35,6 @@ gnutls.dvi
gnutls.tmp
gnutls.xref
sec-tls-app.tex
+cha-cert-auth2.tex
+cha-shared-key.tex
+cha-gtls-examples.tex
diff --git a/doc/latex/Makefile.am b/doc/latex/Makefile.am
index 0d8ded7..55482ba 100644
--- a/doc/latex/Makefile.am
+++ b/doc/latex/Makefile.am
@@ -1,10 +1,10 @@
TEX_OBJECTS = gnutls.tex macros.tex macros-epub.tex fdl.tex cover.tex
gnutls.bib \
cover-epub.tex
-GEN_TEX_OBJECTS = cha-preface.tex cha-library.tex cha-intro-tls.tex
cha-auth.tex \
+GEN_TEX_OBJECTS = cha-preface.tex cha-library.tex cha-intro-tls.tex
cha-cert-auth2.tex \
cha-cert-auth.tex cha-gtls-app.tex sec-tls-app.tex cha-programs.tex
cha-support.tex \
- cha-functions.tex error_codes.tex cha-ciphersuites.tex algorithms.tex \
- cha-errors.tex alerts.tex cha-internals.tex
+ cha-functions.tex error_codes.tex cha-ciphersuites.tex algorithms.tex
cha-shared-key.tex \
+ cha-errors.tex alerts.tex cha-internals.tex cha-gtls-examples.tex
cha-preface.tex: ../cha-preface.texi
../scripts/mytexi2latex $< > $@
@@ -15,15 +15,21 @@ cha-library.tex: ../cha-library.texi
cha-intro-tls.tex: ../cha-intro-tls.texi
../scripts/mytexi2latex $< > $@
-cha-auth.tex: ../cha-auth.texi
+cha-shared-key.tex: ../cha-shared-key.texi
../scripts/mytexi2latex $< > $@
cha-cert-auth.tex: ../cha-cert-auth.texi
../scripts/mytexi2latex $< > $@
+cha-cert-auth2.tex: ../cha-cert-auth2.texi
+ ../scripts/mytexi2latex $< > $@
+
cha-gtls-app.tex: ../cha-gtls-app.texi
../scripts/mytexi2latex $< > $@
+cha-gtls-examples.tex: ../cha-gtls-examples.texi
+ ../scripts/mytexi2latex $< > $@
+
sec-tls-app.tex: ../sec-tls-app.texi
../scripts/mytexi2latex $< > $@
diff --git a/doc/latex/gnutls.tex b/doc/latex/gnutls.tex
index bf4aaaf..1cc2268 100644
--- a/doc/latex/gnutls.tex
+++ b/doc/latex/gnutls.tex
@@ -62,12 +62,16 @@
\input{cha-intro-tls}
-\input{cha-auth}
-
\input{cha-cert-auth}
+\input{cha-shared-key}
+
+\input{cha-cert-auth2}
+
\input{cha-gtls-app}
+\input{cha-gtls-examples}
+
\input{cha-programs}
\input{cha-internals}
diff --git a/doc/scripts/mytexi2latex b/doc/scripts/mytexi2latex
index db333a0..cdb8964 100755
--- a/doc/scripts/mytexi2latex
+++ b/doc/scripts/mytexi2latex
@@ -127,6 +127,7 @@ while ($line = <FILE>) {
push(@stack, FLOAT_TABLE);
$line =~ s/address@hidden address@hidden
([\.\d]+)
([\.\d]+)$/\n\\begin{tabular}{|p{$1\\linewidth}|p{$2\\linewidth}|}\n\\hline\n/g;
$line =~ s/address@hidden address@hidden
([\.\d]+) ([\.\d]+)
([\.\d]+)$/\n\\begin{tabular}{|p{$1\\linewidth}|p{$2\\linewidth}|p{$3\\linewidth}|}\n\\hline\n/g;
+ $line =~ s/address@hidden address@hidden
([\.\d]+) ([\.\d]+) ([\.\d]+)
([\.\d]+)$/\n\\begin{tabular}{|p{$1\\linewidth}|p{$2\\linewidth}|p{$3\\linewidth}|p{$4\\linewidth}|}\n\\hline\n/g;
$line =~ s/address@hidden address@hidden
([\.\d]+) ([\.\d]+) ([\.\d]+) ([\.\d]+)
([\.\d]+)$/\n\\begin{tabular}{|p{$1\\linewidth}|p{$2\\linewidth}|p{$3\\linewidth}|p{$4\\linewidth}|p{$5\\linewidth}|}\n\\hline\n/g;
}
hooks/post-receive
--
GNU gnutls
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [SCM] GNU gnutls branch, master, updated. gnutls_3_0_8-6-g54e3f5b,
Nikos Mavrogiannopoulos <=