path: root/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::
* Managing encrypted keys::
* The certtool application::
* 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 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.

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

@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

@node The certtool application
@section The certtool application
@cindex certtool

This is a program to generate @acronym{X.509} certificates, certificate
requests, CRLs and private keys.

@example
Certtool help
Usage: certtool [options]
     -s, --generate-self-signed 
                              Generate a self-signed certificate.
     -c, --generate-certificate 
                              Generate a signed certificate.
     --generate-proxy         Generate a proxy certificate.
     --generate-crl           Generate a CRL.
     -u, --update-certificate 
                              Update a signed certificate.
     -p, --generate-privkey   Generate a private key.
     -q, --generate-request   Generate a PKCS #10 certificate 
                              request.
     -e, --verify-chain       Verify a PEM encoded certificate chain. 
                              The last certificate in the chain must 
                              be a self signed one.
     --verify                 Verify a PEM encoded certificate chain. 
                              CA certificates must be loaded with 
                              --load-ca-certificate.
     --verify-crl             Verify a CRL.
     --generate-dh-params     Generate PKCS #3 encoded Diffie-Hellman 
                              parameters.
     --get-dh-params          Get the included PKCS #3 encoded 
                              Diffie-Hellman parameters.
     --load-privkey FILE      Private key file to use.
     --load-pubkey FILE       Public key file to use.
     --load-request FILE      Certificate request file to use.
     --load-certificate FILE  
                              Certificate file to use.
     --load-ca-privkey FILE   Certificate authority's private key 
                              file to use.
     --load-ca-certificate FILE  
                              Certificate authority's certificate 
                              file to use.
     --password PASSWORD      Password to use.
     -i, --certificate-info   Print information on a certificate.
     --certificate-pubkey     Print certificate public key.
     --pgp-certificate-info   Print information on a OpenPGP 
                              certificate.
     --pgp-ring-info          Print information on a keyring 
                              structure.
     -l, --crl-info           Print information on a CRL.
     --crq-info               Print information on a Certificate 
                              Request.
     --no-crq-extensions      Do not use extensions in certificate 
                              requests.
     --p12-info               Print information on a PKCS #12 
                              structure.
     --p7-info                Print information on a PKCS #7 
                              structure.
     --smime-to-p7            Convert S/MIME to PKCS #7 structure.
     -k, --key-info           Print information on a private key.
     --pgp-key-info           Print information on a OpenPGP private 
                              key.
     --pubkey-info            Print information on a public key.
     --fix-key                Regenerate the parameters in a private 
                              key.
     --v1                     Generate an X.509 version 1 certificate 
                              (no extensions).
     --to-p12                 Generate a PKCS #12 structure.
     --to-p8                  Generate a PKCS #8 key structure.
     -8, --pkcs8              Use PKCS #8 format for private keys.
     --dsa                    Use DSA keys.
     --ecc                    Use ECC (ECDSA) keys.
     --hash STR               Hash algorithm to use for signing 
                              (MD5,SHA1,RMD160,SHA256,SHA384,SHA512).
     --export-ciphers         Use weak encryption algorithms.
     --inder                  Use DER format for input certificates 
                              and private keys.
     --inraw                  Use RAW/DER format for input 
                              certificates and private keys.
     --outder                 Use DER format for output certificates 
                              and private keys.
     --outraw                 Use RAW/DER format for output 
                              certificates and private keys.
     --bits BITS              specify the number of bits for key 
                              generation.
     --sec-param PARAM        specify the security level 
                              [low|normal|high|ultra].
     --disable-quick-random   Use /dev/random for key generationg, 
                              thus increasing the quality of 
                              randomness used.
     --outfile FILE           Output file.
     --infile FILE            Input file.
     --template FILE          Template file to use for non 
                              interactive operation.
     --pkcs-cipher CIPHER     Cipher to use for pkcs operations 
                              (3des,3des-pkcs12,aes-128,aes-192,aes-25
                              6,rc2-40,arcfour).
     -d, --debug LEVEL        specify the debug level. Default is 1.
     -h, --help               shows this help text
     -v, --version            shows the program's version
@end example

The program can be used interactively or non interactively by
specifying the @code{--template} command line option. See below for an
example of a template file.

@subheading Diffie-Hellman parameter generation
To generate parameters for Diffie-Hellman key exchange, use the command:
@example
$ certtool --generate-dh-params --outfile dh.pem --sec-param normal
@end example

@subheading Self-signed certificate generation

To create a self signed certificate, use the command:
@example
$ certtool --generate-privkey --outfile ca-key.pem
$ certtool --generate-self-signed --load-privkey ca-key.pem \
   --outfile ca-cert.pem
@end example

Note that a self-signed certificate usually belongs to a certificate
authority, that signs other certificates.

@subheading Private key generation
To create a private key (RSA by default), run:

@example
$ certtool --generate-privkey --outfile key.pem
@end example

To create a DSA or elliptic curves (ECDSA) private key use the
above command combined with @code{--dsa} or @code{--ecc} options.

@subheading Certificate generation
To generate a certificate using the private key, use the command:

@example
$ certtool --generate-certificate --load-privkey key.pem \
   --outfile cert.pem --load-ca-certificate ca-cert.pem \
   --load-ca-privkey ca-key.pem
@end example

Alternatively you may create a certificate request, which is needed
when the certificate will be signed by a third party authority.

@example
$ certtool --generate-request --load-privkey key.pem \
  --outfile request.pem
@end example

If the private key is stored in a smart card you can generate
a request by specifying the private key object URL (see @ref{The p11tool application}
on how to obtain the URL).

@example
$ certtool --generate-request --load-privkey pkcs11:(PRIVKEY URL) \
  --load-pubkey pkcs11:(PUBKEY URL) --outfile request.pem
@end example

To generate a certificate using the previous request, use the command:

@example
$ certtool --generate-certificate --load-request request.pem \
   --outfile cert.pem \
   --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem
@end example

@subheading Certificate information
To view the certificate information, use:

@example
$ certtool --certificate-info --infile cert.pem
@end example

@subheading @acronym{PKCS} #12 structure generation
To generate a @acronym{PKCS} #12 structure using the previous key and
certificate, use the command:

@example
$ certtool --load-certificate cert.pem --load-privkey key.pem \
  --to-p12 --outder --outfile key.p12
@end example

Some tools (reportedly web browsers) have problems with that file
because it does not contain the CA certificate for the certificate.
To work around that problem in the tool, you can use the
--load-ca-certificate parameter as follows:

@example
$ certtool --load-ca-certificate ca.pem \
  --load-certificate cert.pem --load-privkey key.pem \
  --to-p12 --outder --outfile key.p12
@end example

@subheading Proxy certificate generation
Proxy certificate can be used to delegate your credential to a
temporary, typically short-lived, certificate.  To create one from the
previously created certificate, first create a temporary key and then
generate a proxy certificate for it, using the commands:

@example
$ certtool --generate-privkey > proxy-key.pem
$ certtool --generate-proxy --load-ca-privkey key.pem \
  --load-privkey proxy-key.pem --load-certificate cert.pem \
  --outfile proxy-cert.pem
@end example

@subheading Certificate revocation list generation
To create an empty Certificate Revocation List (CRL) do:

@example
$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
           --load-ca-certificate x509-ca.pem
@end example

To create a CRL that contains some revoked certificates, place the
certificates in a file and use @code{--load-certificate} as follows:

@example
$ certtool --generate-crl --load-ca-privkey x509-ca-key.pem \
  --load-ca-certificate x509-ca.pem --load-certificate revoked-certs.pem
@end example

To verify a Certificate Revocation List (CRL) do:

@example
$ certtool --verify-crl --load-ca-certificate x509-ca.pem < crl.pem
@end example



@subheading Certtool's template file format:
A template file can be used to avoid the interactive questions of
certtool. Initially create a file named 'cert.cfg' that contains the information
about the certificate. The template can be used as below:

@example
$ certtool --generate-certificate cert.pem --load-privkey key.pem  \
   --template cert.cfg \
   --load-ca-certificate ca-cert.pem --load-ca-privkey ca-key.pem
@end example

An example certtool template file:

@example
# X.509 Certificate options
#
# DN options

# The organization of the subject.
organization = "Koko inc."

# The organizational unit of the subject.
unit = "sleeping dept."

# The locality of the subject.
# locality =

# The state of the certificate owner.
state = "Attiki"

# The country of the subject. Two letter code.
country = GR

# The common name of the certificate owner.
cn = "Cindy Lauper"

# A user id of the certificate owner.
#uid = "clauper"

# If the supported DN OIDs are not adequate you can set
# any OID here.
# For example set the X.520 Title and the X.520 Pseudonym
# by using OID and string pairs.
#dn_oid = "2.5.4.12" "Dr." "2.5.4.65" "jackal"

# This is deprecated and should not be used in new
# certificates.
# pkcs9_email = "none@@none.org"

# The serial number of the certificate
serial = 007

# In how many days, counting from today, this certificate will expire.
expiration_days = 700

# X.509 v3 extensions

# A dnsname in case of a WWW server.
#dns_name = "www.none.org"
#dns_name = "www.morethanone.org"

# An IP address in case of a server.
#ip_address = "192.168.1.1"

# An email in case of a person
email = "none@@none.org"

# An URL that has CRLs (certificate revocation lists)
# available. Needed in CA certificates.
#crl_dist_points = "http://www.getcrl.crl/getcrl/"

# Whether this is a CA certificate or not
#ca

# Whether this certificate will be used for a TLS client
#tls_www_client

# Whether this certificate will be used for a TLS server
#tls_www_server

# Whether this certificate will be used to sign data (needed
# in TLS DHE ciphersuites).
signing_key

# Whether this certificate will be used to encrypt data (needed
# in TLS RSA ciphersuites). Note that it is preferred to use different
# keys for encryption and signing.
#encryption_key

# Whether this key will be used to sign other certificates.
#cert_signing_key

# Whether this key will be used to sign CRLs.
#crl_signing_key

# Whether this key will be used to sign code.
#code_signing_key

# Whether this key will be used to sign OCSP data.
#ocsp_signing_key

# Whether this key will be used for time stamping.
#time_stamping_key

# Whether this key will be used for IPsec IKE operations.
#ipsec_ike_key
@end example


@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 allows decoupling cryptographic
keys from the applications that use them providing an additional security layer.
Since this can also be achieved in software components such as in Gnome keyring,
we will use the term security module to describe such an isolation interface.

@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::
* The p11tool application::
@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.

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

@showfuncC{gnutls_certificate_set_x509_trust_file,gnutls_certificate_set_x509_key_file,gnutls_certificate_set_x509_simple_pkcs12_file}

@node The p11tool application
@subsection The p11tool application
@anchor{p11tool}
@cindex p11tool

p11tool is a program that is used to access tokens
and security modules that support the PKCS #11 API. It requires
individual PKCS #11 modules to be loaded either with the
@code{--provider} option, or by setting up the GnuTLS configuration
file for PKCS #11 as in @ref{Smart cards and HSMs}.

@example
p11tool help
Usage: p11tool [options]
Usage: p11tool --list-tokens
Usage: p11tool --list-all
Usage: p11tool --export 'pkcs11:...'

     --export URL             Export an object specified by a pkcs11 
                              URL
     --list-tokens            List all available tokens
     --list-mechanisms URL    List all available mechanisms in token.
     --list-all               List all objects specified by a PKCS#11 
                              URL
     --list-all-certs         List all certificates specified by a 
                              PKCS#11 URL
     --list-certs             List certificates that have a private 
                              key specified by a PKCS#11 URL
     --list-privkeys          List private keys specified by a 
                              PKCS#11 URL
     --list-trusted           List certificates marked as trusted, 
                              specified by a PKCS#11 URL
     --initialize URL         Initializes a PKCS11 token.
     --write URL              Writes loaded certificates, private or 
                              secret keys to a PKCS11 token.
     --delete URL             Deletes objects matching the URL.
     --label label            Sets a label for the write operation.
     --trusted                Marks the certificate to be written as 
                              trusted.
     --private                Marks the object to be written as 
                              private (requires PIN).
     --no-private             Marks the object to be written as not 
                              private.
     --login                  Force login to token
     --detailed-url           Export detailed URLs.
     --no-detailed-url        Export less detailed URLs.
     --secret-key HEX_KEY     Provide a hex encoded secret key.
     --load-privkey FILE      Private key file to use.
     --load-pubkey FILE       Private key file to use.
     --load-certificate FILE  
                              Certificate file to use.
     -8, --pkcs8              Use PKCS #8 format for private keys.
     --inder                  Use DER format for input certificates 
                              and private keys.
     --inraw                  Use RAW/DER format for input 
                              certificates and private keys.
     --provider Library       Specify the pkcs11 provider library
     --outfile FILE           Output file.
     -d, --debug LEVEL        specify the debug level. Default is 1.
     -h, --help               shows this help text
@end example

After being provided the available PKCS #11 modules, it can list all tokens 
available in your system, the objects on the tokens, and perform operations
on them.

Some examples on how to use p11tool are illustrated in the following  paragraphs.

@subsubheading List all tokens
@example
$ p11tool --list-tokens
@end example

@subsubheading List all objects
The following command will list all objects in a token. The @code{--login}
is required to show objects marked as private.
@example
$ p11tool --login --list-all
@end example

@subsubheading Exporting an object
To retrieve an object stored in the card use the following command.
Note however that objects marked as sensitive (typically PKCS #11 private keys) 
are not allowed to be extracted from the token.
@example 
$ p11tool --login --export [OBJECT URL]
@end example

@subsubheading Copy an object to a token
To copy an object, such as a certificate or private key to a token
use the following command.
@example 
$ p11tool --login --write [TOKEN URL] \
  --load-certificate cert.pem --label "my_cert"
@end example


@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}
@showfuncD{gnutls_pubkey_import_openpgp,gnutls_pubkey_import_pkcs11,gnutls_pubkey_import_pkcs11_url,gnutls_pubkey_import_privkey}

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_hash}
@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}