* Version 3.0.3 (unreleased)
+** libgnutls: All functions related to RSA-EXPORT were deprecated.
+Support for RSA-EXPORT ciphersuites will be ceased in future versions.
+
** libgnutls: Memory leak fixes in ECC ciphersuites.
** libgnutls: Do not send an empty extension structure in server
@showfuncdesc{gnutls_certificate_set_verify_function}
Note that the DHE key exchange methods are generally
-slower@footnote{It really depends on the group used. Primes with
+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.}
-and require Diffie-Hellman parameters to be generated and associated with a credentials
-structure, by the server (see @ref{Parameter generation}).
+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
@showfuncC{gnutls_psk_set_server_credentials_function,gnutls_psk_set_server_credentials_hint,gnutls_psk_client_get_hint}
-Helper functions are included in @acronym{GnuTLS}, and may be used to generate and
-maintain @acronym{PSK} keys.
+Helper functions to generate and maintain @acronym{PSK} keys are also included
+in @acronym{GnuTLS}.
-@showfuncdesc{gnutls_hex_encode}
-
-@showfuncdesc{gnutls_hex_decode}
+@showfuncC{gnutls_key_generate,gnutls_hex_encode,gnutls_hex_decode}
@node Authentication and credentials
@showfuncdesc{gnutls_x509_crq_set_key_purpose_oid}
@showfuncdesc{gnutls_x509_crq_set_basic_constraints}
-The following two functions associate the request with
-a private key and sign it. If a request is to be signed
-with a key residing in a token it is recommended to use
+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_pkcs12_verify_mac}
@showfuncdesc{gnutls_pkcs12_bag_decrypt}
-@showfuncB{gnutls_pkcs12_bag_init,gnutls_pkcs12_bag_deinit}
+@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}
-@showfuncD{gnutls_pkcs12_bag_get_count,gnutls_pkcs12_bag_get_data,gnutls_pkcs12_bag_get_key_id,gnutls_pkcs12_bag_get_friendly_name}
-
-To generate a structure the functions below may be used.
+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_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}
-An example of a @acronym{PKCS} #12 structure generation can be found
-below.
-
@verbatiminclude examples/ex-pkcs12.c
@node OpenPGP certificates
@acronym{X.509} certificates, although the meaning and interpretation
are different. For example an @acronym{OpenPGP} key may be valid, if
the self signature is ok, even if no signers were found. The meaning
-of verification status is shown in the figure below.
+of verification status flags is the same as in the @acronym{X.509} certificates
+(see @ref{gnutls_certificate_verify_flags}).
@showfuncdesc{gnutls_openpgp_crt_verify_ring}
@showfuncdesc{gnutls_openpgp_crt_verify_self}
-@table @code
-
-@item CERT_INVALID:
-A signature on the key is invalid. That means that the key was
-modified by somebody, or corrupted during transport.
-
-@item CERT_REVOKED:
-The key has been revoked by its owner.
-
-@item CERT_SIGNER_NOT_FOUND:
-The key was not signed by a known signer.
-
-@item GNUTLS_CERT_INSECURE_ALGORITHM:
-The certificate was signed using an insecure algorithm such as MD2 or
-MD5. These algorithms have been broken and should not be trusted.
-
-@end table
-
@subsection Verifying a certificate in the context of a TLS session
Similarly with X.509 certificates, one needs to specify
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.
-@showfuncdesc{gnutls_pkcs11_token_init}
+@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}
-@showfuncdesc{gnutls_pkcs11_token_get_url}
-@showfuncdesc{gnutls_pkcs11_token_get_info}
-@showfuncdesc{gnutls_pkcs11_token_get_flags}
-The following example will list all available PKCS #11 tokens in a system.
+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_deinit();
@end example
-
-That example will only list all certificates in a token that have a corresponding
-private key.
@verbatiminclude examples/ex-pkcs11-list.c
@subsection Writing objects
@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 for someone
-to sign an X.509 certificate with a key that resides in a smart he has to follow the steps below:
+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>
@showfuncdesc{gnutls_privkey_import_x509}
-@showfuncdesc{gnutls_privkey_import_openpgp}
-@showfuncdesc{gnutls_privkey_import_pkcs11}
-
-Other information on the private key can be accessed using
-the following functions.
-
+@showfuncB{gnutls_privkey_import_openpgp,gnutls_privkey_import_pkcs11}
@showfuncdesc{gnutls_privkey_get_pk_algorithm}
@showfuncdesc{gnutls_privkey_get_type}
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}
key abstractions.
@showfuncdesc{gnutls_x509_crq_set_pubkey}
-
@showfuncdesc{gnutls_x509_crt_set_pubkey}
-@showfuncdesc{gnutls_x509_crt_privkey_sign}
-@showfuncdesc{gnutls_x509_crl_privkey_sign}
-@showfuncdesc{gnutls_x509_crq_privkey_sign}
+@showfuncC{gnutls_x509_crt_privkey_sign,gnutls_x509_crl_privkey_sign,gnutls_x509_crq_privkey_sign}
@node Digital signatures
@section Digital signatures
transport functions with functions that emulate the operation
of @code{recvfrom} and @code{sendto}. In addition
@acronym{DTLS} requires timers during the receive of a handshake
-message. This requires the following function to be used.
+message. This requires the @funcref{gnutls_transport_set_pull_timeout_function} function to be used.
@showfuncdesc{gnutls_transport_set_pull_timeout_function}
of the peer's identity. When certificates are in use,
this can be done, either after the handshake is complete, or during
the handshake if @funcref{gnutls_certificate_set_verify_function}
-has been used. In both cases the following function can be
+has been used. In both cases the @funcref{gnutls_certificate_verify_peers2} function can be
used to verify the peer's certificate (see @ref{Certificate authentication}
for more information).
session. That way the peer is notified securely about the
intention of termination, which allows distinguishing it
from a malicious connection termination.
+A session can be deinitialized with the @funcref{gnutls_deinit} function.
@showfuncdesc{gnutls_bye}
-
-A session can be deinitialized using the following function.
-
@showfuncdesc{gnutls_deinit}
@subsection Asynchronous operation
If successful a the session should be initialization and associated with
the cookie using @funcref{gnutls_dtls_prestate_set}.
-@showfuncdesc{gnutls_key_generate}
-
-@showfuncdesc{gnutls_dtls_cookie_send}
-
-@showfuncdesc{gnutls_dtls_cookie_verify}
-
-@showfuncdesc{gnutls_dtls_prestate_set}
-
+@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.
transport layer. The ``correct'' maximum transfer unit can be obtained through
a path MTU discovery mechanism @xcite{RFC4821}.
-@showfuncdesc{gnutls_dtls_set_mtu}
-
-@showfuncdesc{gnutls_dtls_get_mtu}
-@showfuncdesc{gnutls_dtls_get_data_mtu}
+@showfuncC{gnutls_dtls_set_mtu,gnutls_dtls_get_mtu,gnutls_dtls_get_data_mtu}
@node Priority Strings
@section Priority strings
The record protocol is the secure communications provider. Its purpose
is to encrypt, authenticate and ---optionally--- compress packets.
-
-@showfuncA{gnutls_record_send}
-
The record layer functions can be called at any time after
the handshake process is finished, when there is need to receive
or send data. In @acronym{DTLS} however, due to re-transmission
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.
-
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.
-@showfuncD{gnutls_record_recv,gnutls_record_recv_seq,gnutls_record_check_pending,gnutls_record_get_direction}
+@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::
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:
+on the proposal @xcite{RFC3749}. The supported algorithms are shown in
+@ref{gnutls_compression_method_t}.
-@table @code
-@item DEFLATE:
-Zlib compression, using the deflate algorithm.
-
-@item NULL:
-No compression.
-
-@end table
+@showenumdesc{gnutls_compression_method_t,Supported compression algorithms}
@node Weaknesses and countermeasures
@subsection Weaknesses and countermeasures
\usepackage{verbatim}
\usepackage{listings}
\usepackage{xcolor}
+\usepackage{afterpage}
+\usepackage{float}
+\usepackage{morefloats}
\usepackage[greek,english]{babel}%for euro sign
+\renewcommand{\textfraction}{0.00}
+\renewcommand{\floatpagefraction}{0.8}
+\renewcommand{\dblfloatpagefraction}{0.8}
+
\hypersetup{
colorlinks,%
citecolor=blue,%
\code{#1}%
}
+\definecolor{light-gray}{gray}{0.95}
+
\newcommand{\showfunc}[1]{%
\let\Oldfd\functionDescription
\let\Oldendfd\endfunctionDescription
}
\newcommand{\showfuncdesc}[1]{%
+ \begin{figure}[htbp]
\begin{minipage}[l]{\linewidth}
\begin{framed}
\texttt{
\input{functions/#1}
}
\end{framed}
- \vspace{0.10cm}
\end{minipage}
- \par
+ \end{figure}
}
\newcommand{\showenumdesc}[2]{%
}
\newcommand{\showfuncA}[1]{%
-% \fcolorbox{black}{light-gray}{
+ \begin{figure}[H]
\begin{samepage}
\begin{framed}
\showfunc{#1}
-% }
\end{framed}
\end{samepage}
+ \end{figure}
}
\newcommand{\showfuncB}[2]{%
-% \fcolorbox{black}{light-gray}{
+ \begin{figure}[H]
\begin{samepage}
\begin{framed}
\showfunc{#1}
+ \vspace{0.2cm}
\showfunc{#2}
-% }
\end{framed}
\end{samepage}
+ \end{figure}
}
\newcommand{\showfuncC}[3]{%
-% \fcolorbox{black}{light-gray}{
+ \begin{figure}[H]
\begin{samepage}
\begin{framed}
\showfunc{#1}
+ \vspace{0.2cm}
\showfunc{#2}
+ \vspace{0.2cm}
\showfunc{#3}
-% }
\end{framed}
\end{samepage}
+ \end{figure}
}
\newcommand{\showfuncD}[4]{%
-% \fcolorbox{black}{light-gray}{
+ \begin{figure}[H]
\begin{samepage}
\begin{framed}
\showfunc{#1}
+ \vspace{0.2cm}
\showfunc{#2}
+ \vspace{0.2cm}
\showfunc{#3}
+ \vspace{0.2cm}
\showfunc{#4}
-% }
\end{framed}
\end{samepage}
+ \end{figure}
}
\newcommand{\showfuncE}[5]{%
-% \fcolorbox{black}{light-gray}{
+ \begin{figure}[H]
\begin{samepage}
\begin{framed}
\showfunc{#1}
+ \vspace{0.2cm}
\showfunc{#2}
+ \vspace{0.2cm}
\showfunc{#3}
+ \vspace{0.2cm}
\showfunc{#4}
+ \vspace{0.2cm}
\showfunc{#5}
-% }
\end{framed}
\end{samepage}
+ \end{figure}
}
\newcommand{\showfuncF}[6]{%
-% \fcolorbox{black}{light-gray}{
+ \begin{figure}[H]
\begin{samepage}
\begin{framed}
\showfunc{#1}
+ \vspace{0.2cm}
\showfunc{#2}
+ \vspace{0.2cm}
\showfunc{#3}
+ \vspace{0.2cm}
\showfunc{#4}
+ \vspace{0.2cm}
\showfunc{#5}
+ \vspace{0.2cm}
\showfunc{#6}
-% }
\end{framed}
\end{samepage}
+ \end{figure}
}
\newenvironment{function}%
push(@stack, NORMAL);
$mode = FLOAT;
}
- if ($line =~ s/\@float Table\,(.*)/\\begin{table}[htp]\n\\centering/g) {
+ if ($line =~ s/\@float Table\,(.*)/\\begin{table}[thp]\n\\centering/g) {
$label = $1;
push(@stack, NORMAL);
$mode = FLOAT_TABLE;
/**
* gnutls_compression_method_t:
* @GNUTLS_COMP_UNKNOWN: Unknown compression method.
- * @GNUTLS_COMP_NULL: The NULL compression method (uncompressed).
- * @GNUTLS_COMP_DEFLATE: The deflate/zlib compression method.
+ * @GNUTLS_COMP_NULL: The NULL compression method (no compression).
+ * @GNUTLS_COMP_DEFLATE: The DEFLATE compression method from zlib.
* @GNUTLS_COMP_ZLIB: Same as %GNUTLS_COMP_DEFLATE.
*
* Enumeration of different TLS compression methods.
projects / thirdparty / gnutls.git / commitdiff
