6.7.1 Initialization

To allow all the GnuTLS applications to access PKCS #11 tokens you can use a configuration per module, stored in /etc/pkcs11/modules/. These are the configuration files of p11-kit(11). For example a file that will load the OpenSC module, could be named /etc/pkcs11/modules/opensc and contain the following:

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

If you use this file, then there is no need for other initialization in GnuTLS, except for the PIN and token functions. Those allow retrieving a PIN when accessing a protected object, such as a private key, as well as probe the user to insert the token. All the initialization functions are below.

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

flags: GNUTLS_PKCS11_FLAG_MANUAL or GNUTLS_PKCS11_FLAG_AUTO

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 by gnutls_global_init() using the GNUTLS_PKCS11_FLAG_AUTO . If other option is required then it must be called before it.

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

Since: 2.12.0

gnutls_pkcs11_set_token_function

gnutls_pkcs11_set_pin_function

gnutls_pkcs11_add_provider

Note that due to limitations of PKCS #11 there are issues when multiple libraries are sharing a module. To avoid this problem GnuTLS uses p11-kit that provides a middleware to control access to resources over the multiple users.

Moreover PKCS #11 modules must be reinitialized on the child processes after a fork. GnuTLS provides gnutls_pkcs11_reinit to be called for this purpose.

Function: int gnutls_pkcs11_reinit ( void)

This function will reinitialize the PKCS 11 subsystem in gnutls. This is required by PKCS 11 when an application uses fork() . The reinitialization function must be called on the child.

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

Since: 3.0