diff options
| -rw-r--r-- | doc/Makefile.am | 5 | ||||
| -rw-r--r-- | doc/cha-auth.texi | 498 | ||||
| -rw-r--r-- | doc/cha-cert-auth.texi | 885 | ||||
| -rw-r--r-- | doc/cha-cert-auth2.texi | 823 | ||||
| -rw-r--r-- | doc/cha-gtls-app.texi | 759 | ||||
| -rw-r--r-- | doc/cha-gtls-examples.texi | 221 | ||||
| -rw-r--r-- | doc/cha-intro-tls.texi | 288 | ||||
| -rw-r--r-- | doc/cha-library.texi | 177 | ||||
| -rw-r--r-- | doc/cha-shared-key.texi | 202 | ||||
| -rw-r--r-- | doc/gnutls.texi | 14 | ||||
| -rw-r--r-- | doc/latex/.gitignore | 3 | ||||
| -rw-r--r-- | doc/latex/Makefile.am | 14 | ||||
| -rw-r--r-- | doc/latex/gnutls.tex | 8 | ||||
| -rwxr-xr-x | doc/scripts/mytexi2latex | 1 |
14 files changed, 1927 insertions, 1971 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index 1625209bdd..9907dafa50 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 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 - diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi index ad352549a1..df9d388b6c 100644 --- a/doc/cha-cert-auth.texi +++ b/doc/cha-cert-auth.texi @@ -1,16 +1,23 @@ -@node More on certificate authentication -@chapter More on certificate authentication +@node Certificate authentication +@chapter Certificate authentication @cindex certificate authentication @menu +* Introduction:: * X.509 certificates:: * OpenPGP certificates:: -* The certtool application:: -* Hardware tokens:: -* Abstract key types:: * Digital signatures:: @end menu +@node Introduction +@section 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 +@acronym{X.509} 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. -@showfuncB{gnutls_x509_trust_list_init,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. -@node Certificate requests -@subsection @acronym{PKCS} #10 certificate requests -@cindex certificate requests -@cindex PKCS #10 - -A certificate request is a structure, which contain information about -an applicant of a certificate service. It usually contains a private -key, a distinguished name and secondary data such as a challenge -password. @acronym{GnuTLS} supports the requests defined in -@acronym{PKCS} #10 @xcite{RFC2986}. Other formats of certificate requests -are not currently supported. - -@showfuncB{gnutls_x509_crq_init,gnutls_x509_crq_deinit} - -@showfuncdesc{gnutls_x509_crq_import} - -@showfuncdesc{gnutls_x509_crq_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. - -@showfuncdesc{gnutls_x509_crq_set_version} -@showfuncdesc{gnutls_x509_crq_set_dn_by_oid} -@showfuncdesc{gnutls_x509_crq_set_key_usage} -@showfuncdesc{gnutls_x509_crq_set_key_purpose_oid} -@showfuncdesc{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}. - -@showfuncdesc{gnutls_x509_crq_set_key} -@showfuncdesc{gnutls_x509_crq_sign2} - -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. - -@anchor{ex:crq} -@verbatiminclude examples/ex-crq.c - -@node Certificate revocation lists -@subsection Certificate revocation lists -@cindex certificate revocation lists -@cindex 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. - -@showfuncB{gnutls_x509_crl_init,gnutls_x509_crl_deinit} -@showfuncB{gnutls_x509_crl_import,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. - -@float Table,tab:crl -@multitable @columnfractions .2 .7 - -@headitem Field @tab Description - -@item version @tab -The field that indicates the version of the CRL structure. - -@item signature @tab -A signature by the issuing authority. - -@item issuer @tab -Holds the issuer's distinguished name. - -@item thisUpdate @tab -The issuing time of the revocation list. - -@item nextUpdate @tab -The issuing time of the revocation list that will update that one. - -@item revokedCertificates @tab -List of revoked certificates serial numbers. - -@item extensions @tab -Optional CRL structure extensions. - -@end multitable -@caption{Certificate revocation list fields.} -@end float - - -@showfuncdesc{gnutls_x509_crl_set_version} -@showfuncdesc{gnutls_x509_crl_set_crt_serial} - -@showfuncC{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. - -@showfuncdesc{gnutls_x509_crl_sign2} -@showfuncdesc{gnutls_x509_crl_privkey_sign} - -Few extensions on the CRL structure are supported, including the -CRL number extension and the authority key identifier. - -@showfuncB{gnutls_x509_crl_set_number,gnutls_x509_crl_set_authority_key_id} - -@node PKCS 12 structures -@subsection @acronym{PKCS} #12 structures -@cindex 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. - -@showfuncB{gnutls_pkcs12_init,gnutls_pkcs12_deinit} - -The following functions are available to read a @acronym{PKCS} #12 -structure. - -@showfuncdesc{gnutls_pkcs12_import} -@showfuncdesc{gnutls_pkcs12_get_bag} -@showfuncdesc{gnutls_pkcs12_verify_mac} -@showfuncdesc{gnutls_pkcs12_bag_decrypt} - -@showfuncF{gnutls_pkcs12_bag_init,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. - -@showfuncdesc{gnutls_pkcs12_set_bag} -@showfuncdesc{gnutls_pkcs12_bag_encrypt} -@showfuncdesc{gnutls_pkcs12_generate_mac} -@showfuncdesc{gnutls_pkcs12_export} -@showfuncE{gnutls_pkcs12_bag_set_data,gnutls_pkcs12_bag_set_crl,gnutls_pkcs12_bag_set_crt,gnutls_pkcs12_bag_set_key_id,gnutls_pkcs12_bag_set_friendly_name} - -@verbatiminclude 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} -@node The certtool application -@section The certtool application -@cindex certtool - -This is a program to generate @acronym{X.509} certificates, certificate -requests, CRLs and private keys. - -@example -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 -@end 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. - -@subsection Diffie-Hellman parameter generation -To generate parameters for Diffie-Hellman key exchange, use the command: -@smallexample -$ certtool --generate-dh-params --outfile dh.pem -@end smallexample - -@subsection Self-signed certificate generation - -To create a self signed certificate, use the command: -@smallexample -$ certtool --generate-privkey --outfile ca-key.pem -$ certtool --generate-self-signed --load-privkey ca-key.pem \ - --outfile ca-cert.pem -@end smallexample - -Note that a self-signed certificate usually belongs to a certificate -authority, that signs other certificates. - -@subsection Private key generation -To create a private key (RSA by default), run: - -@smallexample -$ certtool --generate-privkey --outfile key.pem -@end smallexample - -To create a DSA or elliptic curves (ECDSA) private key use the -above command combined with @code{--dsa} or @code{--ecc} options. - -@subsection Certificate generation -To generate a certificate using the private key, use the command: - -@smallexample -$ certtool --generate-certificate --load-privkey key.pem \ - --outfile cert.pem --load-ca-certificate ca-cert.pem \ - --load-ca-privkey ca-key.pem -@end smallexample - -Alternatively you may create a certificate request, which is needed -when the certificate will be signed by a third party authority. - -@smallexample -$ certtool --generate-request --load-privkey key.pem \ - --outfile request.pem -@end 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). - -@smallexample -$ certtool --generate-request --load-privkey pkcs11:(PRIVKEY URL) \ - --load-pubkey pkcs11:(PUBKEY URL) --outfile request.pem -@end smallexample - -To generate a certificate using the previous request, use the command: - -@smallexample -$ certtool --generate-certificate --load-request request.pem \ - --outfile cert.pem \ - --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem -@end smallexample - -@subsection Certificate information -To view the certificate information, use: - -@smallexample -$ certtool --certificate-info --infile cert.pem -@end smallexample - -@subsection @acronym{PKCS} #12 structure generation -To generate a @acronym{PKCS} #12 structure using the previous key and -certificate, use the command: - -@smallexample -$ certtool --load-certificate cert.pem --load-privkey key.pem \ - --to-p12 --outder --outfile key.p12 -@end 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: - -@smallexample -$ certtool --load-ca-certificate ca.pem \ - --load-certificate cert.pem --load-privkey key.pem \ - --to-p12 --outder --outfile key.p12 -@end smallexample - -@subsection 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: - -@smallexample -$ certtool --generate-privkey > proxy-key.pem -$ certtool --generate-proxy --load-ca-privkey key.pem \ - --load-privkey proxy-key.pem --load-certificate cert.pem \ - --outfile proxy-cert.pem -@end smallexample - -@subsection Certificate revocation list generation -To create an empty Certificate Revocation List (CRL) do: - -@smallexample -$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \ - --load-ca-certificate x509-ca.pem -@end smallexample - -To create a CRL that contains some revoked certificates, place the -certificates in a file and use @code{--load-certificate} as follows: - -@smallexample -$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \ - --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem -@end smallexample - -To verify a Certificate Revocation List (CRL) do: - -@smallexample -$ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem -@end smallexample - - - -@subsection 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: - -@smallexample -$ certtool --generate-certificate cert.pem --load-privkey key.pem \ - --template cert.cfg \ - --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem -@end smallexample - -An example certtool template file: - -@example -# X.509 Certificate options -# -# DN options - -# The organization of the subject. -organization = "Koko inc." - -# The organizational unit of the subject. -unit = "sleeping dept." - -# The locality of the subject. -# locality = - -# The state of the certificate owner. -state = "Attiki" - -# The country of the subject. Two letter code. -country = GR - -# The common name of the certificate owner. -cn = "Cindy Lauper" - -# A user id of the certificate owner. -#uid = "clauper" - -# If the supported DN OIDs are not adequate you can set -# any OID here. -# For example set the X.520 Title and the X.520 Pseudonym -# by using OID and string pairs. -#dn_oid = "2.5.4.12" "Dr." "2.5.4.65" "jackal" - -# This is deprecated and should not be used in new -# certificates. -# pkcs9_email = "none@@none.org" - -# The serial number of the certificate -serial = 007 - -# In how many days, counting from today, this certificate will expire. -expiration_days = 700 - -# X.509 v3 extensions - -# A dnsname in case of a WWW server. -#dns_name = "www.none.org" -#dns_name = "www.morethanone.org" - -# An IP address in case of a server. -#ip_address = "192.168.1.1" - -# An email in case of a person -email = "none@@none.org" - -# An URL that has CRLs (certificate revocation lists) -# available. Needed in CA certificates. -#crl_dist_points = "http://www.getcrl.crl/getcrl/" - -# Whether this is a CA certificate or not -#ca - -# Whether this certificate will be used for a TLS client -#tls_www_client - -# Whether this certificate will be used for a TLS server -#tls_www_server - -# Whether this certificate will be used to sign data (needed -# in TLS DHE ciphersuites). -signing_key - -# Whether this certificate will be used to encrypt data (needed -# in TLS RSA ciphersuites). Note that it is preferred to use different -# keys for encryption and signing. -#encryption_key - -# Whether this key will be used to sign other certificates. -#cert_signing_key - -# Whether this key will be used to sign CRLs. -#crl_signing_key - -# Whether this key will be used to sign code. -#code_signing_key - -# Whether this key will be used to sign OCSP data. -#ocsp_signing_key - -# Whether this key will be used for time stamping. -#time_stamping_key - -# Whether this key will be used for IPsec IKE operations. -#ipsec_ike_key -@end example - - - -@node Hardware tokens -@section Hardware tokens -@cindex PKCS #11 tokens -@cindex hardware tokens -@cindex smart cards - -@menu -* Introduction:: -* PKCS11 Initialization:: -* Reading objects:: -* Writing objects:: -* Using a PKCS11 token with TLS:: -* The p11tool application:: -@end menu - -@node Introduction -@subsection Introduction -This section copes with hardware token support in @acronym{GnuTLS} using -@acronym{PKCS} #11 @xcite{PKCS11}. -@acronym{PKCS} #11 is plugin API allowing applications to access cryptographic -operations on a token, as well as to objects residing on the token. A token can -be a real hardware token such as a smart card 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 -Opensc@footnote{@url{http://www.opensc-project.org}} project, and a -module to access the TPM chip on a PC is available from the Trousers@footnote{@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}. - -@float Figure,fig:pkcs11-vision -@image{pkcs11-vision,9cm} -@caption{PKCS #11 module usage.} -@end float - -@node PKCS11 Initialization -@subsection 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 @acronym{p11-kit}@footnote{@url{http://p11-glue.freedesktop.org/}}. -For example a file that will load the @acronym{OpenSC} module, could be named -@code{/etc/pkcs11/modules/opensc} and contain the following: - -@smallexample -module: /usr/lib/opensc-pkcs11.so -@end smallexample - -If you use this file, then there is no need for other initialization in -@acronym{GnuTLS}, 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. - -@showfuncdesc{gnutls_pkcs11_init} -@showfuncA{gnutls_pkcs11_deinit} - -@showfuncdesc{gnutls_pkcs11_set_token_function} -@showfuncdesc{gnutls_pkcs11_set_pin_function} -@showfuncdesc{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. - -@node Reading objects -@subsection 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: - -@smallexample -pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315; \ -manufacturer=EnterSafe;object=test1;objecttype=public;\ -id=32f153f3e37990b08624141077ca5dec2d15faed -@end smallexample - -while the smart card itself can be referenced as: -@smallexample -pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315;manufacturer=EnterSafe -@end 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. - -@showfuncB{gnutls_pkcs11_obj_init,gnutls_pkcs11_obj_deinit} - -@showfuncdesc{gnutls_pkcs11_obj_import_url} - -@showfuncdesc{gnutls_pkcs11_obj_export_url} - -@showfuncdesc{gnutls_pkcs11_obj_export} - -@showfuncdesc{gnutls_pkcs11_obj_get_info} - -@showfuncdesc{gnutls_pkcs11_obj_list_import_url} - -@showfuncC{gnutls_x509_crt_import_pkcs11,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. - -@showfuncD{gnutls_pkcs11_token_init,gnutls_pkcs11_token_get_url,gnutls_pkcs11_token_get_info,gnutls_pkcs11_token_get_flags} -@showfuncdesc{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. - -@example -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(); -@end example - -@verbatiminclude examples/ex-pkcs11-list.c - -@node Writing objects -@subsection 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 @code{GNUTLS_@-PKCS11_OBJ_@-FLAG_@-MARK_@-SENSITIVE} -to prevent its extraction. An object can be marked as private using the flag -@code{GNUTLS_@-PKCS11_OBJ_@-FLAG_@-MARK_@-PRIVATE}, to require PIN to be -entered before accessing the object (for operations or otherwise). - -@showfuncdesc{gnutls_pkcs11_copy_x509_privkey} - -@showfuncdesc{gnutls_pkcs11_copy_x509_crt} -@showfuncdesc{gnutls_pkcs11_delete_url} - - -@node Using a PKCS11 token with TLS -@subsection 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. - -@showfuncB{gnutls_certificate_set_x509_trust_file,gnutls_certificate_set_x509_key_file} - -@node The p11tool application -@subsection The p11tool application -@anchor{p11tool} -@cindex 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 -@code{--provider} option, or by setting up the GnuTLS configuration -file for PKCS #11 as in @ref{Hardware tokens}. - -@example -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 -@end 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. - -@subsubsection List all tokens -@smallexample -$ p11tool --list-tokens -@end smallexample - -@subsubsection List all objects -The following command will list all objects in a token. The @code{--login} -is required to show objects marked as private. -@smallexample -$ p11tool --login --list-all -@end smallexample - -@subsubsection 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. -@smallexample -$ p11tool --login --export [OBJECT URL] -@end smallexample - -@subsubsection Copy an object to a token -To copy an object, such as a certificate or private key to a token -use the following command. -@smallexample -$ p11tool --login --write [TOKEN URL] \ - --load-certificate cert.pem --label "my_cert" -@end smallexample - - - -@node Abstract key types -@section Abstract key types -@cindex abstract types - -Since there are many forms of a public or private keys supported by @acronym{GnuTLS} such as -@acronym{X.509}, @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. - -@example -#inlude <gnutls/abstract.h> -#inlude <gnutls/pkcs11.h> - -void sign_cert( gnutls_x509_crt_t to_be_signed) -@{ -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); -@} -@end example - -@subsection 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. - -@showfuncB{gnutls_pubkey_init,gnutls_pubkey_deinit} - -@showfuncdesc{gnutls_pubkey_import_x509} - -@showfuncdesc{gnutls_pubkey_import_openpgp} -@showfuncdesc{gnutls_pubkey_import_pkcs11} -@showfuncdesc{gnutls_pubkey_import_pkcs11_url} -@showfuncdesc{gnutls_pubkey_import_privkey} -@showfuncdesc{gnutls_pubkey_import} -@showfuncdesc{gnutls_pubkey_export} - -Additional functions are available that will return -information over a public key. - -@showfuncdesc{gnutls_pubkey_get_pk_algorithm} - -@showfuncdesc{gnutls_pubkey_get_preferred_hash_algorithm} -@showfuncdesc{gnutls_pubkey_get_key_id} - -@subsection 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. - -@showfuncB{gnutls_privkey_init,gnutls_privkey_deinit} - -@showfuncdesc{gnutls_privkey_import_x509} - -@showfuncC{gnutls_privkey_import_openpgp,gnutls_privkey_import_pkcs11,gnutls_privkey_import_ext} -@showfuncdesc{gnutls_privkey_get_pk_algorithm} -@showfuncdesc{gnutls_privkey_get_type} - -@subsection Operations -The abstract key types can be used to access signing and -signature verification operations with the underlying keys. - -@showfuncdesc{gnutls_pubkey_verify_data2} -@showfuncdesc{gnutls_pubkey_verify_hash} -@showfuncdesc{gnutls_privkey_sign_data} -@showfuncdesc{gnutls_privkey_sign_hash} - -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. -@showfuncdesc{gnutls_x509_crq_set_pubkey} -@showfuncdesc{gnutls_x509_crt_set_pubkey} -@showfuncC{gnutls_x509_crt_privkey_sign,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 0000000000..93a771a478 --- /dev/null +++ b/doc/cha-cert-auth2.texi @@ -0,0 +1,823 @@ +@node More on certificate authentication +@chapter More on certificate authentication +@cindex certificate authentication + +@menu +* PKCS 10 certificate requests:: +* PKIX certificate revocation lists:: +* PKCS 12 structures:: +* The certtool application:: +* Hardware tokens:: +* Abstract key types:: +@end menu + +@node PKCS 10 certificate requests +@section @acronym{PKCS} #10 certificate requests +@cindex certificate requests +@cindex PKCS #10 + +A certificate request is a structure, which contain information about +an applicant of a certificate service. It usually contains a private +key, a distinguished name and secondary data such as a challenge +password. @acronym{GnuTLS} supports the requests defined in +@acronym{PKCS} #10 @xcite{RFC2986}. Other 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. + +@showfuncE{gnutls_x509_crq_set_version,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}. + +@showfuncdesc{gnutls_x509_crq_set_key} +@showfuncdesc{gnutls_x509_crq_sign2} + +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. + +@anchor{ex:crq} +@verbatiminclude examples/ex-crq.c + +@node PKIX certificate revocation lists +@section PKIX certificate revocation lists +@cindex certificate revocation lists +@cindex 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. + +@float Table,tab:crl +@multitable @columnfractions .2 .7 + +@headitem Field @tab Description + +@item version @tab +The field that indicates the version of the CRL structure. + +@item signature @tab +A signature by the issuing authority. + +@item issuer @tab +Holds the issuer's distinguished name. + +@item thisUpdate @tab +The issuing time of the revocation list. + +@item nextUpdate @tab +The issuing time of the revocation list that will update that one. + +@item revokedCertificates @tab +List of revoked certificates serial numbers. + +@item extensions @tab +Optional CRL structure extensions. + +@end multitable +@caption{Certificate revocation list fields.} +@end float + + +@showfuncE{gnutls_x509_crl_set_version,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. + +@showfuncdesc{gnutls_x509_crl_sign2} +@showfuncdesc{gnutls_x509_crl_privkey_sign} + +Few extensions on the CRL structure are supported, including the +CRL number extension and the authority key identifier. + +@showfuncB{gnutls_x509_crl_set_number,gnutls_x509_crl_set_authority_key_id} + +@node PKCS 12 structures +@section @acronym{PKCS} #12 structures +@cindex 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. + +@showfuncC{gnutls_pkcs12_get_bag,gnutls_pkcs12_verify_mac,gnutls_pkcs12_bag_decrypt} + +@showfuncD{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. + +@showfuncC{gnutls_pkcs12_set_bag,gnutls_pkcs12_bag_encrypt,gnutls_pkcs12_generate_mac} +@showfuncE{gnutls_pkcs12_bag_set_data,gnutls_pkcs12_bag_set_crl,gnutls_pkcs12_bag_set_crt,gnutls_pkcs12_bag_set_key_id,gnutls_pkcs12_bag_set_friendly_name} + +@verbatiminclude examples/ex-pkcs12.c + +@node The certtool application +@section The certtool application +@cindex certtool + +This is a program to generate @acronym{X.509} certificates, certificate +requests, CRLs and private keys. + +@example +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 +@end 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. + +@subsection Diffie-Hellman parameter generation +To generate parameters for Diffie-Hellman key exchange, use the command: +@smallexample +$ certtool --generate-dh-params --outfile dh.pem +@end smallexample + +@subsection Self-signed certificate generation + +To create a self signed certificate, use the command: +@smallexample +$ certtool --generate-privkey --outfile ca-key.pem +$ certtool --generate-self-signed --load-privkey ca-key.pem \ + --outfile ca-cert.pem +@end smallexample + +Note that a self-signed certificate usually belongs to a certificate +authority, that signs other certificates. + +@subsection Private key generation +To create a private key (RSA by default), run: + +@smallexample +$ certtool --generate-privkey --outfile key.pem +@end smallexample + +To create a DSA or elliptic curves (ECDSA) private key use the +above command combined with @code{--dsa} or @code{--ecc} options. + +@subsection Certificate generation +To generate a certificate using the private key, use the command: + +@smallexample +$ certtool --generate-certificate --load-privkey key.pem \ + --outfile cert.pem --load-ca-certificate ca-cert.pem \ + --load-ca-privkey ca-key.pem +@end smallexample + +Alternatively you may create a certificate request, which is needed +when the certificate will be signed by a third party authority. + +@smallexample +$ certtool --generate-request --load-privkey key.pem \ + --outfile request.pem +@end 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). + +@smallexample +$ certtool --generate-request --load-privkey pkcs11:(PRIVKEY URL) \ + --load-pubkey pkcs11:(PUBKEY URL) --outfile request.pem +@end smallexample + +To generate a certificate using the previous request, use the command: + +@smallexample +$ certtool --generate-certificate --load-request request.pem \ + --outfile cert.pem \ + --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem +@end smallexample + +@subsection Certificate information +To view the certificate information, use: + +@smallexample +$ certtool --certificate-info --infile cert.pem +@end smallexample + +@subsection @acronym{PKCS} #12 structure generation +To generate a @acronym{PKCS} #12 structure using the previous key and +certificate, use the command: + +@smallexample +$ certtool --load-certificate cert.pem --load-privkey key.pem \ + --to-p12 --outder --outfile key.p12 +@end 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: + +@smallexample +$ certtool --load-ca-certificate ca.pem \ + --load-certificate cert.pem --load-privkey key.pem \ + --to-p12 --outder --outfile key.p12 +@end smallexample + +@subsection 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: + +@smallexample +$ certtool --generate-privkey > proxy-key.pem +$ certtool --generate-proxy --load-ca-privkey key.pem \ + --load-privkey proxy-key.pem --load-certificate cert.pem \ + --outfile proxy-cert.pem +@end smallexample + +@subsection Certificate revocation list generation +To create an empty Certificate Revocation List (CRL) do: + +@smallexample +$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \ + --load-ca-certificate x509-ca.pem +@end smallexample + +To create a CRL that contains some revoked certificates, place the +certificates in a file and use @code{--load-certificate} as follows: + +@smallexample +$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \ + --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem +@end smallexample + +To verify a Certificate Revocation List (CRL) do: + +@smallexample +$ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem +@end smallexample + + + +@subsection 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: + +@smallexample +$ certtool --generate-certificate cert.pem --load-privkey key.pem \ + --template cert.cfg \ + --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem +@end smallexample + +An example certtool template file: + +@example +# X.509 Certificate options +# +# DN options + +# The organization of the subject. +organization = "Koko inc." + +# The organizational unit of the subject. +unit = "sleeping dept." + +# The locality of the subject. +# locality = + +# The state of the certificate owner. +state = "Attiki" + +# The country of the subject. Two letter code. +country = GR + +# The common name of the certificate owner. +cn = "Cindy Lauper" + +# A user id of the certificate owner. +#uid = "clauper" + +# If the supported DN OIDs are not adequate you can set +# any OID here. +# For example set the X.520 Title and the X.520 Pseudonym +# by using OID and string pairs. +#dn_oid = "2.5.4.12" "Dr." "2.5.4.65" "jackal" + +# This is deprecated and should not be used in new +# certificates. +# pkcs9_email = "none@@none.org" + +# The serial number of the certificate +serial = 007 + +# In how many days, counting from today, this certificate will expire. +expiration_days = 700 + +# X.509 v3 extensions + +# A dnsname in case of a WWW server. +#dns_name = "www.none.org" +#dns_name = "www.morethanone.org" + +# An IP address in case of a server. +#ip_address = "192.168.1.1" + +# An email in case of a person +email = "none@@none.org" + +# An URL that has CRLs (certificate revocation lists) +# available. Needed in CA certificates. +#crl_dist_points = "http://www.getcrl.crl/getcrl/" + +# Whether this is a CA certificate or not +#ca + +# Whether this certificate will be used for a TLS client +#tls_www_client + +# Whether this certificate will be used for a TLS server +#tls_www_server + +# Whether this certificate will be used to sign data (needed +# in TLS DHE ciphersuites). +signing_key + +# Whether this certificate will be used to encrypt data (needed +# in TLS RSA ciphersuites). Note that it is preferred to use different +# keys for encryption and signing. +#encryption_key + +# Whether this key will be used to sign other certificates. +#cert_signing_key + +# Whether this key will be used to sign CRLs. +#crl_signing_key + +# Whether this key will be used to sign code. +#code_signing_key + +# Whether this key will be used to sign OCSP data. +#ocsp_signing_key + +# Whether this key will be used for time stamping. +#time_stamping_key + +# Whether this key will be used for IPsec IKE operations. +#ipsec_ike_key +@end example + + +@node Hardware tokens +@section Hardware tokens +@cindex PKCS #11 tokens +@cindex hardware tokens +@cindex smart cards + +@menu +* Introduction on hardware tokens:: +* PKCS11 Initialization:: +* Reading objects:: +* Writing objects:: +* Using a PKCS11 token with TLS:: +* The p11tool application:: +@end menu + +@node Introduction on hardware tokens +@subsection Introduction +This section copes with hardware token support in @acronym{GnuTLS} using +@acronym{PKCS} #11 @xcite{PKCS11}. +@acronym{PKCS} #11 is plugin API allowing applications to access cryptographic +operations on a token, as well as to objects residing on the token. A token can +be a real hardware token such as a smart card 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 +Opensc@footnote{@url{http://www.opensc-project.org}} project, and a +module to access the TPM chip on a PC is available from the Trousers@footnote{@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}. + +@float Figure,fig:pkcs11-vision +@image{pkcs11-vision,9cm} +@caption{PKCS #11 module usage.} +@end float + +@node PKCS11 Initialization +@subsection 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 @acronym{p11-kit}@footnote{@url{http://p11-glue.freedesktop.org/}}. +For example a file that will load the @acronym{OpenSC} module, could be named +@code{/etc/pkcs11/modules/opensc} and contain the following: + +@smallexample +module: /usr/lib/opensc-pkcs11.so +@end smallexample + +If you use this file, then there is no need for other initialization in +@acronym{GnuTLS}, 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. + +@showfuncdesc{gnutls_pkcs11_init} +@showfuncC{gnutls_pkcs11_set_token_function,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. + +@node Reading objects +@subsection 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: + +@smallexample +pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315; \ +manufacturer=EnterSafe;object=test1;objecttype=public;\ +id=32f153f3e37990b08624141077ca5dec2d15faed +@end smallexample + +while the smart card itself can be referenced as: +@smallexample +pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315;manufacturer=EnterSafe +@end 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. + +@showfuncB{gnutls_pkcs11_obj_import_url,gnutls_pkcs11_obj_export_url} + +@showfuncdesc{gnutls_pkcs11_obj_get_info} + +@showfuncC{gnutls_x509_crt_import_pkcs11,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. + +@showfuncE{gnutls_pkcs11_token_init,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. + +@example +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(); +@end example + +@verbatiminclude examples/ex-pkcs11-list.c + +@node Writing objects +@subsection 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 @code{GNUTLS_@-PKCS11_OBJ_@-FLAG_@-MARK_@-SENSITIVE} +to prevent its extraction. An object can be marked as private using the flag +@code{GNUTLS_@-PKCS11_OBJ_@-FLAG_@-MARK_@-PRIVATE}, to require PIN to be +entered before accessing the object (for operations or otherwise). + +@showfuncdesc{gnutls_pkcs11_copy_x509_privkey} + +@showfuncdesc{gnutls_pkcs11_copy_x509_crt} +@showfuncdesc{gnutls_pkcs11_delete_url} + + +@node Using a PKCS11 token with TLS +@subsection 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. + +@showfuncB{gnutls_certificate_set_x509_trust_file,gnutls_certificate_set_x509_key_file} + +@node The p11tool application +@subsection The p11tool application +@anchor{p11tool} +@cindex 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 +@code{--provider} option, or by setting up the GnuTLS configuration +file for PKCS #11 as in @ref{Hardware tokens}. + +@example +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 +@end 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. + +@subsubsection List all tokens +@smallexample +$ p11tool --list-tokens +@end smallexample + +@subsubsection List all objects +The following command will list all objects in a token. The @code{--login} +is required to show objects marked as private. +@smallexample +$ p11tool --login --list-all +@end smallexample + +@subsubsection 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. +@smallexample +$ p11tool --login --export [OBJECT URL] +@end smallexample + +@subsubsection Copy an object to a token +To copy an object, such as a certificate or private key to a token +use the following command. +@smallexample +$ p11tool --login --write [TOKEN URL] \ + --load-certificate cert.pem --label "my_cert" +@end smallexample + + +@node Abstract key types +@section Abstract key types +@cindex abstract types + +Since there are many forms of a public or private keys supported by @acronym{GnuTLS} such as +@acronym{X.509}, @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. + +@example +#inlude <gnutls/abstract.h> +#inlude <gnutls/pkcs11.h> + +void sign_cert( gnutls_x509_crt_t to_be_signed) +@{ +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); +@} +@end example + +@subsection 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. + +@showfuncdesc{gnutls_pubkey_import_x509} +@showfuncD{gnutls_pubkey_import_openpgp,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. + +@showfuncC{gnutls_pubkey_get_pk_algorithm,gnutls_pubkey_get_preferred_hash_algorithm,gnutls_pubkey_get_key_id} + +@subsection 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. + +@showfuncD{gnutls_privkey_import_x509,gnutls_privkey_import_openpgp,gnutls_privkey_import_pkcs11,gnutls_privkey_import_ext} +@showfuncB{gnutls_privkey_get_pk_algorithm,gnutls_privkey_get_type} + +@subsection Operations +The abstract key types can be used to access signing and +signature verification operations with the underlying keys. + +@showfuncdesc{gnutls_pubkey_verify_data2} +@showfuncdesc{gnutls_pubkey_verify_hash} +@showfuncdesc{gnutls_privkey_sign_data} +@showfuncdesc{gnutls_privkey_sign_hash} + +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. + +@showfuncdesc{gnutls_x509_crq_set_pubkey} +@showfuncdesc{gnutls_x509_crt_set_pubkey} +@showfuncC{gnutls_x509_crt_privkey_sign,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 a8b8dcc467..d9cba2577b 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 -@anchor{examples} -@cindex example programs -@cindex 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 +@node Introduction to the library +@section Introduction + +@menu +* General idea:: +* Error handling:: +* Debugging and auditing:: +* Thread safety:: +* Callback functions:: +@end menu + +@node General idea +@subsection 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}. + +@float Figure,fig:gnutls-design +@image{gnutls-internals,12cm} +@caption{High level design of GnuTLS.} +@end 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 +@acronym{GnuTLS} 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 hello@footnote{The first message in a @acronym{TLS} handshake}, +and if the session ID sent by the client, matches a stored session, +the stored session will be retrieved, and the new session will be a +resumed one, and will share the same session ID with the previous one. + +@node Error handling +@subsection 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 +@code{GNUTLS_@-E_@-DECRYPTION_@-FAILED}. Non-fatal errors may warn about +something, i.e., a warning alert was received, or indicate the some +action has to be taken. This is the case with the error code +@code{GNUTLS_@-E_@-REHANDSHAKE} returned by @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 +@funcref{gnutls_error_is_fatal}. + +If any non fatal errors, that require an action, are to be returned by +a function, these error codes will be documented in the function's +reference. See @ref{Error codes}, for a description of the available +error codes. + +@node Debugging and auditing +@subsection 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 +@funcref{gnutls_global_set_log_function} are to be used. Those will print +verbose information on the @acronym{GnuTLS} functions internal flow. + +@showfuncB{gnutls_global_set_log_level,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 +@funcref{gnutls_global_set_audit_log_function}. 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. + +@showfuncdesc{gnutls_global_set_audit_log_function} + +@node Thread safety +@subsection Thread safety +@cindex 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 +@code{CriticalSection} 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. + +@example +#include <gnutls.h> + +/* Other thread packages + */ + +int main() +@{ + gnutls_global_set_mutex (mutex_init, mutex_deinit, + mutex_lock, mutex_unlock); + gnutls_global_init(); +@} +@end example + +@showfuncdesc{gnutls_global_set_mutex} + +@node Callback functions +@subsection Callback functions +@cindex 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. + +@showfuncB{gnutls_transport_set_push_function,gnutls_transport_set_pull_function} + +Other callback functions may require more complicated input and data +to be allocated. Such an example is +@funcref{gnutls_srp_set_server_credentials_function}. +All callbacks should allocate and free memory using the functions shown below. + +@showfuncB{gnutls_malloc,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 -@node TLS and DTLS sessions -@section TLS and DTLS sessions -@subsection Session initialization +@node Session initialization +@section 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}. + +@showfuncdesc{gnutls_credentials_set} + +@subsection Associating the credentials +@subsubsection 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. + +@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. + +@showfuncC{gnutls_certificate_set_x509_key_mem,gnutls_certificate_set_x509_key,gnutls_certificate_set_x509_key_file} + +@showfuncD{gnutls_certificate_set_openpgp_key_mem,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 +@funcref{gnutls_sign_algorithm_get_requested}. Both functions are shown below. + +@showfuncB{gnutls_certificate_set_retrieve_function,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}). + +@subsubsection SRP -@subsection 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. + +@showfuncE{gnutls_srp_allocate_server_credentials,gnutls_srp_allocate_client_credentials,gnutls_srp_free_server_credentials,gnutls_srp_free_client_credentials,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} + + +@subsubsection PSK +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} + +@subsubsection Anonymous +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} + +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. + + +@node Setting up the transport layer +@section 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} +@subsection Asynchronous operation +@acronym{GnuTLS} 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). -@subsection Handshake +The @funcintref{select} system call can also be used in combination with the +@acronym{GnuTLS} 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 +@funcref{gnutls_record_recv}. @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 +@code{GNUTLS_NONBLOCK} flag (see @ref{Session initialization}). + +@subsection 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 cookie@footnote{A 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. + +@showfuncD{gnutls_key_generate,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}. + +@showfuncC{gnutls_dtls_set_mtu,gnutls_dtls_get_mtu,gnutls_dtls_get_data_mtu} + + +@node TLS handshake +@section 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} - -@subsection Data transfer and termination +@node Data transfer and termination +@section 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} +@showfuncA{gnutls_record_get_direction} 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} -@subsection Asynchronous operation -@acronym{GnuTLS} 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 -@acronym{GnuTLS} 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 -@funcref{gnutls_record_recv}. @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 -@code{GNUTLS_NONBLOCK} flag (see @ref{TLS and DTLS sessions}). - -@subsection 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 cookie@footnote{A 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. - -@showfuncD{gnutls_key_generate,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}. - -@showfuncC{gnutls_dtls_set_mtu,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. -@showfuncD{gnutls_priority_set_direct,gnutls_priority_init,gnutls_priority_deinit,gnutls_priority_set} +@showfuncB{gnutls_priority_set_direct,gnutls_priority_set} @float Table,tab:prio-keywords @multitable @columnfractions .20 .70 @@ -469,215 +781,6 @@ will allow V1 CAs in chains. @end float -@node Client examples -@section Client examples - -This section contains examples of @acronym{TLS} and @acronym{SSL} -clients, using @acronym{GnuTLS}. Note that these examples contain -little or no error checking. Some of the examples require functions -implemented by another example. - -@menu -* Simple client example with anonymous authentication:: -* Simple client example with X.509 certificate support:: -* 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:: -@end menu - -@node Simple client example with anonymous authentication -@subsection Simple client example with anonymous authentication - -The simplest client using TLS is the one that doesn't do any -authentication. This means no external certificates or passwords are -needed to set up the connection. As could be expected, the connection -is vulnerable to man-in-the-middle (active or redirection) attacks. -However, the data is integrity and privacy protected. - -@verbatiminclude examples/ex-client1.c - -@node Simple client example with X.509 certificate support -@subsection Simple client example with @acronym{X.509} certificate support -@anchor{ex:verify} - -Let's assume now that we want to create a TCP client which -communicates with servers that use @acronym{X.509} or -@acronym{OpenPGP} certificate authentication. The following client is -a very simple @acronym{TLS} client, 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. - -@verbatiminclude examples/ex-rfc2818.c - -@node Simple Datagram TLS client example -@subsection Simple datagram @acronym{TLS} client example - -This is a client that uses @acronym{UDP} to connect to a -server. This is the @acronym{DTLS} equivalent to the example -in @ref{Simple client example with X.509 certificate support}. - -@verbatiminclude examples/ex-client-udp.c - -@node Obtaining session information -@subsection Obtaining session information - -Most of the times it is desirable to know the security properties of -the current established session. This includes the underlying ciphers -and the protocols involved. That is the purpose of the following -function. Note that this function will print meaningful values only -if called after a successful @funcref{gnutls_handshake}. - -@verbatiminclude examples/ex-session-info.c - -@node Using a callback to select the certificate to use -@subsection Using a callback to select the certificate to use - -There are cases where a client holds several certificate and key -pairs, and may not want to load all of them in the credentials -structure. The following example demonstrates the use of the -certificate selection callback. - -@verbatiminclude examples/ex-cert-select.c - -@node Verifying a certificate -@subsection Verifying a certificate -@anchor{ex:verify2} - -An example is listed below which uses the high level verification -functions to verify a given certificate list. - -@verbatiminclude examples/ex-verify.c - -@node Client using a PKCS 11 token with TLS -@subsection Using a @acronym{PKCS} #11 token with TLS -@anchor{ex: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. - -@verbatiminclude examples/ex-cert-select-pkcs11.c - - -@node Client with Resume capability example -@subsection Client with resume capability example -@anchor{ex:resume-client} - -This is a modification of the simple client example. Here we -demonstrate the use of session resumption. The client tries to connect -once using @acronym{TLS}, close the connection and then try to -establish a new connection using the previously negotiated data. - -@verbatiminclude examples/ex-client-resume.c - - -@node Simple client example with SRP authentication -@subsection Simple client example with @acronym{SRP} authentication - -The following client is a very simple @acronym{SRP} @acronym{TLS} -client which connects to a server and authenticates using a -@emph{username} and a @emph{password}. The server may authenticate -itself using a certificate, and in that case it has to be verified. - -@verbatiminclude examples/ex-client-srp.c - -@node Simple client example in C++ -@subsection Simple client example using the C++ API - -The following client is a simple example of a client client utilizing -the GnuTLS C++ API. - -@verbatiminclude examples/ex-cxx.cpp - -@node Helper function for TCP connections -@subsection Helper function for TCP connections - -This helper function abstracts away TCP connection handling from the -other examples. It is required to build some examples. - -@verbatiminclude examples/tcp.c - -@node Server examples -@section Server examples - -This section contains examples of @acronym{TLS} and @acronym{SSL} -servers, using @acronym{GnuTLS}. - -@menu -* Echo Server with X.509 authentication:: -* Echo Server with OpenPGP authentication:: -* Echo Server with SRP authentication:: -* Echo Server with anonymous authentication:: -@end menu - -@node Echo Server with X.509 authentication -@subsection Echo server with @acronym{X.509} authentication - -This example is a very simple echo server which supports -@acronym{X.509} authentication, using the RSA ciphersuites. - -@verbatiminclude examples/ex-serv1.c - -@node Echo Server with OpenPGP authentication -@subsection Echo server with @acronym{OpenPGP} authentication -@cindex OpenPGP server - -The following example is an echo server which supports -@acronym{OpenPGP} key authentication. You can easily combine -this functionality ---that is have a server that supports both -@acronym{X.509} and @acronym{OpenPGP} certificates--- but we separated -them to keep these examples as simple as possible. - -@verbatiminclude examples/ex-serv-pgp.c - -@node Echo Server with SRP authentication -@subsection Echo server with @acronym{SRP} authentication - -This is a server which supports @acronym{SRP} authentication. It is -also possible to combine this functionality with a certificate -server. Here it is separate for simplicity. - -@verbatiminclude examples/ex-serv-srp.c - -@node Echo Server with anonymous authentication -@subsection Echo Server with anonymous authentication - -This example server support anonymous authentication, and could be -used to serve the example client for anonymous authentication. - -@verbatiminclude examples/ex-serv-anon.c - -@node Miscellaneous examples -@section Miscellaneous examples - -@menu -* Checking for an alert:: -* X.509 certificate parsing example:: -@end menu - -@node Checking for an alert -@subsection Checking for an alert - -This is a function that checks if an alert has been received in the -current session. - -@verbatiminclude examples/ex-alert.c - -@node X.509 certificate parsing example -@subsection @acronym{X.509} certificate parsing example -@anchor{ex:x509-info} - -To demonstrate the @acronym{X.509} parsing capabilities an example program is -listed below. That program reads the peer's certificate, and prints -information about it. - -@verbatiminclude examples/ex-x509-info.c @node 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. -@showfuncB{gnutls_dh_params_init,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. -@showfuncB{gnutls_rsa_params_init,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} + +@node Selecting cryptographic key sizes +@section Selecting cryptographic key sizes +@cindex 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. + +@float Table,tab:key-sizes +@multitable @columnfractions .10 .12 .10 .20 .32 + +@headitem Security bits @tab RSA, DH and SRP parameter size @tab ECC key size @tab Security parameter @tab Description + +@item 64 +@tab 816 +@tab 128 +@tab @code{WEAK} +@tab Very short term protection against small organizations + +@item 80 +@tab 1248 +@tab 160 +@tab @code{LOW} +@tab Very short term protection against agencies + +@item 112 +@tab 2432 +@tab 224 +@tab @code{NORMAL} +@tab Medium-term protection + +@item 128 +@tab 3248 +@tab 256 +@tab @code{HIGH} +@tab Long term protection + +@item 256 +@tab 15424 +@tab 512 +@tab @code{ULTRA} +@tab Foreseeable future + +@end multitable +@caption{Key sizes and security parameters.} +@end 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 +@math{2^{112}} 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. + +@c @showenumdesc{gnutls_sec_param_t,The @code{gnutls_sec_@-param_t} 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: + +@showfuncdesc{gnutls_sec_param_to_pk_bits} + +@showfuncdesc{gnutls_pk_bits_to_sec_param} + +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 0000000000..3f9fb6b4cb --- /dev/null +++ b/doc/cha-gtls-examples.texi @@ -0,0 +1,221 @@ +@node GnuTLS application examples +@chapter GnuTLS application examples +@anchor{examples} +@cindex example programs +@cindex examples + +@menu +* Client examples:: +* Server examples:: +* Miscellaneous examples:: +@end menu + +@node Client examples +@section Client examples + +This section contains examples of @acronym{TLS} and @acronym{SSL} +clients, using @acronym{GnuTLS}. Note that these examples contain +little or no error checking. Some of the examples require functions +implemented by another example. + +@menu +* Simple client example with anonymous authentication:: +* Simple client example with X.509 certificate support:: +* 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:: +@end menu + +@node Simple client example with anonymous authentication +@subsection Simple client example with anonymous authentication + +The simplest client using TLS is the one that doesn't do any +authentication. This means no external certificates or passwords are +needed to set up the connection. As could be expected, the connection +is vulnerable to man-in-the-middle (active or redirection) attacks. +However, the data is integrity and privacy protected. + +@verbatiminclude examples/ex-client1.c + +@node Simple client example with X.509 certificate support +@subsection Simple client example with @acronym{X.509} certificate support +@anchor{ex:verify} + +Let's assume now that we want to create a TCP client which +communicates with servers that use @acronym{X.509} or +@acronym{OpenPGP} certificate authentication. The following client is +a very simple @acronym{TLS} client, 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. + +@verbatiminclude examples/ex-rfc2818.c + +@node Simple Datagram TLS client example +@subsection Simple datagram @acronym{TLS} client example + +This is a client that uses @acronym{UDP} to connect to a +server. This is the @acronym{DTLS} equivalent to the example +in @ref{Simple client example with X.509 certificate support}. + +@verbatiminclude examples/ex-client-udp.c + +@node Obtaining session information +@subsection Obtaining session information + +Most of the times it is desirable to know the security properties of +the current established session. This includes the underlying ciphers +and the protocols involved. That is the purpose of the following +function. Note that this function will print meaningful values only +if called after a successful @funcref{gnutls_handshake}. + +@verbatiminclude examples/ex-session-info.c + +@node Using a callback to select the certificate to use +@subsection Using a callback to select the certificate to use + +There are cases where a client holds several certificate and key +pairs, and may not want to load all of them in the credentials +structure. The following example demonstrates the use of the +certificate selection callback. + +@verbatiminclude examples/ex-cert-select.c + +@node Verifying a certificate +@subsection Verifying a certificate +@anchor{ex:verify2} + +An example is listed below which uses the high level verification +functions to verify a given certificate list. + +@verbatiminclude examples/ex-verify.c + +@node Client using a PKCS 11 token with TLS +@subsection Using a @acronym{PKCS} #11 token with TLS +@anchor{ex: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. + +@verbatiminclude examples/ex-cert-select-pkcs11.c + + +@node Client with Resume capability example +@subsection Client with resume capability example +@anchor{ex:resume-client} + +This is a modification of the simple client example. Here we +demonstrate the use of session resumption. The client tries to connect +once using @acronym{TLS}, close the connection and then try to +establish a new connection using the previously negotiated data. + +@verbatiminclude examples/ex-client-resume.c + + +@node Simple client example with SRP authentication +@subsection Simple client example with @acronym{SRP} authentication + +The following client is a very simple @acronym{SRP} @acronym{TLS} +client which connects to a server and authenticates using a +@emph{username} and a @emph{password}. The server may authenticate +itself using a certificate, and in that case it has to be verified. + +@verbatiminclude examples/ex-client-srp.c + +@node Simple client example in C++ +@subsection Simple client example using the C++ API + +The following client is a simple example of a client client utilizing +the GnuTLS C++ API. + +@verbatiminclude examples/ex-cxx.cpp + +@node Helper function for TCP connections +@subsection Helper function for TCP connections + +This helper function abstracts away TCP connection handling from the +other examples. It is required to build some examples. + +@verbatiminclude examples/tcp.c + +@node Server examples +@section Server examples + +This section contains examples of @acronym{TLS} and @acronym{SSL} +servers, using @acronym{GnuTLS}. + +@menu +* Echo Server with X.509 authentication:: +* Echo Server with OpenPGP authentication:: +* Echo Server with SRP authentication:: +* Echo Server with anonymous authentication:: +@end menu + +@node Echo Server with X.509 authentication +@subsection Echo server with @acronym{X.509} authentication + +This example is a very simple echo server which supports +@acronym{X.509} authentication, using the RSA ciphersuites. + +@verbatiminclude examples/ex-serv1.c + +@node Echo Server with OpenPGP authentication +@subsection Echo server with @acronym{OpenPGP} authentication +@cindex OpenPGP server + +The following example is an echo server which supports +@acronym{OpenPGP} key authentication. You can easily combine +this functionality ---that is have a server that supports both +@acronym{X.509} and @acronym{OpenPGP} certificates--- but we separated +them to keep these examples as simple as possible. + +@verbatiminclude examples/ex-serv-pgp.c + +@node Echo Server with SRP authentication +@subsection Echo server with @acronym{SRP} authentication + +This is a server which supports @acronym{SRP} authentication. It is +also possible to combine this functionality with a certificate +server. Here it is separate for simplicity. + +@verbatiminclude examples/ex-serv-srp.c + +@node Echo Server with anonymous authentication +@subsection Echo Server with anonymous authentication + +This example server support anonymous authentication, and could be +used to serve the example client for anonymous authentication. + +@verbatiminclude examples/ex-serv-anon.c + +@node Miscellaneous examples +@section Miscellaneous examples + +@menu +* Checking for an alert:: +* X.509 certificate parsing example:: +@end menu + +@node Checking for an alert +@subsection Checking for an alert + +This is a function that checks if an alert has been received in the +current session. + +@verbatiminclude examples/ex-alert.c + +@node X.509 certificate parsing example +@subsection @acronym{X.509} certificate parsing example +@anchor{ex:x509-info} + +To demonstrate the @acronym{X.509} parsing capabilities an example program is +listed below. That program reads the peer's certificate, and prints +information about it. + +@verbatiminclude examples/ex-x509-info.c diff --git a/doc/cha-intro-tls.texi b/doc/cha-intro-tls.texi index c25cfe1841..64b4888f80 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 -@acronym{TLS}. 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} -@showfuncB{gnutls_record_check_pending,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}. +@node Authentication +@subsection 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. + +@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 + +@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 + +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}. + +@float Table,tab:key-exchange-cred +@multitable @columnfractions .25 .25 .2 .2 + +@headitem Authentication method @tab Key exchange @tab Client credentials @tab Server credentials + +@item Certificate +@tab @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 Password and certificate +@tab @code{KX_SRP_RSA}, @code{KX_SRP_DSS} +@tab @code{CRD_SRP} +@tab @code{CRD_CERTIFICATE}, @code{CRD_SRP} + +@item Password +@tab @code{KX_SRP} +@tab @code{CRD_SRP} +@tab @code{CRD_SRP} + +@item Anonymous +@tab @code{KX_ANON_DH}, +@code{KX_ANON_ECDH} +@tab @code{CRD_ANON} +@tab @code{CRD_ANON} + +@item Pre-shared key +@tab @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 + + @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. -@showfuncdesc{gnutls_session_get_data} - -@showfuncdesc{gnutls_session_get_id} - -@showfuncdesc{gnutls_session_set_data} +@showfuncC{gnutls_session_get_data,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. -@showfuncdesc{gnutls_db_set_retrieve_function} - -@showfuncdesc{gnutls_db_set_store_function} - -@showfuncB{gnutls_db_set_ptr,gnutls_db_set_remove_function} +@showfuncD{gnutls_db_set_retrieve_function,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. -@showfuncdesc{gnutls_db_check_entry} +@showfuncA{gnutls_db_check_entry} @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. -@showfuncdesc{gnutls_record_get_max_size} - -@showfuncdesc{gnutls_record_set_max_size} +@showfuncB{gnutls_record_get_max_size,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. -@showfuncdesc{gnutls_server_name_set} - -@showfuncdesc{gnutls_server_name_get} +@showfuncB{gnutls_server_name_set,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}). -@showfuncdesc{gnutls_session_ticket_key_generate} - -@showfuncdesc{gnutls_session_ticket_enable_server} - -@showfuncdesc{gnutls_session_ticket_enable_client} +@showfuncC{gnutls_session_ticket_key_generate,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. -@node Selecting cryptographic key sizes -@section Selecting cryptographic key sizes -@cindex 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. - -@float Table,tab:key-sizes -@multitable @columnfractions .10 .12 .10 .20 .32 - -@headitem Security bits @tab RSA, DH and SRP parameter size @tab ECC key size @tab Security parameter @tab Description - -@item 64 -@tab 816 -@tab 128 -@tab @code{WEAK} -@tab Very short term protection against small organizations - -@item 80 -@tab 1248 -@tab 160 -@tab @code{LOW} -@tab Very short term protection against agencies - -@item 112 -@tab 2432 -@tab 224 -@tab @code{NORMAL} -@tab Medium-term protection - -@item 128 -@tab 3248 -@tab 256 -@tab @code{HIGH} -@tab Long term protection - -@item 256 -@tab 15424 -@tab 512 -@tab @code{ULTRA} -@tab Foreseeable future - -@end multitable -@caption{Key sizes and security parameters.} -@end 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 -@math{2^{112}} 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. - -@c @showenumdesc{gnutls_sec_param_t,The @code{gnutls_sec_@-param_t} 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: - -@showfuncdesc{gnutls_sec_param_to_pk_bits} - -@showfuncdesc{gnutls_pk_bits_to_sec_param} - -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 de34820d9f..2f751b3e9b 100644 --- a/doc/cha-library.texi +++ b/doc/cha-library.texi @@ -1,5 +1,7 @@ -@node The Library -@chapter The Library +@node Introduction to GnuTLS +@chapter Introduction to GnuTLS + +@section 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. -@item Support for both @acronym{X.509} and @acronym{OpenPGP} certificates. - -@item Support for handling and verification of certificates. +@item 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 libtasn1@footnote{@url{http://www.gnu.org/software/libtasn1/}} library. The ``Cryptographic back-end'' is provided by the nettle@footnote{@url{http://www.lysator.liu.se/~nisse/nettle/}} library. -@menu -* Downloading and installing:: -* General idea:: -* Error handling:: -* Thread safety:: -* Callback functions:: -@end menu - -@node 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}. -@node General idea -@section 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}. - -@float Figure,fig:gnutls-design -@image{gnutls-internals,12cm} -@caption{High level design of GnuTLS.} -@end 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 -@acronym{GnuTLS} 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 hello@footnote{The first message in a @acronym{TLS} handshake}, -and if the session ID sent by the client, matches a stored session, -the stored session will be retrieved, and the new session will be a -resumed one, and will share the same session ID with the previous one. - -@node Error handling -@section Error handling -@subsection 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 -@code{GNUTLS_@-E_@-DECRYPTION_@-FAILED}. Non-fatal errors may warn about -something, i.e., a warning alert was received, or indicate the some -action has to be taken. This is the case with the error code -@code{GNUTLS_@-E_@-REHANDSHAKE} returned by @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 -@funcref{gnutls_error_is_fatal}. - -If any non fatal errors, that require an action, are to be returned by -a function, these error codes will be documented in the function's -reference. See @ref{Error codes}, for a description of the available -error codes. - -@subsection 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 -@funcref{gnutls_global_set_log_function} are to be used. Those will print -verbose information on the @acronym{GnuTLS} functions internal flow. - -@showfuncB{gnutls_global_set_log_level,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 -@funcref{gnutls_global_set_audit_log_function}. 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. - -@showfuncdesc{gnutls_global_set_audit_log_function} - -@node Thread safety -@section 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 -@code{CriticalSection} 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. - -@example -#include <gnutls.h> - -/* Other thread packages - */ - -int main() -@{ - gnutls_global_set_mutex (mutex_init, mutex_deinit, - mutex_lock, mutex_unlock); - gnutls_global_init(); -@} -@end example - -@showfuncdesc{gnutls_global_set_mutex} - -@node Callback functions -@section Callback functions -@cindex 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. - -@showfuncB{gnutls_transport_set_push_function,gnutls_transport_set_pull_function} - -Other callback functions may require more complicated input and data -to be allocated. Such an example is -@funcref{gnutls_srp_set_server_credentials_function}. -All callbacks should allocate and free memory using the functions shown below. - -@showfuncB{gnutls_malloc,gnutls_free} - +@section 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 0000000000..50f4585e43 --- /dev/null +++ b/doc/cha-shared-key.texi @@ -0,0 +1,202 @@ +@node Shared-key and anonymous authentication +@chapter Shared-key and anonymous authentication + +@menu +* SRP authentication:: +* PSK authentication:: +* Anonymous authentication:: +@end menu + +@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} 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 +@acronym{TLS} 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} +@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 + +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 + + +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 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. + +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 diff --git a/doc/gnutls.texi b/doc/gnutls.texi index fd4bf1f9ce..8f4e13fc18 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 -@include cha-auth.texi - @include cha-cert-auth.texi +@include cha-shared-key.texi + +@include cha-cert-auth2.texi + @include cha-gtls-app.texi +@include cha-gtls-examples.texi + @include cha-programs.texi @include cha-internals.texi diff --git a/doc/latex/.gitignore b/doc/latex/.gitignore index 6d679f3c81..ab0ce42876 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 0d8ded79b9..55482ba085 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 bf4aaafc02..1cc22681a7 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 db333a0771..cdb8964541 100755 --- a/doc/scripts/mytexi2latex +++ b/doc/scripts/mytexi2latex @@ -127,6 +127,7 @@ while ($line = <FILE>) { push(@stack, FLOAT_TABLE); $line =~ s/\@multitable \@columnfractions ([\.\d]+) ([\.\d]+)$/\n\\begin{tabular}{|p{$1\\linewidth}|p{$2\\linewidth}|}\n\\hline\n/g; $line =~ s/\@multitable \@columnfractions ([\.\d]+) ([\.\d]+) ([\.\d]+)$/\n\\begin{tabular}{|p{$1\\linewidth}|p{$2\\linewidth}|p{$3\\linewidth}|}\n\\hline\n/g; + $line =~ s/\@multitable \@columnfractions ([\.\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/\@multitable \@columnfractions ([\.\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; } |