@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 #inlude 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}