corrected function name

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

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

Certificates are not the only structures involved in a public key
infrastructure. Several other structures that are used for certificate
requests, encrypted private keys, revocation lists, GnuTLS abstract key
structures, etc., are discussed in this chapter.

@menu
* PKCS 10 certificate requests::
* PKIX certificate revocation lists::
* OCSP certificate status checking::
* Managing encrypted keys::
* certtool Invocation::            Invoking certtool
* ocsptool Invocation::            Invoking ocsptool
* Smart cards and HSMs::
* Abstract key types::
@end menu

@node PKCS 10 certificate requests
@section @acronym{PKCS} #10 certificate requests
@cindex certificate requests
@cindex 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.

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.

@showfuncE{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 @funcref{gnutls_x509_crq_set_key} and @funcref{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 @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 PKIX certificate revocation lists
@section PKIX certificate revocation lists
@cindex certificate revocation lists
@cindex CRL

A certificate revocation list (CRL) is a structure issued by an authority
periodically containing a list of revoked certificates serial numbers. 
The CRL structure is signed with the issuing authorities' keys. A typical
CRL contains the fields as shown in @ref{tab:crl}.
Certificate revocation lists are used to complement the expiration date of a certificate,
in order to account for other reasons of revocation, such as compromised keys, etc.

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. Each CRL is valid for limited amount of
time and is required to provide, except for the current issuing time, also 
the issuing time of the next update.

@float Table,tab:crl
@multitable @columnfractions .2 .7

@headitem Field @tab Description

@item version @tab
The field that indicates the version of the CRL structure.

@item signature @tab
A signature by the issuing authority.

@item issuer @tab
Holds the issuer's distinguished name.

@item thisUpdate @tab
The issuing time of the revocation list.

@item nextUpdate @tab
The issuing time of the revocation list that will update that one.

@item revokedCertificates @tab
List of revoked certificates serial numbers.

@item extensions @tab
Optional CRL structure extensions.

@end multitable
@caption{Certificate revocation list fields.}
@end float


@showfuncE{gnutls_x509_crl_set_version,gnutls_x509_crl_set_crt_serial,gnutls_x509_crl_set_crt,gnutls_x509_crl_set_next_update,gnutls_x509_crl_set_this_update}

The @funcref{gnutls_x509_crl_sign2} and @funcref{gnutls_x509_crl_privkey_sign} 
functions sign the revocation list with a private key. The latter function
can be used to sign with a key residing in a PKCS #11 token.

@showfuncdesc{gnutls_x509_crl_sign2}
@showfuncdesc{gnutls_x509_crl_privkey_sign}

Few extensions on the CRL structure are supported, including the
CRL number extension and the authority key identifier.

@showfuncB{gnutls_x509_crl_set_number,gnutls_x509_crl_set_authority_key_id}

@node OCSP certificate status checking
@section @acronym{OCSP} certificate status checking
@cindex certificate status
@cindex Online Certificate Status Protocol
@cindex OCSP

Certificates may be revoked before their expiration time has been
reached.  There are several reasons for revoking certificates, but a
typical situation is when the private key associated with a
certificate has been compromised.  Traditionally, Certificate
Revocation Lists (CRLs) have been used by application to implement
revocation checking, however, several problems with CRLs have been
identified @xcite{RIVESTCRL}.

The Online Certificate Status Protocol, or @acronym{OCSP} @xcite{RFC2560}, 
is a widely implemented protocol to perform certificate revocation status
checking.  An application that wish to verify the
identity of a peer will verify the certificate against a set of
trusted certificates and then check whether the certificate is listed
in a CRL and/or perform an OCSP check for the certificate.

Before performing the OCSP query, the application will need to figure
out the address of the OCSP server.  The OCSP server address can be
provided by the local user in manual configuration or may be stored
in the certificate that is being checked.  The latter is due to
an extension field called the Authority Information Access (AIA) which
may hold the location of the OCSP responder in 
the access method called @code{id-ad-ocsp}. The following function
extracts this information from a certificate.

@showfuncA{gnutls_x509_crt_get_authority_info_access}

There are several functions in GnuTLS for creating and manipulating
OCSP requests and responses.  The general idea is that a client
application create an OCSP request object, store some information
about the certificate to check in the request, and then export the
request in DER format.  The request will then need to be sent to the
OCSP responder, which needs to be done by the application (GnuTLS does
not send and receive OCSP packets).  Normally an OCSP response is
received that the application will need to import into an OCSP
response object.  The digital signature in the OCSP response needs to
be verified against a set of trust anchors before the information in
the response can be trusted.

The ASN.1 structure of OCSP requests are briefly as follows.  It is
useful to review the structures to get an understanding of which
fields are modified by GnuTLS functions.

@example
OCSPRequest     ::=     SEQUENCE @{
    tbsRequest                  TBSRequest,
    optionalSignature   [0]     EXPLICIT Signature OPTIONAL @}

TBSRequest      ::=     SEQUENCE @{
    version             [0]     EXPLICIT Version DEFAULT v1,
    requestorName       [1]     EXPLICIT GeneralName OPTIONAL,
    requestList                 SEQUENCE OF Request,
    requestExtensions   [2]     EXPLICIT Extensions OPTIONAL @}

Request         ::=     SEQUENCE @{
    reqCert                     CertID,
    singleRequestExtensions     [0] EXPLICIT Extensions OPTIONAL @}

CertID          ::=     SEQUENCE @{
    hashAlgorithm       AlgorithmIdentifier,
    issuerNameHash      OCTET STRING, -- Hash of Issuer's DN
    issuerKeyHash       OCTET STRING, -- Hash of Issuers public key
    serialNumber        CertificateSerialNumber @}
@end example

The basic functions to initialize, import, export and deallocate OCSP
requests are the following.

@showfuncE{gnutls_ocsp_req_init,gnutls_ocsp_req_deinit,gnutls_ocsp_req_import,gnutls_ocsp_req_export,gnutls_ocsp_req_print}

There are two interfaces for setting the identity of a certificate in
a OCSP request, the first being a low-level function when you have the
issuer name hash, issuer key hash, and certificate serial number in
binary form.  The second is usually more useful if you have the
certificate (and its issuer) in a @code{gnutls_x509_crt_t} type.
There is also a function to extract this information from an OCSP
request.

@showfuncC{gnutls_ocsp_req_add_cert_id,gnutls_ocsp_req_add_cert,gnutls_ocsp_req_get_cert_id}

Each OCSP request may contain a number of extensions.  Extensions are
identified by an Object Identifier (OID) and an opaque data buffer
whose syntax and semantics is implied by the OID.

@showfuncB{gnutls_ocsp_req_get_extension,gnutls_ocsp_req_set_extension}

A common OCSP Request extension is the nonce extension (OID
1.3.6.1.5.5.7.48.1.2), which is used to avoid replay attacks of
earlier recorded OCSP responses.  The nonce extension carries a value
that is intended to be sufficiently random and unique so that an
attacker will not be able to give a stale response for the same nonce.

@showfuncC{gnutls_ocsp_req_get_nonce,gnutls_ocsp_req_set_nonce,gnutls_ocsp_req_randomize_nonce}

The OCSP response structures is a bit more complex than the request.
The important ASN.1 structure is as follows.  In practice, all OCSP
responses contain a Basic OCSP response sub-structure.

@example
OCSPResponse ::= SEQUENCE @{
   responseStatus         OCSPResponseStatus,
   responseBytes          [0] EXPLICIT ResponseBytes OPTIONAL @}

OCSPResponseStatus ::= ENUMERATED @{
    successful            (0),  --Response has valid confirmations
    malformedRequest      (1),  --Illegal confirmation request
    internalError         (2),  --Internal error in issuer
    tryLater              (3),  --Try again later
                                --(4) is not used
    sigRequired           (5),  --Must sign the request
    unauthorized          (6)   --Request unauthorized @}

ResponseBytes ::=       SEQUENCE @{
    responseType   OBJECT IDENTIFIER,
    response       OCTET STRING @}

id-pkix-ocsp-basic     OBJECT IDENTIFIER ::= @{ id-pkix-ocsp 1 @}

BasicOCSPResponse       ::= SEQUENCE @{
   tbsResponseData      ResponseData,
   signatureAlgorithm   AlgorithmIdentifier,
   signature            BIT STRING,
   certs                [0] EXPLICIT SEQUENCE OF Certificate OPTIONAL @}

ResponseData ::= SEQUENCE @{
   version              [0] EXPLICIT Version DEFAULT v1,
   responderID              ResponderID,
   producedAt               GeneralizedTime,
   responses                SEQUENCE OF SingleResponse,
   responseExtensions   [1] EXPLICIT Extensions OPTIONAL @}

ResponderID ::= CHOICE @{
   byName               [1] Name,
   byKey                [2] KeyHash @}

KeyHash ::= OCTET STRING -- SHA-1 hash of responder's public key
(excluding the tag and length fields)

SingleResponse ::= SEQUENCE @{
   certID                       CertID,
   certStatus                   CertStatus,
   thisUpdate                   GeneralizedTime,
   nextUpdate         [0]       EXPLICIT GeneralizedTime OPTIONAL,
   singleExtensions   [1]       EXPLICIT Extensions OPTIONAL @}

CertStatus ::= CHOICE @{
    good        [0]     IMPLICIT NULL,
    revoked     [1]     IMPLICIT RevokedInfo,
    unknown     [2]     IMPLICIT UnknownInfo @}

RevokedInfo ::= SEQUENCE @{
    revocationTime              GeneralizedTime,
    revocationReason    [0]     EXPLICIT CRLReason OPTIONAL @}
@end example

We provide basic functions for initialization, importing, exporting
and deallocating OCSP responses.  The Basic OCSP Response structure is
automatically parsed when an OCSP Response is imported.

@showfuncE{gnutls_ocsp_resp_init,gnutls_ocsp_resp_deinit,gnutls_ocsp_resp_import,gnutls_ocsp_resp_export,gnutls_ocsp_resp_print}

The OCSP response needs to be verified against some set of trust
anchors before it can be relied upon.

@showfuncB{gnutls_ocsp_resp_verify,gnutls_ocsp_resp_verify_direct}

@node Managing encrypted keys
@section Managing encrypted keys
@cindex Encrypted keys

Transferring or storing private keys in plain might not be a
good idea. Any access on the keys becomes a fatal compromise.
Storing the keys in hardware security modules (see @ref{Smart cards and HSMs})
could solve the storage problem but it is not always practical
or efficient enough. This section describes alternative ways
that involve encryption of the private keys to store and
transfer.

There are two alternatives to use for key encryption, 
PKCS #8 and #12 methods of private key encryption. The PKCS #8
method only allows encryption of the private key, whilst the
PKCS #12 method allows in addition the bundling of other
data into the structure. That could be bundling together the
certificate as well as the trusted CA certificate.

@subheading @acronym{PKCS} #8 structures
@cindex PKCS #8

PKCS #8 keys can be imported and exported as normal private keys using
the functions below. An addition to the normal import functions, are
a password and a flags argument. The flags can be any element of the @code{gnutls_pkcs_encrypt_flags_t}
enumeration. Note however, that GnuTLS only supports the PKCS #5 PBES2
encryption scheme. Keys encrypted with the obsolete PBES1 scheme cannot 
be decrypted.

@showfuncB{gnutls_x509_privkey_import_pkcs8,gnutls_x509_privkey_export_pkcs8}

@showenumdesc{gnutls_pkcs_encrypt_flags_t,Encryption flags}

@subheading @acronym{PKCS} #12 structures
@cindex 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.

@showfuncC{gnutls_pkcs12_get_bag,gnutls_pkcs12_verify_mac,gnutls_pkcs12_bag_decrypt}

@showfuncD{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.

@showfuncC{gnutls_pkcs12_set_bag,gnutls_pkcs12_bag_encrypt,gnutls_pkcs12_generate_mac}
@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}

@verbatiminclude examples/ex-pkcs12.c

@include invoke-certtool.texi

@include invoke-ocsptool.texi

@node Smart cards and HSMs
@section Smart cards and HSMs
@cindex PKCS #11 tokens
@cindex hardware tokens
@cindex hardware security modules
@cindex smart cards

In this section we present the smart-card and hardware security module (HSM) support 
in @acronym{GnuTLS} using @acronym{PKCS} #11 @xcite{PKCS11}. Hardware security
modules and smart cards provide a way to store private keys and perform
operations on them without exposing them. This decouples cryptographic
keys from the applications that use them and provide an additional 
security layer against cryptographic key extraction.
Since this can also be achieved in software components such as in Gnome keyring,
we will use the term security module to describe any cryptographic key 
separation subsystem.

@acronym{PKCS} #11 is plugin API allowing applications to access cryptographic
operations on a security module, as well as to objects residing on it. PKCS
#11 modules exist for hardware tokens such as smart cards@footnote{@url{http://www.opensc-project.org}},
the trusted 
platform module (TPM)@footnote{@url{http://trousers.sourceforge.net/}}
as well as for software modules like @acronym{Gnome Keyring}. 
The objects residing on a security module may be certificates, public keys, 
private keys or secret keys. Of those certificates and public/private key 
pairs can be used with @acronym{GnuTLS}. PKCS #11's main advantage is that 
it allows operations on private key objects such as decryption
and signing without exposing the key.

Moreover @acronym{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 @ref{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 @acronym{Gnome} 
system, being the @acronym{Gnome Keyring}.

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

@menu
* PKCS11 Initialization::
* Reading objects::
* Writing objects::
* Using a PKCS11 token with TLS::
* p11tool Invocation::             Invoking p11tool
@end menu

@node PKCS11 Initialization
@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:

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

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}
@showfuncC{gnutls_pkcs11_set_token_function,gnutls_pkcs11_set_pin_function,gnutls_pkcs11_add_provider}

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.

Moreover PKCS #11 modules must be reinitialized on the child processes
after a @funcintref{fork}. @acronym{GnuTLS} provides @funcref{gnutls_pkcs11_reinit}
to be called for this purpose.

@showfuncdesc{gnutls_pkcs11_reinit}

@node Reading objects
@subsection Reading objects

All @acronym{PKCS} #11 objects are referenced by @acronym{GnuTLS} functions by
URLs as described in @xcite{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:

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

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

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_import_url,gnutls_pkcs11_obj_export_url}

@showfuncdesc{gnutls_pkcs11_obj_get_info}

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

@showfuncE{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.

@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

@verbatiminclude examples/ex-pkcs11-list.c

@node Writing objects
@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_copy_x509_privkey}

@showfuncdesc{gnutls_pkcs11_copy_x509_crt}
@showfuncdesc{gnutls_pkcs11_delete_url}


@node Using a PKCS11 token with TLS
@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}
@showfuncdesc{gnutls_certificate_set_x509_system_trust}

@include invoke-p11tool.texi

@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
to sign an X.509 certificate with a key that resides in a token the following steps must be
used.

@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_SHA256, 0);
@}
@end example

@menu
* Abstract public keys::
* Abstract private keys::
* Operations::
@end menu


@node Abstract public keys
@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.

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

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

@showfuncC{gnutls_pubkey_get_pk_algorithm,gnutls_pubkey_get_preferred_hash_algorithm,gnutls_pubkey_get_key_id}

@node Abstract private keys
@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.

@showfuncC{gnutls_privkey_import_x509,gnutls_privkey_import_openpgp,gnutls_privkey_import_pkcs11}

@showfuncB{gnutls_privkey_get_pk_algorithm,gnutls_privkey_get_type}

In order to support cryptographic operations using 
an external API, the following function is provided.
This allows for a simple extensibility API without
resorting to @acronym{PKCS} #11.

@showfuncdesc{gnutls_privkey_import_ext}

@node Operations
@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_hash2}
@showfuncdesc{gnutls_pubkey_encrypt_data}

@showfuncdesc{gnutls_privkey_sign_data}
@showfuncdesc{gnutls_privkey_sign_hash}
@showfuncdesc{gnutls_privkey_decrypt_data}

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}
@showfuncC{gnutls_x509_crt_privkey_sign,gnutls_x509_crl_privkey_sign,gnutls_x509_crq_privkey_sign}