Library Settings

## Library Settings Library Settings — functions for manipulating GCR library global settings. |

## Synopsis

    gboolean            gcr_pkcs11_initialize               (GCancellable *cancellable,
                                                             GError **error);
    void                gcr_pkcs11_initialize_async         (GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            gcr_pkcs11_initialize_finish        (GAsyncResult *result,
                                                             GError **error);
    GList *             gcr_pkcs11_get_modules              (void);
    void                gcr_pkcs11_set_modules              (GList *modules);
    void                gcr_pkcs11_add_module               (GckModule *module);
    gboolean            gcr_pkcs11_add_module_from_file     (const gchar *module_path,
                                                             gpointer unused,
                                                             GError **error);
    GList *             gcr_pkcs11_get_trust_lookup_slots   (void);
    GckSlot *           gcr_pkcs11_get_trust_store_slot     (void);
    const gchar **      gcr_pkcs11_get_trust_lookup_uris    (void);
    void                gcr_pkcs11_set_trust_lookup_uris    (const gchar **pkcs11_uris);
    const gchar *       gcr_pkcs11_get_trust_store_uri      (void);
    void                gcr_pkcs11_set_trust_store_uri      (const gchar *pkcs11_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()`

## Details

### gcr_pkcs11_initialize ()

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

Asynchronously initialize the registered PKCS#11 modules.

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

`cancellable` : | optional cancellable used to cancel the operation
`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.

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

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

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

`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. [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. [transfer full]

### 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. [allow-none][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.

`pkcs11_uris` : | the uris which identifies trust lookup slots. [allow-none]

### 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. [allow-none]

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

`pkcs11_uri` : | the uri which identifies trust storage slot. [allow-none]