GckModule: Gck Library Reference Manual

## GckModule GckModule — A loaded and initialized PKCS#11 module. |

## Functions

GckModule * | gck_module_initialize ()
void | gck_module_initialize_async ()
GckModule * | gck_module_initialize_finish ()
GckModule * | gck_module_new ()
gboolean | gck_module_equal ()
guint | gck_module_hash ()
gboolean | gck_module_match ()
const gchar * | gck_module_get_path ()
CK_FUNCTION_LIST_PTR | gck_module_get_functions ()
GckModuleInfo * | gck_module_get_info ()
GList * | gck_module_get_slots ()
GckModuleInfo * | gck_module_info_copy ()
void | gck_module_info_free ()

## Properties

gpointer | functions | Read / Write / Construct Only
gchar * | path | Read / Write / Construct Only

## Signals

gboolean | authenticate-object | Run Last
gboolean | authenticate-slot | Run Last

## Types and Values

struct | GckModule
struct | GckModuleInfo

## Object Hierarchy

        GBoxed
        ╰── GckModuleInfo
        GObject
        ╰── GckModule

## Description

A GckModule object holds a loaded PKCS#11 module. A PKCS#11 module is a shared library.

You can load and initialize a PKCS#11 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()`.

## Functions

### gck_module_initialize ()

    GckModule *
    gck_module_initialize (const gchar *path,
                           GCancellable *cancellable,
                           GError **error);

Load and initialize a PKCS#11 module represented by a GckModule object.

#### Parameters

path | The file system path to the PKCS#11 module to load. |
cancellable | optional cancellation object. | [allow-none]
error | A location to store an error resulting from a failed load. |

#### Returns

The loaded PKCS#11 module or `NULL` if failed.

[transfer full]

### gck_module_initialize_async ()

    void
    gck_module_initialize_async (const gchar *path,
                                 GCancellable *cancellable,
                                 GAsyncReadyCallback callback,
                                 gpointer user_data);

Asynchronously load and initialize a PKCS#11 module represented by a GckModule object.

#### Parameters

path | the file system path to the PKCS#11 module to load |
cancellable | optional cancellation object. | [allow-none]
callback | a callback which will be called when the operation completes |
user_data | data to pass to the callback |

### gck_module_initialize_finish ()

    GckModule *
    gck_module_initialize_finish (GAsyncResult *result,
                                  GError **error);

Finishes the asynchronous initialize operation.

#### Parameters

result | the asynchronous result |
error | location to place an error on failure |

#### Returns

The initialized module, or NULL.

[transfer full][allow-none]

### gck_module_new ()

    GckModule *
    gck_module_new (CK_FUNCTION_LIST_PTR funcs);

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

[skip]

#### Parameters

funcs | Initialized PKCS#11 function list pointer |

#### Returns

The new PKCS#11 module.

### 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 PKCS#11 module.

#### Parameters

module1 | a pointer to the first GckModule. | [type Gck.Module]
module2 | a pointer to the second GckModule. | [type Gck.Module]

#### 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.

#### Parameters

module | a pointer to a GckModule. | [type Gck.Module]

#### Returns

An integer that can be used as a hash value, or 0 if invalid.

### gck_module_match ()

    gboolean
    gck_module_match (GckModule *self,
                      GckUriData *uri);

Check whether the PKCS#11 URI matches the module

#### Parameters

self | the module to match |
uri | the uri to match against the module |

#### Returns

whether the URI matches or not

### 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()`.

#### Parameters

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 PKCS#11 function list for the module.

[skip]

#### Parameters

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 PKCS#11 module.

#### Parameters

self | The module to get info for. |

#### Returns

the module info; release this with `gck_module_info_free()`.

[transfer full]

### gck_module_get_slots ()

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

Get the GckSlot objects for a given module.

#### Parameters

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()`.

[element-type Gck.Slot][transfer full]

### gck_module_info_copy ()

    GckModuleInfo *
    gck_module_info_copy (GckModuleInfo *module_info);

Make a copy of the module info.

#### Parameters

module_info | a module info |

#### Returns

a newly allocated copy module info.

[transfer full]

### gck_module_info_free ()

    void
    gck_module_info_free (GckModuleInfo *module_info);

Free a GckModuleInfo structure.

#### Parameters

module_info | The module info to free, or NULL. |

## Types and Values

### struct GckModule

    struct GckModule;

Holds a loaded and initialized PKCS#11 module.

### struct GckModuleInfo

    struct GckModuleInfo {
    	guint8 pkcs11_version_major;
    	guint8 pkcs11_version_minor;

    	gchar *manufacturer_id;
    	gulong flags;

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

Holds information about the PKCS#11 module.

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

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

#### Members

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

## Property Details

### The `“functions”` property

      “functions”                gpointer

The raw PKCS#11 function list for the module.

This points to a CK_FUNCTION_LIST structure.

Flags: Read / Write / Construct Only

### The `“path”` property

      “path”                     gchar *

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.

Flags: Read / Write / Construct Only

Default value: NULL

## Signal Details

### The `“authenticate-object”` signal

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

Use `gck_session_set_interaction()` instead of connecting to this signal.

`GckModule::authenticate-object` is deprecated and should not be used in newly-written code.

Since 3.4

#### Parameters

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

Flags: Run Last

### The `“authenticate-slot”` signal

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

Use `gck_session_set_interaction()` instead of connecting to this signal.

`GckModule::authenticate-slot` is deprecated and should not be used in newly-written code.

Since 3.4

#### Parameters

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

Flags: Run Last