GckSession: Gck Library Reference Manual

## GckSession GckSession — Represents an open PKCS11 session. |

## Functions

GckSession * | gck_session_from_handle ()
GckSession * | gck_session_open ()
void | gck_session_open_async ()
GckSession * | gck_session_open_finish ()
GckModule * | gck_session_get_module ()
GckSlot * | gck_session_get_slot ()
gulong | gck_session_get_handle ()
GckSessionInfo * | gck_session_get_info ()
GTlsInteraction * | gck_session_get_interaction ()
gboolean | gck_session_login ()
void | gck_session_login_async ()
gboolean | gck_session_login_finish ()
gboolean | gck_session_logout ()
void | gck_session_logout_async ()
gboolean | gck_session_logout_finish ()
GckObject * | gck_session_create_object ()
void | gck_session_create_object_async ()
GckObject * | gck_session_create_object_finish ()
GckEnumerator * | gck_session_enumerate_objects ()
gulong * | gck_session_find_handles ()
void | gck_session_find_handles_async ()
gulong * | gck_session_find_handles_finish ()
GList * | gck_session_find_objects ()
void | gck_session_find_objects_async ()
GList * | gck_session_find_objects_finish ()
guchar * | gck_session_encrypt ()
guchar * | gck_session_encrypt_full ()
void | gck_session_encrypt_async ()
guchar * | gck_session_encrypt_finish ()
guchar * | gck_session_decrypt ()
guchar * | gck_session_decrypt_full ()
void | gck_session_decrypt_async ()
guchar * | gck_session_decrypt_finish ()
gboolean | gck_session_login_interactive ()
void | gck_session_login_interactive_async ()
gboolean | gck_session_login_interactive_finish ()
void | gck_session_set_interaction ()
guchar * | gck_session_sign ()
guchar * | gck_session_sign_full ()
void | gck_session_sign_async ()
guchar * | gck_session_sign_finish ()
gboolean | gck_session_verify ()
gboolean | gck_session_verify_full ()
void | gck_session_verify_async ()
gboolean | gck_session_verify_finish ()
GckObject * | gck_session_derive_key ()
void | gck_session_derive_key_async ()
GckObject * | gck_session_derive_key_finish ()
GckObject * | gck_session_derive_key_full ()
gboolean | gck_session_generate_key_pair ()
void | gck_session_generate_key_pair_async ()
gboolean | gck_session_generate_key_pair_finish ()
gboolean | gck_session_generate_key_pair_full ()
GckSessionOptions | gck_session_get_options ()
gulong | gck_session_get_state ()
gboolean | gck_session_init_pin ()
void | gck_session_init_pin_async ()
gboolean | gck_session_init_pin_finish ()
gboolean | gck_session_set_pin ()
void | gck_session_set_pin_async ()
gboolean | gck_session_set_pin_finish ()
GckObject * | gck_session_unwrap_key ()
void | gck_session_unwrap_key_async ()
GckObject * | gck_session_unwrap_key_finish ()
GckObject * | gck_session_unwrap_key_full ()
guchar * | gck_session_wrap_key ()
void | gck_session_wrap_key_async ()
guchar * | gck_session_wrap_key_finish ()
guchar * | gck_session_wrap_key_full ()
GckSessionInfo * | gck_session_info_copy ()
void | gck_session_info_free ()

## Properties

gpointer | app-data | Write / Construct Only
gulong | handle | Read / Write / Construct Only
GTlsInteraction * | interaction | Read / Write
GckModule * | module | Read
gulong | opening-flags | Write / Construct Only
GckSessionOptions | options | Read / Write / Construct Only
GckSlot * | slot | Read / Write / Construct Only

## Signals

gboolean | discard-handle | Run Last

## Types and Values

struct | GckSession
struct | GckSessionInfo
struct | GckMechanism

## Object Hierarchy

        GBoxed
        ╰── GckSessionInfo
        GObject
        ╰── GckSession

## Implemented Interfaces

GckSession implements GInitable and GAsyncInitable.

## Description

Before performing any PKCS11 operations, a session must be opened. This is analogous to an open database handle, or a file handle.

## Functions

### gck_session_from_handle ()

    GckSession *
    gck_session_from_handle (GckSlot *slot,
                             gulong session_handle,
                             GckSessionOptions options);

Initialize a GckSession object from a raw PKCS#11 session handle. Usually one would use the `gck_slot_open_session()` function to create a session.

#### Parameters

slot | The slot which the session belongs to. |
session_handle | the raw PKCS#11 handle of the session |
options | Session options. Those which are used during opening a session have no effect. |

#### Returns

the new GckSession object.

[transfer full]

### gck_session_open ()

    GckSession *
    gck_session_open (GckSlot *slot,
                      GckSessionOptions options,
                      GTlsInteraction *interaction,
                      GCancellable *cancellable,
                      GError **error);

Open a session on the slot. This call may block for an indefinite period.

#### Parameters

slot | the slot to open session on |
options | session options |
interaction | optional interaction for logins or object authentication. | [nullable]
cancellable | optional cancellation object |
error | location to place error or `NULL` |

#### Returns

the new session.

[transfer full]

### gck_session_open_async ()

    void
    gck_session_open_async (GckSlot *slot,
                            GckSessionOptions options,
                            GTlsInteraction *interaction,
                            GCancellable *cancellable,
                            GAsyncReadyCallback callback,
                            gpointer user_data);

Open a session on the slot. This call will return immediately and complete asynchronously.

#### Parameters

slot | the slot to open session on |
options | session options |
interaction | optional interaction for logins or object authentication. | [nullable]
cancellable | optional cancellation object |
callback | called when the operation completes |
user_data | data to pass to callback |

### gck_session_open_finish ()

    GckSession *
    gck_session_open_finish (GAsyncResult *result,
                             GError **error);

Get the result of an open session operation.

#### Parameters

result | the result passed to the callback |
error | location to return an error or `NULL` |

#### Returns

the new session.

[transfer full]

### gck_session_get_module ()

    GckModule *
    gck_session_get_module (GckSession *self);

Get the PKCS#11 module to which this session belongs.

#### Parameters

self | The session object. |

#### Returns

the module, which should be unreffed after use.

[transfer full]

### gck_session_get_slot ()

    GckSlot *
    gck_session_get_slot (GckSession *self);

Get the PKCS#11 slot to which this session belongs.

#### Parameters

self | The session object. |

#### Returns

The slot, which should be unreffed after use.

[transfer full]

### gck_session_get_handle ()

    gulong
    gck_session_get_handle (GckSession *self);

Get the raw PKCS#11 session handle from a GckSession object.

#### Parameters

self | The session object. |

#### Returns

The raw session handle.

### gck_session_get_info ()

    GckSessionInfo *
    gck_session_get_info (GckSession *self);

Get information about the session.

#### Parameters

self | The session object. |

#### Returns

the session info. Use the `gck_session_info_free()` to release when done.

[transfer full]

### gck_session_get_interaction ()

    GTlsInteraction *
    gck_session_get_interaction (GckSession *self);

Get the interaction object set on this session, which is used to prompt for pins and the like.

#### Parameters

self | the session |

#### Returns

the interaction object, or `NULL`.

[transfer full][nullable]

### gck_session_login ()

    gboolean
    gck_session_login (GckSession *self,
                       gulong user_type,
                       const guchar *pin,
                       gsize n_pin,
                       GCancellable *cancellable,
                       GError **error);

Login the user on the session. This call may block for an indefinite period.

#### Parameters

self | Log in to this session. |
user_type | The type of login user. |
pin | the user's PIN, or `NULL` for protected authentication path. | [nullable][array length=n_pin]
n_pin | The length of the PIN. |
cancellable | Optional cancellation object, or `NULL`. |
error | A location to return an error. |

#### Returns

Whether successful or not.

### gck_session_login_async ()

    void
    gck_session_login_async (GckSession *self,
                             gulong user_type,
                             const guchar *pin,
                             gsize n_pin,
                             GCancellable *cancellable,
                             GAsyncReadyCallback callback,
                             gpointer user_data);

Login the user on the session. This call will return immediately and completes asynchronously.

#### Parameters

self | Log in to this session. |
user_type | The type of login user. |
pin | the user's PIN, or `NULL` for protected authentication path. | [nullable][array length=n_pin]
n_pin | The length of the PIN. |
cancellable | Optional cancellation object, or `NULL`. |
callback | Called when the operation completes. |
user_data | Data to pass to the callback. |

### gck_session_login_finish ()

    gboolean
    gck_session_login_finish (GckSession *self,
                              GAsyncResult *result,
                              GError **error);

Get the result of a login operation.

#### Parameters

self | The session logged into. |
result | The result passed to the callback. |
error | A location to return an error. |

#### Returns

Whether the operation was successful or not.

### gck_session_logout ()

    gboolean
    gck_session_logout (GckSession *self,
                        GCancellable *cancellable,
                        GError **error);

Log out of the session. This call may block for an indefinite period.

#### Parameters

self | Logout of this session. |
cancellable | Optional cancellation object, or `NULL`. |
error | A location to return an error. |

#### Returns

Whether the logout was successful or not.

### gck_session_logout_async ()

    void
    gck_session_logout_async (GckSession *self,
                              GCancellable *cancellable,
                              GAsyncReadyCallback callback,
                              gpointer user_data);

Log out of the session. This call returns immediately and completes asynchronously.

#### Parameters

self | Logout of this session. |
cancellable | Optional cancellation object, or `NULL`. |
callback | Called when the operation completes. |
user_data | Data to pass to the callback. |

### gck_session_logout_finish ()

    gboolean
    gck_session_logout_finish (GckSession *self,
                               GAsyncResult *result,
                               GError **error);

Get the result of logging out of a session.

#### Parameters

self | Logout of this session. |
result | The result passed to the callback. |
error | A location to return an error. |

#### Returns

Whether the logout was successful or not.

### gck_session_create_object ()

    GckObject *
    gck_session_create_object (GckSession *self,
                               GckAttributes *attrs,
                               GCancellable *cancellable,
                               GError **error);

Create a new PKCS#11 object. This call may block for an indefinite period.

If the `attrs` GckAttributes is floating, it is consumed.

#### Parameters

self | The session to create the object on. |
attrs | The attributes to create the object with. |
cancellable | Optional cancellation object, or `NULL`. |
error | A location to return an error, or `NULL`. |

#### Returns

the newly created object or `NULL` if an error occurred.

[transfer full]

### gck_session_create_object_async ()

    void
    gck_session_create_object_async (GckSession *self,
                                     GckAttributes *attrs,
                                     GCancellable *cancellable,
                                     GAsyncReadyCallback callback,
                                     gpointer user_data);

Create a new PKCS#11 object. This call will return immediately and complete asynchronously.

If the `attrs` GckAttributes is floating, it is consumed.

#### Parameters

self | The session to create the object on. |
attrs | The attributes to create the object with. |
cancellable | Optional cancellation object or `NULL`. |
callback | Called when the operation completes. |
user_data | Data to pass to the callback. |

### gck_session_create_object_finish ()

    GckObject *
    gck_session_create_object_finish (GckSession *self,
                                      GAsyncResult *result,
                                      GError **error);

Get the result of creating a new PKCS#11 object.

#### Parameters

self | The session to create the object on. |
result | The result passed to the callback. |
error | A location to return an error, or `NULL`. |

#### Returns

the newly created object or `NULL` if an error occurred.

[transfer full]

### gck_session_enumerate_objects ()

    GckEnumerator *
    gck_session_enumerate_objects (GckSession *self,
                                   GckAttributes *match);

Setup an enumerator for listing matching objects available via this session.

If the `match` GckAttributes is floating, it is consumed.

This call will not block but will return an enumerator immediately.

#### Parameters

self | session to enumerate objects on |
match | attributes that the objects must match, or empty for all objects |

#### Returns

a new enumerator.

[transfer full]

### gck_session_find_handles ()

    gulong *
    gck_session_find_handles (GckSession *self,
                              GckAttributes *match,
                              GCancellable *cancellable,
                              gulong *n_handles,
                              GError **error);

Find the objects matching the passed attributes. This call may block for an indefinite period.

If the `match` GckAttributes is floating, it is consumed.

#### Parameters

self | the session to find objects on |
match | the attributes to match against objects |
cancellable | optional cancellation object or `NULL` |
n_handles | location to return number of handles |
error | a location to return an error or `NULL` |

#### Returns

a list of the matching objects, which may be empty.

[transfer full][array length=n_handles][nullable]

### gck_session_find_handles_async ()

    void
    gck_session_find_handles_async (GckSession *self,
                                    GckAttributes *match,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

Find the objects matching the passed attributes. This call will return immediately and complete asynchronously.

If the `match` GckAttributes is floating, it is consumed.

#### Parameters

self | the session to find objects on |
match | the attributes to match against the objects |
cancellable | optional cancellation object or `NULL` |
callback | called when the operation completes |
user_data | data to pass to the callback |

### gck_session_find_handles_finish ()

    gulong *
    gck_session_find_handles_finish (GckSession *self,
                                     GAsyncResult *result,
                                     gulong *n_handles,
                                     GError **error);

Get the result of a find handles operation.

#### Parameters

self | the session |
result | the asynchronous result |
n_handles | location to store number of handles returned |
error | a location to return an error on failure |

#### Returns

an array of handles that matched, which may be empty, or `NULL` on failure.

[transfer full][array length=n_handles][nullable]

### gck_session_find_objects ()

    GList *
    gck_session_find_objects (GckSession *self,
                              GckAttributes *match,
                              GCancellable *cancellable,
                              GError **error);

Find the objects matching the passed attributes. This call may block for an indefinite period.

If the `match` GckAttributes is floating, it is consumed.

#### Parameters

self | The session to find objects on. |
match | the attributes to match |
cancellable | Optional cancellation object or `NULL`. |
error | A location to return an error or `NULL`. |

#### Returns

a list of the matching objects, which may be empty.

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

### gck_session_find_objects_async ()

    void
    gck_session_find_objects_async (GckSession *self,
                                    GckAttributes *match,
                                    GCancellable *cancellable,
                                    GAsyncReadyCallback callback,
                                    gpointer user_data);

Find the objects matching the passed attributes. This call will return immediately and complete asynchronously.

If the `match` GckAttributes is floating, it is consumed.

#### Parameters

self | The session to find objects on. |
match | The attributes to match. |
cancellable | Optional cancellation object or `NULL`. |
callback | Called when the operation completes. |
user_data | Data to pass to the callback. |

### gck_session_find_objects_finish ()

    GList *
    gck_session_find_objects_finish (GckSession *self,
                                     GAsyncResult *result,
                                     GError **error);

Get the result of a find operation.

#### Parameters

self | The session to find objects on. |
result | The attributes to match. |
error | A location to return an error. |

#### Returns

a list of the matching objects, which may be empty.

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

### gck_session_encrypt ()

    guchar *
    gck_session_encrypt (GckSession *self,
                         GckObject *key,
                         gulong mech_type,
                         const guchar *input,
                         gsize n_input,
                         gsize *n_result,
                         GCancellable *cancellable,
                         GError **error);

Encrypt data in a mechanism specific manner. This call may block for an indefinite period.

#### Parameters

self | The session. |
key | The key to encrypt with. |
mech_type | The mechanism type to use for encryption. |
input | the data to encrypt. | [array length=n_input]
n_input | the length of the data to encrypt |
n_result | location to store the length of the result data |
cancellable | Optional cancellation object, or `NULL` |
error | A location to place error information. |

#### Returns

the data that was encrypted, or `NULL` if an error occured.

[transfer full][array length=n_result]

### gck_session_encrypt_full ()

    guchar *
    gck_session_encrypt_full (GckSession *self,
                              GckObject *key,
                              GckMechanism *mechanism,
                              const guchar *input,
                              gsize n_input,
                              gsize *n_result,
                              GCancellable *cancellable,
                              GError **error);

Encrypt data in a mechanism specific manner. This call may block for an indefinite period.

#### Parameters

self | The session. |
key | The key to encrypt with. |
mechanism | The mechanism type and parameters to use for encryption. |
input | the data to encrypt. | [array length=n_input]
n_input | the length of the data to encrypt |
n_result | location to store the length of the result data |
cancellable | A GCancellable which can be used to cancel the operation. |
error | A location to place error information. |

#### Returns

the data that was encrypted, or `NULL` if an error occured.

[transfer full][array length=n_result]

### gck_session_encrypt_async ()

    void
    gck_session_encrypt_async (GckSession *self,
                               GckObject *key,
                               GckMechanism *mechanism,
                               const guchar *input,
                               gsize n_input,
                               GCancellable *cancellable,
                               GAsyncReadyCallback callback,
                               gpointer user_data);

Encrypt data in a mechanism specific manner. This call will return immediately and complete asynchronously.

#### Parameters

self | The session. |
key | The key to encrypt with. |
mechanism | The mechanism type and parameters to use for encryption. |
input | the data to encrypt. | [array length=n_input]
n_input | length of the data to encrypt |
cancellable | A GCancellable which can be used to cancel the operation. |
callback | Called when the operation completes. |
user_data | A pointer to pass to the callback. |

### gck_session_encrypt_finish ()

    guchar *
    gck_session_encrypt_finish (GckSession *self,
                                GAsyncResult *result,
                                gsize *n_result,
                                GError **error);

Get the result of an encryption operation.

#### Parameters

self | The session. |
result | The result object passed to the callback. |
n_result | A location to store the length of the result data. |
error | A location to place error information. |

#### Returns

the data that was encrypted, or `NULL` if an error occurred.

[transfer full][array length=n_result]

### gck_session_decrypt ()

    guchar *
    gck_session_decrypt (GckSession *self,
                         GckObject *key,
                         gulong mech_type,
                         const guchar *input,
                         gsize n_input,
                         gsize *n_result,
                         GCancellable *cancellable,
                         GError **error);

Decrypt data in a mechanism specific manner. This call may block for an indefinite period.

#### Parameters

self | The session. |
key | The key to decrypt with. |
mech_type | The mechanism type to use for decryption. |
input | data to decrypt. | [array length=n_input]
n_input | length of the data to decrypt |
n_result | location to store the length of the result data |
cancellable | Optional cancellation object, or `NULL` |
error | A location to place an error. |

#### Returns

the data that was decrypted, or `NULL` if an error occured.

[transfer full][array length=n_result]

### gck_session_decrypt_full ()

    guchar *
    gck_session_decrypt_full (GckSession *self,
                              GckObject *key,
                              GckMechanism *mechanism,
                              const guchar *input,
                              gsize n_input,
                              gsize *n_result,
                              GCancellable *cancellable,
                              GError **error);

Decrypt data in a mechanism specific manner. This call may block for an indefinite period.

#### Parameters

self | The session. |
key | The key to decrypt with. |
mechanism | The mechanism type and parameters to use for decryption. |
input | data to decrypt. | [array length=n_input]
n_input | length of the data to decrypt |
n_result | location to store the length of the result data |
cancellable | A GCancellable which can be used to cancel the operation. |
error | A location to place error information. |

#### Returns

the data that was decrypted, or `NULL` if an error occured.

[transfer full][array length=n_result]

### gck_session_decrypt_async ()

    void
    gck_session_decrypt_async (GckSession *self,
                               GckObject *key,
                               GckMechanism *mechanism,
                               const guchar *input,
                               gsize n_input,
                               GCancellable *cancellable,
                               GAsyncReadyCallback callback,
                               gpointer user_data);

Decrypt data in a mechanism specific manner. This call will return immediately and complete asynchronously.

#### Parameters

self | The session. |
key | The key to decrypt with. |
mechanism | The mechanism type and parameters to use for decryption. |
input | data to decrypt. | [array length=n_input]
n_input | length of the data to decrypt |
cancellable | A GCancellable which can be used to cancel the operation. |
callback | Called when the operation completes. |
user_data | A pointer to pass to the callback. |

### gck_session_decrypt_finish ()

    guchar *
    gck_session_decrypt_finish (GckSession *self,
                                GAsyncResult *result,
                                gsize *n_result,
                                GError **error);

Get the result of an decryption operation.

#### Parameters

self | The session. |
result | The result object passed to the callback. |
n_result | A location to store the length of the result data. |
error | A location to place error information. |

#### Returns

the data that was decrypted, or `NULL` if an error occurred.

[transfer full][array length=n_result]

### gck_session_login_interactive ()

    gboolean
    gck_session_login_interactive (GckSession *self,
                                   gulong user_type,
                                   GTlsInteraction *interaction,
                                   GCancellable *cancellable,
                                   GError **error);

Login the user on the session requesting the password interactively when necessary. This call may block for an indefinite period.

#### Parameters

self | session to use for login |
user_type | the type of login user |
interaction | interaction to request PIN when necessary. | [nullable]
cancellable | optional cancellation object, or `NULL` |
error | location to return an error |

#### Returns

Whether successful or not.

### gck_session_login_interactive_async ()

    void
    gck_session_login_interactive_async (GckSession *self,
                                         gulong user_type,
                                         GTlsInteraction *interaction,
                                         GCancellable *cancellable,
                                         GAsyncReadyCallback callback,
                                         gpointer user_data);

Login the user on the session prompting for passwords interactively when necessary. This call will return immediately and completes asynchronously.

#### Parameters

self | session to use for login |
user_type | the type of login user |
interaction | interaction to request PIN when necessary. | [nullable]
cancellable | optional cancellation object, or `NULL` |
callback | called when the operation completes |
user_data | data to pass to the callback |

### gck_session_login_interactive_finish ()

    gboolean
    gck_session_login_interactive_finish (GckSession *self,
                                          GAsyncResult *result,
                                          GError **error);

Get the result of a login operation.

#### Parameters

self | the session logged into |
result | the result passed to the callback |
error | location to return an error |

#### Returns

Whether the operation was successful or not.

### gck_session_set_interaction ()

    void
    gck_session_set_interaction (GckSession *self,
                                 GTlsInteraction *interaction);

Set the interaction object on this session, which is used to prompt for pins and the like.

#### Parameters

self | the session |
interaction | the interaction or `NULL`. | [nullable]

### gck_session_sign ()

    guchar *
    gck_session_sign (GckSession *self,
                      GckObject *key,
                      gulong mech_type,
                      const guchar *input,
                      gsize n_input,
                      gsize *n_result,
                      GCancellable *cancellable,
                      GError **error);

Sign data in a mechanism specific manner. This call may block for an indefinite period.

#### Parameters

self | The session. |
key | The key to sign with. |
mech_type | The mechanism type to use for signing. |
input | data to sign. | [array length=n_input]
n_input | length of the data to sign |
n_result | location to store the length of the result data |
cancellable | Optional cancellation object, or `NULL` |
error | A location to place an error. |

#### Returns

the data that was signed, or `NULL` if an error occured.

[transfer full][array length=n_result]

### gck_session_sign_full ()

    guchar *
    gck_session_sign_full (GckSession *self,
                           GckObject *key,
                           GckMechanism *mechanism,
                           const guchar *input,
                           gsize n_input,
                           gsize *n_result,
                           GCancellable *cancellable,
                           GError **error);

Sign data in a mechanism specific manner. This call may block for an indefinite period.

#### Parameters

self | The session. |
key | The key to sign with. |
mechanism | The mechanism type and parameters to use for signing. |
input | data to sign. | [array length=n_input]
n_input | length of the data to sign |
n_result | location to store the length of the result data |
cancellable | A GCancellable which can be used to cancel the operation. |
error | A location to place error information. |

#### Returns

The data that was signed, or `NULL` if an error occured.

### gck_session_sign_async ()

    void
    gck_session_sign_async (GckSession *self,
                            GckObject *key,
                            GckMechanism *mechanism,
                            const guchar *input,
                            gsize n_input,
                            GCancellable *cancellable,
                            GAsyncReadyCallback callback,
                            gpointer user_data);

Sign data in a mechanism specific manner. This call will return immediately and complete asynchronously.

#### Parameters

self | The session. |
key | The key to sign with. |
mechanism | The mechanism type and parameters to use for signing. |
input | data to sign. | [array length=n_input]
n_input | length of the data to sign |
cancellable | A GCancellable which can be used to cancel the operation. |
callback | Called when the operation completes. |
user_data | A pointer to pass to the callback. |

### gck_session_sign_finish ()

    guchar *
    gck_session_sign_finish (GckSession *self,
                             GAsyncResult *result,
                             gsize *n_result,
                             GError **error);

Get the result of an signing operation.

#### Parameters

self | The session. |
result | The result object passed to the callback. |
n_result | A location to store the length of the result data. |
error | A location to place error information. |

#### Returns

the data that was signed, or `NULL` if an error occurred.

[transfer full][array length=n_result]

### gck_session_verify ()

    gboolean
    gck_session_verify (GckSession *self,
                        GckObject *key,
                        gulong mech_type,
                        const guchar *input,
                        gsize n_input,
                        const guchar *signature,
                        gsize n_signature,
                        GCancellable *cancellable,
                        GError **error);

Verify data in a mechanism specific manner. This call may block for an indefinite period.

#### Parameters

self | The session. |
key | The key to verify with. |
mech_type | The mechanism type to use for verifying. |
input | data to verify. | [array length=n_input]
n_input | length of the data to verify |
signature | the signature. | [array length=n_signature]
n_signature | length of the signature |
cancellable | Optional cancellation object, or `NULL` |
error | A location to place an error. |

#### Returns

`TRUE` if the data verified correctly, otherwise a failure or error occurred.

### gck_session_verify_full ()

    gboolean
    gck_session_verify_full (GckSession *self,
                             GckObject *key,
                             GckMechanism *mechanism,
                             const guchar *input,
                             gsize n_input,
                             const guchar *signature,
                             gsize n_signature,
                             GCancellable *cancellable,
                             GError **error);

Verify data in a mechanism specific manner. This call may block for an indefinite period.

#### Parameters

self | The session. |
key | The key to verify with. |
mechanism | The mechanism type and parameters to use for signing. |
input | data to verify. | [array length=n_input]
n_input | the length of the data to verify |
signature | the signature. | [array length=n_signature]
n_signature | length of the signature |
cancellable | A GCancellable which can be used to cancel the operation. |
error | A location to place an error. |

#### Returns

`TRUE` if the data verified correctly, otherwise a failure or error occurred.

### gck_session_verify_async ()

    void
    gck_session_verify_async (GckSession *self,
                              GckObject *key,
                              GckMechanism *mechanism,
                              const guchar *input,
                              gsize n_input,
                              const guchar *signature,
                              gsize n_signature,
                              GCancellable *cancellable,
                              GAsyncReadyCallback callback,
                              gpointer user_data);

Verify data in a mechanism specific manner. This call returns immediately and completes asynchronously.

#### Parameters

self | The session. |
key | The key to verify with. |
mechanism | The mechanism type and parameters to use for signing. |
input | data to verify. | [array length=n_input]
n_input | the length of the data to verify |
signature | the signature. | [array length=n_signature]
n_signature | the length of the signature |
cancellable | A GCancellable which can be used to cancel the operation. |
callback | Called when the operation completes. |
user_data | A pointer to pass to the callback. |

### gck_session_verify_finish ()

    gboolean
    gck_session_verify_finish (GckSession *self,
                               GAsyncResult *result,
                               GError **error);

Get the result of an verify operation.

#### Parameters

self | The session. |
result | The result object passed to the callback. |
error | A location to place error information. |

#### Returns

`TRUE` if the data verified correctly, otherwise a failure or error occurred.

### gck_session_derive_key ()

    GckObject *
    gck_session_derive_key (GckSession *self,
                            GckObject *base,
                            gulong mech_type,
                            GckAttributes *attrs,
                            GCancellable *cancellable,
                            GError **error);

Derive a key from another key. This call may block for an indefinite period.

If the `attrs` GckAttributes is floating, it is consumed.

#### Parameters

self | The session to use. |
base | The key to derive from. |
mech_type | The mechanism to use for derivation. |
attrs | Additional attributes for the derived key. |
cancellable | Optional cancellation object, or `NULL`. |
error | A location to return an error, or `NULL`. |

#### Returns

the new derived key or `NULL` if the operation failed.

[transfer full]

### gck_session_derive_key_async ()

    void
    gck_session_derive_key_async (GckSession *self,
                                  GckObject *base,
                                  GckMechanism *mechanism,
                                  GckAttributes *attrs,
                                  GCancellable *cancellable,
                                  GAsyncReadyCallback callback,
                                  gpointer user_data);

Derive a key from another key. This call will return immediately and complete asynchronously.

If the `attrs` GckAttributes is floating, it is consumed.

#### Parameters

self | The session to use. |
base | The key to derive from. |
mechanism | The mechanism to use for derivation. |
attrs | Additional attributes for the derived key. |
cancellable | Optional cancellation object or `NULL`. |
callback | Called when the operation completes. |
user_data | Data to pass to the callback. |

### gck_session_derive_key_finish ()

    GckObject *
    gck_session_derive_key_finish (GckSession *self,
                                   GAsyncResult *result,
                                   GError **error);

Get the result of a derive key operation.

#### Parameters

self | The session to use. |
result | The async result passed to the callback. |
error | A location to return an error. |

#### Returns

the new derived key or `NULL` if the operation failed.

[transfer full]

### gck_session_derive_key_full ()

    GckObject *
    gck_session_derive_key_full (GckSession *self,
                                 GckObject *base,
                                 GckMechanism *mechanism,
                                 GckAttributes *attrs,
                                 GCancellable *cancellable,
                                 GError **error);

Derive a key from another key. This call may block for an indefinite period.

If the `attrs` GckAttributes is floating, it is consumed.

#### Parameters

self | The session to use. |
base | The key to derive from. |
mechanism | The mechanism to use for derivation. |
attrs | Additional attributes for the derived key. |
cancellable | Optional cancellation object, or `NULL`. |
error | A location to return an error, or `NULL`. |

#### Returns

the new derived key or `NULL` if the operation failed.

[transfer full]

### gck_session_generate_key_pair ()

    gboolean
    gck_session_generate_key_pair (GckSession *self,
                                   gulong mech_type,
                                   GckAttributes *public_attrs,
                                   GckAttributes *private_attrs,
                                   GckObject **public_key,
                                   GckObject **private_key,
                                   GCancellable *cancellable,
                                   GError **error);

Generate a new key pair of public and private keys. This call may block for an indefinite period.

If the `public_attrs` and/or `private_attrs` GckAttributes is floating, it is consumed.

#### Parameters

self | The session to use. |
mech_type | The mechanism type to use for key generation. |
public_attrs | Additional attributes for the generated public key. |
private_attrs | Additional attributes for the generated private key. |
public_key | location to return the resulting public key. | [optional][out]
private_key | location to return the resulting private key. | [optional][out]
cancellable | Optional cancellation object, or `NULL`. |
error | A location to return an error, or `NULL`. |

#### Returns

`TRUE` if the operation succeeded.

### gck_session_generate_key_pair_async ()

    void
    gck_session_generate_key_pair_async (GckSession *self,
                                         GckMechanism *mechanism,
                                         GckAttributes *public_attrs,
                                         GckAttributes *private_attrs,
                                         GCancellable *cancellable,
                                         GAsyncReadyCallback callback,
                                         gpointer user_data);

Generate a new key pair of public and private keys. This call will return immediately and complete asynchronously.

If the `public_attrs` and/or `private_attrs` GckAttributes is floating, it is consumed.

#### Parameters

self | The session to use. |
mechanism | The mechanism to use for key generation. |
public_attrs | Additional attributes for the generated public key. |
private_attrs | Additional attributes for the generated private key. |
cancellable | Optional cancellation object or `NULL`. |
callback | Called when the operation completes. |
user_data | Data to pass to the callback. |

### gck_session_generate_key_pair_finish ()

    gboolean
    gck_session_generate_key_pair_finish (GckSession *self,
                                          GAsyncResult *result,
                                          GckObject **public_key,
                                          GckObject **private_key,
                                          GError **error);

Get the result of a generate key pair operation.

#### Parameters

self | The session to use. |
result | The async result passed to the callback. |
public_key | a location to return the resulting public key. | [optional][out]
private_key | a location to return the resulting private key. | [optional][out]
error | A location to return an error. |

#### Returns

`TRUE` if the operation succeeded.

### gck_session_generate_key_pair_full ()

    gboolean
    gck_session_generate_key_pair_full (GckSession *self,
                                        GckMechanism *mechanism,
                                        GckAttributes *public_attrs,
                                        GckAttributes *private_attrs,
                                        GckObject **public_key,
                                        GckObject **private_key,
                                        GCancellable *cancellable,
                                        GError **error);

Generate a new key pair of public and private keys. This call may block for an indefinite period.

If the `public_attrs` and/or `private_attrs` GckAttributes is floating, it is consumed.

#### Parameters

self | The session to use. |
mechanism | The mechanism to use for key generation. |
public_attrs | Additional attributes for the generated public key. |
private_attrs | Additional attributes for the generated private key. |
public_key | a location to return the resulting public key. | [optional][out]
private_key | a location to return the resulting private key. | [optional][out]
cancellable | Optional cancellation object, or `NULL`. |
error | A location to return an error, or `NULL`. |

#### Returns

`TRUE` if the operation succeeded.

### gck_session_get_options ()

    GckSessionOptions
    gck_session_get_options (GckSession *self);

Get the options this session was opened with.

#### Parameters

self | The session to get options from. |

#### Returns

The session options.

### gck_session_get_state ()

    gulong
    gck_session_get_state (GckSession *self);

Get the session state. The state is the various PKCS#11 CKS_XXX flags.

#### Parameters

self | the session |

#### Returns

the session state

### gck_session_init_pin ()

    gboolean
    gck_session_init_pin (GckSession *self,
                          const guchar *pin,
                          gsize n_pin,
                          GCancellable *cancellable,
                          GError **error);

Initialize the user's pin on this slot that this session is opened on. According to the PKCS#11 standards, the session must be logged in with the CKU_SO user type.

This call may block for an indefinite period.

#### Parameters

self | Initialize PIN for this session's slot. |
pin | the user's PIN, or `NULL` for protected authentication path. | [nullable][array length=n_pin]
n_pin | the length of the PIN |
cancellable | Optional cancellation object, or `NULL`. |
error | A location to return an error. |

#### Returns

Whether successful or not.

### gck_session_init_pin_async ()

    void
    gck_session_init_pin_async (GckSession *self,
                                const guchar *pin,
                                gsize n_pin,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Initialize the user's pin on this slot that this session is opened on. According to the PKCS#11 standards, the session must be logged in with the CKU_SO user type.

This call will return immediately and completes asynchronously.

#### Parameters

self | Initialize PIN for this session's slot. |
pin | the user's PIN, or `NULL` for protected authentication path. | [nullable][array length=n_pin]
n_pin | the length of the PIN |
cancellable | Optional cancellation object, or `NULL`. |
callback | Called when the operation completes. |
user_data | Data to pass to the callback. |

### gck_session_init_pin_finish ()

    gboolean
    gck_session_init_pin_finish (GckSession *self,
                                 GAsyncResult *result,
                                 GError **error);

Get the result of initializing a user's PIN.

#### Parameters

self | The session. |
result | The result passed to the callback. |
error | A location to return an error. |

#### Returns

Whether the operation was successful or not.

### gck_session_set_pin ()

    gboolean
    gck_session_set_pin (GckSession *self,
                         const guchar *old_pin,
                         gsize n_old_pin,
                         const guchar *new_pin,
                         gsize n_new_pin,
                         GCancellable *cancellable,
                         GError **error);

Change the user's pin on this slot that this session is opened on.

This call may block for an indefinite period.

#### Parameters

self | Change the PIN for this session's slot. |
old_pin | the user's old PIN, or `NULL` for protected authentication path. | [nullable][array length=n_old_pin]
n_old_pin | The length of the PIN. |
new_pin | the user's new PIN, or `NULL` for protected authentication path. | [nullable][array length=n_new_pin]
n_new_pin | The length of the PIN. |
cancellable | Optional cancellation object, or `NULL`. |
error | A location to return an error. |

#### Returns

Whether successful or not.

### gck_session_set_pin_async ()

    void
    gck_session_set_pin_async (GckSession *self,
                               const guchar *old_pin,
                               gsize n_old_pin,
                               const guchar *new_pin,
                               gsize n_new_pin,
                               GCancellable *cancellable,
                               GAsyncReadyCallback callback,
                               gpointer user_data);

Change the user's pin on this slot that this session is opened on.

This call will return immediately and completes asynchronously.

#### Parameters

self | Change the PIN for this session's slot. |
old_pin | the user's old PIN, or `NULL` for protected authentication path. | [nullable][array length=n_new_pin]
n_old_pin | the length of the old PIN |
new_pin | the user's new PIN, or `NULL` for protected authentication path. | [nullable][array length=n_new_pin]
n_new_pin | the length of the new PIN |
cancellable | Optional cancellation object, or `NULL`. |
callback | Called when the operation completes. |
user_data | Data to pass to the callback. |

### gck_session_set_pin_finish ()

    gboolean
    gck_session_set_pin_finish (GckSession *self,
                                GAsyncResult *result,
                                GError **error);

Get the result of changing a user's PIN.

#### Parameters

self | The session. |
result | The result passed to the callback. |
error | A location to return an error. |

#### Returns

Whether the operation was successful or not.

### gck_session_unwrap_key ()

    GckObject *
    gck_session_unwrap_key (GckSession *self,
                            GckObject *wrapper,
                            gulong mech_type,
                            const guchar *input,
                            gsize n_input,
                            GckAttributes *attrs,
                            GCancellable *cancellable,
                            GError **error);

Unwrap a key from a byte stream. This call may block for an indefinite period.

If the `attrs` GckAttributes is floating, it is consumed.

#### Parameters

self | The session to use. |
wrapper | The key to use for unwrapping. |
mech_type | The mechanism to use for unwrapping. |
input | the wrapped data as a byte stream. | [array length=n_input]
n_input | The length of the wrapped data. |
attrs | Additional attributes for the unwrapped key. |
cancellable | Optional cancellation object, or `NULL`. |
error | A location to return an error, or `NULL`. |

#### Returns

the new unwrapped key or `NULL` if the operation failed.

[transfer full]

### gck_session_unwrap_key_async ()

    void
    gck_session_unwrap_key_async (GckSession *self,
                                  GckObject *wrapper,
                                  GckMechanism *mechanism,
                                  const guchar *input,
                                  gsize n_input,
                                  GckAttributes *attrs,
                                  GCancellable *cancellable,
                                  GAsyncReadyCallback callback,
                                  gpointer user_data);

Unwrap a key from a byte stream. This call will return immediately and complete asynchronously.

If the `attrs` GckAttributes is floating, it is consumed.

#### Parameters

self | The session to use. |
wrapper | The key to use for unwrapping. |
mechanism | The mechanism to use for unwrapping. |
input | the wrapped data as a byte stream. | [array length=n_input]
n_input | The length of the wrapped data. |
attrs | Additional attributes for the unwrapped key. |
cancellable | Optional cancellation object or `NULL`. |
callback | Called when the operation completes. |
user_data | Data to pass to the callback. |

### gck_session_unwrap_key_finish ()

    GckObject *
    gck_session_unwrap_key_finish (GckSession *self,
                                   GAsyncResult *result,
                                   GError **error);

Get the result of a unwrap key operation.

#### Parameters

self | The session to use. |
result | The async result passed to the callback. |
error | A location to return an error. |

#### Returns

the new unwrapped key or `NULL` if the operation failed.

[transfer full]

### gck_session_unwrap_key_full ()

    GckObject *
    gck_session_unwrap_key_full (GckSession *self,
                                 GckObject *wrapper,
                                 GckMechanism *mechanism,
                                 const guchar *input,
                                 gsize n_input,
                                 GckAttributes *attrs,
                                 GCancellable *cancellable,
                                 GError **error);

Unwrap a key from a byte stream. This call may block for an indefinite period.

If the `attrs` GckAttributes is floating, it is consumed.

#### Parameters

self | The session to use. |
wrapper | The key to use for unwrapping. |
mechanism | The mechanism to use for unwrapping. |
input | the wrapped data as a byte stream. | [array length=n_input]
n_input | The length of the wrapped data. |
attrs | Additional attributes for the unwrapped key. |
cancellable | Optional cancellation object, or `NULL`. |
error | A location to return an error, or `NULL`. |

#### Returns

the new unwrapped key or `NULL` if the operation failed.

[transfer full]

### gck_session_wrap_key ()

    guchar *
    gck_session_wrap_key (GckSession *self,
                          GckObject *wrapper,
                          gulong mech_type,
                          GckObject *wrapped,
                          gsize *n_result,
                          GCancellable *cancellable,
                          GError **error);

Wrap a key into a byte stream. This call may block for an indefinite period.

#### Parameters

self | The session to use. |
wrapper | The key to use for wrapping. |
mech_type | The mechanism type to use for wrapping. |
wrapped | The key to wrap. |
n_result | A location in which to return the length of the wrapped data. |
cancellable | A GCancellable or `NULL` |
error | A location to return an error, or `NULL`. |

#### Returns

the wrapped data or `NULL` if the operation failed.

[transfer full][array length=n_result]

### gck_session_wrap_key_async ()

    void
    gck_session_wrap_key_async (GckSession *self,
                                GckObject *wrapper,
                                GckMechanism *mechanism,
                                GckObject *wrapped,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Wrap a key into a byte stream. This call will return immediately and complete asynchronously.

#### Parameters

self | The session to use. |
wrapper | The key to use for wrapping. |
mechanism | The mechanism to use for wrapping. |
wrapped | The key to wrap. |
cancellable | Optional cancellation object or `NULL`. |
callback | Called when the operation completes. |
user_data | Data to pass to the callback. |

### gck_session_wrap_key_finish ()

    guchar *
    gck_session_wrap_key_finish (GckSession *self,
                                 GAsyncResult *result,
                                 gsize *n_result,
                                 GError **error);

Get the result of a wrap key operation.

#### Parameters

self | The session to use. |
result | The async result passed to the callback. |
n_result | A location in which to return the length of the wrapped data. |
error | A location to return an error. |

#### Returns

the wrapped data or `NULL` if the operation failed.

[transfer full][array length=n_result]

### gck_session_wrap_key_full ()

    guchar *
    gck_session_wrap_key_full (GckSession *self,
                               GckObject *wrapper,
                               GckMechanism *mechanism,
                               GckObject *wrapped,
                               gsize *n_result,
                               GCancellable *cancellable,
                               GError **error);

Wrap a key into a byte stream. This call may block for an indefinite period.

#### Parameters

self | The session to use. |
wrapper | The key to use for wrapping. |
mechanism | The mechanism to use for wrapping. |
wrapped | The key to wrap. |
n_result | A location in which to return the length of the wrapped data. |
cancellable | Optional cancellation object, or `NULL`. |
error | A location to return an error, or `NULL`. |

#### Returns

the wrapped data or `NULL` if the operation failed.

[transfer full][array length=n_result]

### gck_session_info_copy ()

    GckSessionInfo *
    gck_session_info_copy (GckSessionInfo *session_info);

Make a new copy of a session info structure.

#### Parameters

session_info | a session info structure |

#### Returns

a new copy of the session info.

[transfer full]

### gck_session_info_free ()

    void
    gck_session_info_free (GckSessionInfo *session_info);

Free the GckSessionInfo structure and all associated memory.

#### Parameters

session_info | Session info to free. |

## Types and Values

### struct GckSession

    struct GckSession;

Represents an open PKCS11 session.

### struct GckSessionInfo

    struct GckSessionInfo {
    	gulong slot_id;
    	gulong state;
    	gulong flags;
    	gulong device_error;
    };

Information about the session. This is analogous to a CK_SESSION_INFO structure.

When done with this structure, release it using `gck_session_info_free()`.

#### Members

gulong `slot_id`; | The handle of the PKCS11 slot that this session is opened on. |
gulong `state`; | The user login state of the session. |
gulong `flags`; | Various PKCS11 flags. |
gulong `device_error`; | The last device error that occurred from an operation on this session. |

### struct GckMechanism

    struct GckMechanism {
    	gulong type;
    	gconstpointer parameter;
    	gulong n_parameter;
    };

Represents a mechanism used with crypto operations.

#### Members

gulong `type`; | The mechanism type |
gconstpointer `parameter`; | Mechanism specific data. |
gulong `n_parameter`; | Length of mechanism specific data. |

## Property Details

### The `“app-data”` property

      “app-data”                 gpointer

Raw PKCS#11 application data used to open the PKCS#11 session.

Owner: GckSession

Flags: Write / Construct Only

### The `“handle”` property

      “handle”                   gulong

The raw CK_SESSION_HANDLE handle of this session.

Owner: GckSession

Flags: Read / Write / Construct Only

### The `“interaction”` property

      “interaction”              GTlsInteraction *

Interaction object used to ask the user for pins when opening sessions. Used if the session_options of the enumerator have `GCK_SESSION_LOGIN_USER`

Owner: GckSession

Flags: Read / Write

### The `“module”` property

      “module”                   GckModule *

The GckModule that this session is opened on.

Owner: GckSession

Flags: Read

### The `“opening-flags”` property

      “opening-flags”            gulong

Raw PKCS#11 flags used to open the PKCS#11 session.

Owner: GckSession

Flags: Write / Construct Only

### The `“options”` property

      “options”                  GckSessionOptions

The options this session was opened with.

Owner: GckSession

Flags: Read / Write / Construct Only

### The `“slot”` property

      “slot”                     GckSlot *

The GckSlot this session is opened on.

Owner: GckSession

Flags: Read / Write / Construct Only

## Signal Details

### The `“discard-handle”` signal

    gboolean
    user_function (GckSession *session,
                   gulong      handle,
                   gpointer    user_data)

When a GckSession is being disposed of it emits this signal to allow a session pool to pick up the handle and keep it around.

If no signal handler claims the handle, then it is closed.

#### Parameters

session | The session. |
handle | The handle being discarded. |
user_data | user data set when the signal handler was connected. |

#### Returns

Whether or not this handle was claimed.

Flags: Run Last