| GCK Reference Manual | ||||
|---|---|---|---|---|
| Top | Description | Object Hierarchy | Properties | Signals | ||||
GckSession; GckSession* gck_session_from_handle (GckSlot *slot,CK_SESSION_HANDLE handle,guint options); GckModule* gck_session_get_module (GckSession *self); GckSlot* gck_session_get_slot (GckSession *self); CK_SESSION_HANDLE gck_session_get_handle (GckSession *self); GckSessionInfo* gck_session_get_info (GckSession *self); gboolean gck_session_login (GckSession *self,gulong user_type,const guchar *pin,gsize n_pin,GCancellable *cancellable,GError **err); void gck_session_login_async (GckSession *self,gulong user_type,const guchar *pin,gsize n_pin,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data); gboolean gck_session_login_finish (GckSession *self,GAsyncResult *result,GError **err); gboolean gck_session_logout (GckSession *self,GCancellable *cancellable,GError **err); void gck_session_logout_async (GckSession *self,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data); gboolean gck_session_logout_finish (GckSession *self,GAsyncResult *result,GError **err); GckObject* gck_session_create_object (GckSession *self,GckAttributes *attrs,GCancellable *cancellable,GError **err); void gck_session_create_object_async (GckSession *self,GckAttributes *attrs,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data); GckObject* gck_session_create_object_finish (GckSession *self,GAsyncResult *result,GError **err); GList* gck_session_find_objects (GckSession *self,GckAttributes *attrs,GCancellable *cancellable,GError **err); void gck_session_find_objects_async (GckSession *self,GckAttributes *attrs,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data); GList* gck_session_find_objects_finish (GckSession *self,GAsyncResult *result,GError **err); guchar* gck_session_encrypt (GckSession *self,GckObject *key,gulong mech_type,const guchar *input,gsize n_input,gsize *n_result,GCancellable *cancellable,GError **err); guchar* gck_session_encrypt_full (GckSession *self,GckObject *key,GckMechanism *mechanism,const guchar *input,gsize n_input,gsize *n_result,GCancellable *cancellable,GError **err); void gck_session_encrypt_async (GckSession *self,GckObject *key,GckMechanism *mechanism,const guchar *input,gsize n_input,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data); guchar* gck_session_encrypt_finish (GckSession *self,GAsyncResult *result,gsize *n_result,GError **err); guchar* gck_session_decrypt (GckSession *self,GckObject *key,gulong mech_type,const guchar *input,gsize n_input,gsize *n_result,GCancellable *cancellable,GError **err); guchar* gck_session_decrypt_full (GckSession *self,GckObject *key,GckMechanism *mechanism,const guchar *input,gsize n_input,gsize *n_result,GCancellable *cancellable,GError **err); void gck_session_decrypt_async (GckSession *self,GckObject *key,GckMechanism *mechanism,const guchar *input,gsize n_input,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data); guchar* gck_session_decrypt_finish (GckSession *self,GAsyncResult *result,gsize *n_result,GError **err); guchar* gck_session_sign (GckSession *self,GckObject *key,gulong mech_type,const guchar *input,gsize n_input,gsize *n_result,GCancellable *cancellable,GError **err); guchar* gck_session_sign_full (GckSession *self,GckObject *key,GckMechanism *mechanism,const guchar *input,gsize n_input,gsize *n_result,GCancellable *cancellable,GError **err); void gck_session_sign_async (GckSession *self,GckObject *key,GckMechanism *mechanism,const guchar *input,gsize n_input,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data); guchar* gck_session_sign_finish (GckSession *self,GAsyncResult *result,gsize *n_result,GError **err); 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 **err); 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 **err); 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); gboolean gck_session_verify_finish (GckSession *self,GAsyncResult *result,GError **err); GckSessionInfo; void gck_session_info_free (GckSessionInfo *session_info); GckMechanism;
"handle" gulong : Read / Write / Construct Only "module" GckModule* : Read / Write / Construct Only "options" guint : Read / Write / Construct Only "slot" GckSlot* : Read / Write / Construct Only
Before performing any PKCS11 operations, a session must be opened. This is analogous to an open database handle, or a file handle.
GckSession* gck_session_from_handle (GckSlot *slot,CK_SESSION_HANDLE handle,guint options);
Initialize a GckSession object from a raw PKCS11 session handle.
Usually one would use the gck_slot_open_session() function to
create a session.
|
The slot which the session belongs to. |
|
The raw PKCS11 handle of the session. |
|
Session options. Those which are used during opening a session have no effect. |
Returns : |
The new GckSession object. |
GckModule* gck_session_get_module (GckSession *self);
Get the PKCS11 module to which this session belongs.
|
The session object. |
Returns : |
The module, which should be unreffed after use. |
GckSlot* gck_session_get_slot (GckSession *self);
Get the PKCS11 slot to which this session belongs.
|
The session object. |
Returns : |
The slot, which should be unreffed after use. |
CK_SESSION_HANDLE gck_session_get_handle (GckSession *self);
Get the raw PKCS11 session handle from a GckSession object.
|
The session object. |
Returns : |
The raw session handle. |
GckSessionInfo* gck_session_get_info (GckSession *self);
Get information about the session.
|
The session object. |
Returns : |
The session info. Use the gck_session_info_free() to release
when done.
|
gboolean gck_session_login (GckSession *self,gulong user_type,const guchar *pin,gsize n_pin,GCancellable *cancellable,GError **err);
Login the user on the session. This call may block for an indefinite period.
|
Log in to this session. |
|
The type of login user. |
|
The user's PIN, or NULL for protected authentication path. |
|
The length of the PIN. |
|
Optional cancellation object, or NULL. |
|
A location to return an error. |
Returns : |
Whether successful or not. |
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.
|
Log in to this session. |
|
The type of login user. |
|
The user's PIN, or NULL for protected authentication path. |
|
The length of the PIN. |
|
Optional cancellation object, or NULL. |
|
Called when the operation completes. |
|
Data to pass to the callback. |
gboolean gck_session_login_finish (GckSession *self,GAsyncResult *result,GError **err);
Get the result of a login operation.
|
The session logged into. |
|
The result passed to the callback. |
|
A location to return an error. |
Returns : |
Whether the operation was successful or not. |
gboolean gck_session_logout (GckSession *self,GCancellable *cancellable,GError **err);
Log out of the session. This call may block for an indefinite period.
|
Logout of this session. |
|
Optional cancellation object, or NULL. |
|
A location to return an error. |
Returns : |
Whether the logout was successful or not. |
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.
|
Logout of this session. |
|
Optional cancellation object, or NULL. |
|
Called when the operation completes. |
|
Data to pass to the callback. |
gboolean gck_session_logout_finish (GckSession *self,GAsyncResult *result,GError **err);
Get the result of logging out of a session.
|
Logout of this session. |
|
The result passed to the callback. |
|
A location to return an error. |
Returns : |
Whether the logout was successful or not. |
GckObject* gck_session_create_object (GckSession *self,GckAttributes *attrs,GCancellable *cancellable,GError **err);
Create a new PKCS11 object. This call may block for an indefinite period.
|
The session to create the object on. |
|
The attributes to create the object with. |
|
Optional cancellation object, or NULL. |
|
A location to return an error, or NULL. |
Returns : |
The newly created object or NULL if an error occurred. |
void gck_session_create_object_async (GckSession *self,GckAttributes *attrs,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data);
Create a new PKCS11 object. This call will return immediately and complete asynchronously.
|
The session to create the object on. |
|
The attributes to create the object with. |
|
Optional cancellation object or NULL. |
|
Called when the operation completes. |
|
Data to pass to the callback. |
GckObject* gck_session_create_object_finish (GckSession *self,GAsyncResult *result,GError **err);
Get the result of creating a new PKCS11 object.
|
The session to create the object on. |
|
The result passed to the callback. |
|
A location to return an error, or NULL. |
Returns : |
The newly created object or NULL if an error occurred. |
GList* gck_session_find_objects (GckSession *self,GckAttributes *attrs,GCancellable *cancellable,GError **err);
Find the objects matching the passed attributes. This call may block for an indefinite period.
|
The session to find objects on. |
|
The attributes to match. |
|
Optional cancellation object or NULL. |
|
A location to return an error or NULL. |
Returns : |
A list of the matching objects, which may be empty. |
void gck_session_find_objects_async (GckSession *self,GckAttributes *attrs,GCancellable *cancellable,GAsyncReadyCallback callback,gpointer user_data);
Find the objects matching the passed attributes. This call will return immediately and complete asynchronously.
|
The session to find objects on. |
|
The attributes to match. |
|
Optional cancellation object or NULL. |
|
Called when the operation completes. |
|
Data to pass to the callback. |
GList* gck_session_find_objects_finish (GckSession *self,GAsyncResult *result,GError **err);
Get the result of a find operation.
|
The session to find objects on. |
|
The attributes to match. |
|
A location to return an error. |
Returns : |
A list of the matching objects, which may be empty. |
guchar* gck_session_encrypt (GckSession *self,GckObject *key,gulong mech_type,const guchar *input,gsize n_input,gsize *n_result,GCancellable *cancellable,GError **err);
Encrypt data in a mechanism specific manner. This call may block for an indefinite period.
|
The session. |
|
The key to encrypt with. |
|
The mechanism type to use for encryption. |
|
The data to encrypt. |
|
The length of the data to encrypt. |
|
A location to store the length of the result data. |
|
|
|
A location to place error information. |
Returns : |
The data that was encrypted, or NULL if an error occured. |
guchar* gck_session_encrypt_full (GckSession *self,GckObject *key,GckMechanism *mechanism,const guchar *input,gsize n_input,gsize *n_result,GCancellable *cancellable,GError **err);
Encrypt data in a mechanism specific manner. This call may block for an indefinite period.
|
The session. |
|
The key to encrypt with. |
|
The mechanism type and parameters to use for encryption. |
|
The data to encrypt. |
|
The length of the data to encrypt. |
|
A location to store the length of the result data. |
|
A GCancellable which can be used to cancel the operation. |
|
A location to place error information. |
Returns : |
The data that was encrypted, or NULL if an error occured. |
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.
|
The session. |
|
The key to encrypt with. |
|
The mechanism type and parameters to use for encryption. |
|
The data to encrypt. |
|
The length of the data to encrypt. |
|
A GCancellable which can be used to cancel the operation. |
|
Called when the operation completes. |
|
A pointer to pass to the callback. |
guchar* gck_session_encrypt_finish (GckSession *self,GAsyncResult *result,gsize *n_result,GError **err);
Get the result of an encryption operation.
|
The session. |
|
The result object passed to the callback. |
|
A location to store the length of the result data. |
|
A location to place error information. |
Returns : |
The data that was encrypted, or NULL if an error occurred. |
guchar* gck_session_decrypt (GckSession *self,GckObject *key,gulong mech_type,const guchar *input,gsize n_input,gsize *n_result,GCancellable *cancellable,GError **err);
Decrypt data in a mechanism specific manner. This call may block for an indefinite period.
|
The session. |
|
The key to decrypt with. |
|
The mechanism type to use for decryption. |
|
The data to decrypt. |
|
The length of the data to decrypt. |
|
A location to store the length of the result data. |
|
|
|
A location to place an error. |
Returns : |
The data that was decrypted, or NULL if an error occured. |
guchar* gck_session_decrypt_full (GckSession *self,GckObject *key,GckMechanism *mechanism,const guchar *input,gsize n_input,gsize *n_result,GCancellable *cancellable,GError **err);
Decrypt data in a mechanism specific manner. This call may block for an indefinite period.
|
The session. |
|
The key to decrypt with. |
|
The mechanism type and parameters to use for decryption. |
|
The data to decrypt. |
|
The length of the data to decrypt. |
|
A location to store the length of the result data. |
|
A GCancellable which can be used to cancel the operation. |
|
A location to place error information. |
Returns : |
The data that was decrypted, or NULL if an error occured. |
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.
|
The session. |
|
The key to decrypt with. |
|
The mechanism type and parameters to use for decryption. |
|
The data to decrypt. |
|
The length of the data to decrypt. |
|
A GCancellable which can be used to cancel the operation. |
|
Called when the operation completes. |
|
A pointer to pass to the callback. |
guchar* gck_session_decrypt_finish (GckSession *self,GAsyncResult *result,gsize *n_result,GError **err);
Get the result of an decryption operation.
|
The session. |
|
The result object passed to the callback. |
|
A location to store the length of the result data. |
|
A location to place error information. |
Returns : |
The data that was decrypted, or NULL if an error occurred. |
guchar* gck_session_sign (GckSession *self,GckObject *key,gulong mech_type,const guchar *input,gsize n_input,gsize *n_result,GCancellable *cancellable,GError **err);
Sign data in a mechanism specific manner. This call may block for an indefinite period.
|
The session. |
|
The key to sign with. |
|
The mechanism type to use for signing. |
|
The data to sign. |
|
The length of the data to sign. |
|
A location to store the length of the result data. |
|
|
|
A location to place an error. |
Returns : |
The data that was signed, or NULL if an error occured. |
guchar* gck_session_sign_full (GckSession *self,GckObject *key,GckMechanism *mechanism,const guchar *input,gsize n_input,gsize *n_result,GCancellable *cancellable,GError **err);
Sign data in a mechanism specific manner. This call may block for an indefinite period.
|
The session. |
|
The key to sign with. |
|
The mechanism type and parameters to use for signing. |
|
The data to sign. |
|
The length of the data to sign. |
|
A location to store the length of the result data. |
|
A GCancellable which can be used to cancel the operation. |
|
A location to place error information. |
Returns : |
The data that was signed, or NULL if an error occured. |
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.
|
The session. |
|
The key to sign with. |
|
The mechanism type and parameters to use for signing. |
|
The data to sign. |
|
The length of the data to sign. |
|
A GCancellable which can be used to cancel the operation. |
|
Called when the operation completes. |
|
A pointer to pass to the callback. |
guchar* gck_session_sign_finish (GckSession *self,GAsyncResult *result,gsize *n_result,GError **err);
Get the result of an signing operation.
|
The session. |
|
The result object passed to the callback. |
|
A location to store the length of the result data. |
|
A location to place error information. |
Returns : |
The data that was signed, or NULL if an error occurred. |
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 **err);
Verify data in a mechanism specific manner. This call may block for an indefinite period.
|
The session. |
|
The key to verify with. |
|
The mechanism type to use for verifying. |
|
The data to verify. |
|
The length of the data to verify. |
|
The signature. |
|
The length of the signature. |
|
|
|
A location to place an error. |
Returns : |
TRUE if the data verified correctly, otherwise a failure or error occurred. |
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 **err);
Verify data in a mechanism specific manner. This call may block for an indefinite period.
|
The session. |
|
The key to verify with. |
|
The mechanism type and parameters to use for signing. |
|
The data to verify. |
|
The length of the data to verify. |
|
The signature. |
|
The length of the signature. |
|
A GCancellable which can be used to cancel the operation. |
|
A location to place an error. |
Returns : |
TRUE if the data verified correctly, otherwise a failure or error occurred. |
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.
|
The session. |
|
The key to verify with. |
|
The mechanism type and parameters to use for signing. |
|
The data to verify. |
|
The length of the data to verify. |
|
The signature. |
|
The length of the signature. |
|
A GCancellable which can be used to cancel the operation. |
|
Called when the operation completes. |
|
A pointer to pass to the callback. |
gboolean gck_session_verify_finish (GckSession *self,GAsyncResult *result,GError **err);
Get the result of an verify operation.
|
The session. |
|
The result object passed to the callback. |
|
A location to place error information. |
Returns : |
TRUE if the data verified correctly, otherwise a failure or error occurred. |
typedef struct {
gulong slot_id;
gulong state;
gulong flags;
gulong device_error;
} GckSessionInfo;
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().
void gck_session_info_free (GckSessionInfo *session_info);
Free the GckSessionInfo structure and all associated memory.
|
Session info to free. |
typedef struct {
gulong type;
gconstpointer parameter;
gulong n_parameter;
} GckMechanism;
Represents a mechanism used with crypto operations.
gulong |
The mechanism type |
gconstpointer |
Mechanism specific data. |
gulong |
Length of mechanism specific data. |
"handle" property"handle" gulong : Read / Write / Construct Only
The raw CK_SESSION_HANDLE handle of this session.
"module" property"module" GckModule* : Read / Write / Construct Only
The GckModule that this session is opened on.
"options" property"options" guint : Read / Write / Construct Only
The options this session was opened with.
Default value: 0
"slot" property"slot" GckSlot* : Read / Write / Construct Only
The GckSlot this session is opened on.
"discard-handle" signalgboolean user_function (GckSession *session, gulong handle, gpointer user_data) : Run Last
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. This is used by
gck_module_set_pool_sessions() to implement the module session pool.
|
The session. |
|
The handle being discarded. |
|
user data set when the signal handler was connected. |
Returns : |
Whether or not this handle was claimed. |