GckSlot

GckSlot — Represents a PKCS#11 slot that can contain a token.

Synopsis

struct              GckMechanismInfo;
GckMechanismInfo *  gck_mechanism_info_copy             (GckMechanismInfo *mech_info);
void                gck_mechanism_info_free             (GckMechanismInfo *mech_info);
#define             gck_mechanisms_length               (a)
#define             gck_mechanisms_at                   (a,
                                                         i)
gboolean            gck_mechanisms_check                (GArray *mechanisms,
                                                         ...);
enum                GckSessionOptions;
struct              GckSlot;
gboolean            gck_slot_equal                      (gconstpointer slot1,
                                                         gconstpointer slot2);
guint               gck_slot_hash                       (gconstpointer slot);
GckModule *         gck_slot_get_module                 (GckSlot *self);
gulong              gck_slot_get_handle                 (GckSlot *self);
GckSlotInfo *       gck_slot_get_info                   (GckSlot *self);
gboolean            gck_slot_match                      (GckSlot *self,
                                                         GckUriData *uri);
GckTokenInfo *      gck_slot_get_token_info             (GckSlot *self);
GArray *            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_slot_enumerate_objects          (GckSlot *self,
                                                         GckAttributes *match,
                                                         GckSessionOptions options);
GckEnumerator *     gck_slots_enumerate_objects         (GList *slots,
                                                         GckAttributes *match,
                                                         GckSessionOptions options);
GckSession *        gck_slot_open_session               (GckSlot *self,
                                                         GckSessionOptions options,
                                                         GCancellable *cancellable,
                                                         GError **error);
GckSession *        gck_slot_open_session_full          (GckSlot *self,
                                                         GckSessionOptions options,
                                                         gulong pkcs11_flags,
                                                         gpointer app_data,
                                                         CK_NOTIFY notify,
                                                         GCancellable *cancellable,
                                                         GError **error);
void                gck_slot_open_session_full_async    (GckSlot *self,
                                                         GckSessionOptions options,
                                                         gulong pkcs11_flags,
                                                         gpointer app_data,
                                                         CK_NOTIFY notify,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
void                gck_slot_open_session_async         (GckSlot *self,
                                                         GckSessionOptions options,
                                                         GCancellable *cancellable,
                                                         GAsyncReadyCallback callback,
                                                         gpointer user_data);
GckSession *        gck_slot_open_session_finish        (GckSlot *self,
                                                         GAsyncResult *result,
                                                         GError **error);
GckSlot *           gck_slot_from_handle                (GckModule *module,
                                                         gulong slot_id);
struct              GckSlotInfo;
GckSlotInfo *       gck_slot_info_copy                  (GckSlotInfo *slot_info);
void                gck_slot_info_free                  (GckSlotInfo *slot_info);
struct              GckTokenInfo;
GckTokenInfo *      gck_token_info_copy                 (GckTokenInfo *token_info);
void                gck_token_info_free                 (GckTokenInfo *token_info);

Object Hierarchy

  GBoxed
   +----GckMechanismInfo
  GObject
   +----GckSlot
  GBoxed
   +----GckSlotInfo
  GBoxed
   +----GckTokenInfo

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 PKCS#11 module is not a hardware driver, often the slot and token are equivalent.

Details

struct GckMechanismInfo

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

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_copy ()

GckMechanismInfo *  gck_mechanism_info_copy             (GckMechanismInfo *mech_info);

Make a copy of the mechanism info.

mech_info :

a mechanism info

Returns :

a newly allocated copy mechanism info. [transfer full]

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.

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 mechanism in a the set.

a :

A GckMechanisms set.

i :

The index of a mechanism

Returns :

the mechanism

gck_mechanisms_check ()

gboolean            gck_mechanisms_check                (GArray *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.

enum GckSessionOptions

typedef enum {
	GCK_SESSION_READ_ONLY = 0,
	GCK_SESSION_READ_WRITE = 1 << 1,
	GCK_SESSION_LOGIN_USER =  1 << 2,
	GCK_SESSION_AUTHENTICATE = 1 << 3,
} GckSessionOptions;

Options for creating sessions.

GCK_SESSION_READ_ONLY

Open session as read only

GCK_SESSION_READ_WRITE

Open sessions as read/write

GCK_SESSION_LOGIN_USER

Login as user on new sessions

GCK_SESSION_AUTHENTICATE

Authenticate as necessary

struct GckSlot

struct 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 PKCS#11 slot.

slot1 :

a pointer to the first GckSlot. [type Gck.Slot]

slot2 :

a pointer to the second GckSlot. [type Gck.Slot]

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. [type Gck.Slot]

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. [transfer full]

gck_slot_get_handle ()

gulong              gck_slot_get_handle                 (GckSlot *self);

Get the raw PKCS#11 handle of a slot.

self :

The slot to get the handle of.

Returns :

the raw CK_SLOT_ID 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. [transfer full]

gck_slot_match ()

gboolean            gck_slot_match                      (GckSlot *self,
                                                         GckUriData *uri);

Check whether the PKCS#11 URI matches the slot

self :

the slot to match

uri :

the uri to match against the slot

Returns :

whether the URI matches or not

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. [transfer full]

gck_slot_get_mechanisms ()

GArray *            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, which should be freed with g_array_free(). [transfer full]

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. [transfer full]

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_slot_enumerate_objects ()

GckEnumerator *     gck_slot_enumerate_objects          (GckSlot *self,
                                                         GckAttributes *match,
                                                         GckSessionOptions options);

Setup an enumerator for listing matching objects on the slot.

If the match GckAttributes is floating, it is consumed.

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

self :

a GckSlot to enumerate objects on

match :

attributes that the objects must match, or empty for all objects

options :

options for opening a session

Returns :

a new enumerator. [transfer full]

gck_slots_enumerate_objects ()

GckEnumerator *     gck_slots_enumerate_objects         (GList *slots,
                                                         GckAttributes *match,
                                                         GckSessionOptions options);

Setup an enumerator for listing matching objects on the slots.

If the match GckAttributes is floating, it is consumed.

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

slots :

a list of GckSlot to enumerate objects on. [element-type Gck.Slot]

match :

attributes that the objects must match, or empty for all objects

options :

options for opening a session

Returns :

a new enumerator. [transfer full]

gck_slot_open_session ()

GckSession *        gck_slot_open_session               (GckSlot *self,
                                                         GckSessionOptions options,
                                                         GCancellable *cancellable,
                                                         GError **error);

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 :

The GckSessionOptions to open a session with.

cancellable :

An optional cancellation object, or NULL.

error :

A location to return an error, or NULL.

Returns :

a new session or NULL if an error occurs. [transfer full]

gck_slot_open_session_full ()

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

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 PKCS#11 flags.

app_data :

Application data for notification callback.

notify :

PKCS#11 notification callback.

cancellable :

Optional cancellation object, or NULL.

error :

A location to return an error, or NULL.

Returns :

a new session or NULL if an error occurs. [transfer full]

gck_slot_open_session_full_async ()

void                gck_slot_open_session_full_async    (GckSlot *self,
                                                         GckSessionOptions options,
                                                         gulong pkcs11_flags,
                                                         gpointer app_data,
                                                         CK_NOTIFY notify,
                                                         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.

pkcs11_flags :

Additional raw PKCS#11 flags.

app_data :

Application data for notification callback.

notify :

PKCS#11 notification callback.

cancellable :

Optional cancellation object, or NULL.

callback :

Called when the operation completes.

user_data :

Data to pass to the callback.

gck_slot_open_session_async ()

void                gck_slot_open_session_async         (GckSlot *self,
                                                         GckSessionOptions 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 :

The 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 **error);

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.

error :

A location to return an error or NULL.

Returns :

the new session or NULL if an error occurs. [transfer full]

gck_slot_from_handle ()

GckSlot *           gck_slot_from_handle                (GckModule *module,
                                                         gulong slot_id);

Create a new GckSlot object for a raw PKCS#11 handle.

module :

The module that this slot is on.

slot_id :

The raw PKCS#11 handle or slot id of this slot.

Returns :

The new GckSlot object. [transfer full]

struct GckSlotInfo

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

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_copy ()

GckSlotInfo *       gck_slot_info_copy                  (GckSlotInfo *slot_info);

Make a copy of the slot info.

slot_info :

a slot info

Returns :

a newly allocated copy slot info. [transfer full]

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.

struct GckTokenInfo

struct GckTokenInfo {
	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;
};

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_copy ()

GckTokenInfo *      gck_token_info_copy                 (GckTokenInfo *token_info);

Make a copy of the token info.

token_info :

a token info

Returns :

a newly allocated copy token info. [transfer full]

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.