GP11Module
3
GP11 Library

# GP11Module

A loaded and initialized PKCS11 module.

## Synopsis

                        GP11Module;
    GP11Module*         gp11_module_new                     (CK_FUNCTION_LIST_PTR funcs);
    GP11Module*         gp11_module_initialize              (const gchar *path,
                                                             gpointer reserved,
                                                             GError **err);
    gboolean            gp11_module_equal                   (gconstpointer module1,
                                                             gconstpointer module2);
    guint               gp11_module_hash                    (gconstpointer module);
    const gchar*        gp11_module_get_path                (GP11Module *self);
    CK_FUNCTION_LIST_PTR  gp11_module_get_functions         (GP11Module *self);
    GP11ModuleInfo*     gp11_module_get_info                (GP11Module *self);
    GList*              gp11_module_get_slots               (GP11Module *self,
                                                             gboolean token_present);
    gboolean            gp11_module_get_pool_sessions       (GP11Module *self);
    void                gp11_module_set_pool_sessions       (GP11Module *self,
                                                             gboolean pool_sessions);
    gint                gp11_module_get_auto_authenticate   (GP11Module *self);
    void                gp11_module_set_auto_authenticate   (GP11Module *self,
                                                             gint auto_authenticate);
    gboolean            gp11_module_enumerate_objects       (GP11Module *self,
                                                             GP11ObjectForeachFunc func,
                                                             gpointer user_data);
    gboolean            (*GP11ObjectForeachFunc)            (GP11Object *object,
                                                             gpointer user_data);
                        GP11ModuleInfo;
    void                gp11_module_info_free               (GP11ModuleInfo *module_info);

## Object Hierarchy

      GObject
       +----GP11Module

## Properties

      "auto-authenticate"        gint                  : Read / Write
      "functions"                gpointer              : Read / Write / Construct Only
      "path"                     gchar*                : Read / Write / Construct Only
      "pool-sessions"            gboolean              : Read / Write

## Signals

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

## Description

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

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

## Details

### GP11Module

    typedef struct _GP11Module GP11Module;

Holds a loaded and initialized PKCS11 module.

### gp11_module_new ()

    GP11Module*         gp11_module_new                     (CK_FUNCTION_LIST_PTR funcs);

Create a GP11Module 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.

### gp11_module_initialize ()

    GP11Module*         gp11_module_initialize              (const gchar *path,
                                                             gpointer reserved,
                                                             GError **err);

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

`path` :

  The file system path to the PKCS11 module to load.

`reserved` :

  Extra arguments for the PKCS11 module, should usually be NULL.

`err` :

  A location to store an error resulting from a failed load.

Returns :

  The loaded PKCS11 module or NULL if failed.

### gp11_module_equal ()

    gboolean            gp11_module_equal                   (gconstpointer module1,
                                                             gconstpointer module2);

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

`module1` :

  A pointer to the first GP11Module

`module2` :

  A pointer to the second GP11Module

Returns :

  TRUE if module1 and module2 are equal. FALSE if either is not a GP11Module.

### gp11_module_hash ()

    guint               gp11_module_hash                    (gconstpointer module);

Create a hash value for the GP11Module.

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

`module` :

  A pointer to a GP11Module

Returns :

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

### gp11_module_get_path ()

    const gchar*        gp11_module_get_path                (GP11Module *self);

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

`self` :

  The module for which to get the path.

Returns :

  The path, do not modify or free this value.

### gp11_module_get_functions ()

    CK_FUNCTION_LIST_PTR  gp11_module_get_functions         (GP11Module *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.

### gp11_module_get_info ()

    GP11ModuleInfo*     gp11_module_get_info                (GP11Module *self);

Get the info about a PKCS11 module.

`self` :

  The module to get info for.

Returns :

  The module info. Release this with `gp11_module_info_free()`.

### gp11_module_get_slots ()

    GList*              gp11_module_get_slots               (GP11Module *self,
                                                             gboolean token_present);

Get the GP11Slot 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 `gp11_list_unref_free()`.

### gp11_module_get_pool_sessions ()

    gboolean            gp11_module_get_pool_sessions       (GP11Module *self);

Get the reuse sessions setting. When this is set, sessions will be pooled and reused if their flags match when `gp11_slot_open_session()` is called.

`self` :

  The module to get setting from.

Returns :

  Whether reusing sessions or not.

### gp11_module_set_pool_sessions ()

    void                gp11_module_set_pool_sessions       (GP11Module *self,
                                                             gboolean pool_sessions);

When this is set, sessions will be pooled and reused if their flags match when `gp11_slot_open_session()` is called.

`self` :

  The module to set the setting on.

`pool_sessions` :

### gp11_module_get_auto_authenticate ()

    gint                gp11_module_get_auto_authenticate   (GP11Module *self);

Get the auto login setting. When this is set, this slot will emit the 'authenticate-slot' signal when a session requires authentication, and the 'authenticate-object' signal when an object requires authintication.

`self` :

  The module to get setting from.

Returns :

  Whether auto login or not.

### gp11_module_set_auto_authenticate ()

    void                gp11_module_set_auto_authenticate   (GP11Module *self,
                                                             gint auto_authenticate);

When this is set, this slot will emit the 'authenticate-slot' signal when a session requires authentication, and the 'authenticate-object' signal when an object requires authintication.

`self` :

  The module to set the setting on.

`auto_authenticate` :

### gp11_module_enumerate_objects ()

    gboolean            gp11_module_enumerate_objects       (GP11Module *self,
                                                             GP11ObjectForeachFunc func,
                                                             gpointer user_data);

Call a function for every matching object on the module. This call may block for an indefinite period.

The arguments must be triples of: attribute type, data type, value

The variable argument list should contain:

a)

  The gulong attribute type (ie: CKA_LABEL).

b)

  The attribute data type (one of GP11_BOOLEAN, GP11_ULONG, GP11_STRING, GP11_DATE) orthe raw attribute value length.

c)

  The attribute value, either a gboolean, gulong, gchar*, GDate* or a pointer to a raw attribute value.

The variable argument list should be terminated with GP11_INVALID.

This function will open a session per slot. It's recommended that you set the 'reuse-sessions' property on each slot if you'll be calling it a lot.

You can access the session in which the object was found, by using the `gp11_object_get_session()` function on the resulting objects.

This function skips tokens that are not initialize, and makes a best effort to find objects on valid tokens.

The function can return FALSE to stop the enumeration.

`self` :

  The module to enumerate objects.

`func` :

  Function to call for each object.

`user_data` :

  Data to pass to the function.

Returns :

  If FALSE then an error prevented all matching objects from being enumerated.

### GP11ObjectForeachFunc ()

    gboolean            (*GP11ObjectForeachFunc)            (GP11Object *object,
                                                             gpointer user_data);

This function is passed to `gp11_module_enumerate_objects()` or a similar function. It is called once for each object matched.

The GP11Session through which the object is accessible can be retrieved by calling `gp11_object_get_session()` on object.

`object` :

  The enumerated object.

`user_data` :

  Data passed to enumerate function.

Returns :

  TRUE to continue enumerating, FALSE to stop.

### GP11ModuleInfo

    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;
    } GP11ModuleInfo;

Holds information about the PKCS&num;11 module.

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

Use `gp11_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&num;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.

### gp11_module_info_free ()

    void                gp11_module_info_free               (GP11ModuleInfo *module_info);

Free a GP11ModuleInfo structure.

`module_info` :

  The module info to free, or NULL.

## Property Details

### The `"auto-authenticate"` property

      "auto-authenticate"        gint                  : Read / Write

Whether or not to automatically authenticate token objects that need a C_Login call before they can be used.

The "authenticate-object" signal will be fired when an object needs to be authenticated.

Allowed values: >= 0

Default value: 0

### The `"functions"` property

      "functions"                gpointer              : Read / Write / Construct Only

The raw PKCS&num;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&num;11 module file path.

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

Default value: NULL

### The `"pool-sessions"` property

      "pool-sessions"            gboolean              : Read / Write

Whether or not to pool PKCS&num;11 sessions. When this is set, sessions will be pooled and reused if their flags match when `gp11_slot_open_session()` is called.

Default value: FALSE

## Signal Details

### The `"authenticate-object"` signal

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

This signal is emitted when a password is needed to authenticate a PKCS&num;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                      (GP11Module *module,
                                                            GP11Slot   *slot,
                                                            gchar      *string,
                                                            gpointer    password,
                                                            gpointer    user_data)      : Run Last

This signal is emitted when a password is needed to authenticate a PKCS&num;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.