More on certificate authentication
**********************************

X.509 certificates
==================

The 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.

Figure: An example of the X.509 hierarchical trust model.

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 fig:x509.

X.509 certificate structure
---------------------------

An X.509 certificate usually contains information about the certificate holder, the signer, a unique serial number, expiration dates and some other fields PKIX as shown in tab:x509.

Field   Description

version
The field that indicates the version of the certificate.

serialNumber
This field holds a unique serial number per certificate.

issuer
Holds the issuer's distinguished name.

validity
The activation and expiration dates.

subject
The subject's distinguished name of the certificate.

extensions
The extensions are fields only present in version 3 certificates.

Table: X.509 certificate fields.

The certificate's subject or issuer name is not just a single string.  It is a Distinguished name and in the ASN.1 notation is a sequence of several object identifiers with their corresponding values. Some of available OIDs to be used in an X.509 distinguished name are defined in gnutls/x509.h.

The 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 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.

Certificate extensions are there to include information about the certificate's subject that did not fit in the typical certificate fields. Those may be e-mail addresses, flags that indicate whether the belongs to a CA etc.  All the supported X.509 version 3 extensions are shown in tab:x509-ext.

Extension   OID   Description

Subject key id   2.5.29.14
An identifier of the key of the subject.

Authority key id   2.5.29.35
An identifier of the authority's key used to sign the certificate.

Subject alternative name   2.5.29.17
Alternative names to subject's distinguished name.

Key usage   2.5.29.15
Constraints the key's usage of the certificate.

Extended key usage   2.5.29.37
Constraints the purpose of the certificate.

Basic constraints   2.5.29.19
Indicates whether this is a CA certificate or not, and specify the
maximum path lengths of certificate chains.

CRL distribution points   2.5.29.31
This extension is set by the CA, in order to inform about the issued
CRLs.

Proxy Certification Information   1.3.6.1.5.5.7.1.14
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
RFC3820.

Table: X.509 certificate extensions.

In GnuTLS the X.509 certificate structures are handled using the gnutls_x509_crt_t type and the corresponding private keys with the gnutls_x509_privkey_t type.  All the available functions for X.509 certificate handling have their prototypes in gnutls/x509.h. An example program to demonstrate the X.509 parsing capabilities can be found at ex:x509-info.

Verifying X.509 certificate paths
---------------------------------

Verifying certificate paths is important in X.509 authentication. For this purpose the following functions are provided.

gnutls_x509_trust_list_init,gnutls_x509_trust_list_deinit

gnutls_x509_trust_list_add_cas gnutls_x509_trust_list_add_named_crt gnutls_x509_trust_list_add_crls gnutls_x509_trust_list_verify_crt 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 a bit-wise OR of elements of the gnutls_certificate_status_t enumeration shown in gnutls_certificate_status_t.

gnutls_certificate_status_t,The gnutls_certificate_status_t enumeration.

An example of certificate verification is shown in 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 gnutls_x509_trust_list_add_named_crt and gnutls_x509_trust_list_verify_named_crt.

Verifying a certificate in the context of TLS session
-----------------------------------------------------

When operating in the context of a TLS session, the trusted certificate authority list has been set via the gnutls_certificate_set_x509_trust_file and gnutls_certificate_set_x509_crl_file, thus it is not required to setup a trusted list as above. Convenience functions such as gnutls_certificate_verify_peers2 are equivalent and will verify the peer's certificate chain in a TLS session.

There is also the possibility to pass some input to the verification functions in the form of flags. For gnutls_x509_trust_list_verify_crt the flags are passed straightforward, but gnutls_certificate_verify_peers2 depends on the flags set by calling gnutls_certificate_set_verify_flags.  All the available flags are part of the enumeration gnutls_certificate_verify_flags shown in gnutls_certificate_verify_flags.

gnutls_certificate_verify_flags,The gnutls_certificate_verify_flags enumeration.

Although the verification of a certificate path indicates that the certificate is signed by trusted authority, does not reveal anything about the peer's identity. It is required to verify if the certificate's owner is the one you expect. For more information consult RFC2818 and section ex:verify for an example.

PKCS #10 certificate requests
-----------------------------

A certificate request is a structure, which contain information about an applicant of a certificate service.  It usually contains a private key, a distinguished name and secondary data such as a challenge password. GnuTLS supports the requests defined in PKCS #10 RFC2986. Other formats of certificate requests are not currently supported.

gnutls_x509_crq_init,gnutls_x509_crq_deinit

gnutls_x509_crq_import

gnutls_x509_crq_export

A certificate request can be generated by associating it with a private key, setting the subject's information and finally self signing it. The last step ensures that the requester is in possession of the private key.

gnutls_x509_crq_set_version gnutls_x509_crq_set_dn_by_oid gnutls_x509_crq_set_key_usage gnutls_x509_crq_set_key_purpose_oid gnutls_x509_crq_set_basic_constraints

The gnutls_x509_crq_set_key and gnutls_x509_crq_sign2 functions associate the request with a private key and sign it. If a request is to be signed with a key residing in a PKCS #11 token it is recommended to use the signing functions shown in Abstract key types.

gnutls_x509_crq_set_key gnutls_x509_crq_sign2

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.

     [file ex-crq.c not included]

PKCS #12 structures
-------------------

A PKCS #12 structure PKCS12 usually contains a user's private keys and certificates. It is commonly used in browsers to export and import the user's identities.

In GnuTLS the PKCS #12 structures are handled using the gnutls_pkcs12_t type. This is an abstract type that may hold several gnutls_pkcs12_bag_t types.  The bag types are the holders of the actual data, which may be certificates, private keys or encrypted data.  A bag of type encrypted should be decrypted in order for its data to be accessed.

gnutls_pkcs12_init,gnutls_pkcs12_deinit

The following functions are available to read a PKCS #12 structure.

gnutls_pkcs12_import gnutls_pkcs12_get_bag gnutls_pkcs12_verify_mac gnutls_pkcs12_bag_decrypt

gnutls_pkcs12_bag_init,gnutls_pkcs12_bag_deinit,gnutls_pkcs12_bag_get_count,gnutls_pkcs12_bag_get_data,gnutls_pkcs12_bag_get_key_id,gnutls_pkcs12_bag_get_friendly_name

The functions below are used to generate a PKCS #12 structure. An example of their usage is also shown.

gnutls_pkcs12_set_bag gnutls_pkcs12_bag_encrypt gnutls_pkcs12_generate_mac gnutls_pkcs12_export gnutls_pkcs12_bag_set_data,gnutls_pkcs12_bag_set_crl,gnutls_pkcs12_bag_set_crt,gnutls_pkcs12_bag_set_key_id,gnutls_pkcs12_bag_set_friendly_name

     [file ex-pkcs12.c not included]

OpenPGP certificates
====================

The OpenPGP key authentication relies on a distributed trust model, called the ``web of trust''. The ``web of trust'' uses a decentralized system of trusted introducers, which are the same as a CA. OpenPGP allows anyone to sign anyone else's public key. When Alice signs Bob's key, she is introducing Bob's key to anyone who trusts Alice. If someone trusts Alice to introduce keys, then Alice is a trusted introducer in the mind of that observer. For example in fig:openpgp, David trusts Alice to be an introducer and Alice signed Bob's key thus Dave trusts Bob's key to be the real one.

Figure: An example of the OpenPGP trust model.

There are some key points that are important in that model. In the example Alice has to sign Bob's key, only if she is sure that the key belongs to Bob. Otherwise she may also make Dave falsely believe that this is Bob's key. Dave has also the responsibility to know who to trust.  This model is similar to real life relations.

Just see how Charlie behaves in the previous example. Although he has signed Bob's key - because he knows, somehow, that it belongs to Bob - he does not trust Bob to be an introducer. Charlie decided to trust only Kevin, for some reason. A reason could be that Bob is lazy enough, and signs other people's keys without being sure that they belong to the actual owner.

OpenPGP certificate structure
-----------------------------

In GnuTLS the OpenPGP key structures RFC2440 are handled using the gnutls_openpgp_crt_t type and the corresponding private keys with the gnutls_openpgp_privkey_t type. All the prototypes for the key handling functions can be found at gnutls/openpgp.h.

Verifying an OpenPGP certificate
--------------------------------

The verification functions of OpenPGP keys, included in 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 GnuPG and GPGME (http://www.gnupg.org/related_software/gpgme/) is recommended.

In GnuTLS there is a verification function for OpenPGP certificates, the gnutls_openpgp_crt_verify_ring.  This checks an OpenPGP key against a given set of public keys (keyring) and returns the key status. The key verification status is the same as in X.509 certificates, although the meaning and interpretation are different. For example an OpenPGP key may be valid, if the self signature is ok, even if no signers were found.  The meaning of verification status flags is the same as in the X.509 certificates (see gnutls_certificate_verify_flags).

gnutls_openpgp_crt_verify_ring

gnutls_openpgp_crt_verify_self

Verifying a certificate in the context of a TLS session
-------------------------------------------------------

Similarly with X.509 certificates, one needs to specify the OpenPGP keyring file in the credentials structure. The certificates in this file will be  used by gnutls_certificate_verify_peers2 to verify the signatures in the certificate sent by the peer.

gnutls_certificate_set_openpgp_keyring_file

Hardware tokens
===============

Introduction
------------

This section copes with hardware token support in GnuTLS using PKCS #11 PKCS11. PKCS #11 is plugin API allowing applications to access cryptographic operations on a token, as well as to objects residing on the token. A token can be a real hardware token such as a smart card and a trusted platform module (TPM), or it can be a software component such as Gnome Keyring. The objects residing on such token can be certificates, public keys, private keys or even plain data or  secret keys. Of those certificates and public/private key pairs can be used with GnuTLS. Its main advantage is that it allows operations on private key objects such as decryption and signing without exposing the key.

A PKCS #11 module to access smart cards is provided by the Opensc (http://www.opensc-project.org) project, and a module to access the TPM chip on a PC is available from the Trousers (http://trousers.sourceforge.net/) project.

Moreover PKCS #11 can be (ab)used to allow all applications in the same operating system to access shared cryptographic keys and certificates in a uniform way, as in fig:pkcs11-vision. That way applications could load their trusted certificate list, as well as user certificates from a common PKCS #11 module. Such a provider exists in the Gnome system, being the Gnome Keyring.

Figure: PKCS #11 module usage.

Initialization
--------------

To allow all the  GnuTLS applications to access PKCS #11 tokens you can use a configuration per module, stored in /etc/pkcs11/modules/. These are the configuration files of p11-kit (http://p11-glue.freedesktop.org/). For example a file that will load the OpenSC module, could be named /etc/pkcs11/modules/opensc and contain the following:

     module: /usr/lib/opensc-pkcs11.so

If you use this file, then there is no need for other initialization in 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.

gnutls_pkcs11_init gnutls_pkcs11_deinit

gnutls_pkcs11_set_token_function gnutls_pkcs11_set_pin_function gnutls_pkcs11_add_provider

Note that due to limitations of PKCS #11 there are issues when multiple libraries are sharing a module. To avoid this problem GnuTLS uses p11-kit that provides a middleware to control access to resources over the multiple users.

Reading objects
---------------

All PKCS #11 objects are referenced by GnuTLS functions by URLs as described in PKCS11URI. This allows for a consistent naming of objects across systems and applications in the same system. For example a public key on a smart card may be referenced as:

     pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315; \
     manufacturer=EnterSafe;object=test1;objecttype=public;\
     id=32f153f3e37990b08624141077ca5dec2d15faed

while the smart card itself can be referenced as:

     pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315;manufacturer=EnterSafe

Objects stored in a PKCS #11 token can be extracted if they are not marked as sensitive. Usually only private keys are marked as sensitive and cannot be extracted, while certificates and other data can be retrieved. The functions that can be used to access objects are shown below.

gnutls_pkcs11_obj_init,gnutls_pkcs11_obj_deinit

gnutls_pkcs11_obj_import_url

gnutls_pkcs11_obj_export_url

gnutls_pkcs11_obj_export

gnutls_pkcs11_obj_get_info

gnutls_pkcs11_obj_list_import_url

gnutls_x509_crt_import_pkcs11,gnutls_x509_crt_import_pkcs11_url,gnutls_x509_crt_list_import_pkcs11

Properties of the physical token can also be accessed and altered with GnuTLS. For example data in a token can be erased (initialized), PIN can be altered, etc.

gnutls_pkcs11_token_init,gnutls_pkcs11_token_get_url,gnutls_pkcs11_token_get_info,gnutls_pkcs11_token_get_flags gnutls_pkcs11_token_set_pin

The following examples demonstrate the usage of the API. The first example will list all available PKCS #11 tokens in a system and the latter will list all certificates in a token that have a corresponding private key.

     int i;
     char* url;

     gnutls_global_init();

     for (i=0;;i++)
       {
         ret = gnutls_pkcs11_token_get_url(i, &url);
         if (ret == GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE)
           break;

         if (ret < 0)
           exit(1);

         fprintf(stdout, "Token[%d]: URL: %s\n", i, url);
         gnutls_free(url);
       }
     gnutls_global_deinit();

     [file ex-pkcs11-list.c not included]

Writing objects
---------------

With GnuTLS you can copy existing private keys and certificates to a token. Note that when copying private keys it is recommended to mark them as sensitive using the GNUTLS_PKCS11_OBJ_FLAG_MARK_SENSITIVE to prevent its extraction. An object can be marked as private using the flag GNUTLS_PKCS11_OBJ_FLAG_MARK_PRIVATE, to require PIN to be entered before accessing the object (for operations or otherwise).

gnutls_pkcs11_copy_x509_privkey

gnutls_pkcs11_copy_x509_crt gnutls_pkcs11_delete_url

Using a PKCS #11 token with TLS
-------------------------------

It is possible to use a PKCS #11 token to a TLS session, as shown in ex:pkcs11-client. In addition the following functions can be used to load PKCS #11 key and certificates by specifying a PKCS #11 URL instead of a filename.

gnutls_certificate_set_x509_trust_file,gnutls_certificate_set_x509_key_file

Abstract key types
==================

Since there are many forms of a public or private keys supported by GnuTLS such as X.509, OpenPGP, or PKCS #11 it is desirable to allow common operations on them. For these reasons the abstract gnutls_privkey_t and gnutls_pubkey_t were introduced in gnutls/abstract.h header. Those types are initialized using a specific type of key and then can be used to perform operations in an abstract way. For example in order to sign an X.509 certificate with a key that resides in a token the following steps must be used.

     #inlude <gnutls/abstract.h>
     #inlude <gnutls/pkcs11.h>

     void sign_cert( gnutls_x509_crt_t to_be_signed)
     {
     gnutls_pkcs11_privkey_t ca_key;
     gnutls_x509_crt_t ca_cert;
     gnutls_privkey_t abs_key;

       /* load the PKCS #11 key and certificates */
       gnutls_pkcs11_privkey_init(&ca_key);
       gnutls_pkcs11_privkey_import_url(ca_key, key_url);

       gnutls_x509_crt_init(&ca_cert);
       gnutls_x509_crt_import_pkcs11_url(&ca_cert, cert_url);

       /* initialize the abstract key */
       gnutls_privkey_init(&abs_key);
       gnutls_privkey_import_pkcs11(abs_key, ca_key);

       /* sign the certificate to be signed */
       gnutls_x509_crt_privkey_sign(to_be_signed, ca_cert, ca_key,
                                    GNUTLS_DIG_SHA1, 0);
     }

Public keys
-----------

An abstract gnutls_pubkey_t can be initialized using the functions below. It can be imported through an existing structure like gnutls_x509_crt_t, or through an ASN.1 encoding of the X.509 SubjectPublicKeyInfo sequence.

gnutls_pubkey_init,gnutls_pubkey_deinit

gnutls_pubkey_import_x509

gnutls_pubkey_import_openpgp gnutls_pubkey_import_pkcs11 gnutls_pubkey_import_pkcs11_url gnutls_pubkey_import_privkey gnutls_pubkey_import gnutls_pubkey_export

Additional functions are available that will return information over a public key.

gnutls_pubkey_get_pk_algorithm

gnutls_pubkey_get_preferred_hash_algorithm gnutls_pubkey_get_key_id

Private keys
------------

An abstract gnutls_privkey_t can be initialized using the functions below. It can be imported through an existing structure like gnutls_x509_privkey_t, but unlike public keys it cannot be exported. That is to allow abstraction over PKCS #11 keys that are not extractable.

gnutls_privkey_init,gnutls_privkey_deinit

gnutls_privkey_import_x509

gnutls_privkey_import_openpgp,gnutls_privkey_import_pkcs11,gnutls_privkey_import_ext gnutls_privkey_get_pk_algorithm gnutls_privkey_get_type

Operations
----------

The abstract key types can be used to access signing and signature verification operations with the underlying keys.

gnutls_pubkey_verify_data2 gnutls_pubkey_verify_hash gnutls_privkey_sign_data gnutls_privkey_sign_hash

Signing existing structures, such as certificates, CRLs, or certificate requests, as well as associating public keys with structures is also possible using the key abstractions.

gnutls_x509_crq_set_pubkey gnutls_x509_crt_set_pubkey gnutls_x509_crt_privkey_sign,gnutls_x509_crl_privkey_sign,gnutls_x509_crq_privkey_sign

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 € to Greenpeace and find out that he donated 1.000.000 € to Bad Inc.

For a hash algorithm to be called cryptographic the following three requirements must hold:

 1. Preimage resistance. That means the algorithm must be one way and given the output of the hash function H(x), it is impossible to calculate x.

 2. 2nd preimage resistance. That means that given a pair x,y with y=H(x) it is impossible to calculate an x' such that y=H(x').

 3. Collision resistance. That means that it is impossible to calculate random x and x' such H(x')=H(x).

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 2^((hash size) / 2) operations. Today colliding certificates using the MD5 hash algorithm have been generated as shown in 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 2^64, but it has been showed to have a collision strength well under 2^50.  As of November 2005, it is believed that SHA-1's collision strength is around 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 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.

Trading security for interoperability
-------------------------------------

If you connect to a server and use GnuTLS' functions to verify the certificate chain, and get a GNUTLS_CERT_INSECURE_ALGORITHM validation error (see Verifying X.509 certificate paths), it means that somewhere in the certificate chain there is a certificate signed using RSA-MD2 or 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 RSA-MD2 or RSA-MD5. The certificates in the trusted list are considered trusted irrespective of the signature.

If you are using gnutls_certificate_verify_peers2 to verify the certificate chain, you can call gnutls_certificate_set_verify_flags with the flags:

  * GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD2

  * GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5

as in the following example:

       gnutls_certificate_set_verify_flags (x509cred,
                                            GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5);

This will tell the verifier algorithm to enable RSA-MD5 when verifying the certificates.

If you are using gnutls_x509_crt_verify or gnutls_x509_crt_list_verify, you can pass the GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5 parameter directly in the 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 gnutls_certificate_get_peers to extract the raw server's certificate chain, gnutls_x509_crt_list_import to parse each of the certificates, and then gnutls_x509_crt_get_signature_algorithm to find out the signing algorithm used for each certificate.  If any of the intermediary certificates are using GNUTLS_SIGN_RSA_MD2 or GNUTLS_SIGN_RSA_MD5, you could present a warning.