reorganized documentation

1 files changed, 0 insertions, 498 deletions

diff --git a/doc/cha-auth.texi b/doc/cha-auth.texi
deleted file mode 100644
index 7315389dd8..0000000000
--- a/doc/cha-auth.texi
+++ /dev/null
@@ -1,498 +0,0 @@
-@node Authentication methods
-@chapter Authentication methods
-
-The @acronym{TLS} protocol provides confidentiality and encryption,
-but also offers authentication, which is a prerequisite for a secure
-connection. The available authentication methods in @acronym{GnuTLS}
-are:
-
-@itemize
-
-@item Certificate authentication: Authenticated key exchange using public key infrastructure and certificates (X.509 or OpenPGP).
-
-@item @acronym{SRP} authentication: Authenticated key exchange using a password.
-
-@item @acronym{PSK} authentication: Authenticated key exchange using a pre-shared key.
-
-@item Anonymous authentication: Key exchange without peer authentication.
-
-@end 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
-@funcref{gnutls_credentials_set}. 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.
-
-@showfuncdesc{gnutls_credentials_set}
-
-@menu
-* Certificate authentication::
-* Anonymous authentication::
-* SRP authentication::
-* PSK authentication::
-* Authentication and credentials::
-@end menu
-
-@node Certificate authentication
-@section Certificate authentication
-
-@subsection Authentication using @acronym{X.509} certificates
-@cindex X.509 certificates
-
-@acronym{X.509} certificates contain the public parameters, of a
-public key algorithm, and an authority's signature, which proves the
-authenticity of the parameters.  See @ref{X.509 certificates}, for
-more information on @acronym{X.509} protocols.
-
-@subsection Authentication using @acronym{OpenPGP} keys
-@cindex OpenPGP keys
-
-@acronym{OpenPGP} keys also contain public parameters of a public key
-algorithm, and signatures from several other parties. Depending on
-whether a signer is trusted the key is considered trusted or not.
-@acronym{GnuTLS}'s @acronym{OpenPGP} authentication implementation is
-based on the @xcite{TLSPGP} proposal.
-
-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}.
-
-@subsection Using certificate authentication
-
-In @acronym{GnuTLS} both the @acronym{OpenPGP} and @acronym{X.509}
-certificates are part of the certificate authentication and thus are
-handled using a common API.
-When using certificates the server is required to have at least one
-certificate and private key pair. A client may or may not have such a
-pair. 
-
-@showfuncB{gnutls_certificate_allocate_credentials,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.
-
-@showfuncD{gnutls_certificate_set_x509_key_mem,gnutls_certificate_set_openpgp_key,gnutls_certificate_set_openpgp_key_file,gnutls_certificate_set_openpgp_key_mem}
-@showfuncB{gnutls_certificate_set_x509_key,gnutls_certificate_set_key}
-
-@showfuncdesc{gnutls_certificate_set_x509_key_file}
-
-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
-@funcref{gnutls_sign_algorithm_get_requested}. Both functions are shown below.
-
-@showfuncdesc{gnutls_certificate_set_retrieve_function}
-
-@showfuncdesc{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.
-
-@showfuncB{gnutls_certificate_set_x509_trust_file,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}.
-
-@showfuncdesc{gnutls_certificate_verify_peers2}
-
-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
-@code{DHE_RSA} 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.
-
-@showfuncdesc{gnutls_certificate_set_verify_function}
-
-Note that the DHE key exchange methods are generally
-slower@footnote{It 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}). 
-
-@float Table,tab:key-exchange
-@multitable @columnfractions .2 .7
-
-@headitem Key exchange @tab Description
-
-@item 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.
-
-@item 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.
-
-@item 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.
-
-@item 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.
-
-@item 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).
-
-@item 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. 
-
-@end multitable
-@caption{Supported key exchange algorithms.}
-@end float
-
-@node Anonymous authentication
-@section Anonymous authentication
-@cindex 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
-@ref{Parameter generation} for more information.
-
-The initialization functions for the credentials are shown below.
-
-@showfuncD{gnutls_anon_allocate_server_credentials,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.
-
-@table @code
-
-@item ANON_DH:
-This algorithm exchanges Diffie-Hellman parameters.
-
-@item ANON_ECDH:
-This algorithm exchanges elliptic curve Diffie-Hellman parameters. It is more 
-efficient than ANON_DH on equivalent security levels.
-
-@end table
-
-@node SRP authentication
-@section SRP authentication
-
-@menu
-* Authentication using SRP::
-* Invoking srptool::
-@end menu
-
-@node Authentication using SRP
-@subsection Authentication using @acronym{SRP}
-@cindex SRP authentication
-
-@acronym{GnuTLS} 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
-@acronym{TLS} 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}
-@file{/etc/passwd} file, where the contents of this file did not cause
-harm to the system security if they were revealed.  The @acronym{SRP}
-needs instead of the plain password something called a verifier, which
-is calculated using the user's password, and if stolen cannot be used
-to impersonate the user. 
-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.
-
-@table @code
-
-@item SRP:
-Authentication using the @acronym{SRP} protocol.
-
-@item SRP_DSS:
-Client authentication using the @acronym{SRP} protocol. Server is
-authenticated using a certificate with DSA parameters.
-
-@item SRP_RSA:
-Client authentication using the @acronym{SRP} protocol. Server is
-authenticated using a certificate with RSA parameters.
-
-@end table
-
-The initialization functions in SRP credentials differ between
-client and server.
-
-@showfuncD{gnutls_srp_allocate_server_credentials,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.
-
-@showfuncA{gnutls_srp_set_client_credentials}
-
-@showfuncdesc{gnutls_srp_set_client_credentials_function}
-
-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 
-@funcref{gnutls_srp_set_server_credentials_function} should be called,
-to set an appropriate callback. 
-
-@showfuncdesc{gnutls_srp_set_server_credentials_file}
-
-@showfuncdesc{gnutls_srp_set_server_credentials_function}
-
-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.
-
-@showfuncdesc{gnutls_srp_verifier}
-
-@showfuncB{gnutls_srp_base64_encode,gnutls_srp_base64_decode}
-
-@node Invoking srptool
-@subsection Invoking srptool
-@anchor{srptool}
-@cindex srptool
-
-The @file{srptool} is a very simple program that emulates the programs
-in the @emph{Stanford SRP libraries}@footnote{See
-@url{http://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:
-
-@smallexample
-$ srptool --create-conf /etc/tpasswd.conf
-@end 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.
-
-@smallexample
-$ srptool --passwd /etc/tpasswd \
-    --passwd-conf /etc/tpasswd.conf -u test
-@end smallexample
-
-This command will check against a password.  If the password matches
-the one in /etc/tpasswd you will get an ok.
-
-@smallexample
-$ srptool --passwd /etc/tpasswd \
-    --passwd-conf /etc/tpasswd.conf --verify -u test
-@end smallexample
-
-@node PSK authentication
-@section PSK authentication
-
-@menu
-* Authentication using PSK::
-* Invoking psktool::
-@end menu
-
-@node Authentication using PSK
-@subsection Authentication using @acronym{PSK}
-@cindex 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:
-
-@table @code
-
-@item PSK:
-Authentication using the @acronym{PSK} protocol.
-
-@item DHE-PSK:
-Authentication using the @acronym{PSK} protocol and Diffie-Hellman key
-exchange.  This method offers perfect forward secrecy.
-
-@item ECDHE-PSK:
-Authentication using the @acronym{PSK} protocol and Elliptic curve Diffie-Hellman key
-exchange.  This method offers perfect forward secrecy.
-
-@end table
-
-The initialization functions in PSK credentials differ between
-client and server.
-
-@showfuncD{gnutls_psk_allocate_server_credentials,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 
-@funcref{gnutls_psk_set_client_credentials_function} 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.
-
-@showfuncA{gnutls_psk_set_client_credentials}
-
-@showfuncdesc{gnutls_psk_set_client_credentials_function}
-
-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
-@funcref{gnutls_psk_set_server_credentials_hint}.  The client can retrieve
-the hint, for example in the callback function, using
-@funcref{gnutls_psk_client_get_hint}.
-
-@showfuncdesc{gnutls_psk_set_server_credentials_file}
-
-@showfuncC{gnutls_psk_set_server_credentials_function,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}.
-
-@showfuncC{gnutls_key_generate,gnutls_hex_encode,gnutls_hex_decode}
-
-@node Invoking psktool
-@subsection Invoking psktool
-@cindex 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.
-
-@smallexample
-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
-@end smallexample
-
-The generation of a PSK password file is illustrated in the example below. 
-The password is provided in the prompt.
-
-@smallexample
-$ ./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
-$
-@end smallexample
-
-@node Authentication and credentials
-@section 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
-@funcref{gnutls_credentials_set}.  A mapping of the key exchange methods
-with the credential types is shown in @ref{tab:key-exchange-cred}.
-
-@float Table,tab:key-exchange-cred
-@multitable @columnfractions .4 .25 .25
-
-@headitem Key exchange @tab Client credentials @tab Server credentials
-
-@item @code{KX_RSA},
-@code{KX_DHE_RSA},
-@code{KX_DHE_DSS},
-@code{KX_ECDHE_RSA},
-@code{KX_ECDHE_ECDSA},
-@code{KX_RSA_EXPORT}
-@tab @code{CRD_CERTIFICATE}
-@tab @code{CRD_CERTIFICATE}
-
-@item @code{KX_SRP_RSA}, @code{KX_SRP_DSS}
-@tab @code{CRD_SRP}
-@tab @code{CRD_CERTIFICATE}, @code{CRD_SRP}
-
-@item @code{KX_SRP}
-@tab @code{CRD_SRP}
-@tab @code{CRD_SRP}
-
-@item @code{KX_ANON_DH},
-@code{KX_ANON_ECDH}
-@tab @code{CRD_ANON}
-@tab @code{CRD_ANON}
-
-@item @code{KX_PSK},
-@code{KX_DHE_PSK}, @code{KX_ECDHE_PSK}
-@tab @code{CRD_PSK}
-@tab @code{CRD_PSK}
-
-@end multitable
-@caption{Key exchange algorithms and the corresponding credential types.}
-@end float
-