diff options
Diffstat (limited to 'doc/cha-cert-auth.texi')
| -rw-r--r-- | doc/cha-cert-auth.texi | 696 |
1 files changed, 696 insertions, 0 deletions
diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi new file mode 100644 index 0000000..3f2856f --- /dev/null +++ b/doc/cha-cert-auth.texi @@ -0,0 +1,696 @@ +@node Certificate authentication +@section Certificate authentication +@cindex certificate authentication + +The most known authentication method of @acronym{TLS} are certificates. +The PKIX @xcite{PKIX} public key infrastructure is daily used by anyone +using a browser today. @acronym{GnuTLS} provides a simple API to +verify the @acronym{X.509} certificates as in @xcite{PKIX}. + +The key exchange algorithms supported by certificate authentication are +shown in @ref{tab:key-exchange}. + +@float Table,tab:key-exchange +@multitable @columnfractions .2 .7 + +@headitem Key exchange @tab Description + +@item RSA @tab +The RSA algorithm is used to encrypt a key and send it to the peer. +The certificate must allow the key to be used for encryption. + +@item DHE_@-RSA @tab +The RSA algorithm is used to sign ephemeral Diffie-Hellman parameters +which are sent to the peer. The key in the certificate must allow the +key to be used for signing. Note that key exchange algorithms which +use ephemeral Diffie-Hellman parameters, offer perfect forward +secrecy. That means that even if the private key used for signing is +compromised, it cannot be used to reveal past session data. + +@item ECDHE_@-RSA @tab +The RSA algorithm is used to sign ephemeral elliptic curve Diffie-Hellman +parameters which are sent to the peer. The key in the certificate must allow +the key to be used for signing. It also offers perfect forward +secrecy. That means that even if the private key used for signing is +compromised, it cannot be used to reveal past session data. + +@item DHE_@-DSS @tab +The DSA algorithm is used to sign ephemeral Diffie-Hellman parameters +which are sent to the peer. The certificate must contain DSA +parameters to use this key exchange algorithm. DSA is the algorithm +of the Digital Signature Standard (DSS). + +@item ECDHE_@-ECDSA @tab +The Elliptic curve DSA algorithm is used to sign ephemeral elliptic +curve Diffie-Hellman parameters which are sent to the peer. The +certificate must contain ECDSA parameters (i.e., EC and marked for signing) +to use this key exchange algorithm. + +@end multitable +@caption{Supported key exchange algorithms.} +@end float + +@menu +* X.509 certificates:: +* OpenPGP certificates:: +* Raw public-keys:: +* Advanced certificate verification:: +* Digital signatures:: +@end menu + +@node X.509 certificates +@subsection @acronym{X.509} certificates +@cindex X.509 certificates + +The @acronym{X.509} protocols rely on a hierarchical trust model. In +this trust model Certification Authorities (CAs) are used to certify +entities. Usually more than one certification authorities exist, and +certification authorities may certify other authorities to issue +certificates as well, following a hierarchical model. + +@float Figure,fig-x509 +@image{gnutls-x509,7cm} +@caption{An example of the X.509 hierarchical trust model.} +@end float + +One needs to trust one or more CAs for his secure communications. In +that case only the certificates issued by the trusted authorities are +acceptable. The framework is illustrated on @ref{fig-x509}. + +@menu +* X.509 certificate structure:: +* Importing an X.509 certificate:: +* X.509 certificate names:: +* X.509 distinguished names:: +* X.509 extensions:: +* X.509 public and private keys:: +* Verifying X.509 certificate paths:: +* Verifying a certificate in the context of TLS session:: +* Verification using PKCS11:: +@end menu + +@node X.509 certificate structure +@subsubsection @acronym{X.509} certificate structure + +An @acronym{X.509} certificate usually contains information about the +certificate holder, the signer, a unique serial number, expiration +dates and some other fields @xcite{PKIX} as shown in @ref{tab:x509}. + +@float Table,tab:x509 +@multitable @columnfractions .2 .7 + +@headitem Field @tab Description + +@item version @tab +The field that indicates the version of the certificate. + +@item serialNumber @tab +This field holds a unique serial number per certificate. + +@item signature @tab +The issuing authority's signature. + +@item issuer @tab +Holds the issuer's distinguished name. + +@item validity @tab +The activation and expiration dates. + +@item subject @tab +The subject's distinguished name of the certificate. + +@item extensions @tab +The extensions are fields only present in version 3 certificates. + +@end multitable +@caption{X.509 certificate fields.} +@end float + +The certificate's @emph{subject or issuer name} is not just a single +string. It is a Distinguished name and in the @acronym{ASN.1} +notation is a sequence of several object identifiers with their corresponding +values. Some of available OIDs to be used in an @acronym{X.509} +distinguished name are defined in @file{gnutls/x509.h}. + +The @emph{Version} field in a certificate has values either 1 or 3 for +version 3 certificates. Version 1 certificates do not support the +extensions field so it is not possible to distinguish a CA from a +person, thus their usage should be avoided. + +The @emph{validity} dates are there to indicate the date that the +specific certificate was activated and the date the certificate's key +would be considered invalid. + + +In @acronym{GnuTLS} the @acronym{X.509} certificate structures are +handled using the @code{gnutls_x509_crt_t} type and the corresponding +private keys with the @code{gnutls_x509_privkey_t} type. All the +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 in +@ref{ex-x509-info}. + +@node Importing an X.509 certificate +@subsubsection Importing an X.509 certificate + +The certificate structure should be initialized using @funcref{gnutls_x509_crt_init}, and +a certificate structure can be imported using @funcref{gnutls_x509_crt_import}. + +@showfuncC{gnutls_x509_crt_init,gnutls_x509_crt_import,gnutls_x509_crt_deinit} + +In several functions an array of certificates is required. To assist in initialization +and import the following two functions are provided. + +@showfuncB{gnutls_x509_crt_list_import,gnutls_x509_crt_list_import2} + +In all cases after use a certificate must be deinitialized using @funcref{gnutls_x509_crt_deinit}. +Note that although the functions above apply to @code{gnutls_x509_crt_t} structure, similar functions +exist for the CRL structure @code{gnutls_x509_crl_t}. + +@node X.509 certificate names +@subsubsection X.509 certificate names +@cindex X.509 certificate name + +X.509 certificates allow for multiple names and types of names to be specified. +CA certificates often rely on X.509 distinguished names (see @ref{X.509 distinguished names}) +for unique identification, while end-user and server certificates rely on the +'subject alternative names'. The subject alternative names provide a typed name, e.g., +a DNS name, or an email address, which identifies the owner of the certificate. +The following functions provide access to that names. + +@showfuncB{gnutls_x509_crt_get_subject_alt_name2,gnutls_x509_crt_set_subject_alt_name} +@showfuncC{gnutls_subject_alt_names_init,gnutls_subject_alt_names_get,gnutls_subject_alt_names_set} + +Note however, that server certificates often used the Common Name (CN), part of the +certificate DistinguishedName to place a single DNS address. That practice is discouraged +(see @xcite{RFC6125}), because only a single address can be specified, and the CN field is +free-form making matching ambiguous. + +@node X.509 distinguished names +@subsubsection X.509 distinguished names +@cindex X.509 distinguished name + +The ``subject'' of an X.509 certificate is not described by +a single name, but rather with a distinguished name. This in +X.509 terminology is a list of strings each associated an object +identifier. To make things simple GnuTLS provides @funcref{gnutls_x509_crt_get_dn2} +which follows the rules in @xcite{RFC4514} and returns a single +string. Access to each string by individual object identifiers +can be accessed using @funcref{gnutls_x509_crt_get_dn_by_oid}. + +@showfuncdesc{gnutls_x509_crt_get_dn2} +@showfuncC{gnutls_x509_crt_get_dn,gnutls_x509_crt_get_dn_by_oid,gnutls_x509_crt_get_dn_oid} + +Similar functions exist to access the distinguished name +of the issuer of the certificate. + +@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} + +The more powerful @funcref{gnutls_x509_crt_get_subject} and +@funcref{gnutls_x509_dn_get_rdn_ava} provide efficient but low-level access +to the contents of the distinguished name structure. + +@showfuncB{gnutls_x509_crt_get_subject,gnutls_x509_crt_get_issuer} +@showfuncdesc{gnutls_x509_dn_get_rdn_ava} + +@node X.509 extensions +@subsubsection X.509 extensions +@cindex X.509 extensions + +X.509 version 3 certificates include a list of extensions that can +be used to obtain additional information on the subject or the issuer +of the certificate. Those may be e-mail addresses, flags that indicate whether the +belongs to a CA etc. All the supported @acronym{X.509} version 3 +extensions are shown in @ref{tab:x509-ext}. + +The certificate extensions access is split into two parts. The first +requires to retrieve the extension, and the second is the parsing part. + +To enumerate and retrieve the DER-encoded extension data available in a certificate the following +two functions are available. +@showfuncC{gnutls_x509_crt_get_extension_info,gnutls_x509_crt_get_extension_data2,gnutls_x509_crt_get_extension_by_oid2} + +After a supported DER-encoded extension is retrieved it can be parsed using the APIs in @code{x509-ext.h}. +Complex extensions may require initializing an intermediate structure that holds the +parsed extension data. Examples of simple parsing functions are shown below. +@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} + +More complex extensions, such as Name Constraints, require an intermediate structure, in that +case @code{gnutls_x509_name_constraints_t} to be initialized in order to store the parsed +extension data. +@showfuncB{gnutls_x509_ext_import_name_constraints,gnutls_x509_ext_export_name_constraints} + +After the name constraints are extracted in the structure, the following functions +can be used to access them. + +@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} +@showfuncB{gnutls_x509_name_constraints_check,gnutls_x509_name_constraints_check_crt} + +Other utility functions are listed below. +@showfuncB{gnutls_x509_name_constraints_init,gnutls_x509_name_constraints_deinit} + +Similar functions exist for all of the other supported extensions, listed in @ref{tab:x509-ext}. + +@float Table,tab:x509-ext +@multitable @columnfractions .3 .2 .4 + +@headitem Extension @tab OID @tab Description + +@item Subject key id @tab 2.5.29.14 @tab +An identifier of the key of the subject. + +@item Key usage @tab 2.5.29.15 @tab +Constraints the key's usage of the certificate. + +@item Private key usage period @tab 2.5.29.16 @tab +Constraints the validity time of the private key. + +@item Subject alternative name @tab 2.5.29.17 @tab +Alternative names to subject's distinguished name. + +@item Issuer alternative name @tab 2.5.29.18 @tab +Alternative names to the issuer's distinguished name. + +@item Basic constraints @tab 2.5.29.19 @tab +Indicates whether this is a CA certificate or not, and specify the +maximum path lengths of certificate chains. + +@item Name constraints @tab 2.5.29.30 @tab +A field in CA certificates that restricts the scope of the name of +issued certificates. + +@item CRL distribution points @tab 2.5.29.31 @tab +This extension is set by the CA, in order to inform about the +location of issued Certificate Revocation Lists. + +@item Certificate policy @tab 2.5.29.32 @tab +This extension is set to indicate the certificate policy as object +identifier and may contain a descriptive string or URL. + +@item Extended key usage @tab 2.5.29.54 @tab +Inhibit any policy extension. Constraints the any policy OID +(@code{GNUTLS_X509_OID_POLICY_ANY}) use in the policy extension. + +@item Authority key identifier @tab 2.5.29.35 @tab +An identifier of the key of the issuer of the certificate. That is +used to distinguish between different keys of the same issuer. + +@item Extended key usage @tab 2.5.29.37 @tab +Constraints the purpose of the certificate. + +@item Authority information access @tab 1.3.6.1.5.5.7.1.1 @tab +Information on services by the issuer of the certificate. + +@item Proxy Certification Information @tab 1.3.6.1.5.5.7.1.14 @tab +Proxy Certificates includes this extension that contains the OID of +the proxy policy language used, and can specify limits on the maximum +lengths of proxy chains. Proxy Certificates are specified in +@xcite{RFC3820}. + +@end multitable +@caption{Supported X.509 certificate extensions.} +@end float + +Note, that there are also direct APIs to access extensions that may +be simpler to use for non-complex extensions. They are available +in @code{x509.h} and some examples are listed below. +@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} + + +@node X.509 public and private keys +@subsubsection Accessing public and private keys + +Each X.509 certificate contains a public key that corresponds to a private key. To +get a unique identifier of the public key the @funcref{gnutls_x509_crt_get_key_id} +function is provided. To export the public key or its parameters you may need +to convert the X.509 structure to a @code{gnutls_pubkey_t}. See +@ref{Abstract public keys} for more information. + +@showfuncdesc{gnutls_x509_crt_get_key_id} + +The private key parameters may be directly accessed by using one of the following functions. + +@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} + +@node Verifying X.509 certificate paths +@subsubsection Verifying @acronym{X.509} certificate paths +@cindex verifying certificate paths + +Verifying certificate paths is important in @acronym{X.509} +authentication. For this purpose the following functions are +provided. + +@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_crt2} +@showfuncdesc{gnutls_x509_trust_list_verify_named_crt} + +@showfuncdesc{gnutls_x509_trust_list_add_trust_file} +@showfuncdesc{gnutls_x509_trust_list_add_trust_mem} +@showfuncdesc{gnutls_x509_trust_list_add_system_trust} + +The verification function will verify a given certificate chain against a list of certificate +authorities and certificate revocation lists, and output +a bit-wise OR of elements of the @code{gnutls_@-certificate_@-status_t} +enumeration shown in @ref{gnutls_certificate_status_t}. The @code{GNUTLS_@-CERT_@-INVALID} flag +is always set on a verification error and more detailed flags will also be set when appropriate. + +@showenumdesc{gnutls_certificate_status_t,The @code{gnutls_@-certificate_@-status_t} enumeration.} + +An example of certificate verification is shown in @ref{ex-verify2}. +It is also possible to have a set of certificates that +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}. + +@node Verifying a certificate in the context of TLS session +@subsubsection Verifying a certificate in the context of TLS session +@cindex verifying certificate paths +@tindex gnutls_certificate_verify_flags + +When operating in the context of a TLS session, the trusted certificate +authority list may also be set using: +@showfuncD{gnutls_certificate_set_x509_trust_file,gnutls_certificate_set_x509_trust_dir,gnutls_certificate_set_x509_crl_file,gnutls_certificate_set_x509_system_trust} + +These functions allow the specification of the trusted certificate authorities, either +via a file, a directory or use the system-specified certificate authorities. +Unless the authorities are application specific, it is generally recommended +to use the system trust storage (see @funcref{gnutls_certificate_set_x509_system_trust}). + +Unlike the previous section it is not required to setup a trusted list, and there +are two approaches to verify the peer's certificate and identity. +The recommended in GnuTLS 3.5.0 and later is via the @funcref{gnutls_session_set_verify_cert}, +but for older GnuTLS versions you may use an explicit callback set via +@funcref{gnutls_certificate_set_verify_function} and then utilize +@funcref{gnutls_certificate_verify_peers3} for verification. +The reported verification status is identical to the verification functions described +in the previous section. + +Note that in certain cases it is required to check the marked purpose of +the end certificate (e.g. @code{GNUTLS_KP_TLS_WWW_SERVER}); in these cases +the more advanced @funcref{gnutls_session_set_verify_cert2} and +@funcref{gnutls_certificate_verify_peers} should be used instead. + +There is also the possibility to pass some input to the verification +functions in the form of flags. For @funcref{gnutls_x509_trust_list_verify_crt2} the +flags are passed directly, but for +@funcref{gnutls_certificate_verify_peers3}, the flags are set using +@funcref{gnutls_certificate_set_verify_flags}. All the available +flags are part of the enumeration +@code{gnutls_@-certificate_@-verify_@-flags} shown in @ref{gnutls_certificate_verify_flags}. + +@showenumdesc{gnutls_certificate_verify_flags,The @code{gnutls_@-certificate_@-verify_@-flags} enumeration.} + +@node Verification using PKCS11 +@subsubsection Verifying a certificate using PKCS #11 +@cindex verifying certificate with pkcs11 + +Some systems provide a system wide trusted certificate storage accessible using +the PKCS #11 API. That is, the trusted certificates are queried and accessed using the +PKCS #11 API, and trusted certificate properties, such as purpose, are marked using +attached extensions. One example is the p11-kit trust module@footnote{see @url{https://p11-glue.github.io/p11-glue/trust-module.html}.}. + +These special PKCS #11 modules can be used for GnuTLS certificate verification if marked as trust +policy modules, i.e., with @code{trust-policy: yes} in the p11-kit module file. +The way to use them is by specifying to the file verification function (e.g., @funcref{gnutls_certificate_set_x509_trust_file}), +a pkcs11 URL, or simply @code{pkcs11:} to use all the marked with trust policy modules. + +The trust modules of p11-kit assign a purpose to trusted authorities using the extended +key usage object identifiers. The common purposes are shown in @ref{tab:purposes}. Note +that typically according to @xcite{RFC5280} the extended key usage object identifiers apply to end certificates. Their +application to CA certificates is an extension used by the trust modules. + +@float Table,tab:purposes +@multitable @columnfractions .2 .2 .6 + +@headitem Purpose @tab OID @tab Description + +@item GNUTLS_KP_TLS_WWW_SERVER @tab +1.3.6.1.5.5.7.3.1 @tab +The certificate is to be used for TLS WWW authentication. When in a CA certificate, it +indicates that the CA is allowed to sign certificates for TLS WWW authentication. + +@item GNUTLS_KP_TLS_WWW_CLIENT @tab +1.3.6.1.5.5.7.3.2 @tab +The certificate is to be used for TLS WWW client authentication. When in a CA certificate, it +indicates that the CA is allowed to sign certificates for TLS WWW client authentication. + +@item GNUTLS_KP_CODE_SIGNING @tab +1.3.6.1.5.5.7.3.3 @tab +The certificate is to be used for code signing. When in a CA certificate, it +indicates that the CA is allowed to sign certificates for code signing. + +@item GNUTLS_KP_EMAIL_PROTECTION @tab +1.3.6.1.5.5.7.3.4 @tab +The certificate is to be used for email protection. When in a CA certificate, it +indicates that the CA is allowed to sign certificates for email users. + +@item GNUTLS_KP_OCSP_SIGNING @tab +1.3.6.1.5.5.7.3.9 @tab +The certificate is to be used for signing OCSP responses. When in a CA certificate, it +indicates that the CA is allowed to sign certificates which sign OCSP responses. + +@item GNUTLS_KP_ANY @tab +2.5.29.37.0 @tab +The certificate is to be used for any purpose. When in a CA certificate, it +indicates that the CA is allowed to sign any kind of certificates. + +@end multitable +@caption{Key purpose object identifiers.} +@end float + +With such modules, it is recommended to use the verification functions @funcref{gnutls_x509_trust_list_verify_crt2}, +or @funcref{gnutls_certificate_verify_peers}, which allow to explicitly specify the key purpose. The +other verification functions which do not allow setting a purpose, would operate as if +@code{GNUTLS_KP_TLS_WWW_SERVER} was requested from the trusted authorities. + +@node OpenPGP certificates +@subsection @acronym{OpenPGP} certificates +@cindex OpenPGP certificates + +Previous versions of GnuTLS supported limited @acronym{OpenPGP} key +authentication. That functionality has been deprecated and is no longer +made available. The reason is that, supporting alternative authentication +methods, when X.509 and PKIX were new on the Internet and not well established, seemed like a +good idea, in today's Internet X.509 is unquestionably the main +container for certificates. As such supporting more options with no clear +use-cases, is a distraction that consumes considerable resources for +improving and testing the library. For that we have decided to drop +this functionality completely in 3.6.0. + +@node Raw public-keys +@subsection Raw public-keys +@cindex Raw public-keys + +There are situations in which a rather large certificate / certificate chain is undesirable or impractical. +An example could be a resource constrained sensor network in which you do want to use authentication of and +encryption between your devices but where your devices lack loads of memory or processing power. Furthermore, +there are situations in which you don't want to or can't rely on a PKIX. TLS is, next to a PKIX environment, +also commonly used with self-signed certificates in smaller deployments where the self-signed certificates +are distributed to all involved protocol endpoints out-of-band. This practice does, however, still require +the overhead of the certificate generation even though none of the information found in the certificate is +actually used. + +With raw public-keys, only a subset of the information found in typical certificates is utilized: namely, +the SubjectPublicKeyInfo structure (in ASN.1 format) of a PKIX certificate that carries the parameters +necessary to describe the public-key. Other parameters found in PKIX certificates are omitted. By omitting +various certificate-related structures, the resulting raw public-key is kept fairly small in comparison to +the original certificate, and the code to process the keys can be simpler. + +It should be noted however, that the authenticity of these raw keys must be verified by an out-of-band mechanism +or something like @acronym{TOFU}. + +@menu +* Importing raw public-keys:: +@end menu + +@node Importing raw public-keys +@subsubsection Importing raw public-keys +Raw public-keys and their private counterparts can best be handled by using the abstract types +@code{gnutls_pubkey_t} and @code{gnutls_privkey_t} respectively. To learn how to use these +see @ref{Abstract key types}. + +@node Advanced certificate verification +@subsection Advanced certificate verification +@cindex Certificate verification + +The verification of X.509 certificates in the HTTPS and other Internet protocols is typically +done by loading a trusted list of commercial Certificate Authorities +(see @funcref{gnutls_certificate_set_x509_system_trust}), and using them as trusted anchors. +However, there are several examples (eg. the Diginotar incident) where one of these +authorities was compromised. This risk can be mitigated by using in addition to CA certificate verification, +other verification methods. In this section we list the available in GnuTLS methods. + +@menu +* Verifying a certificate using trust on first use authentication:: +* Verifying a certificate using DANE:: +@end menu + +@node Verifying a certificate using trust on first use authentication +@subsubsection Verifying a certificate using trust on first use authentication +@cindex verifying certificate paths +@cindex SSH-style authentication +@cindex Trust on first use +@cindex Key pinning + +It is possible to use a trust on first use (TOFU) authentication +method in GnuTLS. That is the concept used by the SSH programs, where the +public key of the peer is not verified, or verified in an out-of-bound way, +but subsequent connections to the same peer require the public key to +remain the same. Such a system in combination with the typical CA +verification of a certificate, and OCSP revocation checks, +can help to provide multiple factor verification, where a single point of +failure is not enough to compromise the system. For example a server compromise +may be detected using OCSP, and a CA compromise can be detected using +the trust on first use method. +Such a hybrid system with X.509 and trust on first use authentication is +shown in @ref{Client example with SSH-style certificate verification}. + +See @ref{Certificate verification} on how to use the available functionality. + +@node Verifying a certificate using DANE +@subsubsection Verifying a certificate using DANE (DNSSEC) +@cindex verifying certificate paths +@cindex DANE +@cindex DNSSEC + +The DANE protocol is a protocol that can be used to verify TLS certificates +using the DNS (or better DNSSEC) protocols. The DNS security extensions (DNSSEC) +provide an alternative public key infrastructure to the commercial CAs that +are typically used to sign TLS certificates. The DANE protocol takes advantage +of the DNSSEC infrastructure to verify TLS certificates. This can be +in addition to the verification by CA infrastructure or +may even replace it where DNSSEC is fully deployed. Note however, that DNSSEC deployment is +fairly new and it would be better to use it as an additional verification +method rather than the only one. + +The DANE functionality is provided by the @code{libgnutls-dane} library that is shipped +with GnuTLS and the function prototypes are in @code{gnutls/dane.h}. +See @ref{Certificate verification} for information on how to use the library. + +Note however, that the DANE RFC mandates the verification methods +one should use in addition to the validation via DNSSEC TLSA entries. +GnuTLS doesn't follow that RFC requirement, and the term DANE verification +in this manual refers to the TLSA entry verification. In GnuTLS any +other verification methods can be used (e.g., PKIX or TOFU) on top of +DANE. + +@node Digital signatures +@subsection Digital signatures +@cindex digital signatures + +In this section we will provide some information about digital +signatures, how they work, and give the rationale for disabling some +of the algorithms used. + +Digital signatures work by using somebody's secret key to sign some +arbitrary data. Then anybody else could use the public key of that +person to verify the signature. Since the data may be arbitrary it is +not suitable input to a cryptographic digital signature algorithm. For +this reason and also for performance cryptographic hash algorithms are +used to preprocess the input to the signature algorithm. This works as +long as it is difficult enough to generate two different messages with +the same hash algorithm output. In that case the same signature could +be used as a proof for both messages. Nobody wants to sign an innocent +message of donating 1 euro to Greenpeace and find out that they +donated 1.000.000 euros to Bad Inc. + +For a hash algorithm to be called cryptographic the following three +requirements must hold: + +@enumerate +@item Preimage resistance. +That means the algorithm must be one way and given the output of the +hash function @math{H(x)}, it is impossible to calculate @math{x}. + +@item 2nd preimage resistance. +That means that given a pair @math{x,y} with @math{y=H(x)} it is +impossible to calculate an @math{x'} such that @math{y=H(x')}. + +@item Collision resistance. +That means that it is impossible to calculate random @math{x} and +@math{x'} such @math{H(x')=H(x)}. +@end enumerate + +The last two requirements in the list are the most important in +digital signatures. These protect against somebody who would like to +generate two messages with the same hash output. When an algorithm is +considered broken usually it means that the Collision resistance of +the algorithm is less than brute force. Using the birthday paradox the +brute force attack takes +@iftex +@math{2^{(\rm{hash\ size}) / 2}} +@end iftex +@ifnottex +@math{2^{((hash size) / 2)}} +@end ifnottex +operations. Today colliding certificates using the MD5 hash algorithm +have been generated as shown in @xcite{WEGER}. + +There has been cryptographic results for the SHA-1 hash algorithms as +well, although they are not yet critical. Before 2004, MD5 had a +presumed collision strength of @math{2^{64}}, but it has been showed +to have a collision strength well under @math{2^{50}}. As of November +2005, it is believed that SHA-1's collision strength is around +@math{2^{63}}. We consider this sufficiently hard so that we still +support SHA-1. We anticipate that SHA-256/386/512 will be used in +publicly-distributed certificates in the future. When @math{2^{63}} +can be considered too weak compared to the computer power available +sometime in the future, SHA-1 will be disabled as well. The collision +attacks on SHA-1 may also get better, given the new interest in tools +for creating them. + +@subsubsection Trading security for interoperability + +If you connect to a server and use GnuTLS' functions to verify the +certificate chain, and get a @code{GNUTLS_CERT_INSECURE_ALGORITHM} +validation error (see @ref{Verifying X.509 certificate paths}), it means +that somewhere in the certificate chain there is a certificate signed +using @code{RSA-MD2} or @code{RSA-MD5}. These two digital signature +algorithms are considered broken, so GnuTLS fails verifying +the certificate. In some situations, it may be useful to be +able to verify the certificate chain anyway, assuming an attacker did +not utilize the fact that these signatures algorithms are broken. +This section will give help on how to achieve that. + +It is important to know that you do not have to enable any of +the flags discussed here to be able to use trusted root CA +certificates self-signed using @code{RSA-MD2} or @code{RSA-MD5}. The +certificates in the trusted list are considered trusted irrespective +of the signature. + +If you are using @funcref{gnutls_certificate_verify_peers3} to verify the +certificate chain, you can call +@funcref{gnutls_certificate_set_verify_flags} with the flags: +@itemize +@item @code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2} +@item @code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5} +@item @code{GNUTLS_VERIFY_ALLOW_SIGN_WITH_SHA1} +@item @code{GNUTLS_VERIFY_ALLOW_BROKEN} +@end itemize +as in the following example: + +@example + gnutls_certificate_set_verify_flags (x509cred, + GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5); +@end example + +This will signal the verifier algorithm to enable @code{RSA-MD5} when +verifying the certificates. + +If you are using @funcref{gnutls_x509_crt_verify} or +@funcref{gnutls_x509_crt_list_verify}, you can pass the +@code{GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5} parameter directly in the +@code{flags} parameter. + +If you are using these flags, it may also be a good idea to warn the +user when verification failure occur for this reason. The simplest is +to not use the flags by default, and only fall back to using them +after warning the user. If you wish to inspect the certificate chain +yourself, you can use @funcref{gnutls_certificate_get_peers} to extract +the raw server's certificate chain, @funcref{gnutls_x509_crt_list_import} to parse each of the certificates, and +then @funcref{gnutls_x509_crt_get_signature_algorithm} to find out the +signing algorithm used for each certificate. If any of the +intermediary certificates are using @code{GNUTLS_SIGN_RSA_MD2} or +@code{GNUTLS_SIGN_RSA_MD5}, you could present a warning. |