5.3.1 Initialization

To allow all GnuTLS applications to transparently access smard cards and tokens, PKCS #11 is automatically initialized during the first call of a PKCS #11 related function. The initialization process, based on p11-kit configuration, loads any appropriate modules. The p11-kit configuration files¹² are typically stored in /etc/pkcs11/modules/. For example a file that will instruct GnuTLS to load the OpenSC module, could be named /etc/pkcs11/modules/opensc.module and contain the following:

module: /usr/lib/opensc-pkcs11.so

If you use these configuration files, then there is no need for other initialization in GnuTLS, except for the PIN and token callbacks (see next section). In several cases, however, it is desirable to limit badly behaving modules (e.g., modules that add an unacceptable delay on initialization) 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 gnutls_pkcs11_init with the flag GNUTLS_PKCS11_FLAG_MANUAL prior to gnutls_global_init.

Function: int gnutls_pkcs11_init (unsigned int flags, const char * deprecated_config_file)

flags: An ORed sequence of GNUTLS_PKCS11_FLAG_ *

deprecated_config_file: either NULL or the location of a deprecated configuration file

This function will initialize the PKCS 11 subsystem in gnutls. It will read configuration files if GNUTLS_PKCS11_FLAG_AUTO is used or allow you to independently load PKCS 11 modules using gnutls_pkcs11_add_provider() if GNUTLS_PKCS11_FLAG_MANUAL is specified.

You don’t need to call this function since GnuTLS 3.3.0 because it is being called during the first request PKCS 11 operation. That call will assume the GNUTLS_PKCS11_FLAG_AUTO flag. If another flags are required then it must be called independently prior to any PKCS 11 operation.

Returns: On success, GNUTLS_E_SUCCESS (0) is returned, otherwise a negative error value.

Since: 2.12.0

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¹³. For that reasons 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 GnuTLS required to call gnutls_pkcs11_reinit after a fork() call; since 3.3.0 this is no longer required.