1 @node Certificate authentication
2 @section Certificate authentication
3 @cindex certificate authentication
5 The most known authentication method of @acronym{TLS} are certificates.
6 The PKIX @xcite{PKIX} public key infrastructure is daily used by anyone
7 using a browser today. @acronym{GnuTLS} supports both
8 @acronym{X.509} certificates @xcite{PKIX} and @acronym{OpenPGP}
9 certificates using a common API.
11 The key exchange algorithms supported by certificate authentication are
12 shown in @ref{tab:key-exchange}.
14 @float Table,tab:key-exchange
15 @multitable @columnfractions .2 .7
17 @headitem Key exchange @tab Description
20 The RSA algorithm is used to encrypt a key and send it to the peer.
21 The certificate must allow the key to be used for encryption.
24 The RSA algorithm is used to sign ephemeral Diffie-Hellman parameters
25 which are sent to the peer. The key in the certificate must allow the
26 key to be used for signing. Note that key exchange algorithms which
27 use ephemeral Diffie-Hellman parameters, offer perfect forward
28 secrecy. That means that even if the private key used for signing is
29 compromised, it cannot be used to reveal past session data.
31 @item ECDHE_@-RSA @tab
32 The RSA algorithm is used to sign ephemeral elliptic curve Diffie-Hellman
33 parameters which are sent to the peer. The key in the certificate must allow
34 the key to be used for signing. It also offers perfect forward
35 secrecy. That means that even if the private key used for signing is
36 compromised, it cannot be used to reveal past session data.
39 The DSA algorithm is used to sign ephemeral Diffie-Hellman parameters
40 which are sent to the peer. The certificate must contain DSA
41 parameters to use this key exchange algorithm. DSA is the algorithm
42 of the Digital Signature Standard (DSS).
44 @item ECDHE_@-ECDSA @tab
45 The Elliptic curve DSA algorithm is used to sign ephemeral elliptic
46 curve Diffie-Hellman parameters which are sent to the peer. The
47 certificate must contain ECDSA parameters (i.e., EC and marked for signing)
48 to use this key exchange algorithm.
51 @caption{Supported key exchange algorithms.}
55 * X.509 certificates::
56 * OpenPGP certificates::
57 * Advanced certificate verification::
58 * Digital signatures::
61 @node X.509 certificates
62 @subsection @acronym{X.509} certificates
63 @cindex X.509 certificates
65 The @acronym{X.509} protocols rely on a hierarchical trust model. In
66 this trust model Certification Authorities (CAs) are used to certify
67 entities. Usually more than one certification authorities exist, and
68 certification authorities may certify other authorities to issue
69 certificates as well, following a hierarchical model.
71 @float Figure,fig-x509
72 @image{gnutls-x509,7cm}
73 @caption{An example of the X.509 hierarchical trust model.}
76 One needs to trust one or more CAs for his secure communications. In
77 that case only the certificates issued by the trusted authorities are
78 acceptable. The framework is illustrated on @ref{fig-x509}.
81 * X.509 certificate structure::
82 * Importing an X.509 certificate::
83 * X.509 distinguished names::
85 * X.509 public and private keys::
86 * Verifying X.509 certificate paths::
87 * Verifying a certificate in the context of TLS session::
90 @node X.509 certificate structure
91 @subsubsection @acronym{X.509} certificate structure
93 An @acronym{X.509} certificate usually contains information about the
94 certificate holder, the signer, a unique serial number, expiration
95 dates and some other fields @xcite{PKIX} as shown in @ref{tab:x509}.
98 @multitable @columnfractions .2 .7
100 @headitem Field @tab Description
103 The field that indicates the version of the certificate.
105 @item serialNumber @tab
106 This field holds a unique serial number per certificate.
109 The issuing authority's signature.
112 Holds the issuer's distinguished name.
115 The activation and expiration dates.
118 The subject's distinguished name of the certificate.
120 @item extensions @tab
121 The extensions are fields only present in version 3 certificates.
124 @caption{X.509 certificate fields.}
127 The certificate's @emph{subject or issuer name} is not just a single
128 string. It is a Distinguished name and in the @acronym{ASN.1}
129 notation is a sequence of several object identifiers with their corresponding
130 values. Some of available OIDs to be used in an @acronym{X.509}
131 distinguished name are defined in @file{gnutls/x509.h}.
133 The @emph{Version} field in a certificate has values either 1 or 3 for
134 version 3 certificates. Version 1 certificates do not support the
135 extensions field so it is not possible to distinguish a CA from a
136 person, thus their usage should be avoided.
138 The @emph{validity} dates are there to indicate the date that the
139 specific certificate was activated and the date the certificate's key
140 would be considered invalid.
143 In @acronym{GnuTLS} the @acronym{X.509} certificate structures are
144 handled using the @code{gnutls_x509_crt_t} type and the corresponding
145 private keys with the @code{gnutls_x509_privkey_t} type. All the
146 available functions for @acronym{X.509} certificate handling have
147 their prototypes in @file{gnutls/x509.h}. An example program to
148 demonstrate the @acronym{X.509} parsing capabilities can be found in
151 @node Importing an X.509 certificate
152 @subsubsection Importing an X.509 certificate
154 The certificate structure should be initialized using @funcref{gnutls_x509_crt_init}, and
155 a certificate structure can be imported using @funcref{gnutls_x509_crt_import}.
157 @showfuncC{gnutls_x509_crt_init,gnutls_x509_crt_import,gnutls_x509_crt_deinit}
159 In several functions an array of certificates is required. To assist in initialization
160 and import the following two functions are provided.
162 @showfuncB{gnutls_x509_crt_list_import,gnutls_x509_crt_list_import2}
164 In all cases after use a certificate must be deinitialized using @funcref{gnutls_x509_crt_deinit}.
165 Note that although the functions above apply to @code{gnutls_x509_crt_t} structure, similar functions
166 exist for the CRL structure @code{gnutls_x509_crl_t}.
168 @node X.509 distinguished names
169 @subsubsection X.509 distinguished names
170 @cindex X.509 distinguished name
172 The ``subject'' of an X.509 certificate is not described by
173 a single name, but rather with a distinguished name. This in
174 X.509 terminology is a list of strings each associated an object
175 identifier. To make things simple GnuTLS provides @funcref{gnutls_x509_crt_get_dn2}
176 which follows the rules in @xcite{RFC4514} and returns a single
177 string. Access to each string by individual object identifiers
178 can be accessed using @funcref{gnutls_x509_crt_get_dn_by_oid}.
180 @showfuncdesc{gnutls_x509_crt_get_dn2}
181 @showfuncC{gnutls_x509_crt_get_dn,gnutls_x509_crt_get_dn_by_oid,gnutls_x509_crt_get_dn_oid}
183 Similar functions exist to access the distinguished name
184 of the issuer of the certificate.
186 @showfuncE{gnutls_x509_crt_get_issuer_dn,gnutls_x509_crt_get_issuer_dn2,gnutls_x509_crt_get_issuer_dn_by_oid,gnutls_x509_crt_get_issuer_dn_oid,gnutls_x509_crt_get_issuer}
188 The more powerful @funcref{gnutls_x509_crt_get_subject} and
189 @funcref{gnutls_x509_dn_get_rdn_ava} provide efficient but low-level access
190 to the contents of the distinguished name structure.
192 @showfuncB{gnutls_x509_crt_get_subject,gnutls_x509_crt_get_issuer}
193 @showfuncdesc{gnutls_x509_dn_get_rdn_ava}
195 @node X.509 extensions
196 @subsubsection X.509 extensions
197 @cindex X.509 extensions
199 X.509 version 3 certificates include a list of extensions that can
200 be used to obtain additional information on the subject or the issuer
201 of the certificate. Those may be e-mail addresses, flags that indicate whether the
202 belongs to a CA etc. All the supported @acronym{X.509} version 3
203 extensions are shown in @ref{tab:x509-ext}.
205 The certificate extensions access is split into two parts. The first
206 requires to retrieve the extension, and the second is the parsing part.
208 To enumerate and retrieve the DER-encoded extension data available in a certificate the following
209 two functions are available.
210 @showfuncB{gnutls_x509_crt_get_extension_info,gnutls_x509_crt_get_extension_data2}
212 After a supported DER-encoded extension is retrieved it can be parsed using the APIs in @code{x509-ext.h}.
213 Complex extensions may require initializing an intermediate structure that holds the
214 parsed extension data.
216 Examples of simple parsing functions are shown below.
217 @showfuncD{gnutls_x509_ext_import_basic_constraints,gnutls_x509_ext_export_basic_constraints,gnutls_x509_ext_import_key_usage,gnutls_x509_ext_export_key_usage}
219 More complex extensions, such as Name Constraints, require an intermediate structure, in that
220 case @code{gnutls_x509_name_constraints_t} to be initialized in order to store the parsed
222 @showfuncB{gnutls_x509_ext_import_name_constraints,gnutls_x509_ext_export_name_constraints}
224 After the name constraints are extracted in the structure, the following functions
225 can be used to access them.
227 @showfuncD{gnutls_x509_name_constraints_get_permitted,gnutls_x509_name_constraints_get_excluded,gnutls_x509_name_constraints_add_permitted,gnutls_x509_name_constraints_add_excluded}
228 @showfuncB{gnutls_x509_name_constraints_check,gnutls_x509_name_constraints_check_crt}
230 Other utility functions are listed below.
231 @showfuncB{gnutls_x509_name_constraints_init,gnutls_x509_name_constraints_deinit}
233 Similar functions exist for all of the other supported extensions, listed in @ref{tab:x509-ext}.
235 @float Table,tab:x509-ext
236 @multitable @columnfractions .3 .2 .4
238 @headitem Extension @tab OID @tab Description
240 @item Subject key id @tab 2.5.29.14 @tab
241 An identifier of the key of the subject.
243 @item Key usage @tab 2.5.29.15 @tab
244 Constraints the key's usage of the certificate.
246 @item Private key usage period @tab 2.5.29.16 @tab
247 Constraints the validity time of the private key.
249 @item Subject alternative name @tab 2.5.29.17 @tab
250 Alternative names to subject's distinguished name.
252 @item Issuer alternative name @tab 2.5.29.18 @tab
253 Alternative names to the issuer's distinguished name.
255 @item Basic constraints @tab 2.5.29.19 @tab
256 Indicates whether this is a CA certificate or not, and specify the
257 maximum path lengths of certificate chains.
259 @item Name constraints @tab 2.5.29.30 @tab
260 A field in CA certificates that restricts the scope of the name of
263 @item CRL distribution points @tab 2.5.29.31 @tab
264 This extension is set by the CA, in order to inform about the issued
267 @item Certificate policy @tab 2.5.29.32 @tab
268 This extension is set to indicate the certificate policy as object
269 identifier and may contain a descriptive string or URL.
271 @item Authority key identifier @tab 2.5.29.35 @tab
272 An identifier of the key of the issuer of the certificate. That is
273 used to distinguish between different keys of the same issuer.
275 @item Extended key usage @tab 2.5.29.37 @tab
276 Constraints the purpose of the certificate.
278 @item Authority information access @tab 1.3.6.1.5.5.7.1.1 @tab
279 Information on services by the issuer of the certificate.
281 @item Proxy Certification Information @tab 1.3.6.1.5.5.7.1.14 @tab
282 Proxy Certificates includes this extension that contains the OID of
283 the proxy policy language used, and can specify limits on the maximum
284 lengths of proxy chains. Proxy Certificates are specified in
288 @caption{Supported X.509 certificate extensions.}
291 Note, that there are also direct APIs to access extensions that may
292 be simpler to use for non-complex extensions. They are available
293 in @code{x509.h} and some examples are listed below.
294 @showfuncD{gnutls_x509_crt_get_basic_constraints,gnutls_x509_crt_set_basic_constraints,gnutls_x509_crt_get_key_usage,gnutls_x509_crt_set_key_usage}
297 @node X.509 public and private keys
298 @subsubsection Accessing public and private keys
300 Each X.509 certificate contains a public key that corresponds to a private key. To
301 get a unique identifier of the public key the @funcref{gnutls_x509_crt_get_key_id}
302 function is provided. To export the public key or its parameters you may need
303 to convert the X.509 structure to a @code{gnutls_pubkey_t}. See
304 @ref{Abstract public keys} for more information.
306 @showfuncdesc{gnutls_x509_crt_get_key_id}
308 The private key parameters may be directly accessed by using one of the following functions.
310 @showfuncE{gnutls_x509_privkey_get_pk_algorithm2,gnutls_x509_privkey_export_rsa_raw2,gnutls_x509_privkey_export_ecc_raw,gnutls_x509_privkey_export_dsa_raw,gnutls_x509_privkey_get_key_id}
312 @node Verifying X.509 certificate paths
313 @subsubsection Verifying @acronym{X.509} certificate paths
314 @cindex verifying certificate paths
316 Verifying certificate paths is important in @acronym{X.509}
317 authentication. For this purpose the following functions are
320 @showfuncdesc{gnutls_x509_trust_list_add_cas}
321 @showfuncdesc{gnutls_x509_trust_list_add_named_crt}
322 @showfuncdesc{gnutls_x509_trust_list_add_crls}
323 @showfuncdesc{gnutls_x509_trust_list_verify_crt}
324 @showfuncdesc{gnutls_x509_trust_list_verify_named_crt}
326 @showfuncdesc{gnutls_x509_trust_list_add_trust_file}
327 @showfuncdesc{gnutls_x509_trust_list_add_trust_mem}
328 @showfuncdesc{gnutls_x509_trust_list_add_system_trust}
330 The verification function will verify a given certificate chain against a list of certificate
331 authorities and certificate revocation lists, and output
332 a bit-wise OR of elements of the @code{gnutls_@-certificate_@-status_t}
333 enumeration shown in @ref{gnutls_certificate_status_t}. The @code{GNUTLS_@-CERT_@-INVALID} flag
334 is always set on a verification error and more detailed flags will also be set when appropriate.
336 @showenumdesc{gnutls_certificate_status_t,The @code{gnutls_@-certificate_@-status_t} enumeration.}
338 An example of certificate verification is shown in @ref{ex-verify2}.
339 It is also possible to have a set of certificates that
340 are trusted for a particular server but not to authorize other certificates.
341 This purpose is served by the functions @funcref{gnutls_x509_trust_list_add_named_crt} and @funcref{gnutls_x509_trust_list_verify_named_crt}.
343 @node Verifying a certificate in the context of TLS session
344 @subsubsection Verifying a certificate in the context of TLS session
345 @cindex verifying certificate paths
346 @tindex gnutls_certificate_verify_flags
348 When operating in the context of a TLS session, the trusted certificate
349 authority list may also be set using:
350 @showfuncC{gnutls_certificate_set_x509_trust_file,gnutls_certificate_set_x509_crl_file,gnutls_certificate_set_x509_system_trust}
352 In that case it is not required to setup a trusted list as above, and
353 the function @funcref{gnutls_certificate_verify_peers3}
354 may be used to verify the peer's certificate chain and identity. The flags
355 are set similarly to the verification functions in the previous section.
356 Note that in certain cases it is required to check the marked purpose of
357 the end certificate (e.g. @code{GNUTLS_KP_TLS_WWW_SERVER}); in these case
358 @funcref{gnutls_certificate_verify_peers} should be used instead.
360 There is also the possibility to pass some input to the verification
361 functions in the form of flags. For @funcref{gnutls_x509_trust_list_verify_crt} the
362 flags are passed straightforward, but
363 @funcref{gnutls_certificate_verify_peers3} depends on the flags set by
364 calling @funcref{gnutls_certificate_set_verify_flags}. All the available
365 flags are part of the enumeration
366 @code{gnutls_@-certificate_@-verify_@-flags} shown in @ref{gnutls_certificate_verify_flags}.
368 @showenumdesc{gnutls_certificate_verify_flags,The @code{gnutls_@-certificate_@-verify_@-flags} enumeration.}
371 @node OpenPGP certificates
372 @subsection @acronym{OpenPGP} certificates
373 @cindex OpenPGP certificates
375 The @acronym{OpenPGP} key authentication relies on a distributed trust
376 model, called the ``web of trust''. The ``web of trust'' uses a
377 decentralized system of trusted introducers, which are the same as a
378 CA. @acronym{OpenPGP} allows anyone to sign anyone else's public
379 key. When Alice signs Bob's key, she is introducing Bob's key to
380 anyone who trusts Alice. If someone trusts Alice to introduce keys,
381 then Alice is a trusted introducer in the mind of that observer.
382 For example in @ref{fig-openpgp}, David trusts Alice to be an introducer and Alice
383 signed Bob's key thus Dave trusts Bob's key to be the real one.
385 @float Figure,fig-openpgp
386 @image{gnutls-pgp,8cm}
387 @caption{An example of the OpenPGP trust model.}
390 There are some key points that are important in that model. In the
391 example Alice has to sign Bob's key, only if she is sure that the key
392 belongs to Bob. Otherwise she may also make Dave falsely believe that
393 this is Bob's key. Dave has also the responsibility to know who to
394 trust. This model is similar to real life relations.
396 Just see how Charlie behaves in the previous example. Although he has
397 signed Bob's key - because he knows, somehow, that it belongs to Bob -
398 he does not trust Bob to be an introducer. Charlie decided to trust
399 only Kevin, for some reason. A reason could be that Bob is lazy
400 enough, and signs other people's keys without being sure that they
401 belong to the actual owner.
403 @float Table,tab:openpgp-certificate
404 @multitable @columnfractions .2 .7
406 @headitem Field @tab Description
409 The field that indicates the version of the OpenPGP structure.
412 An RFC 2822 string that identifies the owner of the key. There may be
413 multiple user identifiers in a key.
415 @item public key @tab
416 The main public key of the certificate.
418 @item expiration @tab
419 The expiration time of the main public key.
421 @item public subkey @tab
422 An additional public key of the certificate. There may be multiple subkeys
425 @item public subkey expiration @tab
426 The expiration time of the subkey.
429 @caption{OpenPGP certificate fields.}
433 @subsubsection @acronym{OpenPGP} certificate structure
435 In @acronym{GnuTLS} the @acronym{OpenPGP} certificate structures
436 @xcite{RFC2440} are handled using the @code{gnutls_openpgp_crt_t} type.
437 A typical certificate contains the user ID, which is an RFC 2822
438 mail and name address, a public key, possibly a number of additional
439 public keys (called subkeys), and a number of signatures. The various
440 fields are shown in @ref{tab:openpgp-certificate}.
442 The additional subkeys may provide key for various different purposes,
443 e.g. one key to encrypt mail, and another to sign a TLS key exchange.
444 Each subkey is identified by a unique key ID.
445 The keys that are to be used in a TLS key exchange that requires
446 signatures are called authentication keys in the OpenPGP jargon.
447 The mapping of TLS key exchange methods to public keys is shown in
448 @ref{tab:openpgp-key-exchange}.
450 @float Table,tab:openpgp-key-exchange
451 @multitable @columnfractions .2 .7
453 @headitem Key exchange @tab Public key requirements
456 An RSA public key that allows encryption.
459 An RSA public key that is marked for authentication.
461 @item ECDHE_@-RSA @tab
462 An RSA public key that is marked for authentication.
465 A DSA public key that is marked for authentication.
468 @caption{The types of (sub)keys required for the various TLS key exchange methods.}
471 The corresponding private keys are stored in the
472 @code{gnutls_openpgp_privkey_t} type. All the prototypes for the key
473 handling functions can be found in @file{gnutls/openpgp.h}.
475 @subsubsection Verifying an @acronym{OpenPGP} certificate
477 The verification functions of @acronym{OpenPGP} keys, included in
478 @acronym{GnuTLS}, are simple ones, and do not use the features of the
479 ``web of trust''. For that reason, if the verification needs are
480 complex, the assistance of external tools like @acronym{GnuPG} and
481 GPGME@footnote{@url{http://www.gnupg.org/related_software/gpgme/}} is
484 In GnuTLS there is a verification function for OpenPGP certificates,
485 the @funcref{gnutls_openpgp_crt_verify_ring}. This checks an
486 @acronym{OpenPGP} key against a given set of public keys (keyring) and
487 returns the key status. The key verification status is the same as in
488 @acronym{X.509} certificates, although the meaning and interpretation
489 are different. For example an @acronym{OpenPGP} key may be valid, if
490 the self signature is ok, even if no signers were found. The meaning
491 of verification status flags is the same as in the @acronym{X.509} certificates
492 (see @ref{gnutls_certificate_verify_flags}).
494 @showfuncdesc{gnutls_openpgp_crt_verify_ring}
496 @showfuncdesc{gnutls_openpgp_crt_verify_self}
498 @subsubsection Verifying a certificate in the context of a TLS session
500 Similarly with X.509 certificates, one needs to specify
501 the OpenPGP keyring file in the credentials structure. The certificates
502 in this file will be used by @funcref{gnutls_certificate_verify_peers3}
503 to verify the signatures in the certificate sent by the peer.
505 @showfuncdesc{gnutls_certificate_set_openpgp_keyring_file}
507 @node Advanced certificate verification
508 @subsection Advanced certificate verification
509 @cindex Certificate verification
511 The verification of X.509 certificates in the HTTPS and other Internet protocols is typically
512 done by loading a trusted list of commercial Certificate Authorities
513 (see @funcref{gnutls_certificate_set_x509_system_trust}), and using them as trusted anchors.
514 However, there are several examples (eg. the Diginotar incident) where one of these
515 authorities was compromised. This risk can be mitigated by using in addition to CA certificate verification,
516 other verification methods. In this section we list the available in GnuTLS methods.
519 * Verifying a certificate using trust on first use authentication::
520 * Verifying a certificate using DANE::
523 @node Verifying a certificate using trust on first use authentication
524 @subsubsection Verifying a certificate using trust on first use authentication
525 @cindex verifying certificate paths
526 @cindex SSH-style authentication
527 @cindex Trust on first use
530 It is possible to use a trust on first use (TOFU) authentication
531 method in GnuTLS. That is the concept used by the SSH programs, where the
532 public key of the peer is not verified, or verified in an out-of-bound way,
533 but subsequent connections to the same peer require the public key to
534 remain the same. Such a system in combination with the typical CA
535 verification of a certificate, and OCSP revocation checks,
536 can help to provide multiple factor verification, where a single point of
537 failure is not enough to compromise the system. For example a server compromise
538 may be detected using OCSP, and a CA compromise can be detected using
539 the trust on first use method.
540 Such a hybrid system with X.509 and trust on first use authentication is
541 shown in @ref{Simple client example with SSH-style certificate verification}.
543 See @ref{Certificate verification} on how to use the available functionality.
545 @node Verifying a certificate using DANE
546 @subsubsection Verifying a certificate using DANE (DNSSEC)
547 @cindex verifying certificate paths
551 The DANE protocol is a protocol that can be used to verify TLS certificates
552 using the DNS (or better DNSSEC) protocols. The DNS security extensions (DNSSEC)
553 provide an alternative public key infrastructure to the commercial CAs that
554 are typically used to sign TLS certificates. The DANE protocol takes advantage
555 of the DNSSEC infrastructure to verify TLS certificates. This can be
556 in addition to the verification by CA infrastructure or
557 may even replace it where DNSSEC is fully deployed. Note however, that DNSSEC deployment is
558 fairly new and it would be better to use it as an additional verification
559 method rather than the only one.
561 The DANE functionality is provided by the @code{libgnutls-dane} library that is shipped
562 with GnuTLS and the function prototypes are in @code{gnutls/dane.h}.
563 See @ref{Certificate verification} for information on how to use the library.
565 Note however, that the DANE RFC mandates the verification methods
566 one should use in addition to the validation via DNSSEC TLSA entries.
567 GnuTLS doesn't follow that RFC requirement, and the term DANE verification
568 in this manual refers to the TLSA entry verification. In GnuTLS any
569 other verification methods can be used (e.g., PKIX or TOFU) on top of
572 @node Digital signatures
573 @subsection Digital signatures
574 @cindex digital signatures
576 In this section we will provide some information about digital
577 signatures, how they work, and give the rationale for disabling some
578 of the algorithms used.
580 Digital signatures work by using somebody's secret key to sign some
581 arbitrary data. Then anybody else could use the public key of that
582 person to verify the signature. Since the data may be arbitrary it is
583 not suitable input to a cryptographic digital signature algorithm. For
584 this reason and also for performance cryptographic hash algorithms are
585 used to preprocess the input to the signature algorithm. This works as
586 long as it is difficult enough to generate two different messages with
587 the same hash algorithm output. In that case the same signature could
588 be used as a proof for both messages. Nobody wants to sign an innocent
589 message of donating 1 euro to Greenpeace and find out that he
590 donated 1.000.000 euros to Bad Inc.
592 For a hash algorithm to be called cryptographic the following three
593 requirements must hold:
596 @item Preimage resistance.
597 That means the algorithm must be one way and given the output of the
598 hash function @math{H(x)}, it is impossible to calculate @math{x}.
600 @item 2nd preimage resistance.
601 That means that given a pair @math{x,y} with @math{y=H(x)} it is
602 impossible to calculate an @math{x'} such that @math{y=H(x')}.
604 @item Collision resistance.
605 That means that it is impossible to calculate random @math{x} and
606 @math{x'} such @math{H(x')=H(x)}.
609 The last two requirements in the list are the most important in
610 digital signatures. These protect against somebody who would like to
611 generate two messages with the same hash output. When an algorithm is
612 considered broken usually it means that the Collision resistance of
613 the algorithm is less than brute force. Using the birthday paradox the
614 brute force attack takes
616 @math{2^{(\rm{hash\ size}) / 2}}
619 @math{2^{((hash size) / 2)}}
621 operations. Today colliding certificates using the MD5 hash algorithm
622 have been generated as shown in @xcite{WEGER}.
624 There has been cryptographic results for the SHA-1 hash algorithms as
625 well, although they are not yet critical. Before 2004, MD5 had a
626 presumed collision strength of @math{2^{64}}, but it has been showed
627 to have a collision strength well under @math{2^{50}}. As of November
628 2005, it is believed that SHA-1's collision strength is around
629 @math{2^{63}}. We consider this sufficiently hard so that we still
630 support SHA-1. We anticipate that SHA-256/386/512 will be used in
631 publicly-distributed certificates in the future. When @math{2^{63}}
632 can be considered too weak compared to the computer power available
633 sometime in the future, SHA-1 will be disabled as well. The collision
634 attacks on SHA-1 may also get better, given the new interest in tools
637 @subsubsection Trading security for interoperability
639 If you connect to a server and use GnuTLS' functions to verify the
640 certificate chain, and get a @code{GNUTLS_CERT_INSECURE_ALGORITHM}
641 validation error (see @ref{Verifying X.509 certificate paths}), it means
642 that somewhere in the certificate chain there is a certificate signed
643 using @code{RSA-MD2} or @code{RSA-MD5}. These two digital signature
644 algorithms are considered broken, so GnuTLS fails verifying
645 the certificate. In some situations, it may be useful to be
646 able to verify the certificate chain anyway, assuming an attacker did
647 not utilize the fact that these signatures algorithms are broken.
648 This section will give help on how to achieve that.
650 It is important to know that you do not have to enable any of
651 the flags discussed here to be able to use trusted root CA
652 certificates self-signed using @code{RSA-MD2} or @code{RSA-MD5}. The
653 certificates in the trusted list are considered trusted irrespective
656 If you are using @funcref{gnutls_certificate_verify_peers3} to verify the
657 certificate chain, you can call
658 @funcref{gnutls_certificate_set_verify_flags} with the flags:
660 @item @code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2}
661 @item @code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5}
663 as in the following example:
666 gnutls_certificate_set_verify_flags (x509cred,
667 GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5);
670 This will signal the verifier algorithm to enable @code{RSA-MD5} when
671 verifying the certificates.
673 If you are using @funcref{gnutls_x509_crt_verify} or
674 @funcref{gnutls_x509_crt_list_verify}, you can pass the
675 @code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5} parameter directly in the
676 @code{flags} parameter.
678 If you are using these flags, it may also be a good idea to warn the
679 user when verification failure occur for this reason. The simplest is
680 to not use the flags by default, and only fall back to using them
681 after warning the user. If you wish to inspect the certificate chain
682 yourself, you can use @funcref{gnutls_certificate_get_peers} to extract
683 the raw server's certificate chain, @funcref{gnutls_x509_crt_list_import} to parse each of the certificates, and
684 then @funcref{gnutls_x509_crt_get_signature_algorithm} to find out the
685 signing algorithm used for each certificate. If any of the
686 intermediary certificates are using @code{GNUTLS_SIGN_RSA_MD2} or
687 @code{GNUTLS_SIGN_RSA_MD5}, you could present a warning.