guile.tp
guile.vr
guile.vrs
+alerts.texi
+alert-printlist
+latex/alerts.tex
+latex/functions
# Generated texinfos.
-gnutls_TEXINFOS += error_codes.texi algorithms.texi
+gnutls_TEXINFOS += error_codes.texi algorithms.texi alerts.texi
MAINTAINERCLEANFILES += error_codes.texi algorithms.texi
AM_CPPFLAGS = -I$(top_srcdir)/lib/includes -I$(top_builddir)/lib/includes
-noinst_PROGRAMS = errcodes printlist
+noinst_PROGRAMS = errcodes printlist alert-printlist
errcodes_SOURCES = errcodes.c
errcodes_LDADD = ../lib/libgnutls.la ../gl/libgnu.la
printlist_SOURCES = printlist.c
printlist_LDADD = ../lib/libgnutls.la ../gl/libgnu.la
+alert_printlist_SOURCES = alert-printlist.c
+alert_printlist_LDADD = ../lib/libgnutls.la ../gl/libgnu.la
+
error_codes.texi: $(top_srcdir)/lib/gnutls_errors.c $(srcdir)/errcodes.c
make $(builddir)/errcodes
$(builddir)/errcodes > $@-tmp
mv -f $@-tmp $@
-algorithms.texi: $(srcdir)/printlist.c
- make $(builddir)/printlist
+algorithms.texi: printlist
$(builddir)/printlist > $@-tmp
mv -f $@-tmp $@
+alerts.texi: alert-printlist
+ $(builddir)/alert-printlist > $@-tmp
+ mv -f $@-tmp $@
+
# Guile texinfos.
guile_texi = core.c.texi extra.c.texi
--- /dev/null
+/*
+ * Copyright (C) 2008, 2009, 2010 Free Software Foundation, Inc.
+ * Author: Nikos Mavrogiannopoulos
+ *
+ * This file is part of GnuTLS.
+ *
+ * GnuTLS is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * GnuTLS is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#include <config.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <gnutls/gnutls.h>
+#include <gnutls/x509.h>
+#include <gnutls/openpgp.h>
+
+static void main_texinfo (void);
+static void main_latex(void);
+
+int
+main (int argc, char *argv[])
+{
+ if (argc > 1)
+ main_latex();
+ else
+ main_texinfo();
+
+ return 0;
+}
+
+static void main_texinfo (void)
+{
+ {
+ size_t i;
+ const char *name;
+ gnutls_kx_algorithm_t kx;
+ gnutls_cipher_algorithm_t cipher;
+ gnutls_mac_algorithm_t mac;
+ gnutls_protocol_t version;
+
+ printf ("Available alert messages:\n");
+
+ printf ("@multitable @columnfractions .55 .10 .30\n@anchor{tab:alerts}\n");
+ for (i = 0; i<256;i++)
+ {
+ if (gnutls_alert_get_strname(i)==NULL) continue;
+ printf ("@item %s\n@tab %d\n@tab %s\n",
+ gnutls_alert_get_strname(i),
+ (unsigned int) i, gnutls_alert_get_name (i));
+ }
+ printf ("@end multitable\n");
+
+ }
+}
+
+static const char headers[] = "\\tablefirsthead{%\n"
+ "\\hline\n"
+ "Alert & ID & Description\\\\\n"
+ "\\hline}\n"
+ "\\tablehead{%\n"
+ "\\hline\n"
+ "\\multicolumn{3}{|l|}{\\small\\sl continued from previous page}\\\\\n"
+ "\\hline\n"
+ "Alert & ID & Description\\\\\n"
+ "\\hline}\n"
+ "\\tabletail{%\n"
+ "\\hline\n"
+ "\\multicolumn{3}{|r|}{\\small\\sl continued on next page}\\\\\n"
+ "\\hline}\n"
+ "\\tablelasttail{\\hline}\n"
+ "\\bottomcaption{The TLS alert table}\n\n";
+
+static char* escape_string( const char* str)
+{
+static char buffer[500];
+int i = 0, j = 0;
+
+
+while( str[i] != 0 && j < sizeof(buffer) - 1) {
+ if (str[i]=='_') {
+ buffer[j++] = '\\';
+ buffer[j++] = '_';
+ } else {
+ buffer[j++] = str[i];
+ }
+ i++;
+};
+
+buffer[j] = 0;
+
+return buffer;
+
+}
+
+static void main_latex(void)
+{
+int i, j;
+const char* desc;
+const char* _name;
+
+puts( headers);
+
+printf("\\begin{supertabular}{|l|p{1cm}|p{3.5cm}|}\n\\label{tab:alerts}\n");
+
+ {
+ size_t i;
+ const char *name;
+ gnutls_kx_algorithm_t kx;
+ gnutls_cipher_algorithm_t cipher;
+ gnutls_mac_algorithm_t mac;
+ gnutls_protocol_t version;
+
+ for (i = 0; i<256;i++)
+ {
+ if (gnutls_alert_get_strname(i)==NULL) continue;
+ printf ("{\\small{%s}} & \\code{%d} & %s",
+ escape_string(gnutls_alert_get_strname(i)),
+ (unsigned int) i, gnutls_alert_get_name (i));
+ printf( "\\\\\n");
+ }
+
+ printf("\\end{supertabular}\n\n");
+
+ }
+
+return;
+
+}
@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}. In the next paragraphs
+we elaborate on supported authentication methods.
+
+@showfuncA{gnutls_credentials_set}
+
@menu
* Certificate authentication::
* Anonymous authentication::
certificate need not to be included, since the peer should possess it
already.
-As an alternative, a callback may be used so the server or the client
-specify the certificate and the key at the handshake time. That
-callback can be set using the functions:
-
-@itemize
-
-@item @funcref{gnutls_certificate_server_set_retrieve_function}
+@showfuncE{gnutls_certificate_set_x509_key,gnutls_certificate_set_x509_key_mem,gnutls_certificate_set_openpgp_key,gnutls_certificate_set_openpgp_key_file,gnutls_certificate_set_openpgp_key_mem}
-@item @funcref{gnutls_certificate_client_set_retrieve_function}
+@showfuncdesc{gnutls_certificate_set_x509_key_file}
-@end itemize
+@showfuncdesc{gnutls_certificate_set_retrieve_function}
-Clients and servers that will select certificates using callback
-functions should select a certificate according the peer's signature
+As an alternative, a callback may be used so the server or the client
+specifies the certificate and the key at the handshake time
+using @funcref{gnutls_certificate_set_retrieve_function}.
+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}.
+@showfuncA{gnutls_sign_algorithm_get_requested}
+
+
Certificate verification is possible by loading the trusted
authorities into the credentials structure by using
@funcref{gnutls_certificate_set_x509_trust_file} or
@funcref{gnutls_certificate_set_openpgp_keyring_file} for openpgp
keys. Note however that the peer's certificate is not automatically
verified, you should call @funcref{gnutls_certificate_verify_peers2},
-after a successful handshake, to verify the signatures of the
-certificate. An alternative way, which reports a more detailed
+after a successful handshake or during if @funcref{nutls_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{The X.509 trust model}.
+@showfuncdesc{gnutls_certificate_verify_peers2}
+
In a handshake, the negotiated cipher suite depends on the
certificate's parameters, so not all key exchange methods will be
available with some certificates. @acronym{GnuTLS} will disable
encryption. All the key exchange methods shown below are available in
certificate authentication.
+@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
lesser bits are always faster, but also easier to break. See @ref{Selecting cryptographic key sizes}
may be used to specify a callback function.
The callback will be called once during the @acronym{TLS} handshake.
+@showfuncB{gnutls_srp_set_client_credentials,gnutls_srp_set_client_credentials_function}
+
In server side the default behaviour of @acronym{GnuTLS} is to read
the usernames and @acronym{SRP} verifiers from password files. These
password files are the ones used by the @emph{Stanford srp libraries}
@funcref{gnutls_srp_set_server_credentials_function} should be called,
to set an appropriate callback.
-Some helper functions such as
-
-@itemize
+@showfuncdesc{gnutls_srp_set_server_credentials_file}
-@item @funcref{gnutls_srp_verifier}
+@showfuncdesc{gnutls_srp_set_server_credentials_function}
-@item @funcref{gnutls_srp_base64_encode}
-
-@item @funcref{gnutls_srp_base64_decode}
-
-@end itemize
-
-are included in @acronym{GnuTLS}, and can be used to generate and
+Helper functions are included in @acronym{GnuTLS}, and can be 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 Authentication using PSK
@section Authentication using @acronym{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
Clients supporting @acronym{PSK} should supply the username and key
advantage that the callback will be called only if @acronym{PSK} has
been negotiated.
+@showfuncB{gnutls_psk_set_client_credentials,gnutls_psk_set_client_credentials_function}
+
In server side the default behaviour 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
the hint, for example in the callback function, using
@funcref{gnutls_psk_client_get_hint}.
-Some helper functions such as:
-
-@itemize
+@showfuncdesc{gnutls_psk_set_server_credentials_file}
-@item @funcref{gnutls_hex_encode}
+@showfuncC{gnutls_psk_set_server_credentials_function,gnutls_psk_set_server_credentials_hint,gnutls_psk_client_get_hint}
-@item @funcref{gnutls_hex_decode}
+Helper functions are included in @acronym{GnuTLS}, and may be used to generate and
+maintain @acronym{PSK} keys.
-@end itemize
+@showfuncdesc{gnutls_hex_encode}
-are included in @acronym{GnuTLS}, and may be used to generate and
-maintain @acronym{PSK} keys.
+@showfuncdesc{gnutls_hex_decode}
@node Authentication and credentials
available functions for @acronym{X.509} certificate handling have
their prototypes in @file{gnutls/x509.h}. An example program to
demonstrate the @acronym{X.509} parsing capabilities can be found at
-section @ref{ex:x509-info}.
+@ref{ex:x509-info}.
@node Verifying X.509 certificate paths
@subsection Verifying @acronym{X.509} Certificate Paths
authentication. For this purpose the following functions are
provided.
-@table @code
-
-@item @funcref{gnutls_x509_trust_list_init}:
-A function to initialize a list that will hold trusted
-certificate authorities and certificate revocation lists.
-
-@item @funcref{gnutls_x509_trust_list_deinit}:
-Deinitializes the list.
-
-@item @funcref{gnutls_x509_trust_list_add_cas}:
-Adds certificate authorities to the list.
-
-@item @funcref{gnutls_x509_trust_list_add_named_crt}:
-Adds trusted certificates for an entity identified
-by a name.
-
-@item @funcref{gnutls_x509_trust_list_add_crls}:
-Adds certificate revocation lists.
-
-@item @funcref{gnutls_x509_trust_list_verify_crt}:
-Verifies a certificate chain using the previously setup trusted
-list. A callback can be specified that will provide information
-about the verification procedure (and detailed reasons of failure).
-
-@item @funcref{gnutls_x509_trust_list_verify_named_crt}:
-Does verification of the certificate by looking for a matching one
-in the named certificates. A callback can be specified that will provide information
-about the verification procedure (and detailed reasons of failure).
-
-@end table
+@showfuncdesc{gnutls_x509_trust_list_init}
+@showfuncdesc{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}
+@showfuncdesc{gnutls_x509_trust_list_verify_crt}
+@showfuncdesc{gnutls_x509_trust_list_verify_named_crt}
The verification function will verify a given certificate chain against a list of certificate
authorities and certificate revocation lists, and output
are trusted for a particular server but not to authorize other certificates.
This purpose is served by the functions @funcref{gnutls_x509_trust_list_add_named_crt} and @funcref{gnutls_x509_trust_list_verify_named_crt}.
A detailed description of these elements can be found
-in figure below. An example of these functions in use can be found
-in @ref{ex:verify2}.
-
+in @ref{tab:cert-verify}. An example of certificate verification is shown in @ref{ex:verify2}.
When operating in the context of a TLS session, the trusted certificate
authority list has been set via the
thus it is not required to setup a trusted list as above.
Convenience functions such as @funcref{gnutls_certificate_verify_peers2}
are equivalent and will verify the peer's certificate chain
-in a TLS session. The certificate verification functions output
-codes as in @ref{tab:cert-verify}.
+in a TLS session.
@float Table,tab:cert-verify
@multitable @columnfractions .55 .45
@acronym{PKCS} #10 @xcite{RFC2986}. Other certificate request's format
are not currently supported.
-In @acronym{GnuTLS} the @acronym{PKCS} #10 structures are handled
-using the @code{gnutls_x509_crq_t} type. An example of a certificate
-request generation can be found at section @ref{ex:crq}.
+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 PKCS 12 structures
@subsection @acronym{PKCS} #12 Structures
in order for its data to be accessed.
An example of a @acronym{PKCS} #12 structure generation can be found
-at section @ref{ex:pkcs12}.
+below.
+
+@verbatiminclude examples/ex-pkcs12.c
@node The OpenPGP trust model
@section The @acronym{OpenPGP} Trust Model
@acronym{GnuTLS}, are simple ones, and do not use the features of the
``web of trust''. For that reason, if the verification needs are
complex, the assistance of external tools like @acronym{GnuPG} and
-GPGME (@url{http://www.gnupg.org/related_software/gpgme/}) is
+GPGME@footnote{@url{http://www.gnupg.org/related_software/gpgme/}} is
recommended.
There is one verification function in @acronym{GnuTLS}, the
shared cryptographic keys and certificates in a uniform way, as in @ref{fig:pkcs11-vision}.
@float Figure,fig:pkcs11-vision
-@image{pkcs11-vision,8cm}
+@image{pkcs11-vision,9cm}
@caption{PKCS #11 module usage.}
@end float
it is adviceable to use @code{/etc/pkcs11/modules/mymodule.conf}. This file has the following
format:
-@verbatim
+@smallexample
module: /usr/lib/opensc-pkcs11.so
-@end verbatim
+@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.
-@itemize
-
-@item @funcref{gnutls_pkcs11_init}: Global initialization
-
-@item @funcref{gnutls_pkcs11_deinit}: Global deinitialization
-
-@item @funcref{gnutls_pkcs11_set_token_function}: Sets the token insertion function
-
-@item @funcref{gnutls_pkcs11_set_pin_function}: Sets the PIN request function
-
-@item @funcref{gnutls_pkcs11_add_provider}: Adds an additional @acronym{PKCS} #11 provider
-
-@end itemize
+@showfuncdesc{gnutls_pkcs11_init}
+@showfuncdesc{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 p11-kit@footnote{@url{http://p11-glue.freedesktop.org/}}
@end example
-Objects can be accessed with the following functions
-@itemize
-
-@item @funcref{gnutls_pkcs11_obj_init}: Initializes an object
-
-@item @funcref{gnutls_pkcs11_obj_import_url}: To import an object from a url
-
-@item @funcref{gnutls_pkcs11_obj_export_url}: To export the URL of the object
-
-@item @funcref{gnutls_pkcs11_obj_deinit}: To deinitialize an object
-
-@item @funcref{gnutls_pkcs11_obj_export}: To export data associated with object
-
-@item @funcref{gnutls_pkcs11_obj_get_info}: To obtain information about an object
+@acronym{PKCS} #11 objects can be accessed with the functions shown below.
-@item @funcref{gnutls_pkcs11_obj_list_import_url}: To mass load of objects
+@showfuncB{gnutls_pkcs11_obj_init,gnutls_pkcs11_obj_deinit}
-@item @funcref{gnutls_x509_crt_import_pkcs11}: Import a certificate object
+@showfuncdesc{gnutls_pkcs11_obj_import_url}
-@item @funcref{gnutls_x509_crt_import_pkcs11_url}: Helper function to directly import a URL into a certificate
-
-@item @funcref{gnutls_x509_crt_list_import_pkcs11}: Mass import of certificates
-
-@end itemize
-
-
-Functions that relate to token handling are shown below
-@itemize
+@showfuncdesc{gnutls_pkcs11_obj_export_url}
-@item @funcref{gnutls_pkcs11_token_init}: Initializes a token
+@showfuncdesc{gnutls_pkcs11_obj_export}
-@item @funcref{gnutls_pkcs11_token_set_pin}: Sets the token user's PIN
+@showfuncdesc{gnutls_pkcs11_obj_get_info}
-@item @funcref{gnutls_pkcs11_token_get_url}: Returns the URL of a token
+@showfuncdesc{gnutls_pkcs11_obj_list_import_url}
-@item @funcref{gnutls_pkcs11_token_get_info}: Obtain information about a token
+@showfuncC{gnutls_x509_crt_import_pkcs11,gnutls_x509_crt_import_pkcs11_url,gnutls_x509_crt_list_import_pkcs11}
-@item @funcref{gnutls_pkcs11_token_get_flags}: Returns flags about a token (i.e. hardware or software)
+Functions that relate to token handling are shown below.
-@end itemize
+@showfuncdesc{gnutls_pkcs11_token_init}
+@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 tokens.
+The following example will list all available PKCS #11 tokens in a system.
@example
int i;
char* url;
@end example
-The next one will list all certificates in a token, that have a corresponding
-private key:
+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
With @acronym{GnuTLS} you can copy existing private keys and certificates
to a token. This can be achieved with the following functions
-@itemize
-
-@item @funcref{gnutls_pkcs11_delete_url}: To delete an object
-
-@item @funcref{gnutls_pkcs11_copy_x509_privkey}: To copy a private key to a token
-
-@item @funcref{gnutls_pkcs11_copy_x509_crt}: To copy a certificate to a token
-
-@end itemize
+@showfuncdesc{gnutls_pkcs11_delete_url}
+@showfuncdesc{gnutls_pkcs11_copy_x509_privkey}
+@showfuncdesc{gnutls_pkcs11_copy_x509_crt}
@subsection Using a @acronym{PKCS} #11 token with TLS
the following functions can be used to load PKCS #11 key and
certificates.
-@itemize
-
-@item @funcref{gnutls_certificate_set_x509_trust_file}: If given a PKCS #11 URL will load the trusted certificates from it.
-
-@item @funcref{gnutls_certificate_set_x509_key_file}: Will also load PKCS #11 URLs for keys and certificates.
-
-@end itemize
+@showfuncB{gnutls_certificate_set_x509_trust_file,gnutls_certificate_set_x509_key_file}
@node Abstract key types
@verbatiminclude examples/ex-verify.c
@node Client using a PKCS 11 token with TLS
-@subsection Using a @acronym{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
@menu
* Checking for an alert::
* X.509 certificate parsing example::
-* Certificate request generation::
-* PKCS 12 structure generation::
@end menu
@node Checking for an alert
@verbatiminclude examples/ex-x509-info.c
-@node Certificate request generation
-@subsection Certificate Request Generation
-@anchor{ex:crq}
-
-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.
-
-@verbatiminclude examples/ex-crq.c
-
-@node PKCS 12 structure generation
-@subsection @acronym{PKCS} #12 Structure Generation
-@anchor{ex:pkcs12}
-
-The following example is about generating a @acronym{PKCS} #12
-structure.
-
-@verbatiminclude examples/ex-pkcs12.c
-
@node Advanced and other topics
@section Advanced and other topics
@funcref{gnutls_certificate_set_dh_params} or
@funcref{gnutls_anon_set_server_dh_params} for anonymous sessions.
+@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
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 @funcref{gnutls_sec_param_to_pk_bits} to determine
+recommend the usage of @funcref{gnutls_sec_param_to_pk_bits} (see @ref{Selecting cryptographic key sizes}) to determine
the bit size of the parameters to be generated.
The ciphersuites that involve the RSA-EXPORT key exchange require
parameters to be refreshed (regenerated) in short intervals. The
following functions can be used for these parameters.
-@itemize
-
-@item @funcref{gnutls_rsa_params_generate2}
-
-@item @funcref{gnutls_certificate_set_rsa_export_params}
-
-@item @funcref{gnutls_rsa_params_import_pkcs1}
-
-@item @funcref{gnutls_rsa_params_export_pkcs1}
-
-@end itemize
+@showfuncD{gnutls_rsa_params_generate2,gnutls_certificate_set_rsa_export_params,gnutls_rsa_params_import_pkcs1,gnutls_rsa_params_export_pkcs1}
@node Keying Material Exporters
@section TLS Layers
@cindex TLS Layers
-@acronym{TLS} is a layered protocol, and consists of the Record
-Protocol, the Handshake Protocol and the Alert Protocol. The Record
-Protocol is to serve all other protocols and is above the transport
-layer. The Record protocol offers symmetric encryption, data
+@acronym{TLS} is a layered protocol, and consists of the record
+protocol, the handshake protocol and the alert protocol. The record
+protocol is to serve all other protocols and is above the transport
+layer. The record protocol offers symmetric encryption, data
authenticity, and optionally compression.
-The Alert protocol offers some signaling to the other protocols. It
+The alert protocol offers some signaling to the other protocols. It
can help informing the peer for the cause of failures and other error
conditions. @xref{The Alert Protocol}, for more information. The
alert protocol is above the record protocol.
-The Handshake protocol is responsible for the security parameters'
+The handshake protocol is responsible for the security parameters'
negotiation, the initial key exchange and authentication.
@xref{The Handshake Protocol}, for more information about the handshake
protocol. The protocol layering in TLS is shown in @ref{fig:tls-layers}.
@section The Transport Layer
@cindex Transport protocol
-@acronym{TLS} is not limited to one transport layer, it can be used
-above any transport layer, as long as it is a reliable one. A set of
-functions is provided and their purpose is to load to @acronym{GnuTLS} the
+@acronym{TLS} is not limited to any transport layer and can be used
+above any transport layer, as long as it is a reliable one. @acronym{DTLS}
+can be used over reliable and unreliable transport layers.
+A set of functions is provided and their purpose is to load to @acronym{GnuTLS} the
required callbacks to access the transport layer.
-@itemize
-@item @funcref{gnutls_transport_set_push_function}
-@item @funcref{gnutls_transport_set_vec_push_function}
-@item @funcref{gnutls_transport_set_pull_timeout_function} (for @acronym{DTLS} only)
-@item @funcref{gnutls_transport_set_pull_function}
-@item @funcref{gnutls_transport_set_ptr}
-@item @funcref{gnutls_transport_set_errno}
-@end itemize
+@showfuncE{gnutls_transport_set_push_function,gnutls_transport_set_vec_push_function,gnutls_transport_set_pull_timeout_function,gnutls_transport_set_pull_function,gnutls_transport_set_ptr}
-These functions accept a callback function as a parameter. The
+The function @funcref{gnutls_transport_set_pull_timeout_function} is only applicable
+to @acronym{DTLS} sessions.
+All those functions accept a callback function as a parameter. The
callback functions should return the number of bytes written, or -1 on
error and should set @code{errno} appropriately.
In some environments, setting @code{errno} is unreliable, for example
Windows have several errno variables in different CRTs, or it may be
that errno is not a thread-local variable. If this is a concern to
-you, call @code{gnutls_transport_set_errno} with the intended errno
+you, call @funcref{gnutls_transport_set_errno} with the intended errno
value instead of setting @code{errno} directly.
+@showfuncA{gnutls_transport_set_errno}
+
@acronym{GnuTLS} currently only interprets the EINTR and EAGAIN errno
values and returns the corresponding @acronym{GnuTLS} error codes:
@itemize
blocking operation of @acronym{GnuTLS} during @acronym{DTLS} handshake
can be changed using the appropriate flags in @funcref{gnutls_init}.
+@showfuncdesc{gnutls_init}
+
By default, if the transport functions are not set, @acronym{GnuTLS}
-will use the Berkeley Sockets functions.
+will use the Berkeley sockets.
@node The TLS record protocol
@section The TLS Record Protocol
@cindex Record protocol
-The Record protocol is the secure communications provider. Its purpose
+The record protocol is the secure communications provider. Its purpose
is to encrypt, authenticate and ---optionally--- compress packets.
-The following functions are available:
-
-@table @asis
-
-@item @funcref{gnutls_record_send}:
-To send a record packet with application data.
-
-@item @funcref{gnutls_record_recv}:
-To receive a record packet with application data.
-@item @funcref{gnutls_record_recv_seq}:
-To receive a record packet with application data as well
-as the sequence number of that. This is useful in @acronym{DTLS}
-where packets might be lost or received out of order.
+@showfuncdesc{gnutls_record_send}
-@item @funcref{gnutls_record_get_direction}:
-To get the direction of the last interrupted function call.
-@end table
-
-In @acronym{TLS} those functions can be called at any time after
+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
timers used in the handshake out-of-order handshake data might
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
+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.
+@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
+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.
+@showfuncdesc{gnutls_record_recv}
+@showfuncdesc{gnutls_record_recv_seq}
+@showfuncdesc{gnutls_record_check_pending}
+@c @showfuncdesc{gnutls_record_get_direction}
+
@menu
* Encryption algorithms used in the record layer::
* Compression algorithms used in the record layer::
@end menu
@node Encryption algorithms used in the record layer
-@subsection Encryption Algorithms Used in the Record Layer
+@subsection Encryption Algorithms Used in the record layer
@cindex Symmetric encryption algorithms
Confidentiality in the record layer is achieved by using symmetric
@node Compression algorithms used in the record layer
-@subsection Compression Algorithms Used in the Record Layer
+@subsection Compression Algorithms Used in the record layer
@cindex Compression algorithms
The TLS record layer also supports compression. The algorithms
@node Weaknesses and countermeasures
@subsection Weaknesses and Countermeasures
-Some weaknesses that may affect the security of the Record layer have
+Some weaknesses that may affect the security of the record layer have
been found in @acronym{TLS} 1.0 protocol. These weaknesses can be
exploited by active attackers, and exploit the facts that
@cindex Record padding
@cindex Bad record MAC
-The TLS protocol allows for random padding of records, to make it more
-difficult to perform analysis on the length of exchanged messages (see @xcite{RFC5246} section 6.2.3.2).
+The TLS protocol allows for random padding of records, 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.
GnuTLS implements a work around for this problem. However, it has to
be enabled specifically. It can be enabled by using
@funcref{gnutls_record_disable_padding}, or @funcref{gnutls_priority_set} with
-the @code{%COMPAT} priority string.
+the @code{%COMPAT} priority string (see @ref{Priority Strings}).
If you implement an application that have a configuration file, we
recommend that you make it possible for users or administrators to
flexibility, make it possible to have a different priority string for
different incoming IP addresses.
-To enable the workaround in the @command{gnutls-cli} client or the
-@command{gnutls-serv} server, for testing of other implementations, use
-the parameter: @option{--priority "NORMAL:%COMPAT"}.
-
@node The TLS Alert Protocol
@section The TLS Alert Protocol
@anchor{The Alert Protocol}
@cindex Alert protocol
-The Alert protocol is there to allow signals to be sent between peers.
+The alert protocol is there to allow signals to be sent between peers.
These signals are mostly used to inform the peer about the cause of a
protocol failure. Some of these signals are used internally by the
protocol and the application protocol does not have to cope with them
application protocol solely (e.g. @code{GNUTLS_A_USER_CANCELLED}). An
alert signal includes a level indication which may be either fatal or
warning. Fatal alerts always terminate the current connection, and
-prevent future renegotiations using the current session ID.
+prevent future renegotiations using the current session ID. All alert
+messages are summarized in @ref{tab:alerts}.
+
The alert messages are protected by the record protocol, thus the
information that is included does not leak. You must take extreme care
for the alert information not to leak to a possible attacker, via
-public log files etc.
+public log files etc. The available functions to control the alert
+protocol are shown below.
-@table @asis
-@item @funcref{gnutls_alert_send}:
-To send an alert signal.
+@showfuncdesc{gnutls_alert_get}
-@item @funcref{gnutls_error_to_alert}:
-To map a gnutls error number to an alert signal.
+@showfuncdesc{gnutls_alert_send}
-@item @funcref{gnutls_alert_get}:
-Returns the last received alert.
+@showfuncB{gnutls_error_to_alert,gnutls_alert_get_name}
-@item @funcref{gnutls_alert_get_name}:
-Returns the name, in a character array, of the given alert.
+@include alerts.texi
-@end table
@node The TLS Handshake Protocol
@section The TLS Handshake Protocol
@anchor{The Handshake Protocol}
@cindex Handshake protocol
-The Handshake protocol is responsible for the ciphersuite negotiation,
+The handshake protocol is responsible for the ciphersuite negotiation,
the initial key exchange, and the authentication of the two peers.
This is fully controlled by the application layer, thus your program
-has to set up the required parameters. Available functions to control
-the handshake protocol include:
+has to set up the required parameters. The main handshake function
+is @funcref{gnutls_handshake}. In the next paragraphs we elaborate on
+controlling of the handshake protocol, i.e., the ciphersuite negotiation.
-@table @asis
-@item @funcref{gnutls_priority_init}:
-To initialize a priority set of ciphers.
-
-@item @funcref{gnutls_priority_deinit}:
-To deinitialize a priority set of ciphers.
-
-@item @funcref{gnutls_priority_set}:
-To associate a priority set with a @acronym{TLS} session.
-
-@item @funcref{gnutls_priority_set_direct}:
-To directly associate a session with a given priority string.
+@showfuncdesc{gnutls_handshake}
-@item @funcref{gnutls_credentials_set}:
-To set the appropriate credentials structures.
-
-@item @funcref{gnutls_certificate_server_set_request}:
-To set whether client certificate is required or not.
-
-@item @funcref{gnutls_handshake}:
-To initiate the handshake.
-@end table
@menu
* TLS Cipher Suites:: TLS session parameters.
* Priority Strings:: Defining how parameters are negotiated.
* Client Authentication:: Requesting a certificate from the client.
* Resuming Sessions:: Reusing previously established keys.
-* Resuming Internals:: More information on reusing previously established keys.
* Interoperability:: About interoperability with other implementations.
@end menu
@node TLS Cipher Suites
@subsection TLS Cipher Suites
-The Handshake Protocol of @acronym{TLS} negotiates cipher suites of
+The handshake protocol of @acronym{TLS} negotiates cipher suites of
a special form illustrated by the @code{TLS_DHE_RSA_WITH_3DES_CBC_SHA} cipher suite name. A typical cipher
suite contains these parameters:
@end itemize
The cipher suite negotiated in the handshake protocol will affect the
-Record Protocol, by enabling encryption and data authentication. Note
+record protocol, by enabling encryption and data authentication. Note
that you should not over rely on @acronym{TLS} to negotiate the
strongest available cipher suite. Do not enable ciphers and algorithms
that you consider weak.
-All the supported ciphersuites are shown in @ref{ciphersuites}.
+All the supported ciphersuites are listed in @ref{ciphersuites}.
@node Priority Strings
@subsection Priority Strings
-In order to specify cipher suite preferences, the
+In order to specify cipher suite preferences on client or server side, the
previously shown priority functions accept a string
-that specifies the algorithms to be enabled in a TLS handshake.
+that specifies the enable for the handshake algorithms.
That string may contain some high level keyword such as
-the keywords in @ref{tab:prio-keywords}.
+the keywords in @ref{tab:prio-keywords}
+or it might contain special keywords, to be explained
+later on.
+
+@showfuncD{gnutls_priority_set_direct,gnutls_priority_init,gnutls_priority_deinit,gnutls_priority_set}
@float Table,tab:prio-keywords
@multitable @columnfractions .30 .70
@caption{Supported priority string keywords.}
@end float
-or it might contain special keywords, that will be explained
-later on.
-
Unless the first keyword is "NONE" the defaults (in preference
order) are for TLS protocols TLS 1.2, TLS1.1, TLS1.0, SSL3.0; for
compression NULL; for certificate types X.509, OpenPGP.
are enabled (except for the RSA-EXPORT which is only enabled in
EXPORT level).
-The NONE keyword is followed by the algorithms to be enabled,
-and is used to provide the exact list of requested algorithms@footnote{
-To avoid collisions in order to specify a compression algorithm in
+The NONE keyword must followed by the algorithms to be enabled,
+and is used to provide the exact list of requested algorithms@footnote{To avoid collisions in order to specify a compression algorithm in
this string you have to prefix it with "COMP-", protocol versions
with "VERS-", signature algorithms with "SIGN-" and certificate types with "CTYPE-". All other
algorithms don't need a prefix.}. The order with which every algorithm
is specified is significant. Similar algorithms specified before others
will take precedence. The individual algorithms are shown in @ref{tab:prio-algorithms}
and special keywords are in @ref{tab:prio-special}.
-
-
-Keywords prepended to individual algorithms:
+The prefixes for individual algorithms are:
@table @asis
-
@item '!' or '-'
appended with an algorithm will remove this algorithm.
-
@item "+"
appended with an algorithm will add this algorithm.
-
@end table
In the case of ciphersuites that use certificate authentication, the
authentication of the client is optional in @acronym{TLS}. A server
-may request a certificate from the client --- using the
+may request a certificate from the client using the
@funcref{gnutls_certificate_server_set_request} function. If a certificate
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
-by the server. That is the ones set using
-@itemize
-@item @funcref{gnutls_certificate_set_x509_trust_file}
-@item @funcref{gnutls_certificate_set_x509_trust_mem}
-@end itemize
+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}
-Sending of the names of the certificate authorities can be controlled using the function
-@funcref{gnutls_certificate_send_x509_rdn_sequence}. The client, then, may
-send a certificate, signed by one of the server's acceptable signers.
+@showfuncdesc{gnutls_certificate_server_set_request}
+
+In cases where the server supports a large number of certificate authorities
+it makes sense not to advertize all of the names to save bandwidth. That can
+be controlled using the function @funcref{gnutls_certificate_send_x509_rdn_sequence}.
+This however will have the side-effect of not restricting the client to certificates
+signed by server's acceptable signers.
+
+@showfuncdesc{gnutls_certificate_send_x509_rdn_sequence}
@node Resuming Sessions
@subsection Resuming Sessions
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. @strong{Session
-resuming} is a feature of the @acronym{TLS} protocol which allows a
+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 expensive calculations. This is achieved by using the previously
+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.
-Keep in mind that sessions are expired after some time, for security
-reasons, thus it may be normal for a server not to resume a session
-even if you requested that. Also note that you must enable, using the
+Keep in mind that sessions might be expired after some time,
+thus it may be normal for a server not to resume a session
+even if you requested that. That is to prevent temporal session keys
+from becoming long-term keys. Also note that as a client you must enable, using the
priority functions, at least the algorithms used in the last session.
-@node Resuming Internals
-@subsection Resuming Internals
-
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
-necessary parameters. See the functions:
+necessary parameters. The relevant functions are listed below.
-@itemize
+@showfuncdesc{gnutls_session_get_data}
-@item @funcref{gnutls_session_get_data}
+@showfuncdesc{gnutls_session_get_id}
-@item @funcref{gnutls_session_get_id}
+@showfuncdesc{gnutls_session_set_data}
-@item @funcref{gnutls_session_set_data}
-
-@end itemize
-
-The server side is different. A server has to specify some callback
+Server side is different. A server needs to specify callback
functions which store, retrieve and delete session data. These can be
-registered with:
+registered with the functions shown below.
-@itemize
+@showfuncdesc{gnutls_db_set_retrieve_function}
-@item @funcref{gnutls_db_set_remove_function}
+@showfuncdesc{gnutls_db_set_store_function}
-@item @funcref{gnutls_db_set_store_function}
-
-@item @funcref{gnutls_db_set_retrieve_function}
-
-@item @funcref{gnutls_db_set_ptr}
-
-@end itemize
+@showfuncB{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}
+
@node Interoperability
@subsection Interoperability
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.
-We suggest however only to use this mode if compatibility issues occur.
+We suggest however only to use this mode if compatibility is preferred over
+security.
@node TLS Extensions
@section TLS Extensions
This extension allows a @acronym{TLS} implementation to negotiate a
smaller value for record packet maximum length. This extension may be
-useful to clients with constrained capabilities. See the functions:
-@itemize
-@item @funcref{gnutls_record_set_max_size}
-@item @funcref{gnutls_record_get_max_size}
-@end itemize
+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}
@subsection Server Name Indication
@anchor{serverind}
used to enable this extension, or to retrieve the name sent by a
client.
+@showfuncdesc{gnutls_server_name_set}
+
+@showfuncdesc{gnutls_server_name_get}
+
@subsection Session Tickets
@cindex TLS Extensions
@cindex Session Tickets
Clients resume sessions using the ticket using the normal session
resume functions, @ref{resume}.
+@showfuncdesc{gnutls_session_ticket_key_generate}
+
+@showfuncdesc{gnutls_session_ticket_enable_server}
+
+@showfuncdesc{gnutls_session_ticket_enable_client}
+
@subsection Safe Renegotiation
@cindex renegotiation
authentication.
@float Table,tab:key-sizes
-@multitable @columnfractions .10 .15 .10 .20 .35
+@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
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.
-
-NIST publication SP 800-57 @xcite{NISTSP80057} contains a similar
+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:
-@itemize
-@item @funcref{gnutls_pk_bits_to_sec_param}
+@showfuncdesc{gnutls_sec_param_to_pk_bits}
-@item @funcref{gnutls_sec_param_to_pk_bits}
+@showfuncdesc{gnutls_pk_bits_to_sec_param}
-@end itemize
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.
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 suggested.
+is not the case, the use of the operating system defaults is recommended. Examples
+are shown below.
-There are helper macros to help you properly initialize the libraries.
-Examples are shown in the following paragraphs.
-
-@subsection Native threads
@example
#include <gnutls.h>
+/* Native threads
+ */
+
int main()
@{
gnutls_global_init();
@}
@end example
-@subsection Other thread packages
@example
+#include <gnutls.h>
+
+/* Other thread packages
+ */
int main()
@{
which are used to specify the functions that will retrieve and send
data to the transport layer.
-@itemize
-
-@item @funcref{gnutls_transport_set_push_function}
-
-@item @funcref{gnutls_transport_set_pull_function}
-
-@end itemize
+@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.
-@itemize
-
-@item @funcref{gnutls_malloc}
-
-@item @funcref{gnutls_free}
+@showfuncB{gnutls_malloc,gnutls_free}
-@end itemize
@ref{\ref\}
@end macro
+@macro showfuncA{ref}
+@itemize
+@item @ref{\ref\}
+@end itemize
+@end macro
+
+@macro showfuncB{ref1,ref2}
+@itemize
+@item @ref{\ref1\}
+@item @ref{\ref2\}
+@end itemize
+@end macro
+
+@macro showfuncC{ref1,ref2,ref3}
+@itemize
+@item @ref{\ref1\}
+@item @ref{\ref2\}
+@item @ref{\ref3\}
+@end itemize
+@end macro
+
+@macro showfuncD{ref1,ref2,ref3,ref4}
+@itemize
+@item @ref{\ref1\}
+@item @ref{\ref2\}
+@item @ref{\ref3\}
+@item @ref{\ref4\}
+@end itemize
+@end macro
+
+@macro showfuncE{ref1,ref2,ref3,ref4,ref5}
+@itemize
+@item @ref{\ref1\}
+@item @ref{\ref2\}
+@item @ref{\ref3\}
+@item @ref{\ref4\}
+@item @ref{\ref5\}
+@end itemize
+@end macro
+
+@macro showfuncF{ref1,ref2,ref3,ref4,ref5,ref6}
+@itemize
+@item @ref{\ref1\}
+@item @ref{\ref2\}
+@item @ref{\ref3\}
+@item @ref{\ref4\}
+@item @ref{\ref5\}
+@item @ref{\ref6\}
+@end itemize
+@end macro
+
+@macro showfuncdesc{ref}
+@itemize
+@item @ref{\ref\}
+@end itemize
+@end macro
+
@contents
@ifnottex
GEN_TEX_OBJECTS = cha-preface.tex cha-library.tex cha-intro-tls.tex cha-auth.tex \
cha-cert-auth.tex cha-gtls-app.tex cha-tls-app.tex cha-programs.tex cha-support.tex \
cha-functions.tex error_codes.tex cha-ciphersuites.tex algorithms.tex \
- cha-errors.tex
+ cha-errors.tex alerts.tex
cha-preface.tex: ../cha-preface.texi
../scripts/mytexi2latex $< > $@
$(builddir)/../errcodes --latex > $@-tmp
mv -f $@-tmp $@
-algorithms.tex: $(srcdir)/../printlist.c $(builddir)/../printlist
+algorithms.tex: ../printlist
$(builddir)/../printlist --latex > $@-tmp
mv -f $@-tmp $@
+alerts.tex: ../alert-printlist
+ $(builddir)/../alert-printlist --latex > $@-tmp
+ mv -f $@-tmp $@
+
gnutls-api.tex: $(srcdir)/../../lib/*.c $(srcdir)/../../lib/ext/*.c $(srcdir)/../../lib/auth/*.c $(srcdir)/../../lib/algorithms/*.c
echo "" > $@-tmp
for i in $^; do \
echo "ok"; \
done
$(srcdir)/../scripts/sort1.pl < $@-tmp > $@-tmp2
+ $(srcdir)/../scripts/split.pl functions < $@-tmp
rm -f $@-tmp
mv -f $@-tmp2 $@
echo "ok"; \
done
$(srcdir)/../scripts/sort1.pl < $@-tmp > $@-tmp2
+ $(srcdir)/../scripts/split.pl functions < $@-tmp
rm -f $@-tmp
mv -f $@-tmp2 $@
echo "ok"; \
done
$(srcdir)/../scripts/sort1.pl < $@-tmp > $@-tmp2
+ $(srcdir)/../scripts/split.pl functions < $@-tmp
rm -f $@-tmp
mv -f $@-tmp2 $@
echo "ok"; \
done
$(srcdir)/../scripts/sort1.pl < $@-tmp > $@-tmp2
+ $(srcdir)/../scripts/split.pl functions < $@-tmp
rm -f $@-tmp
mv -f $@-tmp2 $@
clean-am:
rm -f $(GEN_TEX_OBJECTS) $(SOURCE_GEN_FILES) gnutls.aux gnutls.bbl gnutls.blg gnutls.idx gnutls.ilg gnutls.ind gnutls.log gnutls.out gnutls.toc
+ rm -rf functions
+
-\documentclass{book}
+\documentclass[letterpaper,10pt]{book}
\bibliographystyle{plain}
-\usepackage{html}
\usepackage{fancyhdr}
\usepackage{graphicx}
\usepackage{makeidx}
\usepackage{supertabular}
\usepackage{color}
-\usepackage{colortbl}
\usepackage{fancyvrb}
\usepackage{eurosans}
\usepackage{parskip}
\usepackage{hyperref}
+\usepackage{framed}
+\usepackage{verbatim}
+\usepackage{listings}
+\usepackage{xcolor}
+\usepackage[greek,english]{babel}%for euro sign
+
\hypersetup{
colorlinks,%
%\hyperref[#2]{#1()}%
\code{#1}%
}
+
+\newcommand{\showfunc}[1]{%
+ \let\Oldfd\functionDescription
+ \let\Oldendfd\endfunctionDescription
+ \let\functionDescription=\comment
+ \let\endfunctionDescription=\endcomment
+ \let\Oldfr\functionReturns
+ \let\Oldendfr\endfunctionReturns
+ \let\functionReturns=\comment
+ \let\endfunctionReturns=\endcomment
+\texttt{
+ \input{functions/#1}
+}
+ \let\functionDescription=\Oldfd
+ \let\endfunctionDescription=\Oldendfd
+ \let\functionReturns=\Oldfr
+ \let\endfunctionReturns=\Oldendfr
+}
+
+\newcommand{\showfuncdesc}[1]{%
+%\fcolorbox{black}{light-gray}{
+ \begin{minipage}[l]{\linewidth}
+ \begin{framed}
+ \texttt{
+ \input{functions/#1}
+ }
+% }
+ \end{framed}
+ \vspace{0.15cm}
+ \end{minipage}
+}
+
+\newcommand{\showfuncA}[1]{%
+% \fcolorbox{black}{light-gray}{
+ \begin{samepage}
+ \begin{framed}
+ \texttt{
+ \showfunc{#1}
+ }
+% }
+ \end{framed}
+ \end{samepage}
+}
+
+\newcommand{\showfuncB}[2]{%
+% \fcolorbox{black}{light-gray}{
+ \begin{samepage}
+ \begin{framed}
+ \texttt{
+ \showfunc{#1}
+ \showfunc{#2}
+ }
+% }
+ \end{framed}
+ \end{samepage}
+}
+
+\newcommand{\showfuncC}[3]{%
+% \fcolorbox{black}{light-gray}{
+ \begin{samepage}
+ \begin{framed}
+ \texttt{
+ \showfunc{#1}
+ \showfunc{#2}
+ \showfunc{#3}
+ }
+% }
+ \end{framed}
+ \end{samepage}
+}
+
+\newcommand{\showfuncD}[4]{%
+% \fcolorbox{black}{light-gray}{
+ \begin{samepage}
+ \begin{framed}
+ \texttt{
+ \showfunc{#1}
+ \showfunc{#2}
+ \showfunc{#3}
+ \showfunc{#4}
+ }
+% }
+ \end{framed}
+ \end{samepage}
+}
+
+\newcommand{\showfuncE}[5]{%
+% \fcolorbox{black}{light-gray}{
+ \begin{samepage}
+ \begin{framed}
+ \texttt{
+ \showfunc{#1}
+ \showfunc{#2}
+ \showfunc{#3}
+ \showfunc{#4}
+ \showfunc{#5}
+ }
+% }
+ \end{framed}
+ \end{samepage}
+}
+
+\newcommand{\showfuncF}[6]{%
+% \fcolorbox{black}{light-gray}{
+ \begin{samepage}
+ \begin{framed}
+ \texttt{
+ \showfunc{#1}
+ \showfunc{#2}
+ \showfunc{#3}
+ \showfunc{#4}
+ \showfunc{#5}
+ \showfunc{#6}
+ }
+% }
+ \end{framed}
+ \end{samepage}
+}
+
+\newenvironment{function}%
+ {\begin{minipage}[l]{1\linewidth}}%
+ {\end{minipage}}
+
+\let\functionArguments=\comment
+\let\endfunctionArguments=\endcomment
+
+\let\functionExamples=\comment
+\let\endfunctionExamples=\endcomment
+
+\newenvironment{functionDescription}%
+{\vspace{0.5cm}{\bf Description:}\footnotesize}
+{}
+
+\newcommand{\functionTitle}[1]{}
+
+\newenvironment{functionReturns}%
+{\vspace{0.5cm}{\bf Returns:}\footnotesize}
+{}
+
+\let\functionSince=\comment
+\let\endfunctionSince=\endcomment
+
$func =~ s/_/\\_/g;
- print "\n\n\\subsection{". $func . "}\n\\label{" . $args{'function'} . "}\n";
+ print "\n\n\\begin{function}\n";
+ print "\\functionTitle{". $func . "}\n";
$type = $args{'functiontype'};
$type =~ s/_/\\_/g;
}
print ")\n";
- print "\n{\\large{Arguments}}\n";
+ print "\n\\begin{functionArguments}\n";
- print "\\begin{itemize}\n";
$check=0;
foreach $parameter (@{$args{'parameterlist'}}) {
$param1 = $args{'parametertypes'}{$parameter};
$param2 =~ s/_/\\_/g;
$check = 1;
- print "\\item {\\it ".$param1."} {\\bf ".$param2."}: \n";
+ print "\\functionArgument {\\it ".$param1."} {\\bf ".$param2."}: \n";
# print "\n";
$param3 = $args{'parameters'}{$parameter};
- $param3 =~ s/#([a-zA-Z\_]+)/{\\it \1}/g;
+ $param3 =~ s/\#([a-zA-Z\_]+)/{\\it $1}/g;
+ $param3 =~ s/\%([a-zA-Z\_]+)/{\\bf $1}/g;
$out = just_highlight($param3);
$out =~ s/_/\\_/g;
if ($check==0) {
print "\\item void\n";
}
- print "\\end{itemize}\n";
+ print "\\end{functionArguments}\n";
foreach $section (@{$args{'sectionlist'}}) {
$sec = $section;
$sec =~ s/_/\\_/g;
$sec =~ s/#([a-zA-Z\_]+)/{\\it \1}/g;
- print "\n{\\large{$sec}}\\\\\n";
- print "\\begin{rmfamily}\n";
+ print "\n\\begin{function$sec}\n";
+ $out = $args{'sections'}{$section};
- $sec = $args{'sections'}{$section};
- $sec =~ s/\\:/:/g;
- $sec =~ s/#([a-zA-Z\_]+)/{\\it \1}/g;
- $sec =~ s/->/\$\\rightarrow\$/g;
- $sec =~ s/([0-9]+)\^([0-9]+)/\$\{\1\}\^\{\2\}\$/g;
-
- $out = just_highlight($sec);
+ $out =~ s/\#([a-zA-Z\_]+)/{\\it $1}/g;
+ $out =~ s/\%([a-zA-Z\_]+)/{\\bf $1}/g;
+ $out =~ s/\@([a-zA-Z\_]+)/{\\bf $1}/g;
$out =~ s/_/\\_/g;
+ $out =~ s/#/\\#/g;
+ $out =~ s/\n\n/\n/g;
+ $out =~ s/\\:/:/g;
+ $out =~ s/\-\>/\$\\rightarrow\$/g;
+ $out =~ s/([0-9]+)\^([0-9]+)/\$\{\1\}\^\{\2\}\$/g;
print $out;
- print "\\end{rmfamily}\n";
+ print "\\end{function$sec}\n";
}
- print "\n";
+ print "\\end{function}\n\n";
}
my $prefix = $_[0];
my $suffix=$_[0];
$suffix =~ s/\\//g;
+ $prefix =~ s/\\_/\\_\\-/g;
return "\\funcref\{$prefix\}\{$suffix\}";
}
+sub showfunc()
+{
+my $prefix = $_[0];
+my $suffix = $_[1];
+ $suffix =~ s/\\//g;
+ $suffix =~ s/\,/\}\{/g;
+ return "\\showfunc$prefix\{$suffix\}";
+}
+
+sub showfuncdesc()
+{
+my $suffix = $_[0];
+ $suffix =~ s/\\//g;
+ return "\\showfuncdesc\{$suffix\}";
+}
+
my $punescape = \&unescape;
my $pfuncref = \&funcref;
+my $pshowfunc = \&showfunc;
+my $pshowfuncdesc = \&showfuncdesc;
my $mode;
my $num_args = $#ARGV + 1;
my $spacematch = "[\\s\\w\\d-\\.\\/\\@\\#\\:]";
my $mathmatch = "[\\s\\w\\d-\\.\\/\\:\\(\\)\\+\\/\\^\\'\\=\{\}\\\\\\,]";
my $underscorematch = "[\\s\\w\\d-\\.\\/\\@\\_\\\\\:\\~]";
-my $codematch = "[\\s\\w\\d-\\.\\/\\@\\_\\\\\:\\-\\\"\+\\%]";
+my $codematch = "[\\s\\w\\d-\\.\\/\\@\\_\\\\\:\\-\\\"\+\\%\\,]";
my ($line, $prev_mode);
my ($verbatim, $label);
my @stack = ();
$line =~ s/\@cindex (.+)/\\index{$1}/g;
$line =~ s/\@url\{($underscorematch+)\}/\\url{$1}/g;
#$line =~ s/\@euro/\\euro/g;
- $line =~ s/\@euro\{\}/euro/g;
+ $line =~ s/\s*\@euro\{\}/\~\\textgreek\{\\euro\}/g;
+ $line =~ s/\@page/\\newpage/g;
$line =~ s/\@file\{($spacematch+)\}/\\file{$1}/g;
$line =~ s/\@code\{($codematch+)\}/\\code{$1}/g;
$line =~ s/\@option\{($codematch+)\}/\\command{$1}/g;
$line =~ s/\@emph\{($spacematch+)\}/\\emph{$1}/g;
$line =~ s/\@xref\{/\\myref\{/g;
$line =~ s/\@funcref\{($codematch+)\}/$pfuncref->($1)/ge;
+ $line =~ s/\@showfunc([A-Z])\{($codematch+)\}/$pshowfunc->($1,$2)/ge;
+ $line =~ s/\@showfuncdesc\{($codematch+)\}/$pshowfuncdesc->($1)/ge;
$line =~ s/\@pxref\{/\\myref\{/g;
$line =~ s/\@center (.*)/\\begin{center}\n$1\n\\end{center}/g;
if ($line =~ m/\@email/) {
my ($i) = 1;
my ($key) = $lines[$i];
- while( !($key =~ m/^\\label(.*)/) && ($i < 5)) { $i=$i+1; $key = $lines[$i]; }
+ while( !($key =~ m/^\\functionTitle\{(.*)\}/) && ($i < 5)) { $i=$i+1; $key = $lines[$i]; }
return $key;
}
-$/="\n\n\n"; # Records are separated by blank lines.
+$/="\n\\end{function}"; # Records are separated by blank lines.
@records = <>; # Read in whole file, one record per array element.
@records = sort { key_of_record($a) cmp key_of_record($b) } @records;
--- /dev/null
+#!/usr/bin/perl
+
+$dir = shift;
+
+sub key_of_record {
+ local($record) = @_;
+
+ # Split record into lines:
+ my @lines = split /\n/, $record;
+
+ my ($i) = 1;
+ my ($key) = $lines[$i];
+
+ while( !($key =~ m/^\\functionTitle\{(.*)\}/) && ($i < 5)) { $i=$i+1; $key = $lines[$i]; }
+
+ return $key;
+}
+
+$/="\n\\end{function}"; # Records are separated by blank lines.
+@records = <>; # Read in whole file, one record per array element.
+
+mkdir $dir;
+
+@records = sort { key_of_record($a) cmp key_of_record($b) } @records;
+foreach (@records) {
+ $key = $_;
+ $key =~ m/\\functionTitle\{(.*)\}/;
+
+ $key = $1;
+ $key =~ s/\\_/_/g;
+
+ if (defined $key && $key ne "") {
+ open FILE, "> $dir/$key\n" or die $!;
+ print FILE $_ . "\n";
+ close FILE;
+ }
+}
+
+#print @records;
*
* This function sets a certificate/private key pair in the
* gnutls_certificate_credentials_t structure. This function may be called
- * more than once (in case multiple keys/certificates exist for the
- * server).
- *
- * Currently are supported: RSA PKCS-1 encoded private keys,
- * DSA private keys.
- *
- * DSA private keys are encoded the OpenSSL way, which is an ASN.1
- * DER sequence of 6 INTEGERs - version, p, q, g, pub, priv.
+ * more than once, in case multiple keys/certificates exist for the
+ * server.
*
* Note that the keyUsage (2.5.29.15) PKIX extension in X.509 certificates
* is supported. This means that certificates intended for signing cannot
* The @key may be %NULL if you are using a sign callback, see
* gnutls_sign_callback_set().
*
- * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
+ * Returns: %GNUTLS_E_SUCCESS (0) on success, or a negative error code.
**/
int
gnutls_certificate_set_x509_key_mem (gnutls_certificate_credentials_t res,
*
* This function sets a certificate/private key pair in the
* gnutls_certificate_credentials_t structure. This function may be
- * called more than once (in case multiple keys/certificates exist for
- * the server). For clients that wants to send more than its own end
+ * called more than once, in case multiple keys/certificates exist for
+ * the server. For clients that wants to send more than its own end
* entity certificate (e.g., also an intermediate CA cert) then put
* the certificate chain in @cert_list.
*
*
*
- * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
+ * Returns: %GNUTLS_E_SUCCESS (0) on success, or a negative error code.
*
* Since: 2.4.0
**/
*
* This function sets a certificate/private key pair in the
* gnutls_certificate_credentials_t structure. This function may be
- * called more than once (in case multiple keys/certificates exist for
- * the server). For clients that wants to send more than its own end
- * entity certificate (e.g., also an intermediate CA cert) then put
- * the certificate chain in @certfile.
+ * called more than once, in case multiple keys/certificates exist for
+ * the server. For clients that need to send more than its own end
+ * entity certificate, e.g., also an intermediate CA cert, then the
+ * @certfile must contain the ordered certificate chain.
*
- * Currently only PKCS-1 encoded RSA and DSA private keys are accepted by
- * this function.
+ * This function can also accept PKCS #11 URLs at @keyfile and @certfile. In that case it
+ * will import the private key and certificate indicated by the URLs.
*
- * This function can also accept PKCS #11 URLs. In that case it
- * will import the private key and certificate indicated by the urls.
- *
- * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
+ * Returns: %GNUTLS_E_SUCCESS (0) on success, or a negative error code.
**/
int
gnutls_certificate_set_x509_key_file (gnutls_certificate_credentials_t res,
* a certificate request is sent. This can be disabled using
* gnutls_certificate_send_x509_rdn_sequence().
*
- * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
+ * Returns: %GNUTLS_E_SUCCESS (0) on success, or a negative error code.
*
* Since: 2.4.0
**/
* gnutls_certificate_verify_peers2(). This function may be called
* multiple times.
*
- * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
+ * Returns: %GNUTLS_E_SUCCESS (0) on success, or a negative error code.
*
* Since: 2.4.0
**/
* only password based security, and the same password for all
* operations, are supported.
*
- * The private keys may be RSA PKCS#1 or DSA private keys encoded in
- * the OpenSSL way.
- *
* PKCS#12 file may contain many keys and/or certificates, and there
* is no way to identify which key/certificate pair you want. You
* should make sure the PKCS#12 file only contain one key/certificate
* complexity that would make it harder to use this functionality at
* all.
*
- * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
+ * Returns: %GNUTLS_E_SUCCESS (0) on success, or a negative error code.
**/
int
gnutls_certificate_set_x509_simple_pkcs12_file
* only password based security, and the same password for all
* operations, are supported.
*
- * The private keys may be RSA PKCS#1 or DSA private keys encoded in
- * the OpenSSL way.
- *
* PKCS#12 file may contain many keys and/or certificates, and there
* is no way to identify which key/certificate pair you want. You
* should make sure the PKCS#12 file only contain one key/certificate
* complexity that would make it harder to use this functionality at
* all.
*
- * Returns: %GNUTLS_E_SUCCESS on success, or an error code.
+ * Returns: %GNUTLS_E_SUCCESS (0) on success, or a negative error code.
*
* Since: 2.8.0
**/
projects / thirdparty / gnutls.git / commitdiff
