GckObject: Gck Library Reference Manual

GckObject

GckObject — Represents a PKCS11 object such as a key or certificate.

Functions

GckObject *	gck_object_from_handle ()
GList *	gck_objects_from_handle_array ()
gboolean	gck_object_equal ()
guint	gck_object_hash ()
GckModule *	gck_object_get_module ()
gulong	gck_object_get_handle ()
GckSession *	gck_object_get_session ()
gboolean	gck_object_destroy ()
void	gck_object_destroy_async ()
gboolean	gck_object_destroy_finish ()
gboolean	gck_object_set ()
void	gck_object_set_async ()
gboolean	gck_object_set_finish ()
GckAttributes *	gck_object_get ()
void	gck_object_get_async ()
GckAttributes *	gck_object_get_finish ()
guchar *	gck_object_get_data ()
guchar *	gck_object_get_data_full ()
void	gck_object_get_data_async ()
guchar *	gck_object_get_data_finish ()
GckAttributes *	gck_object_get_full ()
GckAttributes *	gck_object_get_template ()
void	gck_object_get_template_async ()
GckAttributes *	gck_object_get_template_finish ()
gboolean	gck_object_set_template ()
void	gck_object_set_template_async ()
gboolean	gck_object_set_template_finish ()

Properties

gulong	handle	Read / Write / Construct Only
GckModule *	module	Read / Write / Construct Only
GckSession *	session	Read / Write / Construct Only

Types and Values

struct	GckObject
struct	GckObjectClass

Object Hierarchy

    GObject
    ╰── GckObject

Known Derived Interfaces

GckObject is required by GckObjectCache.

Description

A GckObject holds a handle to a PKCS11 object such as a key or certificate. Token objects are stored on the token persistently. Others are transient and are called session objects.

Functions

gck_object_from_handle ()

GckObject *
gck_object_from_handle (GckSession *session,
                        gulong object_handle);

Initialize a GckObject from a raw PKCS#11 handle. Normally you would use gck_session_create_object() or gck_session_find_objects() to access objects.

Parameters

session	The session through which this object is accessed or created.
object_handle	The raw CK_OBJECT_HANDLE of the object.

Returns

The new GckObject. You should use g_object_unref() when done with this object.

[transfer full]

gck_objects_from_handle_array ()

GList *
gck_objects_from_handle_array (GckSession *session,
                               gulong *object_handles,
                               gulong n_object_handles);

Initialize a list of GckObject from raw PKCS#11 handles. The handles argument must contain contiguous CK_OBJECT_HANDLE handles in an array.

Parameters

session	The session for these objects
object_handles	The raw object handles.	[array length=n_object_handles]
n_object_handles	The number of raw object handles.

Returns

The list of GckObject objects. You should use gck_list_unref_free() when done with this list.

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

gck_object_equal ()

gboolean
gck_object_equal (gconstpointer object1,
                  gconstpointer object2);

Checks equality of two objects. Two GckObject objects can point to the same underlying PKCS#11 object.

Parameters

object1	a pointer to the first GckObject.	[type Gck.Object]
object2	a pointer to the second GckObject.	[type Gck.Object]

Returns

TRUE if object1 and object2 are equal. FALSE if either is not a GckObject.

gck_object_hash ()

guint
gck_object_hash (gconstpointer object);

Create a hash value for the GckObject.

This function is intended for easily hashing a GckObject to add to a GHashTable or similar data structure.

Parameters

object

a pointer to a GckObject.

[type Gck.Object]

Returns

An integer that can be used as a hash value, or 0 if invalid.

gck_object_get_module ()

GckModule *
gck_object_get_module (GckObject *self);

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

Parameters

self

The object.

Returns

the module, which should be unreffed after use.

[transfer full]

gck_object_get_handle ()

gulong
gck_object_get_handle (GckObject *self);

Get the raw PKCS#11 handle of a GckObject.

Parameters

self

The object.

Returns

the raw CK_OBJECT_HANDLE object handle

gck_object_get_session ()

GckSession *
gck_object_get_session (GckObject *self);

Get the PKCS#11 session assigned to make calls on when operating on this object.

This will only return a session if it was set explitly on this object. By default an object will open and close sessions appropriate for its calls.

Parameters

self

The object

Returns

the assigned session, which must be unreffed after use.

[transfer full]

gck_object_destroy ()

gboolean
gck_object_destroy (GckObject *self,
                    GCancellable *cancellable,
                    GError **error);

Destroy a PKCS#11 object, deleting it from storage or the session. This call may block for an indefinite period.

Parameters

self	The object to destroy.
cancellable	Optional cancellable object, or NULL to ignore.
error	A location to return an error.

Returns

Whether the call was successful or not.

gck_object_destroy_async ()

void
gck_object_destroy_async (GckObject *self,
                          GCancellable *cancellable,
                          GAsyncReadyCallback callback,
                          gpointer user_data);

Destroy a PKCS#11 object, deleting it from storage or the session. This call will return immediately and complete asynchronously.

Parameters

self	The object to destroy.
cancellable	Optional cancellable object, or NULL to ignore.
callback	Callback which is called when operation completes.
user_data	Data to pass to the callback.

gck_object_destroy_finish ()

gboolean
gck_object_destroy_finish (GckObject *self,
                           GAsyncResult *result,
                           GError **error);

Get the status of the operation to destroy a PKCS#11 object, begun with gck_object_destroy_async().

Parameters

self	The object being destroyed.
result	The result of the destory operation passed to the callback.
error	A location to store an error.

Returns

Whether the object was destroyed successfully or not.

gck_object_set ()

gboolean
gck_object_set (GckObject *self,
                GckAttributes *attrs,
                GCancellable *cancellable,
                GError **error);

Set PKCS#11 attributes on an object. This call may block for an indefinite period.

If the attrs GckAttributes is floating, it is consumed.

Parameters

self	The object to set attributes on.
attrs	The attributes to set on the object.
cancellable	Optional cancellable object, or NULL to ignore.
error	A location to return an error.

Returns

Whether the call was successful or not.

gck_object_set_async ()

void
gck_object_set_async (GckObject *self,
                      GckAttributes *attrs,
                      GCancellable *cancellable,
                      GAsyncReadyCallback callback,
                      gpointer user_data);

Set PKCS#11 attributes on an object. This call will return immediately and completes asynchronously.

If the attrs GckAttributes is floating, it is consumed.

Parameters

self	The object to set attributes on.
attrs	The attributes to set on the object.
cancellable	Optional cancellable object, or NULL to ignore.
callback	Callback which is called when operation completes.
user_data	Data to pass to the callback.

gck_object_set_finish ()

gboolean
gck_object_set_finish (GckObject *self,
                       GAsyncResult *result,
                       GError **error);

Get the status of the operation to set attributes on a PKCS#11 object, begun with gck_object_set_async().

Parameters

self	The object to set attributes on.
result	The result of the destory operation passed to the callback.
error	A location to store an error.

Returns

Whether the attributes were successfully set on the object or not.

gck_object_get ()

GckAttributes *
gck_object_get (GckObject *self,
                GCancellable *cancellable,
                GError **error,
                ...);

Get the specified attributes from the object. This call may block for an indefinite period.

Parameters

self	The object to get attributes from.
cancellable	A GCancellable or `NULL`
error	A location to store an error.
...	The attribute types to get.

Returns

the resulting PKCS#11 attributes, or NULL if an error occurred; the result must be unreffed when you're finished with it.

[transfer full]

gck_object_get_async ()

void
gck_object_get_async (GckObject *self,
                      const gulong *attr_types,
                      guint n_attr_types,
                      GCancellable *cancellable,
                      GAsyncReadyCallback callback,
                      gpointer user_data);

Get the specified attributes from the object. The attributes will be cleared of their current values, and new attributes will be stored. The attributes should not be accessed in any way except for referencing and unreferencing them until gck_object_get_finish() is called.

This call returns immediately and completes asynchronously.

Parameters

self	The object to get attributes from.
attr_types	the types of the attributes to get.	[array length=n_attr_types]
n_attr_types	the number of attr_types
cancellable	optional cancellation object, or `NULL`
callback	A callback which is called when the operation completes.
user_data	Data to be passed to the callback.

gck_object_get_finish ()

GckAttributes *
gck_object_get_finish (GckObject *self,
                       GAsyncResult *result,
                       GError **error);

Get the result of a get operation and return specified attributes from the object.

No extra references are added to the returned attributes pointer.

Parameters

self	The object to get attributes from.
result	The result passed to the callback.
error	A location to store an error.

Returns

The filled in attributes structure if successful or NULL if not successful.

gck_object_get_data ()

guchar *
gck_object_get_data (GckObject *self,
                     gulong attr_type,
                     GCancellable *cancellable,
                     gsize *n_data,
                     GError **error);

Get the data for the specified attribute from the object. For convenience the returned data has a null terminator.

This call may block for an indefinite period.

Parameters

self	The object to get attribute data from.
attr_type	The attribute to get data for.
cancellable	A GCancellable or `NULL`
n_data	The length of the resulting data.
error	A location to store an error.

Returns

the resulting PKCS#11 attribute data, or NULL if an error occurred.

[transfer full][array length=n_data]

gck_object_get_data_full ()

guchar *
gck_object_get_data_full (GckObject *self,
                          gulong attr_type,
                          GckAllocator allocator,
                          GCancellable *cancellable,
                          gsize *n_data,
                          GError **error);

Get the data for the specified attribute from the object. For convenience the returned data has an extra null terminator, not included in the returned length.

This call may block for an indefinite period.

[skip]

Parameters

self	The object to get attribute data from.
attr_type	The attribute to get data for.
allocator	An allocator with which to allocate memory for the data, or NULL for default.
cancellable	Optional cancellation object, or NULL.
n_data	The length of the resulting data.
error	A location to store an error.

Returns

The resulting PKCS#11 attribute data, or NULL if an error occurred.

[transfer full][array length=n_data]

gck_object_get_data_async ()

void
gck_object_get_data_async (GckObject *self,
                           gulong attr_type,
                           GckAllocator allocator,
                           GCancellable *cancellable,
                           GAsyncReadyCallback callback,
                           gpointer user_data);

Get the data for the specified attribute from the object.

This call will return immediately and complete asynchronously.

Parameters

self	The object to get attribute data from.
attr_type	The attribute to get data for.
allocator	An allocator with which to allocate memory for the data, or NULL for default.	[skip]
cancellable	Optional cancellation object, or NULL.
callback	Called when the operation completes.
user_data	Data to be passed to the callback.

gck_object_get_data_finish ()

guchar *
gck_object_get_data_finish (GckObject *self,
                            GAsyncResult *result,
                            gsize *n_data,
                            GError **error);

Get the result of an operation to get attribute data from an object. For convenience the returned data has an extra null terminator, not included in the returned length.

Parameters

self	The object to get an attribute from.
result	The result passed to the callback.
n_data	The length of the resulting data.
error	A location to store an error.

Returns

The PKCS#11 attribute data or NULL if an error occurred.

[transfer full][array length=n_data]

gck_object_get_full ()

GckAttributes *
gck_object_get_full (GckObject *self,
                     const gulong *attr_types,
                     guint n_attr_types,
                     GCancellable *cancellable,
                     GError **error);

Get the specified attributes from the object. This call may block for an indefinite period.

No extra references are added to the returned attributes pointer. During this call you may not access the attributes in any way.

Parameters

self	The object to get attributes from.
attr_types	the types of the attributes to get.	[array length=n_attr_types]
n_attr_types	the number of attr_types
cancellable	optional cancellation object, or `NULL`
error	A location to store an error.

Returns

a pointer to the filled in attributes if successful, or NULL if not.

[transfer full]

gck_object_get_template ()

GckAttributes *
gck_object_get_template (GckObject *self,
                         gulong attr_type,
                         GCancellable *cancellable,
                         GError **error);

Get an attribute template from the object. The attr_type must be for an attribute which returns a template.

This call may block for an indefinite period.

Parameters

self	The object to get an attribute template from.
attr_type	The template attribute type.
cancellable	Optional cancellation object, or NULL.
error	A location to store an error.

Returns

the resulting PKCS#11 attribute template, or NULL if an error occurred.

[transfer full]

gck_object_get_template_async ()

void
gck_object_get_template_async (GckObject *self,
                               gulong attr_type,
                               GCancellable *cancellable,
                               GAsyncReadyCallback callback,
                               gpointer user_data);

Get an attribute template from the object. The attr_type must be for an attribute which returns a template.

This call will return immediately and complete asynchronously.

Parameters

self	The object to get an attribute template from.
attr_type	The template attribute type.
cancellable	Optional cancellation object, or NULL.
callback	Called when the operation completes.
user_data	Data to be passed to the callback.

gck_object_get_template_finish ()

GckAttributes *
gck_object_get_template_finish (GckObject *self,
                                GAsyncResult *result,
                                GError **error);

Get the result of an operation to get attribute template from an object.

Parameters

self	The object to get an attribute from.
result	The result passed to the callback.
error	A location to store an error.

Returns

the resulting PKCS#11 attribute template, or NULL if an error occurred.

[transfer full]

gck_object_set_template ()

gboolean
gck_object_set_template (GckObject *self,
                         gulong attr_type,
                         GckAttributes *attrs,
                         GCancellable *cancellable,
                         GError **error);

Set an attribute template on the object. The attr_type must be for an attribute which contains a template.

If the attrs GckAttributes is floating, it is consumed.

This call may block for an indefinite period.

Parameters

self	The object to set an attribute template on.
attr_type	The attribute template type.
attrs	The attribute template.
cancellable	Optional cancellation object, or NULL.
error	A location to store an error.

Returns

TRUE if the operation succeeded.

gck_object_set_template_async ()

void
gck_object_set_template_async (GckObject *self,
                               gulong attr_type,
                               GckAttributes *attrs,
                               GCancellable *cancellable,
                               GAsyncReadyCallback callback,
                               gpointer user_data);

Set an attribute template on the object. The attr_type must be for an attribute which contains a template.

If the attrs GckAttributes is floating, it is consumed.

This call will return immediately and complete asynchronously.

Parameters

self	The object to set an attribute template on.
attr_type	The attribute template type.
attrs	The attribute template.
cancellable	Optional cancellation object, or NULL.
callback	Called when the operation completes.
user_data	Data to be passed to the callback.

gck_object_set_template_finish ()

gboolean
gck_object_set_template_finish (GckObject *self,
                                GAsyncResult *result,
                                GError **error);

Get the result of an operation to set attribute template on an object.

Parameters

self	The object to set an attribute template on.
result	The result passed to the callback.
error	A location to store an error.

Returns

TRUE if the operation succeeded.

Types and Values

struct GckObject

struct GckObject;

Represents a PKCS11 object handle such as a key or certifiacte.

struct GckObjectClass

struct GckObjectClass {
	GObjectClass parent;
};

The class for a GckObject.

If the attribute_types field is set by a derived class, then the a GckEnumerator which has been setup using gck_enumerator_set_object_type() with this derived type will retrieve these attributes when enumerating. In this case the class must implement an 'attributes' property of boxed type GCK_TYPE_ATTRIBUTES.

Members

GObjectClass parent;

derived from this

Property Details

The `“handle”` property

  “handle”                   gulong

The raw PKCS11 handle for this object.

Flags: Read / Write / Construct Only

The `“module”` property

  “module”                   GckModule *

The GckModule that this object belongs to.

Flags: Read / Write / Construct Only

The `“session”` property

  “session”                  GckSession *

The PKCS11 session to make calls on when this object needs to perform operations on itself.

If this is NULL then a new session is opened for each operation, such as gck_object_get(), gck_object_set() or gck_object_destroy().

Flags: Read / Write / Construct Only