GP11Object
3
GP11 Library

# GP11Object

Represents a PKCS11 object such as a key or certificate.

## Synopsis

                        GP11Object;
    GP11Object*         gp11_object_from_handle             (GP11Slot *slot,
                                                             CK_OBJECT_HANDLE handle);
    GList*              gp11_objects_from_handle_array      (GP11Slot *slot,
                                                             CK_OBJECT_HANDLE_PTR handles,
                                                             CK_ULONG n_handles);
    gboolean            gp11_object_equal                   (gconstpointer slot1,
                                                             gconstpointer slot2);
    guint               gp11_object_hash                    (gconstpointer slot);
    GP11Module*         gp11_object_get_module              (GP11Object *self);
    GP11Slot*           gp11_object_get_slot                (GP11Object *self);
    CK_OBJECT_HANDLE    gp11_object_get_handle              (GP11Object *self);
    GP11Session*        gp11_object_get_session             (GP11Object *self);
    void                gp11_object_set_session             (GP11Object *self,
                                                             GP11Session *session);
    gboolean            gp11_object_destroy                 (GP11Object *self,
                                                             GError **err);
    gboolean            gp11_object_destroy_full            (GP11Object *self,
                                                             GCancellable *cancellable,
                                                             GError **err);
    void                gp11_object_destroy_async           (GP11Object *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            gp11_object_destroy_finish          (GP11Object *self,
                                                             GAsyncResult *result,
                                                             GError **err);
    gboolean            gp11_object_set                     (GP11Object *self,
                                                             GError **err);
    void                gp11_object_set_async               (GP11Object *self,
                                                             GP11Attributes *attrs,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gboolean            gp11_object_set_finish              (GP11Object *self,
                                                             GAsyncResult *result,
                                                             GError **err);
    GP11Attributes*     gp11_object_get                     (GP11Object *self,
                                                             GError **err);
    void                gp11_object_get_async               (GP11Object *self,
                                                             GP11Attributes *attrs,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    GP11Attributes*     gp11_object_get_finish              (GP11Object *self,
                                                             GAsyncResult *result,
                                                             GError **err);
    gpointer            gp11_object_get_data                (GP11Object *self,
                                                             gulong attr_type,
                                                             gsize *n_data,
                                                             GError **err);
    gpointer            gp11_object_get_data_full           (GP11Object *self,
                                                             gulong attr_type,
                                                             GP11Allocator allocator,
                                                             GCancellable *cancellable,
                                                             gsize *n_data,
                                                             GError **err);
    void                gp11_object_get_data_async          (GP11Object *self,
                                                             gulong attr_type,
                                                             GP11Allocator allocator,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);
    gpointer            gp11_object_get_data_finish         (GP11Object *self,
                                                             GAsyncResult *result,
                                                             gsize *n_data,
                                                             GError **err);

## Object Hierarchy

      GObject
       +----GP11Object

## Properties

      "handle"                   gulong                : Read / Write / Construct Only
      "module"                   GP11Module*           : Read / Write / Construct Only
      "session"                  GP11Session*          : Read / Write
      "slot"                     GP11Slot*             : Read / Write / Construct Only

## Description

A GP11Object 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.

## Details

### GP11Object

    typedef struct _GP11Object GP11Object;

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

### gp11_object_from_handle ()

    GP11Object*         gp11_object_from_handle             (GP11Slot *slot,
                                                             CK_OBJECT_HANDLE handle);

Initialize a GP11Object from a raw PKCS11 handle. Normally you would use `gp11_session_create_object()` or `gp11_session_find_objects()` to access objects.

`slot` :

  The slot on which this object is present.

`handle` :

  The raw handle of the object.

Returns :

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

### gp11_objects_from_handle_array ()

    GList*              gp11_objects_from_handle_array      (GP11Slot *slot,
                                                             CK_OBJECT_HANDLE_PTR handles,
                                                             CK_ULONG n_handles);

Initialize a list of GP11Object from raw PKCS11 handles. The handles argument must contain contiguous CK_OBJECT_HANDLE handles in an array.

`slot` :

  The slot on which these objects are present.

`handles` :

  The raw object handles.

`n_handles` :

  The number of raw object handles.

Returns :

  The list of GP11Object. You should use `gp11_list_unref_free()` when done with this list.

### gp11_object_equal ()

    gboolean            gp11_object_equal                   (gconstpointer slot1,
                                                             gconstpointer slot2);

Checks equality of two objects. Two GP11Object objects can point to the same underlying PKCS11 object.

`slot1` :

`slot2` :

Returns :

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

### gp11_object_hash ()

    guint               gp11_object_hash                    (gconstpointer slot);

Create a hash value for the GP11Object.

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

`slot` :

Returns :

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

### gp11_object_get_module ()

    GP11Module*         gp11_object_get_module              (GP11Object *self);

Get the PKCS11 module to which this object belongs.

`self` :

  The object.

Returns :

  The module, which should be unreffed after use.

### gp11_object_get_slot ()

    GP11Slot*           gp11_object_get_slot                (GP11Object *self);

Get the PKCS11 slot to which this object belongs.

`self` :

  The object.

Returns :

  The slot, which should be unreffed after use.

### gp11_object_get_handle ()

    CK_OBJECT_HANDLE    gp11_object_get_handle              (GP11Object *self);

Get the raw PKCS11 handle of a GP11Object.

`self` :

  The object.

Returns :

  The raw object handle.

### gp11_object_get_session ()

    GP11Session*        gp11_object_get_session             (GP11Object *self);

Get the PKCS11 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.

`self` :

  The object

Returns :

  The assigned session, which must be unreffed after use.

### gp11_object_set_session ()

    void                gp11_object_set_session             (GP11Object *self,
                                                             GP11Session *session);

Set the PKCS11 session assigned to make calls on when operating on this object.

It isn't always necessary to assign a session to an object. By default an object will open and close sessions appropriate for its calls.

If you assign a read-only session, then calls on this object that modify the state of the object will probably fail.

`self` :

  The object

`session` :

  The assigned session

### gp11_object_destroy ()

    gboolean            gp11_object_destroy                 (GP11Object *self,
                                                             GError **err);

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

`self` :

  The object to destroy.

`err` :

  A location to return an error.

Returns :

  Whether the call was successful or not.

### gp11_object_destroy_full ()

    gboolean            gp11_object_destroy_full            (GP11Object *self,
                                                             GCancellable *cancellable,
                                                             GError **err);

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

`self` :

  The object to destroy.

`cancellable` :

  Optional cancellable object, or NULL to ignore.

`err` :

  A location to return an error.

Returns :

  Whether the call was successful or not.

### gp11_object_destroy_async ()

    void                gp11_object_destroy_async           (GP11Object *self,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

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

`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.

### gp11_object_destroy_finish ()

    gboolean            gp11_object_destroy_finish          (GP11Object *self,
                                                             GAsyncResult *result,
                                                             GError **err);

Get the status of the operation to destroy a PKCS11 object, begun with `gp11_object_destroy_async()`.

`self` :

  The object being destroyed.

`result` :

  The result of the destory operation passed to the callback.

`err` :

  A location to store an error.

Returns :

  Whether the object was destroyed successfully or not.

### gp11_object_set ()

    gboolean            gp11_object_set                     (GP11Object *self,
                                                             GError **err);

Set PKCS11 attributes on an object. This call may block for an indefinite period.

The arguments must be triples of: attribute type, data type, value

The variable argument list should contain:

a)

  The gulong attribute type (ie: CKA_LABEL).

b)

  The attribute data type (one of GP11_BOOLEAN, GP11_ULONG, GP11_STRING, GP11_DATE) orthe raw attribute value length.

c)

  The attribute value, either a gboolean, gulong, gchar*, GDate* or a pointer to a raw attribute value.

The variable argument list should be terminated with GP11_INVALID.

`self` :

  The object to set attributes on.

`err` :

  A location to return an error. ...: The attributes to set.

Returns :

  Whether the call was successful or not.

### gp11_object_set_async ()

    void                gp11_object_set_async               (GP11Object *self,
                                                             GP11Attributes *attrs,
                                                             GCancellable *cancellable,
                                                             GAsyncReadyCallback callback,
                                                             gpointer user_data);

Set PKCS11 attributes on an object. This call will return immediately and completes asynchronously.

`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.

### gp11_object_set_finish ()

    gboolean            gp11_object_set_finish              (GP11Object *self,
                                                             GAsyncResult *result,
                                                             GError **err);

Get the status of the operation to set attributes on a PKCS11 object, begun with `gp11_object_set_async()`.

`self` :

  The object to set attributes on.

`result` :

  The result of the destory operation passed to the callback.

`err` :

  A location to store an error.

Returns :

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

### gp11_object_get ()

    GP11Attributes*     gp11_object_get                     (GP11Object *self,
                                                             GError **err);

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.

`self` :

  The object to get attributes from.

`err` :

  A location to store an error.

Returns :

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

### gp11_object_get_async ()

    void                gp11_object_get_async               (GP11Object *self,
                                                             GP11Attributes *attrs,
                                                             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 `gp11_object_get_finish()` is called.

This call returns immediately and completes asynchronously.

`self` :

  The object to get attributes from.

`attrs` :

  The attributes to get, initialized with their 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.

### gp11_object_get_finish ()

    GP11Attributes*     gp11_object_get_finish              (GP11Object *self,
                                                             GAsyncResult *result,
                                                             GError **err);

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

No extra references are added to the returned attributes pointer.

`self` :

  The object to get attributes from.

`result` :

  The result passed to the callback.

`err` :

  A location to store an error.

Returns :

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

### gp11_object_get_data ()

    gpointer            gp11_object_get_data                (GP11Object *self,
                                                             gulong attr_type,
                                                             gsize *n_data,
                                                             GError **err);

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

`self` :

  The object to get attribute data from.

`attr_type` :

  The attribute to get data for.

`n_data` :

  The length of the resulting data.

`err` :

  A location to store an error.

Returns :

  The resulting PKCS11 attribute data, or NULL if an error occurred.

### gp11_object_get_data_full ()

    gpointer            gp11_object_get_data_full           (GP11Object *self,
                                                             gulong attr_type,
                                                             GP11Allocator allocator,
                                                             GCancellable *cancellable,
                                                             gsize *n_data,
                                                             GError **err);

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

`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.

`err` :

  A location to store an error.

Returns :

  The resulting PKCS11 attribute data, or NULL if an error occurred.

### gp11_object_get_data_async ()

    void                gp11_object_get_data_async          (GP11Object *self,
                                                             gulong attr_type,
                                                             GP11Allocator 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.

`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.

`callback` :

  Called when the operation completes.

`user_data` :

  Data to be passed to the callback.

### gp11_object_get_data_finish ()

    gpointer            gp11_object_get_data_finish         (GP11Object *self,
                                                             GAsyncResult *result,
                                                             gsize *n_data,
                                                             GError **err);

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

`self` :

  The object to get an attribute from.

`result` :

  The result passed to the callback.

`n_data` :

  The length of the resulting data.

`err` :

  A location to store an error.

Returns :

  The PKCS11 attribute data or NULL if an error occurred.

## Property Details

### The `"handle"` property

      "handle"                   gulong                : Read / Write / Construct Only

The raw PKCS11 handle for this object.

### The `"module"` property

      "module"                   GP11Module*           : Read / Write / Construct Only

The GP11Module that this object belongs to.

### The `"session"` property

      "session"                  GP11Session*          : Read / Write

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 `gp11_object_get()`, `gp11_object_set()` or `gp11_object_destroy()`.

### The `"slot"` property

      "slot"                     GP11Slot*             : Read / Write / Construct Only

The GP11Slot that this object belongs to.

If this is a token object then it will be stored on the token in this slot. If this is a session object, then it belongs to a session opened on this slot.