More on 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.

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.

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]

PKIX certificate revocation lists
=================================

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

Field   Description

version
The field that indicates the version of the CRL structure.

signature
A signature by the issuing authority.

issuer
Holds the issuer's distinguished name.

thisUpdate
The issuing time of the revocation list.

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

revokedCertificates
List of revoked certificates serial numbers.

extensions
Optional CRL structure extensions.

Table: Certificate revocation list fields.

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 gnutls_x509_crl_sign2 and 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.

gnutls_x509_crl_sign2 gnutls_x509_crl_privkey_sign

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

gnutls_x509_crl_set_number,gnutls_x509_crl_set_authority_key_id

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

PKCS #8 structures
------------------

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

gnutls_x509_privkey_import_pkcs8,gnutls_x509_privkey_export_pkcs8

gnutls_pkcs_encrypt_flags_t,Encryption flags

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.

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

gnutls_pkcs12_get_bag,gnutls_pkcs12_verify_mac,gnutls_pkcs12_bag_decrypt

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_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]

The certtool application
========================

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

     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

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

Diffie-Hellman parameter generation
-----------------------------------

To generate parameters for Diffie-Hellman key exchange, use the command:

     $ certtool --generate-dh-params --outfile dh.pem --sec-param normal

Self-signed certificate generation
----------------------------------

To create a self signed certificate, use the command:

     $ certtool --generate-privkey --outfile ca-key.pem
     $ certtool --generate-self-signed --load-privkey ca-key.pem \
        --outfile ca-cert.pem

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

Private key generation
----------------------

To create a private key (RSA by default), run:

     $ certtool --generate-privkey --outfile key.pem

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

Certificate generation
----------------------

To generate a certificate using the private key, use the command:

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

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

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

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

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

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

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

Certificate information
-----------------------

To view the certificate information, use:

     $ certtool --certificate-info --infile cert.pem

PKCS #12 structure generation
-----------------------------

To generate a PKCS #12 structure using the previous key and certificate, use the command:

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

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:

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

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:

     $ 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

Certificate revocation list generation
--------------------------------------

To create an empty Certificate Revocation List (CRL) do:

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

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

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

To verify a Certificate Revocation List (CRL) do:

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

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:

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

An example certtool template file:

     # 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

Smart cards and HSMs
====================

In this section we present the smart-card and hardware security module (HSM) support in GnuTLS using PKCS #11 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.

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 (http://www.opensc-project.org), the trusted platform module (TPM) (http://trousers.sourceforge.net/) as well as for software modules like 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 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 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_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_import_url,gnutls_pkcs11_obj_export_url

gnutls_pkcs11_obj_get_info

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,gnutls_certificate_set_x509_simple_pkcs12_file

The p11tool application
-----------------------

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 --provider option, or by setting up the GnuTLS configuration file for PKCS #11 as in Smart cards and HSMs.

     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

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.

List all tokens
...............

     $ p11tool --list-tokens

List all objects
................

The following command will list all objects in a token. The --login is required to show objects marked as private.

     $ p11tool --login --list-all

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.

     $ p11tool --login --export [OBJECT URL]

Copy an object to a token
.........................

To copy an object, such as a certificate or private key to a token use the following command.

     $ p11tool --login --write [TOKEN URL] \
       --load-certificate cert.pem --label "my_cert"

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_SHA256, 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_import_x509 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.

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_import_x509,gnutls_privkey_import_openpgp,gnutls_privkey_import_pkcs11

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 PKCS #11.

gnutls_privkey_import_ext

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_pubkey_encrypt_data

gnutls_privkey_sign_data gnutls_privkey_sign_hash 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.

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