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

gck_session_login ()

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

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

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

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

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

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.	[allow-none][out]
private_key	location to return the resulting private key.	[allow-none][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.	[allow-none][out]
private_key	a location to return the resulting private key.	[allow-none][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.	[allow-none][out]
private_key	a location to return the resulting private key.	[allow-none][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.	[allow-none][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.	[allow-none][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.	[allow-none][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.	[allow-none][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.	[allow-none][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.	[allow-none][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.

Flags: Write / Construct Only

The `“handle”` property

  “handle”                   gulong

The raw CK_SESSION_HANDLE handle of this session.

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

Flags: Read / Write

The `“module”` property

  “module”                   GckModule *

The GckModule that this session is opened on.

Flags: Read

The `“opening-flags”` property

  “opening-flags”            gulong

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

Flags: Write / Construct Only

The `“options”` property

  “options”                  GckSessionOptions

The options this session was opened with.

Flags: Read / Write / Construct Only

The `“slot”` property

  “slot”                     GckSlot *

The GckSlot this session is opened on.

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