Deprecated

Deprecated — Deprecated functions

Functions

Description

These functions have been deprecated from p11-kit and are not recommended for general usage. In large part they were deprecated because they did not adequately insulate multiple callers of a PKCS#11 module from another, and could not support the 'managed' mode needed to do this.

Functions

p11_kit_initialize_registered ()

CK_RV
p11_kit_initialize_registered (void);

p11_kit_initialize_registered is deprecated and should not be used in newly-written code.

Since: 0.19.0: Use p11_kit_modules_load() instead.

Initialize all the registered PKCS#11 modules.

If this is the first time this function is called multiple times consecutively within a single process, then it merely increments an initialization reference count for each of these modules.

Use p11_kit_finalize_registered() to finalize these registered modules once the caller is done with them.

If this function fails, then an error message will be available via the p11_kit_message() function.

Returns

CKR_OK if the initialization succeeded, or an error code.


p11_kit_finalize_registered ()

CK_RV
p11_kit_finalize_registered (void);

p11_kit_finalize_registered is deprecated and should not be used in newly-written code.

Since 0.19.0: Use p11_kit_modules_release() instead.

Finalize all the registered PKCS#11 modules. These should have been initialized with p11_kit_initialize_registered().

If p11_kit_initialize_registered() has been called more than once in this process, then this function must be called the same number of times before actual finalization will occur.

If this function fails, then an error message will be available via the p11_kit_message() function.

Returns

CKR_OK if the finalization succeeded, or an error code.


p11_kit_registered_modules ()

CK_FUNCTION_LIST_PTR *
p11_kit_registered_modules (void);

p11_kit_registered_modules is deprecated and should not be used in newly-written code.

Since 0.19.0: Use p11_kit_modules_load() instead.

Get a list of all the registered PKCS#11 modules. This list will be valid once the p11_kit_initialize_registered() function has been called.

The returned value is a NULL terminated array of

CK_FUNCTION_LIST_PTR pointers.

The returned modules are unmanaged.

Returns

A list of all the registered modules. Use the free() function to free the list.


p11_kit_registered_module_to_name ()

char *
p11_kit_registered_module_to_name (CK_FUNCTION_LIST_PTR module);

p11_kit_registered_module_to_name is deprecated and should not be used in newly-written code.

Since 0.19.0: Use p11_kit_module_get_name() instead.

Get the name of a registered PKCS#11 module.

You can use p11_kit_registered_modules() to get a list of all the registered modules. This name is specified by the registered module configuration.

Parameters

module

pointer to a registered module

 

Returns

A newly allocated string containing the module name, or

NULL if no such registered module exists. Use free() to

free this string.


p11_kit_registered_name_to_module ()

CK_FUNCTION_LIST_PTR
p11_kit_registered_name_to_module (const char *name);

p11_kit_registered_name_to_module is deprecated and should not be used in newly-written code.

Since 0.19.0: Use p11_kit_module_for_name() instead.

Lookup a registered PKCS#11 module by its name. This name is specified by the registered module configuration.

Parameters

name

name of a registered module

 

Returns

a pointer to a PKCS#11 module, or NULL if this name was not found.


p11_kit_registered_option ()

char *
p11_kit_registered_option (CK_FUNCTION_LIST_PTR module,
                           const char *field);

p11_kit_registered_option is deprecated and should not be used in newly-written code.

Since 0.19.0: Use p11_kit_config_option() instead.

Lookup a configured option for a registered PKCS#11 module. If a

NULL module argument is specified, then this will lookup

the configuration option in the global config file.

Parameters

module

a pointer to a registered module

 

field

the name of the option to lookup.

 

Returns

A newly allocated string containing the option value, or

NULL if the registered module or the option were not found.

Use free() to free the returned string.


p11_kit_initialize_module ()

CK_RV
p11_kit_initialize_module (CK_FUNCTION_LIST_PTR module);

p11_kit_initialize_module is deprecated and should not be used in newly-written code.

Since 0.19.0: Use p11_kit_module_initialize() instead.

Initialize an arbitrary PKCS#11 module. Normally using the p11_kit_initialize_registered() is preferred.

Using this function to initialize modules allows coordination between multiple users of the same module in a single process. It should be called on modules that have been loaded (with dlopen() for example) but not yet initialized. The caller should not yet have called the module's

C_Initialize method. This function will call C_Initialize as necessary.

Subsequent calls to this function for the same module will result in an initialization count being incremented for the module. It is safe (although usually unnecessary) to use this function on registered modules.

The module must be finalized with p11_kit_finalize_module() instead of calling its C_Finalize method directly.

This function does not accept a CK_C_INITIALIZE_ARGS argument. Custom initialization arguments cannot be supported when multiple consumers load the same module.

If this function fails, then an error message will be available via the p11_kit_message() function.

Parameters

module

loaded module to initialize.

 

Returns

CKR_OK if the initialization was successful.


p11_kit_load_initialize_module ()

CK_RV
p11_kit_load_initialize_module (const char *module_path,
                                CK_FUNCTION_LIST_PTR *module);

p11_kit_load_initialize_module is deprecated and should not be used in newly-written code.

Since 0.19.0: Use p11_kit_module_load() instead.

Load an arbitrary PKCS#11 module from a dynamic library file, and initialize it. Normally using the p11_kit_initialize_registered() function is preferred.

Using this function to load and initialize modules allows coordination between multiple users of the same module in a single process. The caller should not call the module's C_Initialize method. This function will call

C_Initialize as necessary.

If a module has already been loaded, then use of this function is unnecesasry. Instead use the p11_kit_initialize_module() function to initialize it.

Subsequent calls to this function for the same module will result in an initialization count being incremented for the module. It is safe (although usually unnecessary) to use this function on registered modules.

The module must be finalized with p11_kit_finalize_module() instead of calling its C_Finalize method directly.

This function does not accept a CK_C_INITIALIZE_ARGS argument. Custom initialization arguments cannot be supported when multiple consumers load the same module.

If this function fails, then an error message will be available via the p11_kit_message() function.

Parameters

module_path

full file path of module library

 

module

location to place loaded module pointer

 

Returns

CKR_OK if the initialization was successful.


p11_kit_finalize_module ()

CK_RV
p11_kit_finalize_module (CK_FUNCTION_LIST_PTR module);

p11_kit_finalize_module is deprecated and should not be used in newly-written code.

Since 0.19.0: Use p11_kit_module_finalize() and p11_kit_module_release() instead.

Finalize an arbitrary PKCS#11 module. The module must have been initialized using p11_kit_initialize_module(). In most cases callers will want to use p11_kit_finalize_registered() instead of this function.

Using this function to finalize modules allows coordination between multiple users of the same module in a single process. The caller should not call the module's C_Finalize method. This function will call

C_Finalize as necessary.

If the module was initialized more than once, then this function will decrement an initialization count for the module. When the count reaches zero the module will be truly finalized. It is safe (although usually unnecessary) to use this function on registered modules if (and only if) they were initialized using p11_kit_initialize_module() for some reason.

If this function fails, then an error message will be available via the p11_kit_message() function.

Parameters

module

loaded module to finalize.

 

Returns

CKR_OK if the finalization was successful.


P11_KIT_DEPRECATED_FOR()

#define P11_KIT_DEPRECATED_FOR(f) __attribute__((deprecated("Use " #f " instead")))