diff options
| -rw-r--r-- | NEWS | 1 | ||||
| -rw-r--r-- | doc/Makefile.am | 34 | ||||
| -rw-r--r-- | doc/cha-cert-auth2.texi | 279 | ||||
| -rw-r--r-- | doc/cha-functions.texi | 9 | ||||
| -rw-r--r-- | doc/cha-gtls-app.texi | 8 | ||||
| -rw-r--r-- | doc/cha-library.texi | 2 | ||||
| -rw-r--r-- | doc/cha-tokens.texi | 396 | ||||
| -rw-r--r-- | doc/gnutls.texi | 3 | ||||
| -rw-r--r-- | doc/invoke-tpmtool.texi | 171 | ||||
| -rw-r--r-- | lib/gnutls_ui.c | 4 | ||||
| -rw-r--r-- | lib/gnutls_x509.c | 10 |
11 files changed, 627 insertions, 290 deletions
@@ -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 b300557daf..8cdc10dc4d 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/$@.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 \ @@ -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 09acc3175e..09d79a155b 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 aca17e2e33..786c2503e9 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 5a017e2ec2..ea2dfb8e61 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 d42fe3f066..ecd4356975 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 0000000000..b9c25dbf44 --- /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 0a2604c64e..b35bbfad32 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 0000000000..a34eef8b49 --- /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 c3525ed98e..608462b869 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 540b570779..51ac6724ed 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. |