GckSlot

GckSlot — Represents a PKCS11 slot that can contain a token.

Synopsis

                    GckMechanismInfo;
void                gck_mechanism_info_free             (GckMechanismInfo *mech_info);
typedef             GckMechanisms;
#define             gck_mechanisms_length               (a)
#define             gck_mechanisms_at                   (a,
                                                         i)
#define             gck_mechanisms_free                 (a)
gboolean            gck_mechanisms_check                (GckMechanisms *mechanisms,
                                                         ...);
                    GckSlot;
gboolean            gck_slot_equal                      (gconstpointer slot1,
                                                         gconstpointer slot2);
guint               gck_slot_hash                       (gconstpointer slot);
GckModule*          gck_slot_get_module                 (GckSlot *self);
CK_SLOT_ID          gck_slot_get_handle                 (GckSlot *self);
GckSlotInfo*        gck_slot_get_info                   (GckSlot *self);
GckTokenInfo*       gck_slot_get_token_info             (GckSlot *self);
GckMechanisms*      gck_slot_get_mechanisms             (GckSlot *self);
GckMechanismInfo*   gck_slot_get_mechanism_info         (GckSlot *self,
                                                         gulong mech_type);
gboolean            gck_slot_has_flags                  (GckSlot *self,
                                                         gulong flags);
GckEnumerator*      gck_slots_enumerate_objects         (GList *slots,
                                                         GckAttributes *attrs,
                                                         guint session_options);
GckSession*         gck_slot_open_session               (GckSlot *self,
                                                         guint options,
                                                         GCancellable *cancellable,
                                                         GError **err);
GckSession*         gck_slot_open_session_full          (GckSlot *self,
                                                         guint options,
                                                         gulong pkcs11_flags,
                                                         gpointer app_data,
                                                         CK_NOTIFY notify,
                                                         GCancellable *cancellable,
                                                         GError **err);
void                gck_slot_open_session_async         (GckSlot *self,
                                                         guint options,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
GckSession*         gck_slot_open_session_finish        (GckSlot *self,
                                                         GAsyncResult *result,
                                                         GError **err);
                    GckSlotInfo;
void                gck_slot_info_free                  (GckSlotInfo *slot_info);
                    GckTokenInfo;
void                gck_token_info_free                 (GckTokenInfo *token_info);

Object Hierarchy

  GObject
   +----GckSlot

Properties

  "handle"                   gulong                : Read / Write / Construct Only
  "module"                   GckModule*            : Read / Write / Construct Only

Description

A PKCS11 slot can contain a token. As an example, a slot might be a card reader, and the token the card. If the PKCS11 module is not a hardware driver, often the slot and token are equivalent.

Details

GckMechanismInfo

typedef struct {
	gulong min_key_size;
	gulong max_key_size;
	gulong flags;
} GckMechanismInfo;

Represents information about a PKCS11 mechanism.

This is analogous to a CK_MECHANISM_INFO structure.

When you're done with this structure it should be released with gck_mechanism_info_free().

gulong min_key_size;

The minimum key size that can be used with this mechanism.

gulong max_key_size;

The maximum key size that can be used with this mechanism.

gulong flags;

Various PKCS11 flags that apply to this mechanism.

gck_mechanism_info_free ()

void                gck_mechanism_info_free             (GckMechanismInfo *mech_info);

Free the GckMechanismInfo and associated resources.

mech_info :

The mechanism info to free, or NULL.

GckMechanisms

typedef GArray GckMechanisms;

A set of GckMechanismInfo structures.


gck_mechanisms_length()

#define             gck_mechanisms_length(a)                ((a)->len)

Get the number of GckMechanismInfo in the set.

a :

A GckMechanisms set.

Returns :

The number in the set.

gck_mechanisms_at()

#define             gck_mechanisms_at(a, i)                 (g_array_index(a, CK_MECHANISM_TYPE, i))

Get a specific GckMechanismInfo in a the set.

a :

A GckMechanisms set.

i :

The index of a GckMechanismInfo.

Returns :

The GckMechanismInfo.

gck_mechanisms_free()

#define             gck_mechanisms_free(a)                  (g_array_free(a, TRUE))

Free a GckMechanisms set.

a :

A GckMechanism set.

gck_mechanisms_check ()

gboolean            gck_mechanisms_check                (GckMechanisms *mechanisms,
                                                         ...);

Check whether all the mechanism types are in the list.

The arguments should be a list of CKM_XXX mechanism types. The last argument should be GCK_INVALID.

mechanisms :

A list of mechanisms, perhaps retrieved from gck_slot_get_mechanisms().

... :

A list of mechanism types followed by GCK_INVALID.

Returns :

Whether the mechanism is in the list or not.

GckSlot

typedef struct _GckSlot GckSlot;

Represents a PKCS11 slot.


gck_slot_equal ()

gboolean            gck_slot_equal                      (gconstpointer slot1,
                                                         gconstpointer slot2);

Checks equality of two slots. Two GckSlot objects can point to the same underlying PKCS11 slot.

slot1 :

A pointer to the first GckSlot

slot2 :

A pointer to the second GckSlot

Returns :

TRUE if slot1 and slot2 are equal. FALSE if either is not a GckSlot.

gck_slot_hash ()

guint               gck_slot_hash                       (gconstpointer slot);

Create a hash value for the GckSlot.

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

slot :

A pointer to a GckSlot

Returns :

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

gck_slot_get_module ()

GckModule*          gck_slot_get_module                 (GckSlot *self);

Get the module that this slot is on.

self :

The slot to get the module for.

Returns :

The module, you must unreference this after you're done with it.

gck_slot_get_handle ()

CK_SLOT_ID          gck_slot_get_handle                 (GckSlot *self);

Get the raw PKCS11 handle of a slot.

self :

The slot to get the handle of.

Returns :

The raw handle.

gck_slot_get_info ()

GckSlotInfo*        gck_slot_get_info                   (GckSlot *self);

Get the information for this slot.

self :

The slot to get info for.

Returns :

The slot information. When done, use gck_slot_info_free() to release it.

gck_slot_get_token_info ()

GckTokenInfo*       gck_slot_get_token_info             (GckSlot *self);

Get the token information for this slot.

self :

The slot to get info for.

Returns :

The token information. When done, use gck_token_info_free() to release it.

gck_slot_get_mechanisms ()

GckMechanisms*      gck_slot_get_mechanisms             (GckSlot *self);

Get the available mechanisms for this slot.

self :

The slot to get mechanisms for.

Returns :

A list of the mechanisms for this slot. Use gck_mechanisms_free() when done with this.

gck_slot_get_mechanism_info ()

GckMechanismInfo*   gck_slot_get_mechanism_info         (GckSlot *self,
                                                         gulong mech_type);

Get information for the specified mechanism.

self :

The slot to get mechanism info from.

mech_type :

The mechanisms type to get info for.

Returns :

The mechanism information, or NULL if failed. Use gck_mechanism_info_free() when done with it.

gck_slot_has_flags ()

gboolean            gck_slot_has_flags                  (GckSlot *self,
                                                         gulong flags);

Check if the PKCS11 slot has the given flags.

self :

The GckSlot object.

flags :

The flags to check.

Returns :

Whether one or more flags exist.

gck_slots_enumerate_objects ()

GckEnumerator*      gck_slots_enumerate_objects         (GList *slots,
                                                         GckAttributes *attrs,
                                                         guint session_options);

Setup an enumerator for listing matching objects on the slots.

This call will not block but will return an enumerator immediately.

slots :

a list of GckSlot to enumerate objects on.

attrs :

Attributes that the objects must have, or empty for all objects.

session_options :

Options for opening a session.

Returns :

a new enumerator

gck_slot_open_session ()

GckSession*         gck_slot_open_session               (GckSlot *self,
                                                         guint options,
                                                         GCancellable *cancellable,
                                                         GError **err);

Open a session on the slot. If the 'auto reuse' setting is set, then this may be a recycled session with the same flags.

This call may block for an indefinite period.

self :

The slot ot open a session on.

options :

cancellable :

err :

A location to return an error, or NULL.

Returns :

A new session or NULL if an error occurs.

gck_slot_open_session_full ()

GckSession*         gck_slot_open_session_full          (GckSlot *self,
                                                         guint options,
                                                         gulong pkcs11_flags,
                                                         gpointer app_data,
                                                         CK_NOTIFY notify,
                                                         GCancellable *cancellable,
                                                         GError **err);

Open a session on the slot. If the 'auto reuse' setting is set, then this may be a recycled session with the same flags.

This call may block for an indefinite period.

self :

The slot to open a session on.

options :

The options to open the new session with.

pkcs11_flags :

Additional raw PKCS11 flags.

app_data :

Application data for notification callback.

notify :

PKCS11 notification callback.

cancellable :

Optional cancellation object, or NULL.

err :

A location to return an error, or NULL.

Returns :

A new session or NULL if an error occurs.

gck_slot_open_session_async ()

void                gck_slot_open_session_async         (GckSlot *self,
                                                         guint options,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);

Open a session on the slot. If the 'auto reuse' setting is set, then this may be a recycled session with the same flags.

This call will return immediately and complete asynchronously.

self :

The slot to open a session on.

options :

Options to open the new session with.

cancellable :

Optional cancellation object, or NULL.

callback :

Called when the operation completes.

user_data :

Data to pass to the callback.

gck_slot_open_session_finish ()

GckSession*         gck_slot_open_session_finish        (GckSlot *self,
                                                         GAsyncResult *result,
                                                         GError **err);

Get the result of an open session operation. If the 'auto reuse' setting is set, then this may be a recycled session with the same flags.

self :

The slot to open a session on.

result :

The result passed to the callback.

err :

A location to return an error or NULL.

Returns :

The new session or NULL if an error occurs.

GckSlotInfo

typedef struct {
	gchar *slot_description;
	gchar *manufacturer_id;
	gulong flags;
	guint8 hardware_version_major;
	guint8 hardware_version_minor;
	guint8 firmware_version_major;
	guint8 firmware_version_minor;
} GckSlotInfo;

Represents information about a PKCS11 slot.

This is analogous to a CK_SLOT_INFO structure, but the strings are far more usable.

When you're done with this structure it should be released with gck_slot_info_free().

gchar *slot_description;

Description of the slot.

gchar *manufacturer_id;

The manufacturer of this slot.

gulong flags;

Various PKCS11 flags that apply to this slot.

guint8 hardware_version_major;

The major version of the hardware.

guint8 hardware_version_minor;

The minor version of the hardware.

guint8 firmware_version_major;

The major version of the firmware.

guint8 firmware_version_minor;

The minor version of the firmware.

gck_slot_info_free ()

void                gck_slot_info_free                  (GckSlotInfo *slot_info);

Free the GckSlotInfo and associated resources.

slot_info :

The slot info to free, or NULL.

GckTokenInfo

typedef struct {
	gchar *label;
	gchar *manufacturer_id;
	gchar *model;
	gchar *serial_number;
	gulong flags;
	glong max_session_count;
	glong session_count;
	glong max_rw_session_count;
	glong rw_session_count;
	glong max_pin_len;
	glong min_pin_len;
	glong total_public_memory;
	glong free_public_memory;
	glong total_private_memory;
	glong free_private_memory;
	guint8 hardware_version_major;
	guint8 hardware_version_minor;
	guint8 firmware_version_major;
	guint8 firmware_version_minor;
	gint64 utc_time;
} GckTokenInfo;

Represents information about a PKCS11 token.

This is analogous to a CK_TOKEN_INFO structure, but the strings are far more usable.

When you're done with this structure it should be released with gck_token_info_free().

gchar *label;

The displayable token label.

gchar *manufacturer_id;

The manufacturer of this slot.

gchar *model;

The token model number as a string.

gchar *serial_number;

The token serial number as a string.

gulong flags;

Various PKCS11 flags that apply to this token.

glong max_session_count;

The maximum number of sessions allowed on this token.

glong session_count;

The number of sessions open on this token.

glong max_rw_session_count;

The maximum number of read/write sessions allowed on this token.

glong rw_session_count;

The number of sessions open on this token.

glong max_pin_len;

The maximum length of a PIN for locking this token.

glong min_pin_len;

The minimum length of a PIN for locking this token.

glong total_public_memory;

The total amount of memory on this token for storing public objects.

glong free_public_memory;

The available amount of memory on this token for storing public objects.

glong total_private_memory;

The total amount of memory on this token for storing private objects.

glong free_private_memory;

The available amount of memory on this token for storing private objects.

guint8 hardware_version_major;

The major version of the hardware.

guint8 hardware_version_minor;

The minor version of the hardware.

guint8 firmware_version_major;

The major version of the firmware.

guint8 firmware_version_minor;

The minor version of the firmware.

gint64 utc_time;

If the token has a hardware clock, this is set to the number of seconds since the epoch.

gck_token_info_free ()

void                gck_token_info_free                 (GckTokenInfo *token_info);

Free the GckTokenInfo and associated resources.

token_info :

The token info to free, or NULL.

Property Details

The "handle" property

  "handle"                   gulong                : Read / Write / Construct Only

The raw CK_SLOT_ID handle of this slot.


The "module" property

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

The PKCS11 object that this slot is a part of.