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 functions (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.

In all cases, you can also 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 must be reinitialized on the child processes after a fork. In older versions of GnuTLS it was required to call gnutls_pkcs11_reinit; since 3.3.0 this is no longer required, as reinitialization occurs automatically.