GckSlot: Gck Library Reference Manual

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

## Functions

GckMechanismInfo * | gck_mechanism_info_copy ()
void | gck_mechanism_info_free ()
#define | gck_mechanisms_length()
#define | gck_mechanisms_at()
gboolean | gck_mechanisms_check ()
gboolean | gck_slot_equal ()
guint | gck_slot_hash ()
GckModule * | gck_slot_get_module ()
gulong | gck_slot_get_handle ()
GckSlotInfo * | gck_slot_get_info ()
gboolean | gck_slot_match ()
GckTokenInfo * | gck_slot_get_token_info ()
GArray * | gck_slot_get_mechanisms ()
GckMechanismInfo * | gck_slot_get_mechanism_info ()
gboolean | gck_slot_has_flags ()
GckEnumerator * | gck_slot_enumerate_objects ()
GckEnumerator * | gck_slots_enumerate_objects ()
GckSession * | gck_slot_open_session ()
GckSession * | gck_slot_open_session_full ()
void | gck_slot_open_session_full_async ()
void | gck_slot_open_session_async ()
GckSession * | gck_slot_open_session_finish ()
GckSlot * | gck_slot_from_handle ()
GckSlotInfo * | gck_slot_info_copy ()
void | gck_slot_info_free ()
GckTokenInfo * | gck_token_info_copy ()
void | gck_token_info_free ()

## Properties

gulong | handle | Read / Write / Construct Only
GckModule * | module | Read / Write / Construct Only

## Types and Values

struct | GckMechanismInfo
enum | GckSessionOptions
struct | GckSlot
struct | GckSlotInfo
struct | GckTokenInfo

## Object Hierarchy

        GBoxed
        ├── GckMechanismInfo
        ├── GckSlotInfo
        ╰── GckTokenInfo
        GObject
        ╰── GckSlot

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

## Functions

### gck_mechanism_info_copy ()

    GckMechanismInfo *
    gck_mechanism_info_copy (GckMechanismInfo *mech_info);

Make a copy of the mechanism info.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

mechanisms | A list of mechanisms, perhaps retrieved from `gck_slot_get_mechanisms()`. | [element-type ulong]
... | A list of mechanism types followed by GCK_INVALID. |

#### Returns

Whether the mechanism is in the list or not.

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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][element-type ulong]

### gck_slot_get_mechanism_info ()

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

Get information for the specified mechanism.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

[skip]

#### Parameters

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.

[skip]

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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]

### gck_slot_info_copy ()

    GckSlotInfo *
    gck_slot_info_copy (GckSlotInfo *slot_info);

Make a copy of the slot info.

#### Parameters

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.

#### Parameters

slot_info | The slot info to free, or NULL. |

### gck_token_info_copy ()

    GckTokenInfo *
    gck_token_info_copy (GckTokenInfo *token_info);

Make a copy of the token info.

#### Parameters

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.

#### Parameters

token_info | The token info to free, or NULL. |

## Types and Values

### 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()`.

#### Members

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

### enum GckSessionOptions

Options for creating sessions.

#### Members

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.

### 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()`.

#### Members

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

### 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()`.

#### Members

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

## Property Details

### The `“handle”` property

      “handle”                   gulong

The raw CK_SLOT_ID handle of this slot.

Flags: Read / Write / Construct Only

### The `“module”` property

      “module”                   GckModule *

The PKCS11 object that this slot is a part of.

Flags: Read / Write / Construct Only