5.2.1 Initialization

To allow all GnuTLS applications to transparently access smard cards and tokens, PKCS #11 is automatically initialized during the global initialization (see gnutls_global_init). The initialization function, to select which modules to load reads certain module configuration files. Those are stored in /etc/pkcs11/modules/ and are the configuration files of p11-kit(8). For example a file that will 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.

Normally you don’t need to call this function since it is being called when the first PKCS 11 operation is requested using 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.

This document was generated on May 31, 2014 using texi2html 5.0.