diff options
-rw-r--r-- | doc/cha-tokens.texi | 44 | ||||
-rw-r--r-- | lib/pkcs11.c | 28 |
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. * |