[SCM] GNU gnutls branch, master, updated. gnutls_3_0_21-51-g84889ed
"Nikos Mavrogiannopoulos" <[email protected]> Wed, 18 Jul 2012 18:52:44 +0000
| Newsgroups | gmane.comp.encryption.gpg.gnutls.cvs |
|---|---|
| Message-ID | <[email protected]> |
This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU gnutls".
http://git.savannah.gnu.org/cgit/gnutls.git/commit/?id=84889edffbe7efa4b141249b6365fbc74394cd45
The branch, master has been updated
via 84889edffbe7efa4b141249b6365fbc74394cd45 (commit)
from 8e5417ad28fd3821e830446f2c74ccc22adde70e (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit 84889edffbe7efa4b141249b6365fbc74394cd45
Author: Nikos Mavrogiannopoulos <[email protected]>
Date: Wed Jul 18 20:40:02 2012 +0200
Added documentation for TPM keys.
-----------------------------------------------------------------------
Summary of changes:
NEWS | 1 +
doc/Makefile.am | 34 ++++-
doc/cha-cert-auth2.texi | 279 ---------------------------------
doc/cha-functions.texi | 9 +
doc/cha-gtls-app.texi | 8 +
doc/cha-library.texi | 2 +-
doc/cha-tokens.texi | 396 +++++++++++++++++++++++++++++++++++++++++++++++
doc/gnutls.texi | 3 +
doc/invoke-tpmtool.texi | 171 ++++++++++++++++++++
lib/gnutls_ui.c | 4 +-
lib/gnutls_x509.c | 10 +-
11 files changed, 627 insertions(+), 290 deletions(-)
create mode 100644 doc/cha-tokens.texi
create mode 100644 doc/invoke-tpmtool.texi
diff --git a/NEWS b/NEWS
index 97cf515..4c1b357 100644
--- a/NEWS
+++ b/NEWS
@@ -48,6 +48,7 @@ gnutls_pkcs11_obj_set_pin_function: Added
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
diff --git a/doc/Makefile.am b/doc/Makefile.am
index b300557..8cdc10d 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -36,6 +36,7 @@ SRC_DEF_OCSPTOOL =
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
@@ -45,6 +46,7 @@ SRC_DEF_OCSPTOOL += ../src/ocsptool-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)
@@ -109,6 +111,15 @@ invoke-p11tool.texi: $(SRC_DEF_P11TOOL)
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/[email protected] && \
+ mv -f ../doc/[email protected] ../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 \
@@ -116,11 +127,13 @@ gnutls_TEXINFOS = gnutls.texi fdl-1.3.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
@@ -176,11 +189,11 @@ MAINTAINERCLEANFILES =
# 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 \
@@ -246,6 +259,17 @@ pkcs11-api.texi: $(top_srcdir)/lib/includes/gnutls/pkcs11.h
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 \
@@ -351,7 +375,7 @@ enums.texi: $(HEADER_FILES)
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; \
diff --git a/doc/cha-cert-auth2.texi b/doc/cha-cert-auth2.texi
index 09acc31..09d79a1 100644
--- a/doc/cha-cert-auth2.texi
+++ b/doc/cha-cert-auth2.texi
@@ -14,8 +14,6 @@ structures, etc., are discussed in this chapter.
* 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
@@ -359,280 +357,3 @@ of their usage is also shown.
@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}
diff --git a/doc/cha-functions.texi b/doc/cha-functions.texi
index aca17e2..786c250 100644
--- a/doc/cha-functions.texi
+++ b/doc/cha-functions.texi
@@ -10,6 +10,7 @@
* OpenPGP API::
* PKCS 12 API::
* PKCS 11 API::
+* TPM API::
* Abstract key API::
* Cryptographic API::
* Compatibility API::
@@ -75,6 +76,14 @@ Their prototypes lie in @file{gnutls/pkcs11.h}.
@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
diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index 5a017e2..ea2dfb8 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -415,6 +415,14 @@ already.
@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}.
diff --git a/doc/cha-library.texi b/doc/cha-library.texi
index d42fe3f..ecd4356 100644
--- a/doc/cha-library.texi
+++ b/doc/cha-library.texi
@@ -25,7 +25,7 @@ include:
@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
diff --git a/doc/cha-tokens.texi b/doc/cha-tokens.texi
new file mode 100644
index 0000000..b9c25db
--- /dev/null
+++ b/doc/cha-tokens.texi
@@ -0,0 +1,396 @@
+@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
+
diff --git a/doc/gnutls.texi b/doc/gnutls.texi
index 0a2604c..b35bbfa 100644
--- a/doc/gnutls.texi
+++ b/doc/gnutls.texi
@@ -152,6 +152,7 @@ Documentation License''.
* 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::
@@ -180,6 +181,8 @@ Documentation License''.
@include cha-cert-auth2.texi
+@include cha-tokens.texi
+
@include cha-gtls-app.texi
@include cha-gtls-examples.texi
diff --git a/doc/invoke-tpmtool.texi b/doc/invoke-tpmtool.texi
new file mode 100644
index 0000000..a34eef8
--- /dev/null
+++ b/doc/invoke-tpmtool.texi
@@ -0,0 +1,171 @@
+@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
+
diff --git a/lib/gnutls_ui.c b/lib/gnutls_ui.c
index c3525ed..608462b 100644
--- a/lib/gnutls_ui.c
+++ b/lib/gnutls_ui.c
@@ -778,7 +778,9 @@ size_t len;
* @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
**/
diff --git a/lib/gnutls_x509.c b/lib/gnutls_x509.c
index 540b570..51ac672 100644
--- a/lib/gnutls_x509.c
+++ b/lib/gnutls_x509.c
@@ -1142,8 +1142,9 @@ cleanup:
* 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.
**/
@@ -1497,8 +1498,9 @@ cleanup:
* 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.
hooks/post-receive
--
GNU gnutls