## Library PKCS#11

Library PKCS#11 — functions for manipulating GCR library global settings.

## Functions

gboolean | gcr_pkcs11_initialize ()
void | gcr_pkcs11_initialize_async ()
gboolean | gcr_pkcs11_initialize_finish ()
GList * | gcr_pkcs11_get_modules ()
void | gcr_pkcs11_set_modules ()
void | gcr_pkcs11_add_module ()
gboolean | gcr_pkcs11_add_module_from_file ()
GList * | gcr_pkcs11_get_trust_lookup_slots ()
GckSlot * | gcr_pkcs11_get_trust_store_slot ()
const gchar ** | gcr_pkcs11_get_trust_lookup_uris ()
void | gcr_pkcs11_set_trust_lookup_uris ()
const gchar * | gcr_pkcs11_get_trust_store_uri ()
void | gcr_pkcs11_set_trust_store_uri ()

## Description

Manage or lookup various global aspesct and settings of the library.

The GCR library maintains a global list of PKCS#11 modules to use for its various lookups and storage operations. Each module is represented by a GckModule object. You can examine this list by using `gcr_pkcs11_get_modules()`.

The list is configured automatically by looking for system installed PKCS#11 modules. It's not not normally necessary to modify this list. But if you have special needs, you can use the `gcr_pkcs11_set_modules()` and `gcr_pkcs11_add_module()` to do so.

Trust assertions are stored and looked up in specific PKCS#11 slots. You can examine this list with `gcr_pkcs11_get_trust_lookup_slots()`

## Functions

### gcr_pkcs11_initialize ()

    gboolean
    gcr_pkcs11_initialize (GCancellable *cancellable,
                           GError **error);

Asynchronously initialize the registered PKCS#11 modules.

#### Parameters

cancellable | optional cancellable used to cancel the operation |
error | location to place an error on failure |

#### Returns

whether the operation was successful or not.

### gcr_pkcs11_initialize_async ()

    void
    gcr_pkcs11_initialize_async (GCancellable *cancellable,
                                 GAsyncReadyCallback callback,
                                 gpointer user_data);

Asynchronously initialize the registered PKCS#11 modules.

#### Parameters

cancellable | optional cancellable used to cancel the operation. | [nullable]
callback | callback which will be called when the operation completes |
user_data | data passed to the callback |

### gcr_pkcs11_initialize_finish ()

    gboolean
    gcr_pkcs11_initialize_finish (GAsyncResult *result,
                                  GError **error);

Complete the asynchronous operation to initialize the registered PKCS#11 modules.

#### Parameters

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

#### Returns

whether the operation was successful or not.

### gcr_pkcs11_get_modules ()

    GList *
    gcr_pkcs11_get_modules (void);

List all the PKCS#11 modules that are used by the GCR library. Each module is a GckModule object.

An empty list of modules will be returned if `gcr_pkcs11_set_modules()`, or `gcr_pkcs11_initialize()` has not yet run.

When done with the list, free it with `gck_list_unref_free()`.

#### Returns

a newly allocated list of GckModule objects.

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

### gcr_pkcs11_set_modules ()

    void
    gcr_pkcs11_set_modules (GList *modules);

Set the list of PKCS#11 modules that are used by the GCR library. Each module in the list is a GckModule object.

It is not normally necessary to call this function. The available PKCS#11 modules installed on the system are automatically loaded by the GCR library.

#### Parameters

modules | a list of GckModule. | [element-type Gck.Module]

### gcr_pkcs11_add_module ()

    void
    gcr_pkcs11_add_module (GckModule *module);

Add a GckModule to the list of PKCS#11 modules that are used by the GCR library.

It is not normally necessary to call this function. The available PKCS#11 modules installed on the system are automatically loaded by the GCR library.

#### Parameters

module | a GckModule |

### gcr_pkcs11_add_module_from_file ()

    gboolean
    gcr_pkcs11_add_module_from_file (const gchar *module_path,
                                     gpointer unused,
                                     GError **error);

Initialize a PKCS#11 module and add it to the modules that are used by the GCR library. Note that is an error to initialize the same PKCS#11 module twice.

It is not normally necessary to call this function. The available PKCS#11 modules installed on the system are automatically loaded by the GCR library.

#### Parameters

module_path | the full file path of the PKCS#11 module |
unused | unused |
error | a GError or `NULL` |

#### Returns

whether the module was sucessfully added.

### gcr_pkcs11_get_trust_lookup_slots ()

    GList *
    gcr_pkcs11_get_trust_lookup_slots (void);

List all the PKCS#11 slots that are used by the GCR library for lookup of trust assertions. Each slot is a GckSlot object.

This will return an empty list if the `gcr_pkcs11_initialize()` function has not yet been called.

When done with the list, free it with `gck_list_unref_free()`.

#### Returns

a list of GckSlot objects to use for lookup of trust, or the empty list if not initialized or no appropriate trust stores could be found.

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

### gcr_pkcs11_get_trust_store_slot ()

    GckSlot *
    gcr_pkcs11_get_trust_store_slot (void);

Selects an appropriate PKCS#11 slot to store trust assertions. The slot to use is normally configured automatically by the system.

This will only return a valid result after the `gcr_pkcs11_initialize()` method has been called.

When done with the GckSlot, use `g_object_unref()` to release it.

#### Returns

the GckSlot to use for trust assertions, or null if not initialized or no appropriate trust store could be found.

[transfer full][nullable]

### gcr_pkcs11_get_trust_lookup_uris ()

    const gchar **
    gcr_pkcs11_get_trust_lookup_uris (void);

Get the PKCS#11 URIs that are used to identify which slots to use for lookup trust assertions.

#### Returns

the uri which identifies trust storage slot.

[nullable][transfer none]

### gcr_pkcs11_set_trust_lookup_uris ()

    void
    gcr_pkcs11_set_trust_lookup_uris (const gchar **pkcs11_uris);

Set the PKCS#11 URIs that are used to identify which slots to use for lookup of trust assertions.

It is not normally necessary to call this function. The relevant PKCS#11 slots are automatically configured by the GCR library.

#### Parameters

pkcs11_uris | the uris which identifies trust lookup slots. | [nullable]

### gcr_pkcs11_get_trust_store_uri ()

    const gchar *
    gcr_pkcs11_get_trust_store_uri (void);

Get the PKCS#11 URI that is used to identify which slot to use for storing trust storage.

#### Returns

the uri which identifies trust storage slot.

[nullable]

### gcr_pkcs11_set_trust_store_uri ()

    void
    gcr_pkcs11_set_trust_store_uri (const gchar *pkcs11_uri);

Set the PKCS#11 URI that is used to identify which slot to use for storing trust assertions.

It is not normally necessary to call this function. The relevant PKCS#11 slot is automatically configured by the GCR library.

#### Parameters

pkcs11_uri | the uri which identifies trust storage slot. | [nullable]