GckModule

GckModule — A loaded and initialized PKCS11 module.

Synopsis

struct              GckModule;
GckModule *         gck_module_new                      (CK_FUNCTION_LIST_PTR funcs,
                                                         guint reserved_options);
GckModule *         gck_module_initialize               (const gchar *path,
                                                         gpointer reserved,
                                                         guint reserved_options,
                                                         GError **err);
gboolean            gck_module_equal                    (gconstpointer module1,
                                                         gconstpointer module2);
guint               gck_module_hash                     (gconstpointer module);
const gchar *       gck_module_get_path                 (GckModule *self);
CK_FUNCTION_LIST_PTR gck_module_get_functions           (GckModule *self);
GckModuleInfo *     gck_module_get_info                 (GckModule *self);
GList *             gck_module_get_slots                (GckModule *self,
                                                         gboolean token_present);
                    GckModuleInfo;
void                gck_module_info_free                (GckModuleInfo *module_info);

Object Hierarchy

  GObject
   +----GckModule

Properties

  "functions"                gpointer              : Read / Write / Construct Only
  "path"                     gchar*                : Read / Write / Construct Only

Signals

  "authenticate-object"                            : Run Last
  "authenticate-slot"                              : Run Last

Description

A GckModule object holds a loaded PKCS11 module. A PKCS11 module is a shared library.

You can load and initialize a PKCS11 module with the gck_module_initialize() call. If you already have a loaded and initialized module that you'd like to use with the various gck functions, then you can use gck_module_new().

Details

struct GckModule

struct GckModule;

Holds a loaded and initialized PKCS11 module.

gck_module_new ()

GckModule *         gck_module_new                      (CK_FUNCTION_LIST_PTR funcs,
                                                         guint reserved_options);

Create a GckModule representing a PKCS11 module. It is assumed that this the module is already initialized. In addition it will not be finalized when complete.

`funcs` :	Initialized PKCS11 function list pointer
Returns :	The new PKCS11 module.

gck_module_initialize ()

GckModule *         gck_module_initialize               (const gchar *path,
                                                         gpointer reserved,
                                                         guint reserved_options,
                                                         GError **err);

Load and initialize a PKCS11 module represented by a GckModule object.

`path` :	The file system path to the PKCS11 module to load.
`reserved` :	Extra arguments for the PKCS11 module, should usually be NULL.
`reserved_options` :	No options are currently available.
`err` :	A location to store an error resulting from a failed load.
Returns :	The loaded PKCS11 module or NULL if failed.

gck_module_equal ()

gboolean            gck_module_equal                    (gconstpointer module1,
                                                         gconstpointer module2);

Checks equality of two modules. Two GckModule objects can point to the same underlying PKCS11 module.

`module1` :	A pointer to the first GckModule
`module2` :	A pointer to the second GckModule
Returns :	TRUE if module1 and module2 are equal. FALSE if either is not a GckModule.

gck_module_hash ()

guint               gck_module_hash                     (gconstpointer module);

Create a hash value for the GckModule.

This function is intended for easily hashing a GckModule to add to a GHashTable or similar data structure.

`module` :	A pointer to a GckModule
Returns :	An integer that can be used as a hash value, or 0 if invalid.

gck_module_get_path ()

const gchar *       gck_module_get_path                 (GckModule *self);

Get the file path of this module. This may not be an absolute path, and usually reflects the path passed to gck_module_initialize().

`self` :	The module for which to get the path.
Returns :	The path, do not modify or free this value.

gck_module_get_functions ()

CK_FUNCTION_LIST_PTR gck_module_get_functions           (GckModule *self);

Get the PKCS11 function list for the module.

`self` :	The module for which to get the function list.
Returns :	The function list, do not modify this structure.

gck_module_get_info ()

GckModuleInfo *     gck_module_get_info                 (GckModule *self);

Get the info about a PKCS11 module.

`self` :	The module to get info for.
Returns :	The module info. Release this with `gck_module_info_free()`.

gck_module_get_slots ()

GList *             gck_module_get_slots                (GckModule *self,
                                                         gboolean token_present);

Get the GckSlot objects for a given module.

`self` :	The module for which to get the slots.
`token_present` :	Whether to limit only to slots with a token present.
Returns :	The possibly empty list of slots. Release this with `gck_list_unref_free()`.

GckModuleInfo

typedef struct {
	guint8 pkcs11_version_major;
	guint8 pkcs11_version_minor;

	gchar *manufacturer_id;
	gulong flags;

	gchar *library_description;
	guint8 library_version_major;
	guint8 library_version_minor;
} GckModuleInfo;

Holds information about the PKCS#11 module.

This structure corresponds to CK_MODULE_INFO in the PKCS11 standard. The strings are NULL terminated for easier use.

Use gck_module_info_free() to release this structure when done with it.

guint8 `pkcs11_version_major`;	The major version of the module.
guint8 `pkcs11_version_minor`;	The minor version of the module.
gchar *`manufacturer_id`;	The module manufacturer.
gulong `flags`;	The module PKCS#11 flags.
gchar *`library_description`;	The module description.
guint8 `library_version_major`;	The major version of the library.
guint8 `library_version_minor`;	The minor version of the library.

gck_module_info_free ()

void                gck_module_info_free                (GckModuleInfo *module_info);

Free a GckModuleInfo structure.

module_info :

The module info to free, or NULL.

Property Details

The `"functions"` property

  "functions"                gpointer              : Read / Write / Construct Only

The raw PKCS#11 function list for the module.

This points to a CK_FUNCTION_LIST structure.

The `"path"` property

  "path"                     gchar*                : Read / Write / Construct Only

The PKCS#11 module file path.

This may be set to NULL if this object was created from an already initialized module via the gck_module_new() function.

Default value: NULL

Signal Details

The `"authenticate-object"` signal

gboolean            user_function                      (GckModule *module,
                                                        GckObject *object,
                                                        gchar     *label,
                                                        gpointer   password,
                                                        gpointer   user_data)      : Run Last

This signal is emitted when a password is needed to authenticate a PKCS#11 object like a key. If the module prompts for passwords itself, then this signal will not be emitted.

`module` :	The module.
`object` :	The object to be authenticated.
`label` :	A displayable label which describes the object.
`password` :	A gchar** where a password should be returned.
`user_data` :	user data set when the signal handler was connected.
Returns :	FALSE if the user cancelled, TRUE if we should proceed.

The `"authenticate-slot"` signal

gboolean            user_function                      (GckModule *module,
                                                        GckSlot   *slot,
                                                        gchar     *string,
                                                        gpointer   password,
                                                        gpointer   user_data)      : Run Last

This signal is emitted when a password is needed to authenticate a PKCS#11 slot. If the module prompts for passwords itself, then this signal will not be emitted.

`module` :	The module
`slot` :	The slot to be authenticated.
`string` :	A displayable label which describes the object.
`password` :	A gchar** where a password should be returned.
`user_data` :	user data set when the signal handler was connected.
Returns :	FALSE if the user cancelled, TRUE if we should proceed.

			GCK Reference Manual
Top \| Description \| Object Hierarchy \| Properties \| Signals