Added the ability to register application specific URLs for keys and certs

1 files changed, 59 insertions, 2 deletions

diff --git a/doc/cha-tokens.texi b/doc/cha-tokens.texi
index 756a9ca3e3..7d76e5b1be 100644
--- a/doc/cha-tokens.texi
+++ b/doc/cha-tokens.texi
@@ -1,5 +1,5 @@
 @node Hardware security modules and abstract key types
-@chapter Hardware security modules and abstract key types
+@chapter Abstract keys types and Hardware security modules
 
 In several cases storing the long term cryptographic keys in a hard disk or
 even in memory poses a significant risk. Once the system they are stored
@@ -35,6 +35,7 @@ tpmkey:uuid=42309df8-d101-11e1-a89a-97bb33c23ad1;storage=user
 
 @menu
 * Abstract key types::
+* Application-specific keys::
 * Smart cards and HSMs::
 * Trusted Platform Module::
 @end menu
@@ -147,7 +148,7 @@ 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}
+@showfuncdesc{gnutls_privkey_import_ext3}
 
 @node Operations
 @subsection Operations
@@ -171,6 +172,62 @@ key abstractions.
 @showfuncdesc{gnutls_x509_crt_set_pubkey}
 @showfuncC{gnutls_x509_crt_privkey_sign,gnutls_x509_crl_privkey_sign,gnutls_x509_crq_privkey_sign}
 
+
+@node Application-specific keys
+@section System and application-specific keys
+@cindex Application-specific keys
+@cindex System-specific keys
+
+@subsection System-specific keys
+In several systems there are keystores which allow to read, store and use certificates
+and private keys. For these systems GnuTLS provides the system-key API in @code{gnutls/system-keys.h}.
+That API provides the ability to iterate through all stored keys, add and delete keys as well
+as use these keys using a URL which starts with "system:".
+
+@showfuncdesc{gnutls_system_key_iter_get_info}
+
+@showfuncC{gnutls_system_key_iter_deinit, gnutls_system_key_add_x509, gnutls_system_key_delete}
+
+@subsection Application-specific keys
+For systems where GnuTLS doesn't provide a system specific store,
+it may often be desirable to define a custom class of keys
+that are identified via URLs and available to GnuTLS calls such as @funcref{gnutls_certificate_set_x509_key_file2}.
+Such keys can be registered using the API in @code{gnutls/urls.h}. The function
+which registers such keys is @funcref{gnutls_register_custom_url}.
+
+@showfuncdesc{gnutls_register_custom_url}
+
+The input to this function are three callback functions as well as
+the prefix of the URL, (e.g., "mypkcs11:") and the length of the prefix.
+The types of the callbacks are shown below, and are expected to
+use the exported gnutls functions to import the keys and certificates.
+E.g., a typical @code{import_key} callback should use @funcref{gnutls_privkey_import_ext3}.
+
+@example
+typedef int (*gnutls_privkey_import_url_func)(gnutls_privkey_t pkey,
+                                              const char *url,
+                                              unsigned flags);
+
+typedef int (*gnutls_x509_crt_import_url_func)(gnutls_x509_crt_t pkey,
+                                               const char *url,
+                                               unsigned flags);
+
+/* This callback is optional */
+typedef int (*gnutls_pubkey_import_url_func)(gnutls_pubkey_t pkey,
+                                             const char *url,
+                                             unsigned flags);
+
+typedef struct custom_url_st @{
+        const char *name;
+        unsigned name_size;
+        gnutls_privkey_import_url_func import_key;
+        gnutls_x509_crt_import_url_func import_crt;
+        gnutls_pubkey_import_url_func import_pubkey;
+@} gnutls_custom_url_st;
+@end example
+
+
+
 @node Smart cards and HSMs
 @section Smart cards and HSMs
 @cindex PKCS #11 tokens