[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[SCM] GNU gnutls branch, master, updated. gnutls_3_0_21-51-g84889ed
|
From: |
Nikos Mavrogiannopoulos |
|
Subject: |
[SCM] GNU gnutls branch, master, updated. gnutls_3_0_21-51-g84889ed |
|
Date: |
Wed, 18 Jul 2012 18:52:44 +0000 |
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 <address@hidden>
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/address@hidden && \
+ mv -f ../doc/address@hidden ../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 address@hidden $@
+tpm-api.texi: $(top_srcdir)/lib/includes/gnutls/tpm.h
+ echo "" > address@hidden
+ 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 >>
address@hidden 2>/dev/null && \
+ echo "ok"; \
+ done
+ mv -f address@hidden $@
+
abstract-api.texi: $(top_srcdir)/lib/includes/gnutls/abstract.h
echo "" > address@hidden
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
address@hidden Smart cards and HSMs
address@hidden Smart cards and HSMs
address@hidden PKCS #11 tokens
address@hidden hardware tokens
address@hidden hardware security modules
address@hidden 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.
-
address@hidden #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
address@hidden@url{http://www.opensc-project.org}},
-the trusted
-platform module (TPM)@address@hidden://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}.
-
address@hidden Figure,fig:pkcs11-vision
address@hidden,9cm}
address@hidden #11 module usage.}
address@hidden float
-
address@hidden
-* PKCS11 Initialization::
-* Reading objects::
-* Writing objects::
-* Using a PKCS11 token with TLS::
-* p11tool Invocation:: Invoking p11tool
address@hidden menu
-
address@hidden PKCS11 Initialization
address@hidden 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
@address@hidden@url{http://p11-glue.freedesktop.org/}}.
-For example a file that will load the @acronym{OpenSC} module, could be named
address@hidden/etc/pkcs11/modules/opensc} and contain the following:
-
address@hidden
-module: /usr/lib/opensc-pkcs11.so
address@hidden example
-
-If you use this file, then there is no need for other initialization in
address@hidden, 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.
-
address@hidden
address@hidden,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,
address@hidden 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.
-
address@hidden
-
address@hidden Reading objects
address@hidden 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:
-
address@hidden
-pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315; \
-manufacturer=EnterSafe;object=test1;objecttype=public;\
-id=32f153f3e37990b08624141077ca5dec2d15faed
address@hidden example
-
-while the smart card itself can be referenced as:
address@hidden
-pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315;manufacturer=EnterSafe
address@hidden 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.
-
address@hidden,gnutls_pkcs11_obj_export_url}
-
address@hidden
-
address@hidden,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.
-
address@hidden,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.
-
address@hidden
-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();
address@hidden example
-
address@hidden examples/ex-pkcs11-list.c
-
address@hidden Writing objects
address@hidden 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 @address@hidden@address@hidden@-SENSITIVE}
-to prevent its extraction. An object can be marked as private using the flag
address@hidden@address@hidden@address@hidden, to require PIN to be
-entered before accessing the object (for operations or otherwise).
-
address@hidden
-
address@hidden
address@hidden
-
-
address@hidden Using a PKCS11 token with TLS
address@hidden 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.
-
address@hidden,gnutls_certificate_set_x509_key_file}
address@hidden
-
address@hidden invoke-p11tool.texi
-
address@hidden Abstract key types
address@hidden Abstract key types
address@hidden abstract types
-
-Since there are many forms of a public or private keys supported by
@acronym{GnuTLS} such as
address@hidden, @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.
-
address@hidden
-#inlude <gnutls/abstract.h>
-
-void sign_cert( gnutls_x509_crt_t to_be_signed)
address@hidden
-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);
address@hidden
address@hidden example
-
address@hidden
-* Abstract public keys::
-* Abstract private keys::
-* Operations::
address@hidden menu
-
-
address@hidden Abstract public keys
address@hidden 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.
-
address@hidden,gnutls_pubkey_import_openpgp,gnutls_pubkey_import_pkcs11}
address@hidden,gnutls_pubkey_import_privkey,gnutls_pubkey_import}
-
address@hidden
-
-Additional functions are available that will return
-information over a public key.
-
address@hidden,gnutls_pubkey_get_preferred_hash_algorithm,gnutls_pubkey_get_key_id}
-
address@hidden Abstract private keys
address@hidden 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.
-
address@hidden,gnutls_privkey_import_openpgp,gnutls_privkey_import_pkcs11}
address@hidden,gnutls_privkey_import_openpgp_raw,gnutls_privkey_import_url}
-
address@hidden,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.
-
address@hidden
-
address@hidden Operations
address@hidden Operations
-The abstract key types can be used to access signing and
-signature verification operations with the underlying keys.
-
address@hidden
address@hidden
address@hidden
-
address@hidden
address@hidden
address@hidden
-
-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.
-
address@hidden
address@hidden
address@hidden,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
address@hidden TPM API
address@hidden TPM API
+
+The following functions are to be used for TPM handling.
+Their prototypes lie in @file{gnutls/tpm.h}.
+
address@hidden 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.
+
address@hidden
+
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}.
address@hidden Support for @acronym{PKCS} #11 tokens and smart-cards.
address@hidden 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 @@
address@hidden Hardware security modules and abstract key types
address@hidden 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.
+
address@hidden
+* Abstract key types::
+* Smart cards and HSMs::
+* Trusted platform module::
address@hidden menu
+
address@hidden Abstract key types
address@hidden Abstract key types
address@hidden abstract types
+
+Since there are many forms of a public or private keys supported by
@acronym{GnuTLS} such as
address@hidden, @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.
+
address@hidden
+#inlude <gnutls/abstract.h>
+
+void sign_cert( gnutls_x509_crt_t to_be_signed)
address@hidden
+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);
address@hidden
address@hidden example
+
address@hidden
+* Abstract public keys::
+* Abstract private keys::
+* Operations::
address@hidden menu
+
address@hidden Abstract public keys
address@hidden 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.
+
address@hidden,gnutls_pubkey_import_openpgp,gnutls_pubkey_import_pkcs11}
+
address@hidden,gnutls_pubkey_import_privkey,gnutls_pubkey_import}
+
address@hidden
+
+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}.
+
address@hidden
+
+Additional functions are available that will return
+information over a public key.
+
address@hidden,gnutls_pubkey_get_preferred_hash_algorithm,gnutls_pubkey_get_key_id}
+
address@hidden Abstract private keys
address@hidden 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.
+
address@hidden,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.
+
address@hidden,gnutls_privkey_import_openpgp_raw}
+
address@hidden
+
address@hidden,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.
+
address@hidden
+
address@hidden Operations
address@hidden Operations
+The abstract key types can be used to access signing and
+signature verification operations with the underlying keys.
+
address@hidden
address@hidden
address@hidden
+
address@hidden
address@hidden
address@hidden
+
+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.
+
address@hidden
address@hidden
address@hidden,gnutls_x509_crl_privkey_sign,gnutls_x509_crq_privkey_sign}
+
address@hidden Smart cards and HSMs
address@hidden Smart cards and HSMs
address@hidden PKCS #11 tokens
address@hidden hardware tokens
address@hidden hardware security modules
address@hidden 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.
+
address@hidden #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
address@hidden@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}.
+
address@hidden Figure,fig:pkcs11-vision
address@hidden,9cm}
address@hidden #11 module usage.}
address@hidden float
+
address@hidden
+* PKCS11 Initialization::
+* Reading objects::
+* Writing objects::
+* Using a PKCS11 token with TLS::
+* p11tool Invocation:: Invoking p11tool
address@hidden menu
+
address@hidden PKCS11 Initialization
address@hidden 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
@address@hidden@url{http://p11-glue.freedesktop.org/}}.
+For example a file that will load the @acronym{OpenSC} module, could be named
address@hidden/etc/pkcs11/modules/opensc} and contain the following:
+
address@hidden
+module: /usr/lib/opensc-pkcs11.so
address@hidden example
+
+If you use this file, then there is no need for other initialization in
address@hidden, 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.
+
address@hidden
address@hidden,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,
address@hidden 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.
+
address@hidden
+
address@hidden Reading objects
address@hidden 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:
+
address@hidden
+pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315; \
+manufacturer=EnterSafe;object=test1;objecttype=public;\
+id=32f153f3e37990b08624141077ca5dec2d15faed
address@hidden example
+
+while the smart card itself can be referenced as:
address@hidden
+pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315;manufacturer=EnterSafe
address@hidden 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.
+
address@hidden,gnutls_pkcs11_obj_export_url}
+
address@hidden
+
address@hidden,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.
+
address@hidden,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.
+
address@hidden
+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();
address@hidden example
+
address@hidden examples/ex-pkcs11-list.c
+
address@hidden Writing objects
address@hidden 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 @address@hidden@address@hidden@-SENSITIVE}
+to prevent its extraction. An object can be marked as private using the flag
address@hidden@address@hidden@address@hidden, to require PIN to be
+entered before accessing the object (for operations or otherwise).
+
address@hidden
+
address@hidden
address@hidden
+
+
address@hidden Using a PKCS11 token with TLS
address@hidden 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.
+
address@hidden,gnutls_certificate_set_x509_key_file}
address@hidden
+
address@hidden invoke-p11tool.texi
+
address@hidden Trusted platform module
address@hidden Trusted platform module
address@hidden trusted platform module
address@hidden 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}.
+
address@hidden
+* Keys in TPM::
+* Key generation::
+* Using keys::
+* tpmtool Invocation:: Invoking tpmtool
address@hidden menu
+
address@hidden Keys in TPM
address@hidden 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.
address@hidden
+tpmkey:uuid=42309df8-d101-11e1-a89a-97bb33c23ad1;storage=user
address@hidden 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:
address@hidden
+tpmkey:file=/path/to/file
address@hidden verbatim
+
address@hidden Key generation
address@hidden Key generation
+
+All keys used by the TPM must be generated by the TPM. This can be
+done using @funcref{gnutls_tpm_privkey_generate}.
+
address@hidden
+
address@hidden,gnutls_tpm_key_list_deinit,gnutls_tpm_key_list_get_url}
+
address@hidden
+
address@hidden Using keys
address@hidden Using keys
+
address@hidden 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.
+
address@hidden,gnutls_pubkey_import_tpm_raw}
+
address@hidden
address@hidden
+
address@hidden 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}.
+
address@hidden,gnutls_tpm_key_list_deinit,gnutls_tpm_key_list_get_url}
+
address@hidden
+
+
address@hidden 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
address@hidden 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 @@
address@hidden tpmtool Invocation
address@hidden Invoking tpmtool
address@hidden tpmtool
address@hidden GnuTLS TPM tool
address@hidden
+# -*- 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
address@hidden 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.
+
+
address@hidden usage}
address@hidden tpmtool help/usage (-h)
address@hidden 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.
address@hidden is disabled on platforms without a working
address@hidden(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.
+
address@hidden 0
address@hidden
+tpmtool - GnuTLS TPM tool - Ver. @@VERSION@@
+USAGE: tpmtool [ -<flag> [<val>] | --<name>address@hidden| @}<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
address@hidden example
address@hidden 4
+
address@hidden debug}
address@hidden debug option (-d)
address@hidden tpmtool-debug
+
+This is the ``enable debugging.'' option.
+This option takes an argument number.
+Specifies the debug level.
address@hidden generate-rsa}
address@hidden generate-rsa option
address@hidden 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.
address@hidden user}
address@hidden user option
address@hidden tpmtool-user
+
+This is the ``any registered key will be a user key'' option.
+
address@hidden
+This option has some usage constraints. It:
address@hidden @bullet
address@hidden
+must appear in combination with the following options:
+register.
address@hidden
+must not appear in combination with any of the following options:
+system.
address@hidden itemize
+
+The generated key will be stored in a user specific persistent storage.
address@hidden system}
address@hidden system option
address@hidden tpmtool-system
+
+This is the ``any registred key will be a system key'' option.
+
address@hidden
+This option has some usage constraints. It:
address@hidden @bullet
address@hidden
+must appear in combination with the following options:
+register.
address@hidden
+must not appear in combination with any of the following options:
+user.
address@hidden itemize
+
+The generated key will be stored in system persistent storage.
address@hidden sec-param}
address@hidden sec-param option
address@hidden 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.
address@hidden exit status}
address@hidden tpmtool exit status
+
+One of the following exit values will be returned:
address@hidden @samp
address@hidden 0 (EXIT_SUCCESS)
+Successful program execution.
address@hidden 1 (EXIT_FAILURE)
+The operation failed or the command syntax was not valid.
address@hidden table
address@hidden See Also}
address@hidden tpmtool See Also
+ p11tool (1), certtool (1)
+
address@hidden Examples}
address@hidden tpmtool Examples
+To generate a public key use:
address@hidden
+$ tpmtool --generate-rsa --sec-param normal --outfile tpmkey.pem
address@hidden example
+
+To get the public key of a TPM key use:
address@hidden
+$ tpmtool --pubkey --infile tpmkey.tpm --outfile pubkey.pem
address@hidden 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
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [SCM] GNU gnutls branch, master, updated. gnutls_3_0_21-51-g84889ed,
Nikos Mavrogiannopoulos <=