@node Hardware security modules and abstract key types @chapter Abstract key types and Hardware security modules In several cases storing the long term cryptographic keys in a hard disk or even in memory poses a significant risk. Once the system they are stored is compromised the keys must be replaced as the secrecy of future sessions is no longer guaranteed. Moreover, past sessions that were not protected by a perfect forward secrecy offering ciphersuite are also to be assumed compromised. If such threats need to be addressed, then it may be wise storing the keys in a security module such as a smart card, an HSM or the TPM chip. Those modules ensure the protection of the cryptographic keys by only allowing operations on them and preventing their extraction. The purpose of the abstract key API is to provide an API that will allow the handle of keys in memory and files, as well as keys stored in such modules. In GnuTLS the approach is to handle all keys transparently by the high level API, e.g., the API that loads a key or certificate from a file. The high-level API will accept URIs in addition to files that specify keys on an HSM or in TPM, and a callback function will be used to obtain any required keys. The URI format is defined in @xcite{PKCS11URI}. More information on the API is provided in the next sections. Examples of a URI of a certificate stored in an HSM, as well as a key stored in the TPM chip are shown below. To discover the URIs of the objects the @code{p11tool} (see @ref{p11tool Invocation}). @example pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315; \ manufacturer=EnterSafe;object=test1;type=cert @end example @menu * Abstract key types:: * Application-specific keys:: * Smart cards and HSMs:: * Trusted Platform Module:: @end menu @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{PKCS} #11 or TPM 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 can be used. @example #include void sign_cert( gnutls_x509_crt_t to_be_signed) @{ gnutls_x509_crt_t ca_cert; gnutls_privkey_t abs_key; /* initialize the abstract key */ gnutls_privkey_init(&abs_key); /* keys stored in tokens are identified by URLs */ gnutls_privkey_import_url(abs_key, key_url); gnutls_x509_crt_init(&ca_cert); gnutls_x509_crt_import_url(&ca_cert, cert_url); /* sign the certificate to be signed */ gnutls_x509_crt_privkey_sign(to_be_signed, ca_cert, abs_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 and freed by using the functions below. @showfuncB{gnutls_pubkey_init,gnutls_pubkey_deinit} After initialization its values can be imported from an existing structure like @code{gnutls_x509_crt_t}, or through an ASN.1 encoding of the X.509 @code{SubjectPublicKeyInfo} sequence. @showfuncB{gnutls_pubkey_import_x509,gnutls_pubkey_import_pkcs11} @showfuncD{gnutls_pubkey_import_url,gnutls_pubkey_import_privkey,gnutls_pubkey_import,gnutls_pubkey_export} @showfuncdesc{gnutls_pubkey_export2} Other helper functions that allow directly importing from raw X.509 structures are shown below. @showfuncA{gnutls_pubkey_import_x509_raw} An important function is @funcref{gnutls_pubkey_import_url} which will import public keys from URLs that identify objects stored in tokens (see @ref{Smart cards and HSMs} and @ref{Trusted Platform Module}). A function to check for a supported by GnuTLS URL is @funcref{gnutls_url_is_supported}. @showfuncdesc{gnutls_url_is_supported} Additional functions are available that will return information over a public key, such as a unique key ID, as well as a function that given a public key fingerprint would provide a memorable sketch. Note that @funcref{gnutls_pubkey_get_key_id} calculates a SHA1 digest of the public key as a DER-formatted, subjectPublicKeyInfo object. Other implementations use different approaches, e.g., some use the ``common method'' described in section 4.2.1.2 of @xcite{RFC5280} which calculates a digest on a part of the subjectPublicKeyInfo object. @showfuncD{gnutls_pubkey_get_pk_algorithm,gnutls_pubkey_get_preferred_hash_algorithm,gnutls_pubkey_get_key_id,gnutls_random_art} To export the key-specific parameters, or obtain a unique key ID the following functions are provided. @showfuncD{gnutls_pubkey_export_rsa_raw2,gnutls_pubkey_export_dsa_raw2,gnutls_pubkey_export_ecc_raw2,gnutls_pubkey_export_ecc_x962} @node Abstract private keys @subsection Private keys An abstract @code{gnutls_privkey_t} can be initialized and freed by using the functions below. @showfuncB{gnutls_privkey_init,gnutls_privkey_deinit} After initialization its values can be imported from an existing structure like @code{gnutls_x509_privkey_t}, but unlike public keys it cannot be exported. That is to allow abstraction over keys stored in hardware that makes available only operations. @showfuncB{gnutls_privkey_import_x509,gnutls_privkey_import_pkcs11} Other helper functions that allow directly importing from raw X.509 structures are shown below. Again, as with public keys, private keys can be imported from a hardware module using URLs. @showfuncdesc{gnutls_privkey_import_url} @showfuncD{gnutls_privkey_import_x509_raw,gnutls_privkey_get_pk_algorithm,gnutls_privkey_get_type,gnutls_privkey_status} 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_ext4} On the private keys where exporting of parameters is possible (i.e., software keys), the following functions are also available. @showfuncC{gnutls_privkey_export_rsa_raw2,gnutls_privkey_export_dsa_raw2,gnutls_privkey_export_ecc_raw2} @node Operations @subsection Operations The abstract key types can be used to access signing and signature verification operations with the underlying keys. @showfuncdesc{gnutls_pubkey_verify_data2} @showfuncdesc{gnutls_pubkey_verify_hash2} @showfuncdesc{gnutls_pubkey_encrypt_data} @showfuncdesc{gnutls_privkey_sign_data} @showfuncdesc{gnutls_privkey_sign_hash} @showfuncdesc{gnutls_privkey_decrypt_data} Signing existing structures, such as certificates, CRLs, or certificate requests, as well as associating public keys with structures is also possible using the key abstractions. @showfuncdesc{gnutls_x509_crq_set_pubkey} @showfuncdesc{gnutls_x509_crt_set_pubkey} @showfuncC{gnutls_x509_crt_privkey_sign,gnutls_x509_crl_privkey_sign,gnutls_x509_crq_privkey_sign} @node Application-specific keys @section System and application-specific keys @cindex Application-specific keys @cindex System-specific keys @subsection System-specific keys In several systems there are keystores which allow to read, store and use certificates and private keys. For these systems GnuTLS provides the system-key API in @code{gnutls/system-keys.h}. That API provides the ability to iterate through all stored keys, add and delete keys as well as use these keys using a URL which starts with "system:". The format of the URLs is system-specific. The @code{systemkey} tool is also provided to assist in listing keys and debugging. The systems supported via this API are the following. @itemize @item Windows Cryptography API (CNG) @end itemize @showfuncdesc{gnutls_system_key_iter_get_info} @showfuncC{gnutls_system_key_iter_deinit,gnutls_system_key_add_x509,gnutls_system_key_delete} @subsection Application-specific keys For systems where GnuTLS doesn't provide a system specific store, it may often be desirable to define a custom class of keys that are identified via URLs and available to GnuTLS calls such as @funcref{gnutls_certificate_set_x509_key_file2}. Such keys can be registered using the API in @code{gnutls/urls.h}. The function which registers such keys is @funcref{gnutls_register_custom_url}. @showfuncdesc{gnutls_register_custom_url} The input to this function are three callback functions as well as the prefix of the URL, (e.g., "mypkcs11:") and the length of the prefix. The types of the callbacks are shown below, and are expected to use the exported gnutls functions to import the keys and certificates. E.g., a typical @code{import_key} callback should use @funcref{gnutls_privkey_import_ext4}. @example typedef int (*gnutls_privkey_import_url_func)(gnutls_privkey_t pkey, const char *url, unsigned flags); typedef int (*gnutls_x509_crt_import_url_func)(gnutls_x509_crt_t pkey, const char *url, unsigned flags); /* The following callbacks are optional */ /* This is to enable gnutls_pubkey_import_url() */ typedef int (*gnutls_pubkey_import_url_func)(gnutls_pubkey_t pkey, const char *url, unsigned flags); /* This is to allow constructing a certificate chain. It will be provided * the initial certificate URL and the certificate to find its issuer, and must * return zero and the DER encoding of the issuer's certificate. If not available, * it should return GNUTLS_E_REQUESTED_DATA_NOT_AVAILABLE. */ typedef int (*gnutls_get_raw_issuer_func)(const char *url, gnutls_x509_crt_t crt, gnutls_datum_t *issuer_der, unsigned flags); typedef struct custom_url_st @{ const char *name; unsigned name_size; gnutls_privkey_import_url_func import_key; gnutls_x509_crt_import_url_func import_crt; gnutls_pubkey_import_url_func import_pubkey; gnutls_get_raw_issuer_func get_issuer; @} gnutls_custom_url_st; @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 decouples cryptographic keys from the applications that use them and provide an additional security layer against cryptographic key extraction. Since this can also be achieved in software components such as in Gnome keyring, we will use the term security module to describe any cryptographic key separation subsystem. @acronym{PKCS} #11 is plugin API allowing applications to access cryptographic operations on a security module, as well as to objects residing on it. PKCS #11 modules exist for hardware tokens such as smart cards@footnote{For example, OpenSC-supported cards.}, cryptographic tokens, 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. In GnuTLS the PKCS #11 functionality is available in @code{gnutls/pkcs11.h}. @float Figure,fig-pkcs11-vision @image{pkcs11-vision,9cm} @caption{PKCS #11 module usage.} @end float @menu * PKCS11 Initialization:: * PKCS11 Manual Initialization:: * Accessing objects that require a PIN:: * Reading objects:: * Writing objects:: * PKCS11 Low Level Access:: * Using a PKCS11 token with TLS:: * Verifying certificates over PKCS11:: * p11tool Invocation:: @end menu @node PKCS11 Initialization @subsection Initialization To allow all @acronym{GnuTLS} applications to transparently access smart cards and tokens, @acronym{PKCS} #11 is automatically initialized during the first call of a @acronym{PKCS} #11 related function, in a thread safe way. The default initialization process, utilizes p11-kit configuration, and loads any appropriate @acronym{PKCS} #11 modules. The p11-kit configuration files@footnote{@url{https://p11-glue.github.io/p11-glue/p11-kit.html}} are typically stored in @code{/etc/pkcs11/modules/}. For example a file that will instruct GnuTLS to load the @acronym{OpenSC} module, could be named @code{/etc/pkcs11/modules/opensc.module} and contain the following: @example module: /usr/lib/opensc-pkcs11.so @end example If you use these configuration files, then there is no need for other initialization in @acronym{GnuTLS}, except for the PIN and token callbacks (see next section). In several cases, however, it is desirable to limit badly behaving modules (e.g., modules that add an unacceptable delay on initialization) to single applications. That can be done using the ``enable-in:'' option followed by the base name of applications that this module should be used. It is also possible to manually initialize or even disable the PKCS #11 subsystem if the default settings are not desirable or not available (see @ref{PKCS11 Manual Initialization} for more information). Note that, PKCS #11 modules behave in a peculiar way after a fork; they require a reinitialization of all the used PKCS #11 resources. While GnuTLS automates that process, there are corner cases where it is not possible to handle it correctly in an automated way@footnote{For example when an open session is to be reinitialized, but the PIN is not available to GnuTLS (e.g., it was entered at a pinpad).}. For that, it is recommended not to mix fork() and PKCS #11 module usage. It is recommended to initialize and use any PKCS #11 resources in a single process. Older versions of @acronym{GnuTLS} required to call @funcref{gnutls_pkcs11_reinit} after a fork() call; since 3.3.0 this is no longer required. @node PKCS11 Manual Initialization @subsection Manual initialization of user-specific modules In systems where one cannot rely on a globally available p11-kit configuration to be available, it is still possible to utilize PKCS #11 objects. That can be done by loading directly the PKCS #11 shared module in the application using @funcref{gnutls_pkcs11_add_provider}, after having called @funcref{gnutls_pkcs11_init} specifying the @code{GNUTLS_PKCS11_FLAG_MANUAL} flag. @showfuncdesc{gnutls_pkcs11_add_provider} In that case, the application will only have access to the modules explicitly loaded. If the @code{GNUTLS_PKCS11_FLAG_MANUAL} flag is specified and no calls to @funcref{gnutls_pkcs11_add_provider} are made, then the PKCS #11 functionality is effectively disabled. @showfuncdesc{gnutls_pkcs11_init} @node Accessing objects that require a PIN @subsection Accessing objects that require a PIN Objects stored in token such as a private keys are typically protected from access by a PIN or password. This PIN may be required to either read the object (if allowed) or to perform operations with it. To allow obtaining the PIN when accessing a protected object, as well as probe the user to insert the token the following functions allow to set a callback. @showfuncD{gnutls_pkcs11_set_token_function,gnutls_pkcs11_set_pin_function,gnutls_pkcs11_add_provider,gnutls_pkcs11_get_pin_function} The callback is of type @funcintref{gnutls_pin_callback_t} and will have as input the provided userdata, the PIN attempt number, a URL describing the token, a label describing the object and flags. The PIN must be at most of @code{pin_max} size and must be copied to pin variable. The function must return 0 on success or a negative error code otherwise. @verbatim typedef int (*gnutls_pin_callback_t) (void *userdata, int attempt, const char *token_url, const char *token_label, unsigned int flags, char *pin, size_t pin_max); @end verbatim The flags are of @code{gnutls_pin_flag_t} type and are explained below. @showenumdesc{gnutls_pin_flag_t,The @code{gnutls_pin_@-flag_t} enumeration.} 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. To avoid conflicts with multiple registered callbacks for PIN functions, @funcref{gnutls_pkcs11_get_pin_function} may be used to check for any previously set functions. In addition context specific PIN functions are allowed, e.g., by using functions below. @showfuncE{gnutls_certificate_set_pin_function,gnutls_pubkey_set_pin_function,gnutls_privkey_set_pin_function,gnutls_pkcs11_obj_set_pin_function,gnutls_x509_crt_set_pin_function} @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;type=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 typically 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 enumerate and access objects are shown below. @showfuncC{gnutls_pkcs11_obj_list_import_url4,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_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_privkey2} @showfuncdesc{gnutls_pkcs11_copy_x509_crt2} @showfuncdesc{gnutls_pkcs11_delete_url} @node PKCS11 Low Level Access @subsection Low Level Access When it is needed to use PKCS#11 functionality which is not wrapped by GnuTLS, it is possible to extract the PKCS#11 session, object or token pointers. That allows an application to still access the low-level functionality, while at the same time take advantage of the URI addressing scheme supported by GnuTLS. @showfuncdesc{gnutls_pkcs11_token_get_ptr} @showfuncdesc{gnutls_pkcs11_obj_get_ptr} @node Using a PKCS11 token with TLS @subsection Using a @acronym{PKCS} #11 token with TLS It is possible to use a @acronym{PKCS} #11 token to a TLS session, as shown in @ref{ex-pkcs11-client}. In addition the following functions can be used to load PKCS #11 key and certificates by specifying a PKCS #11 URL instead of a filename. @showfuncB{gnutls_certificate_set_x509_trust_file,gnutls_certificate_set_x509_key_file2} @node Verifying certificates over PKCS11 @subsection Verifying certificates over @acronym{PKCS} #11 The @acronym{PKCS} #11 API can be used to allow all applications in the same operating system to access shared cryptographic keys and certificates in a uniform way, as in @ref{fig-pkcs11-vision}. That way applications could load their trusted certificate list, as well as user certificates from a common PKCS #11 module. Such a provider is the p11-kit trust storage module@footnote{@url{https://p11-glue.github.io/p11-glue/trust-module.html}} and it provides access to the trusted Root CA certificates in a system. That provides a more dynamic list of Root CA certificates, as opposed to a static list in a file or directory. That store, allows for blacklisting of CAs or certificates, as well as categorization of the Root CAs (Web verification, Code signing, etc.), in addition to restricting their purpose via stapled extensions@footnote{See the 'Restricting the scope of CA certificates' post at @url{https://nmav.gnutls.org/2016/06/restricting-scope-of-ca-certificates.html}}. GnuTLS will utilize the p11-kit trust module as the default trust store if configured to; i.e., if '--with-default-trust-store-pkcs11=pkcs11:' is given to the configure script. @include invoke-p11tool.texi @node Trusted Platform Module @section Trusted Platform Module (TPM) @cindex trusted platform module @cindex TPM In this section we present the Trusted Platform Module (TPM) support in @acronym{GnuTLS}. Note that we recommend against using TPM with this API because it is restricted to TPM 1.2. We recommend instead to use PKCS#11 wrappers for TPM such as CHAPS@footnote{@url{https://github.com/google/chaps-linux}} or opencryptoki@footnote{@url{https://sourceforge.net/projects/opencryptoki/}}. These will allow using the standard smart card and HSM functionality (see @ref{Smart cards and HSMs}) for TPM keys. There was a big hype when the TPM chip was introduced into computers. Briefly it is a co-processor in your PC that allows it to perform calculations independently of the main processor. This has good and bad side-effects. In this section we focus on the good ones; these are the fact that you can use the TPM chip to perform cryptographic operations on keys stored in it, without accessing them. That is very similar to the operation of a @acronym{PKCS} #11 smart card. The chip allows for storage and usage of RSA keys, but has quite some operational differences from @acronym{PKCS} #11 module, and thus require different handling. The basic TPM operations supported and used by GnuTLS, are key generation and signing. That support is currently limited to TPM 1.2. The next sections assume that the TPM chip in the system is already initialized and in a operational state. If not, ensure that the TPM chip is enabled by your BIOS, that the @code{tcsd} daemon is running, and that TPM ownership is set (by running @code{tpm_takeownership}). In GnuTLS the TPM functionality is available in @code{gnutls/tpm.h}. @menu * Keys in TPM:: * Key generation:: * Using keys:: * tpmtool Invocation:: @end menu @node Keys in TPM @subsection Keys in TPM The RSA keys in the TPM module may either be stored in a flash memory within TPM or stored in a file in disk. In the former case the key can provide operations as with @acronym{PKCS} #11 and is identified by a URL. The URL is described in @xcite{TPMURI} and is of the following form. @verbatim tpmkey:uuid=42309df8-d101-11e1-a89a-97bb33c23ad1;storage=user @end verbatim It consists from a unique identifier of the key as well as the part of the flash memory the key is stored at. The two options for the storage field are `user' and `system'. The user keys are typically only available to the generating user and the system keys to all users. The stored in TPM keys are called registered keys. The keys that are stored in the disk are exported from the TPM but in an encrypted form. To access them two passwords are required. The first is the TPM Storage Root Key (SRK), and the other is a key-specific password. Also those keys are identified by a URL of the form: @verbatim tpmkey:file=/path/to/file @end verbatim When objects require a PIN to be accessed the same callbacks as with PKCS #11 objects are expected (see @ref{Accessing objects that require a PIN}). Note that the PIN function may be called multiple times to unlock the SRK and the specific key in use. The label in the key function will then be set to `SRK' when unlocking the SRK key, or to `TPM' when unlocking any other key. @node Key generation @subsection Key generation All keys used by the TPM must be generated by the TPM. This can be done using @funcref{gnutls_tpm_privkey_generate}. @showfuncdesc{gnutls_tpm_privkey_generate} @showfuncC{gnutls_tpm_get_registered,gnutls_tpm_key_list_deinit,gnutls_tpm_key_list_get_url} @showfuncdesc{gnutls_tpm_privkey_delete} @node Using keys @subsection Using keys @subsubheading Importing keys The TPM keys can be used directly by the abstract key types and do not require any special structures. Moreover functions like @funcref{gnutls_certificate_set_x509_key_file2} can access TPM URLs. @showfuncB{gnutls_privkey_import_tpm_raw,gnutls_pubkey_import_tpm_raw} @showfuncdesc{gnutls_privkey_import_tpm_url} @showfuncdesc{gnutls_pubkey_import_tpm_url} @subsubheading Listing and deleting keys The registered keys (that are stored in the TPM) can be listed using one of the following functions. Those keys are unfortunately only identified by their UUID and have no label or other human friendly identifier. Keys can be deleted from permament storage using @funcref{gnutls_tpm_privkey_delete}. @showfuncC{gnutls_tpm_get_registered,gnutls_tpm_key_list_deinit,gnutls_tpm_key_list_get_url} @showfuncdesc{gnutls_tpm_privkey_delete} @include invoke-tpmtool.texi