diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/cha-auth.texi | 43 | ||||
| -rw-r--r-- | doc/cha-cert-auth.texi | 6 | ||||
| -rw-r--r-- | doc/cha-gtls-app.texi | 92 | ||||
| -rw-r--r-- | doc/gnutls.texi | 6 |
4 files changed, 88 insertions, 59 deletions
diff --git a/doc/cha-auth.texi b/doc/cha-auth.texi index b359af9b18..9336ab5834 100644 --- a/doc/cha-auth.texi +++ b/doc/cha-auth.texi @@ -116,40 +116,10 @@ certificate authentication. Note that the DHE key exchange methods are generally slower@footnote{It really depends on the group used. Primes with lesser bits are always faster, but also easier to break. Values less -than 768 should not be used today} than plain RSA and require Diffie +than 1024 should not be used today} than plain RSA and require Diffie Hellman parameters to be generated and associated with a credentials -structure, by the server. The @code{RSA-EXPORT} method also requires -512 bit RSA parameters, that should also be generated and associated -with the credentials structure. See the functions: - -@itemize - -@item @ref{gnutls_dh_params_generate2} - -@item @ref{gnutls_certificate_set_dh_params} - -@item @ref{gnutls_rsa_params_generate2} - -@item @ref{gnutls_certificate_set_rsa_export_params} - -@end itemize - -Sometimes in order to avoid bottlenecks in programs it is useful to -store and read parameters from formats that can be generated by -external programs such as @code{certtool}. This is possible with -@acronym{GnuTLS} by using the following functions: - -@itemize - -@item @ref{gnutls_dh_params_import_pkcs3} - -@item @ref{gnutls_rsa_params_import_pkcs1} - -@item @ref{gnutls_dh_params_export_pkcs3} - -@item @ref{gnutls_rsa_params_export_pkcs1} - -@end itemize +structure, by the server. For more information check the @ref{Parameter generation} +section. Key exchange algorithms for @acronym{OpenPGP} and @acronym{X.509} certificates: @@ -209,7 +179,8 @@ are shown below. Note that the key exchange methods for anonymous authentication require Diffie-Hellman parameters to be generated by the server and -associated with an anonymous credentials structure. +associated with an anonymous credentials structure. Check +@ref{Parameter generation} for more information. Supported anonymous key exchange algorithms: @@ -389,6 +360,8 @@ Key exchange algorithms and the corresponding credential types: @item @code{KX_RSA} @item @code{KX_DHE_RSA} @item @code{KX_DHE_DSS} +@item @code{KX_ECDHE_RSA} +@item @code{KX_ECDHE_ECDSA} @item @code{KX_RSA_EXPORT} @tab @code{CRD_CERTIFICATE} @tab @code{CRD_CERTIFICATE} @@ -405,10 +378,12 @@ Key exchange algorithms and the corresponding credential types: @tab @code{CRD_SRP} @item @code{KX_ANON_DH} +@item @code{KX_ANON_ECDH} @tab @code{CRD_ANON} @tab @code{CRD_ANON} @item @code{KX_PSK} +@item @code{KX_DHE_PSK} @tab @code{CRD_PSK} @tab @code{CRD_PSK} diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi index 69e10b87b6..c64e61bcdd 100644 --- a/doc/cha-cert-auth.texi +++ b/doc/cha-cert-auth.texi @@ -7,7 +7,7 @@ * The X.509 trust model:: * The OpenPGP trust model:: * PKCS #11 tokens:: -* Abstract data types:: +* Abstract key types:: * Digital signatures:: @end menu @@ -555,8 +555,8 @@ certificates. @end itemize -@node Abstract data types -@section Abstract data types +@node Abstract key types +@section Abstract key types @anchor{sec:abstract} @cindex Abstract types diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi index 935ea40d3b..c61d3f5c9f 100644 --- a/doc/cha-gtls-app.texi +++ b/doc/cha-gtls-app.texi @@ -8,9 +8,7 @@ * Client examples:: * Server examples:: * Miscellaneous examples:: -* Compatibility with the OpenSSL library:: -* Keying Material Exporters:: -* Channel Bindings:: +* Advanced and other topics:: @end menu @node Preparation @@ -375,31 +373,63 @@ structure. @verbatiminclude examples/ex-pkcs12.c -@node Compatibility with the OpenSSL library -@section Compatibility with the OpenSSL Library -@cindex OpenSSL +@node Advanced and other topics +@section Advanced and other topics -To ease @acronym{GnuTLS}' integration with existing applications, a -compatibility layer with the widely used OpenSSL library is included -in the @code{gnutls-openssl} library. This compatibility layer is not -complete and it is not intended to completely reimplement the OpenSSL -API with @acronym{GnuTLS}. It only provides source-level -compatibility. There is currently no attempt to make it -binary-compatible with OpenSSL. +@menu +* Parameter generation:: +* Keying Material Exporters:: +* Channel Bindings:: +* Compatibility with the OpenSSL library:: +@end menu -The prototypes for the compatibility functions are in the -@file{gnutls/openssl.h} header file. -Current limitations imposed by the compatibility layer include: +@node Parameter generation +@subsection Parameter generation +@cindex parameter generation +@cindex generating parameters + +Several TLS ciphersuites require additional parameters that +need to be generated or provided by the application. The +Diffie-Hellman based ciphersuites (ANON-DH or DHE), require +the group information to be provided. This information can be either +be generated on the fly using @ref{gnutls_dh_params_generate2} +or imported from some pregenerated value using @ref{gnutls_dh_params_import_pkcs3}. +The parameters can be used in a session by calling +@ref{gnutls_certificate_set_dh_params} or +@ref{gnutls_anon_set_server_dh_params} for anonymous sessions. + +Due to the time-consuming calculations required for the generation +of Diffie-Hellman parameters we suggest against performing generation +of them within an application. The @code{certtool} tool can be used to +generate or export known safe values that can be stored in code +or in a configuration file to provide the ability to replace. We also +recommend the usage of @ref{gnutls_sec_param_to_pk_bits} to determine +the bit size of the parameters to be generated. + +The ciphersuites that involve the RSA-EXPORT key exchange require +additional parameters. Those ciphersuites are rarely used today +because they are by design insecure, thus if you have no requirement +for them, this section should be skipped. The RSA-EXPORT key exchange +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. @itemize -@item Error handling is not thread safe. +@item @ref{gnutls_rsa_params_generate2} + +@item @ref{gnutls_certificate_set_rsa_export_params} + +@item @ref{gnutls_rsa_params_import_pkcs1} + +@item @ref{gnutls_rsa_params_export_pkcs1} @end itemize + @node Keying Material Exporters -@section Keying Material Exporters +@subsection Keying Material Exporters @cindex Keying Material Exporters @cindex Exporting Keying Material @@ -425,7 +455,7 @@ If you don't want to mix in the client/server random, there is a more low-level TLS PRF interface called @ref{gnutls_prf_raw}. @node Channel Bindings -@section Channel Bindings +@subsection Channel Bindings @cindex Channel Bindings In user authentication protocols (e.g., EAP or SASL mechanisms) it is @@ -465,3 +495,27 @@ Note that it must be run after a successful TLS handshake. @} @} @end smallexample + +@node Compatibility with the OpenSSL library +@subsection Compatibility with the OpenSSL Library +@cindex OpenSSL + +To ease @acronym{GnuTLS}' integration with existing applications, a +compatibility layer with the widely used OpenSSL library is included +in the @code{gnutls-openssl} library. This compatibility layer is not +complete and it is not intended to completely reimplement the OpenSSL +API with @acronym{GnuTLS}. It only provides limited source-level +compatibility. There is currently no attempt to make it +binary-compatible with OpenSSL. + +The prototypes for the compatibility functions are in the +@file{gnutls/openssl.h} header file. + +Current limitations imposed by the compatibility layer include: + +@itemize + +@item Error handling is not thread safe. + +@end itemize + diff --git a/doc/gnutls.texi b/doc/gnutls.texi index eb8c1c73dc..f0d7ed2b02 100644 --- a/doc/gnutls.texi +++ b/doc/gnutls.texi @@ -76,8 +76,8 @@ Documentation License''. * Introduction to TLS:: * Authentication methods:: * More on certificate authentication:: -* How to use TLS in application protocols:: * How to use GnuTLS in applications:: +* How to use TLS in application protocols:: * Included programs:: * Function reference:: * All the supported ciphersuites in GnuTLS:: @@ -100,10 +100,10 @@ Documentation License''. @include cha-cert-auth.texi -@include cha-tls-app.texi - @include cha-gtls-app.texi +@include cha-tls-app.texi + @include cha-programs.texi @include cha-functions.texi |