guile: Fix `priorities' test to use `run-test'.

[gnutls.git] / doc / cha-cert-auth.texi

@node More on certificate authentication
@chapter More on certificate authentication
@cindex certificate authentication

@menu
* X.509 certificates::
* OpenPGP certificates::
* Hardware tokens::
* Abstract key types::
* Digital signatures::
@end menu

@node X.509 certificates
@section @acronym{X.509} certificates
@cindex @acronym{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{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::
* Verifying X.509 certificate paths::
* Verifying a certificate in the context of TLS session::
* Certificate requests::
* PKCS 12 structures::
@end menu

@node X.509 certificate structure
@subsection @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 .3 .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 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.

Certificate @emph{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 @acronym{X.509} version 3
extensions are shown in @ref{tab:x509-ext}.

@float Table,tab:x509-ext
@multitable @columnfractions .3 .2 .5

@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 Authority key id @tab 2.5.29.35 @tab
An identifier of the authority's key used to sign the certificate.

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

@item Key usage @tab 2.5.29.15 @tab
Constraints the key's usage of the certificate.

@item Extended key usage @tab 2.5.29.37 @tab
Constraints the purpose of the certificate.

@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 CRL distribution points @tab 2.5.29.31 @tab
This extension is set by the CA, in order to inform about the issued
CRLs.

@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{X.509 certificate extensions.}
@end float

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 at
@ref{ex:x509-info}.

@node Verifying X.509 certificate paths
@subsection 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.

@showfuncB{gnutls_x509_trust_list_init,gnutls_x509_trust_list_deinit}

@showfuncdesc{gnutls_x509_trust_list_add_cas}
@showfuncdesc{gnutls_x509_trust_list_add_named_crt}
@showfuncdesc{gnutls_x509_trust_list_add_crls}
@showfuncdesc{gnutls_x509_trust_list_verify_crt}
@showfuncdesc{gnutls_x509_trust_list_verify_named_crt}

The verification function will verify a given certificate chain against a list of certificate
authorities and certificate revocation lists, and output
a bit-wise OR of elements of the @code{gnutls_@-certificate_@-status_t} 
enumeration. 
A detailed description of these elements can be found 
in @ref{tab:cert-verify}. 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
@subsection 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 has been set via the
@funcref{gnutls_certificate_set_x509_trust_file} and @funcref{gnutls_certificate_set_x509_crl_file},
thus it is not required to setup a trusted list as above.
Convenience functions such as @funcref{gnutls_certificate_verify_peers2} 
are equivalent and will verify the peer's certificate chain
in a TLS session. 

@float Table,tab:cert-verify
@multitable @columnfractions .55 .45

@headitem Flag @tab Description

@item GNUTLS_CERT_INVALID @tab
The certificate is not signed by one of the known authorities, or
the signature is invalid.

@item GNUTLS_CERT_REVOKED @tab
The certificate has been revoked by its CA.

@item GNUTLS_CERT_SIGNER_NOT_FOUND @tab
The certificate's issuer is not known. This is the case when the
issuer is not in the trusted certificates list.

@item GNUTLS_CERT_SIGNER_NOT_CA @tab
The certificate's signer was not a CA. This may happen if
this was a version 1 certificate, which is common with some CAs, or
a version 3 certificate without the basic constrains extension.

@item GNUTLS_CERT_INSECURE_ALGORITHM @tab
The certificate was signed using an insecure algorithm such as MD2 or
MD5.  These algorithms have been broken and should not be trusted.

@end multitable
@caption{Certificate verification output flags.}
@end float

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_crt} the
flags are passed straightforward, but
@funcref{gnutls_certificate_verify_peers2} depends on the flags set by
calling @funcref{gnutls_certificate_set_verify_flags}.  All the available
flags are part of the enumeration
@code{gnutls_certificate_verify_flags} and are explained in @ref{tab:cert-flags}.

@float Table,tab:cert-flags
@multitable @columnfractions .5 .5

@headitem Flag @tab Description
@item GNUTLS_VERIFY_@-DISABLE_CA_SIGN @tab
If set a signer does not have to be a certificate authority. This
flag should normally be disabled, unless you know what this means.

@item GNUTLS_VERIFY_@-ALLOW_X509_V1_CA_CRT @tab
Allow only trusted CA certificates that have version 1.  This is
safer than GNUTLS_VERIFY_@-ALLOW_ANY_X509_V1_CA_CRT, and should be
used instead. That way only signers in your trusted list will be
allowed to have certificates of version 1. This is the default.

@item GNUTLS_VERIFY_@-DO_NOT_ALLOW_X509_V1_CA_CRT @tab
Do not allow trusted version 1 CA certificates.  This option is to be used
in order consider all V1 certificates as deprecated.

@item GNUTLS_VERIFY_@-ALLOW_ANY_X509_V1_CA_CRT @tab
Allow CA certificates that have version 1 (both root and
intermediate). This is dangerous since those haven't the
basicConstraints extension. Must be used in combination with
GNUTLS_VERIFY_@-ALLOW_X509_V1_CA_CRT.

@item GNUTLS_VERIFY_@-DO_NOT_ALLOW_SAME @tab
If a certificate is not signed by anyone trusted but exists in
the trusted CA list do not treat it as trusted.

@item GNUTLS_VERIFY_@-ALLOW_SIGN_RSA_MD2 @tab
Allow certificates to be signed using the old MD2 algorithm.

@item GNUTLS_VERIFY_@-ALLOW_SIGN_RSA_MD5 @tab
Allow certificates to be signed using the broken MD5 algorithm.

@item GNUTLS_VERIFY_@-DISABLE_TIME_CHECKS @tab
Disable checking of activation
and expiration validity periods of certificate chains. Don't set
this unless you understand the security implications.

@item GNUTLS_VERIFY_@-DISABLE_CRL_CHECKS @tab
Disables checking for validity using certificate revocation lists.

@end multitable
@caption{Certificate verification flags.}
@end float

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 @xcite{RFC2818} and section @ref{ex:verify} for an example.

@node Certificate requests
@subsection @acronym{PKCS} #10 certificate requests
@cindex certificate requests
@cindex @acronym{PKCS} #10

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. @acronym{GnuTLS} supports the requests defined in
@acronym{PKCS} #10 @xcite{RFC2986}. Other formats of certificate requests
are not currently supported.

@showfuncB{gnutls_x509_crq_init,gnutls_x509_crq_deinit}

@showfuncdesc{gnutls_x509_crq_import}
@showfuncdesc{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.

@showfuncdesc{gnutls_x509_crq_set_version}
@showfuncdesc{gnutls_x509_crq_set_dn_by_oid}
@showfuncdesc{gnutls_x509_crq_set_key_usage}
@showfuncdesc{gnutls_x509_crq_set_key_purpose_oid}
@showfuncdesc{gnutls_x509_crq_set_basic_constraints}

The following two functions associate the request with
a private key and sign it. If a request is to be signed
with a key residing in a token it is recommended to use
the signing functions shown in @ref{Abstract key types}.

@showfuncdesc{gnutls_x509_crq_set_key}
@showfuncdesc{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.

@anchor{ex:crq}
@verbatiminclude examples/ex-crq.c

@node PKCS 12 structures
@subsection @acronym{PKCS} #12 structures
@cindex @acronym{PKCS} #12

A @acronym{PKCS} #12 structure @xcite{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 @acronym{GnuTLS} the @acronym{PKCS} #12 structures are handled
using the @code{gnutls_pkcs12_t} type. This is an abstract type that
may hold several @code{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.

@showfuncB{gnutls_pkcs12_init,gnutls_pkcs12_deinit}

The following functions are available to read a @acronym{PKCS} #12
structure.

@showfuncdesc{gnutls_pkcs12_import}
@showfuncdesc{gnutls_pkcs12_get_bag}
@showfuncdesc{gnutls_pkcs12_verify_mac}
@showfuncdesc{gnutls_pkcs12_bag_decrypt}

@showfuncB{gnutls_pkcs12_bag_init,gnutls_pkcs12_bag_deinit}

@showfuncD{gnutls_pkcs12_bag_get_count,gnutls_pkcs12_bag_get_data,gnutls_pkcs12_bag_get_key_id,gnutls_pkcs12_bag_get_friendly_name}

To generate a structure the functions below may be used.

@showfuncdesc{gnutls_pkcs12_set_bag}
@showfuncdesc{gnutls_pkcs12_bag_encrypt}
@showfuncdesc{gnutls_pkcs12_generate_mac}
@showfuncdesc{gnutls_pkcs12_export}
@showfuncE{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}

An example of a @acronym{PKCS} #12 structure generation can be found
below.

@verbatiminclude examples/ex-pkcs12.c

@node OpenPGP certificates
@section @acronym{OpenPGP} certificates
@cindex @acronym{OpenPGP} certificates

The @acronym{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. @acronym{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 @ref{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.

@float Figure,fig:openpgp
@image{gnutls-pgp,8cm}
@caption{The OpenPGP trust model.}
@end float

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.

@subsection @acronym{OpenPGP} certificate structure

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

@subsection Verifying an @acronym{OpenPGP} certificate

The verification functions of @acronym{OpenPGP} keys, included in
@acronym{GnuTLS}, are simple ones, and do not use the features of the
``web of trust''.  For that reason, if the verification needs are
complex, the assistance of external tools like @acronym{GnuPG} and
GPGME@footnote{@url{http://www.gnupg.org/related_software/gpgme/}} is
recommended.

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

@showfuncdesc{gnutls_openpgp_crt_verify_ring}

@showfuncdesc{gnutls_openpgp_crt_verify_self}

@table @code

@item CERT_INVALID:
A signature on the key is invalid. That means that the key was
modified by somebody, or corrupted during transport.

@item CERT_REVOKED:
The key has been revoked by its owner.

@item CERT_SIGNER_NOT_FOUND:
The key was not signed by a known signer.

@item GNUTLS_CERT_INSECURE_ALGORITHM:
The certificate was signed using an insecure algorithm such as MD2 or
MD5.  These algorithms have been broken and should not be trusted.

@end table

@subsection 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 @funcref{gnutls_certificate_verify_peers2}
to verify the signatures in the certificate sent by the peer.

@showfuncdesc{gnutls_certificate_set_openpgp_keyring_file}


@node Hardware tokens
@section Hardware tokens
@cindex PKCS #11 tokens
@cindex hardware tokens
@cindex smart cards

@subsection Introduction
This section copes with hardware token support in @acronym{GnuTLS} using 
@acronym{PKCS} #11 @xcite{PKCS11}.
@acronym{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, or it can be a software component
such as @acronym{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 @acronym{GnuTLS}. Its
main advantage is that it allows operations on private key objects such as decryption
and signing without exposing the key.

Moreover it can be used to allow all applications in the same operating system to access
shared cryptographic keys and certificates in a uniform way, as in @ref{fig:pkcs11-vision}.

@float Figure,fig:pkcs11-vision
@image{pkcs11-vision,9cm}
@caption{PKCS #11 module usage.}
@end float

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

@smallexample
module: /usr/lib/opensc-pkcs11.so
@end smallexample

If you use this file, then there is no need for other initialization in
@acronym{GnuTLS}, except for the PIN and token functions. Those allow retrieving a PIN
when accessing a protected object, such as a private key, as well as probe
the user to insert the token. All the initialization functions are below.

@showfuncdesc{gnutls_pkcs11_init}
@showfuncdesc{gnutls_pkcs11_set_token_function}
@showfuncdesc{gnutls_pkcs11_set_pin_function}
@showfuncdesc{gnutls_pkcs11_add_provider}
@showfuncA{gnutls_pkcs11_deinit}

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

@subsection Reading objects

All @acronym{PKCS} #11 objects are referenced by @acronym{GnuTLS} functions by
URLs as described in @code{draft-pechanec-pkcs11uri-05}. 
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:

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

while the smart card itself can be referenced as:
@smallexample
pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315;manufacturer=EnterSafe
@end smallexample

Objects stored in a @acronym{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.

@showfuncB{gnutls_pkcs11_obj_init,gnutls_pkcs11_obj_deinit}

@showfuncdesc{gnutls_pkcs11_obj_import_url}

@showfuncdesc{gnutls_pkcs11_obj_export_url}

@showfuncdesc{gnutls_pkcs11_obj_export}

@showfuncdesc{gnutls_pkcs11_obj_get_info}

@showfuncdesc{gnutls_pkcs11_obj_list_import_url}

@showfuncC{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 @acronym{GnuTLS}.
For example data in a token can be erased (initialized), PIN can be altered, etc.

@showfuncdesc{gnutls_pkcs11_token_init}
@showfuncdesc{gnutls_pkcs11_token_set_pin}
@showfuncdesc{gnutls_pkcs11_token_get_url}
@showfuncdesc{gnutls_pkcs11_token_get_info}
@showfuncdesc{gnutls_pkcs11_token_get_flags}

The following example will list all available PKCS #11 tokens in a system.
@example
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();
@end example


That example will only list all certificates in a token that have a corresponding
private key.
@verbatiminclude examples/ex-pkcs11-list.c

@subsection Writing objects

With @acronym{GnuTLS} you can copy existing private keys and certificates
to a token. Note that when copying private keys it is recommended to mark
them as sensitive using the @code{GNUTLS_@-PKCS11_OBJ_@-FLAG_@-MARK_@-SENSITIVE}
to prevent its extraction. An object can be marked as private using the flag 
@code{GNUTLS_@-PKCS11_OBJ_@-FLAG_@-MARK_@-PRIVATE}, to require PIN to be
entered before accessing the object (for operations or otherwise).

@showfuncdesc{gnutls_pkcs11_delete_url}
@showfuncdesc{gnutls_pkcs11_copy_x509_privkey}
@showfuncdesc{gnutls_pkcs11_copy_x509_crt}


@subsection Using a @acronym{PKCS} #11 token with TLS

It is possible to use a @acronym{PKCS} #11 token to a TLS
session, as shown in @ref{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.

@showfuncB{gnutls_certificate_set_x509_trust_file,gnutls_certificate_set_x509_key_file}


@node Abstract key types
@section Abstract key types
@cindex abstract types

Since there are many forms of a public or private keys supported by @acronym{GnuTLS} such as
@acronym{X.509}, @acronym{OpenPGP}, or @acronym{PKCS} #11 it is desirable to allow common operations
on them. For these reasons the abstract @code{gnutls_privkey_t} and @code{gnutls_pubkey_t} were
introduced in @code{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 for someone 
to sign an X.509 certificate with a key that resides in a smart he has to follow the steps below:

@example
#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);
@}
@end example

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

@showfuncB{gnutls_pubkey_init,gnutls_pubkey_deinit}

@showfuncdesc{gnutls_pubkey_import_x509}
@showfuncdesc{gnutls_pubkey_import_openpgp}
@showfuncdesc{gnutls_pubkey_import_pkcs11}
@showfuncdesc{gnutls_pubkey_import_pkcs11_url}
@showfuncdesc{gnutls_pubkey_import_privkey}
@showfuncdesc{gnutls_pubkey_import}
@showfuncdesc{gnutls_pubkey_export}

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

@showfuncdesc{gnutls_pubkey_get_pk_algorithm}
@showfuncdesc{gnutls_pubkey_get_preferred_hash_algorithm}
@showfuncdesc{gnutls_pubkey_get_key_id}

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

@showfuncB{gnutls_privkey_init,gnutls_privkey_deinit}

@showfuncdesc{gnutls_privkey_import_x509}
@showfuncdesc{gnutls_privkey_import_openpgp}
@showfuncdesc{gnutls_privkey_import_pkcs11}

Other information on the private key can be accessed using
the following functions.

@showfuncdesc{gnutls_privkey_get_pk_algorithm}
@showfuncdesc{gnutls_privkey_get_type}

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

@showfuncdesc{gnutls_pubkey_verify_data2}
@showfuncdesc{gnutls_pubkey_verify_hash}
@showfuncdesc{gnutls_privkey_sign_data}
@showfuncdesc{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.

@showfuncdesc{gnutls_x509_crq_set_pubkey}
@showfuncdesc{gnutls_x509_crt_set_pubkey}
@showfuncdesc{gnutls_x509_crt_privkey_sign}
@showfuncdesc{gnutls_x509_crl_privkey_sign}
@showfuncdesc{gnutls_x509_crq_privkey_sign}

@node Digital signatures
@section 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 he
donated 1.000.000 @euro{} 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.

@subsection 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 fail when attempting to
verify 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.

First, 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 signed using @code{RSA-MD2} or @code{RSA-MD5}.  The only
attack today is that it is possible to generate certificates with
colliding signatures (collision resistance); you cannot generate a
certificate that has the same signature as an already existing
signature (2nd preimage resistance).

If you are using @funcref{gnutls_certificate_verify_peers2} 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}
@end itemize
as in the following example:

@smallexample
  gnutls_certificate_set_verify_flags (x509cred,
                                       GNUTLS_VERIFY_ALLOW_SIGN_RSA_MD5);
@end smallexample

This will tell 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, then use
@funcref{gnutls_x509_crt_import} to parse each of the certificates, and
then use @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.