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:
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:
@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}
@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}
* Client examples::
* Server examples::
* Miscellaneous examples::
-* Compatibility with the OpenSSL library::
-* Keying Material Exporters::
-* Channel Bindings::
+* Advanced and other topics::
@end menu
@node Preparation
@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
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
@}
@}
@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
+
projects / thirdparty / gnutls.git / commitdiff
