manpagez: man pages & more
html files: gck
Home | html | info | man

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);

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.

[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);

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.

[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

© manpagez.com 2000-2024
Individual documents may contain additional copyright information.