1939
1978
@node Digital signatures
1940
1979
@section Digital Signatures
1941
1980
@cindex Digital signatures
1942
@include signatures.texi
1982
In this section we will provide some information about digital
1983
signatures, how they work, and give the rationale for disabling some
1984
of the algorithms used.
1986
Digital signatures work by using somebody's secret key to sign some
1987
arbitrary data. Then anybody else could use the public key of that
1988
person to verify the signature. Since the data may be arbitrary it is
1989
not suitable input to a cryptographic digital signature algorithm. For
1990
this reason and also for performance cryptographic hash algorithms are
1991
used to preprocess the input to the signature algorithm. This works as
1992
long as it is difficult enough to generate two different messages with
1993
the same hash algorithm output. In that case the same signature could
1994
be used as a proof for both messages. Nobody wants to sign an innocent
1995
message of donating 1 @euro{} to Greenpeace and find out that he
1996
donated 1.000.000 @euro{} to Bad Inc.
1998
For a hash algorithm to be called cryptographic the following three
1999
requirements must hold:
2002
@item Preimage resistance.
2003
That means the algorithm must be one way and given the output of the
2004
hash function @math{H(x)}, it is impossible to calculate @math{x}.
2006
@item 2nd preimage resistance.
2007
That means that given a pair @math{x,y} with @math{y=H(x)} it is
2008
impossible to calculate an @math{x'} such that @math{y=H(x')}.
2010
@item Collision resistance.
2011
That means that it is impossible to calculate random @math{x} and
2012
@math{x'} such @math{H(x')=H(x)}.
2015
The last two requirements in the list are the most important in
2016
digital signatures. These protect against somebody who would like to
2017
generate two messages with the same hash output. When an algorithm is
2018
considered broken usually it means that the Collision resistance of
2019
the algorithm is less than brute force. Using the birthday paradox the
2020
brute force attack takes
2022
@math{2^{(\rm{hash\ size}) / 2}}
2025
@math{2^{((hash size) / 2)}}
2027
operations. Today colliding certificates using the MD5 hash algorithm
2028
have been generated as shown in @xcite{WEGER}.
2030
There has been cryptographic results for the SHA-1 hash algorithms as
2031
well, although they are not yet critical. Before 2004, MD5 had a
2032
presumed collision strength of @math{2^{64}}, but it has been showed
2033
to have a collision strength well under @math{2^{50}}. As of November
2034
2005, it is believed that SHA-1's collision strength is around
2035
@math{2^{63}}. We consider this sufficiently hard so that we still
2036
support SHA-1. We anticipate that SHA-256/386/512 will be used in
2037
publicly-distributed certificates in the future. When @math{2^{63}}
2038
can be considered too weak compared to the computer power available
2039
sometime in the future, SHA-1 will be disabled as well. The collision
2040
attacks on SHA-1 may also get better, given the new interest in tools
2043
@subsection Trading Security for Interoperability
2045
If you connect to a server and use GnuTLS' functions to verify the
2046
certificate chain, and get a @ref{GNUTLS_CERT_INSECURE_ALGORITHM}
2047
validation error (@pxref{Verifying X.509 certificate paths}), it means
2048
that somewhere in the certificate chain there is a certificate signed
2049
using @code{RSA-MD2} or @code{RSA-MD5}. These two digital signature
2050
algorithms are considered broken, so GnuTLS fail when attempting to
2051
verify the certificate. In some situations, it may be useful to be
2052
able to verify the certificate chain anyway, assuming an attacker did
2053
not utilize the fact that these signatures algorithms are broken.
2054
This section will give help on how to achieve that.
2056
First, it is important to know that you do not have to enable any of
2057
the flags discussed here to be able to use trusted root CA
2058
certificates signed using @code{RSA-MD2} or @code{RSA-MD5}. The only
2059
attack today is that it is possible to generate certificates with
2060
colliding signatures (collision resistance); you cannot generate a
2061
certificate that has the same signature as an already existing
2062
signature (2nd preimage resistance).
2064
If you are using @ref{gnutls_certificate_verify_peers2} to verify the
2065
certificate chain, you can call
2066
@ref{gnutls_certificate_set_verify_flags} with the
2067
@code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2} or
2068
@code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5} flag, as in:
2071
gnutls_certificate_set_verify_flags (x509cred,
2072
GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5);
2075
This will tell the verifier algorithm to enable @code{RSA-MD5} when
2076
verifying the certificates.
2078
If you are using @ref{gnutls_x509_crt_verify} or
2079
@ref{gnutls_x509_crt_list_verify}, you can pass the
2080
@code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5} parameter directly in the
2081
@code{flags} parameter.
2083
If you are using these flags, it may also be a good idea to warn the
2084
user when verification failure occur for this reason. The simplest is
2085
to not use the flags by default, and only fall back to using them
2086
after warning the user. If you wish to inspect the certificate chain
2087
yourself, you can use @ref{gnutls_certificate_get_peers} to extract
2088
the raw server's certificate chain, then use
2089
@ref{gnutls_x509_crt_import} to parse each of the certificates, and
2090
then use @ref{gnutls_x509_crt_get_signature_algorithm} to find out the
2091
signing algorithm used for each certificate. If any of the
2092
intermediary certificates are using @code{GNUTLS_SIGN_RSA_MD2} or
2093
@code{GNUTLS_SIGN_RSA_MD5}, you could present a warning.
1945
2097
@node How to use TLS in application protocols
2183
2352
@section Multi-Threaded Applications
2185
2354
Although the @acronym{GnuTLS} library is thread safe by design, some
2186
parts of the crypto backend, such as the random generator, are
2187
not. Since @emph{libgcrypt 1.1.92} there was an automatic detection of
2188
the thread library used by the application, so most applications
2189
wouldn't need to do any changes to ensure thread-safety. Due to the
2190
unportability of the automatic thread detection, this was removed from
2191
later releases of @emph{libgcrypt}, so applications have now to
2192
register callback functions to ensure proper locking in sensitive
2193
parts of @emph{libgcrypt}.
2355
parts of Libgcrypt, such as the random generator, are not.
2356
Applications have to register callback functions to ensure proper
2357
locking in the sensitive parts of @emph{libgcrypt}.
2195
2359
There are helper macros to help you properly initialize the libraries.
2196
2360
Examples are shown below.
3463
3624
@anchor{ciphersuites}
3464
3625
@cindex Ciphersuites
3466
@multitable @columnfractions .45 .20 .35
3468
@item @code{TLS_RSA_NULL_MD5}
3472
@item @code{TLS_ANON_DH_3DES_EDE_CBC_SHA}
3476
@item @code{TLS_ANON_DH_ARCFOUR_MD5}
3480
@item @code{TLS_ANON_DH_AES_128_CBC_SHA}
3484
@item @code{TLS_ANON_DH_AES_256_CBC_SHA}
3488
@item @code{TLS_RSA_ARCFOUR_SHA}
3492
@item @code{TLS_RSA_ARCFOUR_MD5}
3496
@item @code{TLS_RSA_3DES_EDE_CBC_SHA}
3500
@item @code{TLS_RSA_EXPORT_ARCFOUR_40_MD5}
3504
@item @code{TLS_DHE_DSS_3DES_EDE_CBC_SHA}
3508
@item @code{TLS_DHE_RSA_3DES_EDE_CBC_SHA}
3512
@item @code{TLS_RSA_AES_128_CBC_SHA}
3516
@item @code{TLS_RSA_AES_256_CBC_SHA}
3520
@item @code{TLS_DHE_DSS_AES_256_CBC_SHA}
3524
@item @code{TLS_DHE_DSS_AES_128_CBC_SHA}
3528
@item @code{TLS_DHE_RSA_AES_256_CBC_SHA}
3532
@item @code{TLS_DHE_RSA_AES_128_CBC_SHA}
3536
@item @code{TLS_SRP_SHA_3DES_EDE_CBC_SHA}
3540
@item @code{TLS_SRP_SHA_AES_128_CBC_SHA}
3544
@item @code{TLS_SRP_SHA_AES_256_CBC_SHA}
3548
@item @code{TLS_SRP_SHA_RSA_3DES_EDE_CBC_SHA}
3552
@item @code{TLS_SRP_SHA_DSS_3DES_EDE_CBC_SHA}
3556
@item @code{TLS_SRP_SHA_RSA_AES_128_CBC_SHA}
3560
@item @code{TLS_SRP_SHA_DSS_AES_128_CBC_SHA}
3564
@item @code{TLS_SRP_SHA_RSA_AES_256_CBC_SHA}
3568
@item @code{TLS_SRP_SHA_DSS_AES_256_CBC_SHA}
3572
@item @code{TLS_DHE_DSS_ARCFOUR_SHA}
3574
@tab draft-ietf-tls-56-bit-ciphersuites
3576
@item @code{TLS_PSK_ARCFOUR_SHA}
3578
@tab draft-ietf-tls-psk
3580
@item @code{TLS_PSK_3DES_EDE_CBC_SHA}
3582
@tab draft-ietf-tls-psk
3584
@item @code{TLS_PSK_AES_128_CBC_SHA}
3586
@tab draft-ietf-tls-psk
3588
@item @code{TLS_PSK_AES_256_CBC_SHA}
3590
@tab draft-ietf-tls-psk
3627
@include algorithms.texi
3629
Some additional information regarding some of the algorithms:
3633
RSA is public key cryptosystem designed by Ronald Rivest, Adi Shamir
3634
and Leonard Adleman. It can be used with any hash functions.
3637
DSA is the USA's Digital Signature Standard. It uses only the SHA-1
3641
MD2 is a cryptographic hash algorithm designed by Ron Rivest. It is
3642
optimized for 8-bit processors. Outputs 128 bits of data. There are
3643
no known weaknesses of this algorithm but since this algorithm is
3644
rarely used and not really studied it should not be used today.
3647
MD5 is a cryptographic hash algorithm designed by Ron Rivest. Outputs
3648
128 bits of data. It is considered to be broken.
3651
SHA is a cryptographic hash algorithm designed by NSA. Outputs 160
3652
bits of data. It is also considered to be broken, though no practical
3653
attacks have been found.
3656
RIPEMD is a cryptographic hash algorithm developed in the framework of
3657
the EU project RIPE. Outputs 160 bits of data.
3595
3662
@c Guile Bindings
3835
3915
@image{gnutls-certificate-user-use-case,12cm}
3917
@node Cryptographic Backend
3918
@section Cryptographic Backend
3919
Several new systems provide hardware assisted cryptographic algorithm implementations
3920
that offer implementations some orders of magnitude faster than the software. For this
3921
reason in current releases of GnuTLS it is possible to override parts of the crypto
3922
backend or the whole. It is possible to override them both at runtime and compile time, however
3923
here we will discuss the runtime possibility. The API available for this functionality
3924
is in @code{gnutls/crypto.h} header file.
3926
@subsection Override specific algorithms
3927
When an optimized implementation of a single algorithm is available, say a
3928
hardware assisted version of @acronym{AES-CBC} then the following functions
3929
can be used to register those algorithms.
3933
@item @ref{gnutls_crypto_single_cipher_register2}
3934
To register a cipher algorithm.
3936
@item @ref{gnutls_crypto_single_mac_register2}
3937
To register a MAC algorithm.
3939
@ref{gnutls_crypto_single_digest_register2}
3940
To register a digest (hash) algorithm.
3944
Those registration functions will only replace the specified algorithm and leave the
3945
rest of subsystem intact.
3947
@subsection Override parts of the backend
3948
In some systems, such as embedded ones, it might be desirable to override big parts
3949
of the cryptographic backend, or even all of them. For this reason the following
3950
functions are provided.
3954
@item @ref{gnutls_crypto_cipher_register2}
3955
To override the cryptographic algorithms backend.
3957
@item @ref{gnutls_crypto_mac_register2}
3958
To override the MAC algorithms backend.
3960
@item @ref{gnutls_crypto_digest_register2}
3961
To override the digest algorithms backend.
3963
@item @ref{gnutls_crypto_rnd_register2}
3964
To override the random number generator backend.
3966
@item @ref{gnutls_crypto_bigint_register2}
3967
To override the big number number operations backend.
3969
@item @ref{gnutls_crypto_pk_register2}
3970
To override the public key encryption backend. This is tight to the big number
3971
operations so either both of them should be updated or care must be taken to
3972
use the same format.
3976
If all of them are used then GnuTLS will no longer use libgcrypt.
3838
3978
@node Copying Information
3839
3979
@appendix Copying Information
added
removed
doc/gnutls.texi
