doc: updated PKCS #11 documentation

2 files changed, 54 insertions, 18 deletions

diff --git a/doc/cha-tokens.texi b/doc/cha-tokens.texi
index 754592269b..cce55b8bb8 100644
--- a/doc/cha-tokens.texi
+++ b/doc/cha-tokens.texi
@@ -278,6 +278,7 @@ storage module@footnote{@url{http://p11-glue.freedesktop.org/trust-module.html}}
 
 @menu
 * PKCS11 Initialization::
+* PKCS11 Manual Initialization::
 * Accessing objects that require a PIN::
 * Reading objects::
 * Writing objects::
@@ -289,8 +290,9 @@ storage module@footnote{@url{http://p11-glue.freedesktop.org/trust-module.html}}
 @subsection Initialization
 To allow all @acronym{GnuTLS} applications to transparently access smart cards
 and tokens, @acronym{PKCS} #11 is automatically initialized during the first
-call of a @acronym{PKCS} #11 related function. The initialization process, based
-on p11-kit configuration, loads any appropriate modules. The p11-kit configuration
+call of a @acronym{PKCS} #11 related function, in a thread safe way.
+The default initialization process, utilizes p11-kit configuration, and loads any
+appropriate @acronym{PKCS} #11 modules. The p11-kit configuration
 files@footnote{@url{http://p11-glue.freedesktop.org/}} are typically stored in @code{/etc/pkcs11/modules/}.
 For example a file that will instruct GnuTLS to load the @acronym{OpenSC} module,
 could be named @code{/etc/pkcs11/modules/opensc.module} and contain the following:
@@ -306,25 +308,43 @@ In several cases, however, it is desirable to limit badly behaving modules
 to single applications. That can be done using the ``enable-in:'' option
 followed by the base name of applications that this module should be used.
 
-It is also possible to manually initialize the PKCS #11 subsystem if the 
-default settings are not desirable. To completely disable PKCS #11 support you
-need to call @funcref{gnutls_pkcs11_init} with the flag @code{GNUTLS_PKCS11_FLAG_MANUAL}
-prior to @funcref{gnutls_global_init}.
-
-@showfuncdesc{gnutls_pkcs11_init}
+It is also possible to manually initialize or even disable the PKCS #11 subsystem if the 
+default settings are not desirable or not available (see @ref{PKCS11 Manual Initialization}
+for more information).
 
 Note that, PKCS #11 modules behave in a peculiar way after a fork; they
 require a reinitialization of all the used PKCS #11 resources.
 While GnuTLS automates that process, there are corner cases where
 it is not possible to handle it correctly in an automated way@footnote{For
 example when an open session is to be reinitialized, but the PIN is not available
-to GnuTLS (e.g., it was entered at a pinpad).}. For that reasons it is
+to GnuTLS (e.g., it was entered at a pinpad).}. For that, it is
 recommended not to mix fork() and PKCS #11 module usage. It is recommended
 to initialize and use any PKCS #11 resources in a single process.
 
 Older versions of @acronym{GnuTLS} required to call @funcref{gnutls_pkcs11_reinit}
 after a fork() call; since 3.3.0 this is no longer required.
 
+
+@node PKCS11 Manual Initialization
+@subsection Manual initialization of user-specific modules
+
+In systems where one cannot rely on a globally available p11-kit configuration
+to be available, it is still possible to utilize PKCS #11 objects. That
+can be done by loading directly the PKCS #11 shared module in the
+application using @funcref{gnutls_pkcs11_add_provider}, after having
+called @funcref{gnutls_pkcs11_init} specifying the @code{GNUTLS_PKCS11_FLAG_MANUAL}
+flag.
+
+@showfuncdesc{gnutls_pkcs11_add_provider}
+
+In that case, the application will only have access to the modules explictly
+loaded. If the @code{GNUTLS_PKCS11_FLAG_MANUAL} flag is specified and no calls
+to @funcref{gnutls_pkcs11_add_provider} are made, then the PKCS #11 functionality
+is effectively disabled.
+
+@showfuncdesc{gnutls_pkcs11_init}
+
+
 @node Accessing objects that require a PIN
 @subsection Accessing objects that require a PIN
 
@@ -386,13 +406,13 @@ while the smart card itself can be referenced as:
 pkcs11:token=Nikos;serial=307521161601031;model=PKCS%2315;manufacturer=EnterSafe
 @end example
 
-Objects stored in a @acronym{PKCS} #11 token can be extracted
+Objects stored in a @acronym{PKCS} #11 token can typically 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
+be retrieved. The functions that can be used to enumerate and access objects
 are shown below.
 
-@showfuncB{gnutls_pkcs11_obj_import_url,gnutls_pkcs11_obj_export_url}
+@showfuncC{gnutls_pkcs11_obj_list_import_url4,gnutls_pkcs11_obj_import_url,gnutls_pkcs11_obj_export_url}
 
 @showfuncdesc{gnutls_pkcs11_obj_get_info}
 
diff --git a/lib/pkcs11.c b/lib/pkcs11.c
index b2508d4ed4..57162b3efb 100644
--- a/lib/pkcs11.c
+++ b/lib/pkcs11.c
@@ -2928,20 +2928,32 @@ find_objs_cb(struct ck_function_list *module, struct pkcs11_session_info *sinfo,
 
 /**
  * gnutls_pkcs11_obj_list_import_url3:
- * @p_list: An uninitialized object list (may be NULL)
- * @n_list: initially should hold the maximum size of the list. Will contain the actual size.
+ * @p_list: An uninitialized object list (may be %NULL)
+ * @n_list: Initially should hold the maximum size of the list. Will contain the actual size.
  * @url: A PKCS 11 url identifying a set of objects
  * @flags: Or sequence of GNUTLS_PKCS11_OBJ_* flags
  *
  * This function will initialize and set values to an object list
  * by using all objects identified by a PKCS 11 URL.
  *
+ * This function will enumerate all the objects specified by the PKCS#11 URL
+ * provided. It expects an already allocated @p_list which has *@n_list elements,
+ * and that value will be updated to the actual number of present objects. The
+ * @p_list objects will be initialized and set by this function.
+ * To obtain a list of all available objects use a @url of 'pkcs11:'.
+ *
+ * All returned objects must be deinitialized using gnutls_pkcs11_obj_deinit().
+ *
  * The supported in this function @flags are %GNUTLS_PKCS11_OBJ_FLAG_LOGIN,
  * %GNUTLS_PKCS11_OBJ_FLAG_LOGIN_SO, %GNUTLS_PKCS11_OBJ_FLAG_PRESENT_IN_TRUSTED_MODULE,
  * %GNUTLS_PKCS11_OBJ_FLAG_CRT, %GNUTLS_PKCS11_OBJ_FLAG_PUBKEY, %GNUTLS_PKCS11_OBJ_FLAG_PRIVKEY,
  * %GNUTLS_PKCS11_OBJ_FLAG_WITH_PRIVKEY, %GNUTLS_PKCS11_OBJ_FLAG_MARK_CA,
  * %GNUTLS_PKCS11_OBJ_FLAG_MARK_TRUSTED.
  *
+ * On versions of GnuTLS prior to 3.4.0 the equivalent function was
+ * gnutls_pkcs11_obj_list_import_url(). That is also available on this version
+ * as a macro which maps to this function.
+ *
  * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise a
  *   negative error value.
  *
@@ -3012,12 +3024,12 @@ gnutls_pkcs11_obj_list_import_url3(gnutls_pkcs11_obj_t * p_list,
  * @url: A PKCS 11 url identifying a set of objects
  * @flags: Or sequence of GNUTLS_PKCS11_OBJ_* flags
  *
- * This function will initialize and set values to an object list
- * by using all objects identified by the PKCS 11 URL. The output
- * is stored in @p_list, which will be initialized.
+ * This function will enumerate all the objects specified by the PKCS#11 URL
+ * provided. It will initialize and set values to the object pointer list (@p_list)
+ * provided. To obtain a list of all available objects use a @url of 'pkcs11:'.
  *
  * All returned objects must be deinitialized using gnutls_pkcs11_obj_deinit(),
- * and @p_list must be free'd using gnutls_free().
+ * and @p_list must be deinitialized using gnutls_free().
  *
  * The supported in this function @flags are %GNUTLS_PKCS11_OBJ_FLAG_LOGIN,
  * %GNUTLS_PKCS11_OBJ_FLAG_LOGIN_SO, %GNUTLS_PKCS11_OBJ_FLAG_PRESENT_IN_TRUSTED_MODULE,
@@ -3025,6 +3037,10 @@ gnutls_pkcs11_obj_list_import_url3(gnutls_pkcs11_obj_t * p_list,
  * %GNUTLS_PKCS11_OBJ_FLAG_WITH_PRIVKEY, %GNUTLS_PKCS11_OBJ_FLAG_MARK_CA,
  * %GNUTLS_PKCS11_OBJ_FLAG_MARK_TRUSTED.
  *
+ * On versions of GnuTLS prior to 3.4.0 the equivalent function was
+ * gnutls_pkcs11_obj_list_import_url2(). That is also available on this version
+ * as a macro which maps to this function.
+ *
  * Returns: On success, %GNUTLS_E_SUCCESS (0) is returned, otherwise a
  *   negative error value.
  *