diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/cha-tokens.texi | 631 |
1 files changed, 631 insertions, 0 deletions
diff --git a/doc/cha-tokens.texi b/doc/cha-tokens.texi new file mode 100644 index 0000000..1ae0540 --- /dev/null +++ b/doc/cha-tokens.texi @@ -0,0 +1,631 @@ +@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 <gnutls/abstract.h> + +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 permanent 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 + |