gnutls_pkcs11_privkey_set_pin_function: Added
gnutls_pkcs11_get_pin_function: Added
gnutls_privkey_import_tpm_raw: Added
+gnutls_privkey_import_tpm_url: Added
gnutls_privkey_import_pkcs11_url: Added
gnutls_privkey_import_openpgp_raw: Added
gnutls_privkey_import_x509_raw: Added
SRC_DEF_SRPTOOL =
SRC_DEF_PSKTOOL =
SRC_DEF_P11TOOL =
+SRC_DEF_TPMTOOL =
if WANT_TEST_SUITE
SRC_DEF_CLI += ../src/cli-args.def
SRC_DEF_CLI_DEBUG += ../src/cli-debug-args.def
SRC_DEF_SRPTOOL += ../src/srptool-args.def
SRC_DEF_PSKTOOL += ../src/psk-args.def
SRC_DEF_P11TOOL += ../src/p11tool-args.def
+SRC_DEF_TPMTOOL += ../src/tpmtool-args.def
endif
invoke-gnutls-cli.texi: $(SRC_DEF_CLI)
sed -i 's/@subheading/@subsubheading/g' ../doc/$@ && \
sed -i 's/@section/@subsection/g' ../doc/$@
+invoke-tpmtool.texi: $(SRC_DEF_TPMTOOL)
+ @-cd ../src/ && autogen -Tagtexi-cmd.tpl $< && \
+ rm -f ../doc/$@ && \
+ ../doc/scripts/cleanup-autogen.pl <../src/$@ >../doc/$@.tmp && \
+ mv -f ../doc/$@.tmp ../doc/$@ && \
+ rm -f ../src/$@ && \
+ sed -i 's/@subheading/@subsubheading/g' ../doc/$@ && \
+ sed -i 's/@section/@subsection/g' ../doc/$@
+
info_TEXINFOS = gnutls.texi gnutls-guile.texi
gnutls_TEXINFOS = gnutls.texi fdl-1.3.texi \
cha-bib.texi cha-cert-auth.texi cha-cert-auth2.texi \
cha-gtls-app.texi cha-internals.texi cha-intro-tls.texi \
cha-library.texi cha-preface.texi cha-programs.texi \
sec-tls-app.texi cha-errors.texi cha-support.texi \
- cha-shared-key.texi cha-gtls-examples.texi cha-upgrade.texi
+ cha-shared-key.texi cha-gtls-examples.texi cha-upgrade.texi \
+ cha-tokens.texi
gnutls_TEXINFOS += invoke-gnutls-cli.texi invoke-gnutls-cli-debug.texi \
invoke-gnutls-serv.texi invoke-certtool.texi invoke-srptool.texi \
- invoke-ocsptool.texi invoke-psktool.texi invoke-p11tool.texi
+ invoke-ocsptool.texi invoke-psktool.texi invoke-p11tool.texi \
+ invoke-tpmtool.texi
gnutls_TEXINFOS += stamp_functions
# Generated texinfos.
gnutls_TEXINFOS += gnutls-api.texi x509-api.texi pgp-api.texi \
- pkcs12-api.texi pkcs11-api.texi abstract-api.texi \
+ pkcs12-api.texi pkcs11-api.texi abstract-api.texi tpm-api.texi \
compat-api.texi dtls-api.texi crypto-api.texi ocsp-api.texi
MAINTAINERCLEANFILES += gnutls-api.texi x509-api.texi pgp-api.texi \
- pkcs12-api.texi pkcs11-api.texi abstract-api.texi \
+ pkcs12-api.texi pkcs11-api.texi abstract-api.texi tpm-api.texi \
compat-api.texi dtls-api.texi crypto-api.texi ocsp-api.texi
HEADER_FILES = $(top_srcdir)/lib/includes/gnutls/gnutls.h.in \
done
mv -f $@-tmp $@
+tpm-api.texi: $(top_srcdir)/lib/includes/gnutls/tpm.h
+ echo "" > $@-tmp
+ for i in `$(top_srcdir)/doc/scripts/getfuncs.pl <$(top_srcdir)/lib/includes/gnutls/tpm.h|sort|uniq`; do \
+ echo -n "Creating documentation for $$i... " && \
+ $(srcdir)/scripts/gdoc -texinfo \
+ -function $$i \
+ $(top_srcdir)/lib/*.c $(top_srcdir)/lib/*/*.c >> $@-tmp 2>/dev/null && \
+ echo "ok"; \
+ done
+ mv -f $@-tmp $@
+
abstract-api.texi: $(top_srcdir)/lib/includes/gnutls/abstract.h
echo "" > $@-tmp
for i in `$(top_srcdir)/doc/scripts/getfuncs.pl <$(top_srcdir)/lib/includes/gnutls/abstract.h|sort|uniq`; do \
gnutls_TEXINFOS += $(ENUMS) $(FUNCS)
DISTCLEANFILES += $(ENUMS) stamp_enums stamp_functions
-stamp_functions: gnutls-api.texi x509-api.texi pgp-api.texi pkcs12-api.texi pkcs11-api.texi abstract-api.texi compat-api.texi dtls-api.texi crypto-api.texi ocsp-api.texi
+stamp_functions: gnutls-api.texi x509-api.texi pgp-api.texi pkcs12-api.texi tpm-api.texi pkcs11-api.texi abstract-api.texi compat-api.texi dtls-api.texi crypto-api.texi ocsp-api.texi tpm-api.texi
-mkdir functions
for i in $^; do \
$(srcdir)/scripts/split-texi.pl functions < $$i; \
* Managing encrypted keys::
* certtool Invocation:: Invoking certtool
* ocsptool Invocation:: Invoking ocsptool
-* Smart cards and HSMs::
-* Abstract key types::
@end menu
@node PKCS 10 certificate requests
@include invoke-ocsptool.texi
-@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{@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::
-* p11tool Invocation:: Invoking p11tool
-@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}
-@showfuncD{gnutls_pkcs11_set_token_function,gnutls_pkcs11_set_pin_function,gnutls_pkcs11_add_provider,gnutls_pkcs11_get_pin_function}
-
-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.
-
-Moreover PKCS #11 modules must be reinitialized on the child processes
-after a @funcintref{fork}. @acronym{GnuTLS} provides @funcref{gnutls_pkcs11_reinit}
-to be called for this purpose.
-
-@showfuncdesc{gnutls_pkcs11_reinit}
-
-@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.
-
-@showfuncB{gnutls_certificate_set_x509_trust_file,gnutls_certificate_set_x509_key_file}
-@showfuncdesc{gnutls_certificate_set_x509_system_trust}
-
-@include invoke-p11tool.texi
-
-@node Abstract key types
-@section Abstract key types
-@cindex abstract types
-
-Since there are many forms of a public or private keys supported by @acronym{GnuTLS} such as
-@acronym{X.509}, @acronym{OpenPGP}, or @acronym{PKCS} #11 it is desirable to allow common operations
-on them. For these reasons the abstract @code{gnutls_privkey_t} and @code{gnutls_pubkey_t} were
-introduced in @code{gnutls/abstract.h} header. Those types are initialized using a specific type of
-key and then can be used to perform operations in an abstract way. For example in order
-to sign an X.509 certificate with a key that resides in a token the following steps must be
-used.
-
-@example
-#inlude <gnutls/abstract.h>
-
-void sign_cert( gnutls_x509_crt_t to_be_signed)
-@{
-gnutls_x509_crt_t ca_cert;
-gnutls_privkey_t abs_key;
-
- /* load the PKCS #11 key and certificates */
- /* initialize the abstract key */
- gnutls_privkey_init(&abs_key);
- gnutls_privkey_import_url(abs_key, key_url);
-
- gnutls_x509_crt_init(&ca_cert);
- gnutls_x509_crt_import_pkcs11_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
-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.
-
-@showfuncC{gnutls_pubkey_import_x509,gnutls_pubkey_import_openpgp,gnutls_pubkey_import_pkcs11}
-@showfuncC{gnutls_pubkey_import_url,gnutls_pubkey_import_privkey,gnutls_pubkey_import}
-
-@showfuncdesc{gnutls_pubkey_export}
-
-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}
-@showfuncC{gnutls_privkey_import_x509_raw,gnutls_privkey_import_openpgp_raw,gnutls_privkey_import_url}
-
-@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_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}
* OpenPGP API::
* PKCS 12 API::
* PKCS 11 API::
+* TPM API::
* Abstract key API::
* Cryptographic API::
* Compatibility API::
@include pkcs11-api.texi
+@node TPM API
+@section TPM API
+
+The following functions are to be used for TPM handling.
+Their prototypes lie in @file{gnutls/tpm.h}.
+
+@include tpm-api.texi
+
@node Abstract key API
@section Abstract key API
@showfuncC{gnutls_certificate_set_openpgp_key_mem,gnutls_certificate_set_openpgp_key,gnutls_certificate_set_openpgp_key_file}
+Note however, that since functions like @funcref{gnutls_certificate_set_x509_key_file}
+may accept URLs that specify objects stored in token, another important
+function is @funcref{gnutls_certificate_set_pin_function}. That
+allows setting a callback function to retrieve a PIN if the input keys are
+protected by PIN by the token.
+
+@showfuncdesc{gnutls_certificate_set_pin_function}
+
If the imported keys and certificates need to be accessed before any TLS session
is established, it is convenient to use @funcref{gnutls_certificate_set_key}
in combination with @funcref{gnutls_pcert_import_x509_raw} and @funcref{gnutls_privkey_import_x509_raw}.
@item Support for keyed authentication using @acronym{TLS-PSK}.
-@item Support for @acronym{PKCS} #11 tokens and smart-cards.
+@item Support for TPM, @acronym{PKCS} #11 tokens and smart-cards.
@end itemize
--- /dev/null
+@node Hardware security modules and abstract key types
+@chapter Hardware security modules and abstract key types
+
+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 guarranteed. 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.
+
+@menu
+* Abstract key types::
+* 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{OpenPGP}, @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 must be
+used.
+
+@example
+#inlude <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_pkcs11_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
+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.
+
+@showfuncC{gnutls_pubkey_import_x509,gnutls_pubkey_import_openpgp,gnutls_pubkey_import_pkcs11}
+
+@showfuncC{gnutls_pubkey_import_url,gnutls_pubkey_import_privkey,gnutls_pubkey_import}
+
+@showfuncdesc{gnutls_pubkey_export}
+
+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,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.
+
+@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 keys stored in hardware that
+makes available only operations.
+
+@showfuncC{gnutls_privkey_import_x509,gnutls_privkey_import_openpgp,gnutls_privkey_import_pkcs11}
+
+Other helper functions that allow directly importing from raw X.509 or
+OpenPGP structures are shown below. Again, as with public keys, private keys
+can be imported from a hardware module using URLs.
+
+@showfuncB{gnutls_privkey_import_x509_raw,gnutls_privkey_import_openpgp_raw}
+
+@showfuncdesc{gnutls_privkey_import_url}
+
+@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_ext2}
+
+@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 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{@url{http://www.opensc-project.org}},
+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}.
+
+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::
+* p11tool Invocation:: Invoking p11tool
+@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}
+@showfuncD{gnutls_pkcs11_set_token_function,gnutls_pkcs11_set_pin_function,gnutls_pkcs11_add_provider,gnutls_pkcs11_get_pin_function}
+
+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.
+
+Moreover PKCS #11 modules must be reinitialized on the child processes
+after a @funcintref{fork}. @acronym{GnuTLS} provides @funcref{gnutls_pkcs11_reinit}
+to be called for this purpose.
+
+@showfuncdesc{gnutls_pkcs11_reinit}
+
+@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.
+
+@showfuncB{gnutls_certificate_set_x509_trust_file,gnutls_certificate_set_x509_key_file}
+@showfuncdesc{gnutls_certificate_set_x509_system_trust}
+
+@include invoke-p11tool.texi
+
+@node Trusted platform module
+@section Trusted platform module
+@cindex trusted platform module
+@cindex TPM
+
+In this section we present the Trusted Platform Module (TPM) support
+in @acronym{GnuTLS}. The TPM chip allows for storing and using RSA keys in a
+similar way as a @acronym{PKCS} #11 module, but with slight differences
+that require different handling. The basic operations supported, and used
+by GnuTLS, are key generation and signing.
+
+In GnuTLS the TPM functionality is available in @code{gnutls/tpm.h}.
+
+@menu
+* Keys in TPM::
+* Key generation::
+* Using keys::
+* tpmtool Invocation:: Invoking tpmtool
+@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 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
+
+@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_file}
+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 accessing 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
+
* Certificate authentication::
* Shared-key and anonymous authentication::
* More on certificate authentication::
+* Hardware security modules and abstract key types::
* How to use GnuTLS in applications::
* GnuTLS application examples::
* Other included programs::
@include cha-cert-auth2.texi
+@include cha-tokens.texi
+
@include cha-gtls-app.texi
@include cha-gtls-examples.texi
--- /dev/null
+@node tpmtool Invocation
+@subsection Invoking tpmtool
+@pindex tpmtool
+@cindex GnuTLS TPM tool
+@ignore
+# -*- buffer-read-only: t -*- vi: set ro:
+#
+# DO NOT EDIT THIS FILE (invoke-tpmtool.texi)
+#
+# It has been AutoGen-ed July 18, 2012 at 07:46:21 PM by AutoGen 5.16
+# From the definitions ../src/tpmtool-args.def
+# and the template file agtexi-cmd.tpl
+@end ignore
+
+
+Program that allows handling cryptographic data from the TPM chip.
+
+This section was generated by @strong{AutoGen},
+using the @code{agtexi-cmd} template and the option descriptions for the @code{tpmtool} program.
+This software is released under the GNU General Public License, version 3 or later.
+
+
+@anchor{tpmtool usage}
+@subsubheading tpmtool help/usage (-h)
+@cindex tpmtool help
+
+This is the automatically generated usage text for tpmtool.
+The text printed is the same whether for the @code{help} option (-h) or the @code{more-help} option (-!). @code{more-help} will print
+the usage text by passing it through a pager program.
+@code{more-help} is disabled on platforms without a working
+@code{fork(2)} function. The @code{PAGER} environment variable is
+used to select the program, defaulting to @file{more}. Both will exit
+with a status code of 0.
+
+@exampleindent 0
+@example
+tpmtool - GnuTLS TPM tool - Ver. @@VERSION@@
+USAGE: tpmtool [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]...
+
+ -d, --debug=num Enable debugging.
+ - It must be in the range:
+ 0 to 9999
+ --infile=file Input file
+ - file must pre-exist
+ --outfile=str Output file
+ --generate-rsa Generate an RSA private-public key pair
+ --register Any generated key will be registered in the TPM
+ - requires these options:
+ generate-rsa
+ --signing Any generated key will be a signing key
+ - requires these options:
+ generate-rsa
+ -- and prohibits these options:
+ legacy
+ --user Any registered key will be a user key
+ - requires these options:
+ register
+ -- and prohibits these options:
+ system
+ --system Any registred key will be a system key
+ - requires these options:
+ register
+ -- and prohibits these options:
+ user
+ --legacy Any generated key will be a legacy key
+ - requires these options:
+ generate-rsa
+ -- and prohibits these options:
+ signing
+ --pubkey=str Prints the public key of the provided key
+ --list Lists all stored keys in the TPM
+ --delete=str Delete the key identified by the given URL (UUID).
+ --sec-param=str Specify the security level [low, legacy, normal, high, ultra].
+ --bits=num Specify the number of bits for key generate
+ -v, --version[=arg] Output version information and exit
+ -h, --help Display extended usage information and exit
+ -!, --more-help Extended usage information passed thru pager
+
+Options are specified by doubled hyphens and their name or by a single
+hyphen and the flag character.
+
+
+
+Program that allows handling cryptographic data from the TPM chip.
+
+please send bug reports to: bug-gnutls@@gnu.org
+@end example
+@exampleindent 4
+
+@anchor{tpmtool debug}
+@subsubheading debug option (-d)
+@cindex tpmtool-debug
+
+This is the ``enable debugging.'' option.
+This option takes an argument number.
+Specifies the debug level.
+@anchor{tpmtool generate-rsa}
+@subsubheading generate-rsa option
+@cindex tpmtool-generate-rsa
+
+This is the ``generate an rsa private-public key pair'' option.
+Generates an RSA private-public key pair on the specified token.
+@anchor{tpmtool user}
+@subsubheading user option
+@cindex tpmtool-user
+
+This is the ``any registered key will be a user key'' option.
+
+@noindent
+This option has some usage constraints. It:
+@itemize @bullet
+@item
+must appear in combination with the following options:
+register.
+@item
+must not appear in combination with any of the following options:
+system.
+@end itemize
+
+The generated key will be stored in a user specific persistent storage.
+@anchor{tpmtool system}
+@subsubheading system option
+@cindex tpmtool-system
+
+This is the ``any registred key will be a system key'' option.
+
+@noindent
+This option has some usage constraints. It:
+@itemize @bullet
+@item
+must appear in combination with the following options:
+register.
+@item
+must not appear in combination with any of the following options:
+user.
+@end itemize
+
+The generated key will be stored in system persistent storage.
+@anchor{tpmtool sec-param}
+@subsubheading sec-param option
+@cindex tpmtool-sec-param
+
+This is the ``specify the security level [low, legacy, normal, high, ultra].'' option.
+This option takes an argument string @file{Security parameter}.
+This is alternative to the bits option.
+@anchor{tpmtool exit status}
+@subsubheading tpmtool exit status
+
+One of the following exit values will be returned:
+@table @samp
+@item 0 (EXIT_SUCCESS)
+Successful program execution.
+@item 1 (EXIT_FAILURE)
+The operation failed or the command syntax was not valid.
+@end table
+@anchor{tpmtool See Also}
+@subsubheading tpmtool See Also
+ p11tool (1), certtool (1)
+
+@anchor{tpmtool Examples}
+@subsubheading tpmtool Examples
+To generate a public key use:
+@example
+$ tpmtool --generate-rsa --sec-param normal --outfile tpmkey.pem
+@end example
+
+To get the public key of a TPM key use:
+@example
+$ tpmtool --pubkey --infile tpmkey.tpm --outfile pubkey.pem
+@end example
+
* @url: A PKCS 11 url
*
* This function will return non-zero if the given URL
- * is supported, and zero if it is not known.
+ * is supported, and zero if it is not known. Depending
+ * on the system libraries GnuTLS may support pkcs11 or
+ * tpmkey URLs.
*
* Since: 3.1.0
**/
* entity certificate, e.g., also an intermediate CA cert, then the
* @certfile must contain the ordered certificate chain.
*
- * This function can also accept PKCS #11 URLs at @keyfile and @certfile. In that case it
- * will import the private key and certificate indicated by the URLs.
+ * This function can also accept URLs at @keyfile and @certfile. In that case it
+ * will import the private key and certificate indicated by the URLs. Note
+ * that the supported URLs are the ones indicated by gnutls_url_is_supported().
*
* Returns: %GNUTLS_E_SUCCESS (0) on success, or a negative error code.
**/
* the client if a certificate request is sent. This can be disabled
* using gnutls_certificate_send_x509_rdn_sequence().
*
- * This function can also accept PKCS #11 URLs. In that case it
- * will import all certificates that are marked as trusted.
+ * This function can also accept URLs. In that case it
+ * will import all certificates that are marked as trusted. Note
+ * that the supported URLs are the ones indicated by gnutls_url_is_supported().
*
* Returns: number of certificates processed, or a negative error code on
* error.
projects / thirdparty / gnutls.git / commitdiff
