GckAttributes

typedef struct _GckAttributes GckAttributes;

A set of GckAttribute structures.

gck_attributes_new_empty ()

GckAttributes *     gck_attributes_new_empty            (gulong first_type,
                                                         ...);

Creates an GckAttributes array with empty attributes

Terminate the argument list with GCK_INVALID.

The returned set of attributes is floating, and should either be passed to another gck library function which consumes this floating reference, or if you wish to keep these attributes around you should ref them with gck_attributes_ref_sink() and unref them later with gck_attributes_unref().

gck_attributes_at ()

const GckAttribute * gck_attributes_at                  (GckAttributes *attrs,
                                                         guint index);

Get attribute at the specified index in the attribute array.

Use gck_attributes_count() to determine how many attributes are in the array.

gck_attributes_find ()

const GckAttribute * gck_attributes_find                (GckAttributes *attrs,
                                                         gulong attr_type);

Find an attribute with the specified type in the array.

gck_attributes_find_boolean ()

gboolean            gck_attributes_find_boolean         (GckAttributes *attrs,
                                                         gulong attr_type,
                                                         gboolean *value);

Find an attribute with the specified type in the array.

The attribute (if found) must be of the right size to store a boolean value (ie: CK_BBOOL). If the attribute is marked invalid then it will be treated as not found.

gck_attributes_find_ulong ()

gboolean            gck_attributes_find_ulong           (GckAttributes *attrs,
                                                         gulong attr_type,
                                                         gulong *value);

Find an attribute with the specified type in the array.

The attribute (if found) must be of the right size to store a unsigned long value (ie: CK_ULONG). If the attribute is marked invalid then it will be treated as not found.

gck_attributes_find_string ()

gboolean            gck_attributes_find_string          (GckAttributes *attrs,
                                                         gulong attr_type,
                                                         gchar **value);

Find an attribute with the specified type in the array.

If the attribute is marked invalid then it will be treated as not found. The resulting string will be null-terminated, and must be freed by the caller using g_free().

gck_attributes_find_date ()

gboolean            gck_attributes_find_date            (GckAttributes *attrs,
                                                         gulong attr_type,
                                                         GDate *value);

Find an attribute with the specified type in the array.

The attribute (if found) must be of the right size to store a date value (ie: CK_DATE). If the attribute is marked invalid then it will be treated as not found.

gck_attributes_count ()

gulong              gck_attributes_count                (GckAttributes *attrs);

Get the number of attributes in this attribute array.

gck_attributes_ref ()

GckAttributes *     gck_attributes_ref                  (GckAttributes *attrs);

Reference this attributes array.

gck_attributes_ref_sink ()

GckAttributes *     gck_attributes_ref_sink             (GckAttributes *attrs);

GckAttributes uses a floating reference count system. gck_builder_end() and gck_attributes_new_empty() both return floating references.

Calling gck_attributes_ref_sink() on a GckAttributes with a floating reference will convert the floating reference into a full reference. Calling gck_attributes_ref_sink() on a non-floating GckAttributes results in an additional normal reference being added.

In other words, if the attrs is floating, then this call "assumes ownership" of the floating reference, converting it to a normal reference. If the attrs is not floating, then this call adds a new normal reference increasing the reference count by one.

All Gck library functions that assume ownership of floating references are documented as such. Essentially any Gck function that performs an operation using a GckAttributes argument rather than operating on the atributes themselves, will accept a floating reference.

gck_attributes_unref ()

void                gck_attributes_unref                (gpointer attrs);

Unreference this attribute array.

When all outstanding references are gone, the array will be freed.

gck_attributes_contains ()

gboolean            gck_attributes_contains             (GckAttributes *attrs,
                                                         const GckAttribute *match);

Check whether the attributes contain a certain attribute.

gck_attributes_to_string ()

gchar *             gck_attributes_to_string            (GckAttributes *attrs);

Print out attributes to a string in aform that's useful for debugging or logging.

The format of the string returned may change in the future.

gck_attributes_dump ()

void                gck_attributes_dump                 (GckAttributes *attrs);

Dump the attributes using g_printerr().

struct GckBuilder

struct GckBuilder {
};

A builder for a set of attributes. Add attributes to a builder, and then use gck_builder_end() to get the completed GckAttributes.

The fields of GckBuilder are private and not to be accessed directly.

enum GckBuilderFlags

typedef enum {
	GCK_BUILDER_NONE,
	GCK_BUILDER_SECURE_MEMORY = 1,
} GckBuilderFlags;

Flags to be used with a gck_builder_init_full() and gck_builder_new().

GCK_BUILDER_INIT

#define              GCK_BUILDER_INIT                       { { 0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }

Values that can be assigned to a GckBuilder allocated on the stack.

1

GckBuilder builder = GCK_BUILDER_INIT;

gck_builder_init ()

void                gck_builder_init                    (GckBuilder *builder);

Initialize a stack allocated builder, with the default flags.

This is equivalent to initializing a builder variable with the GCK_BUILDER_INIT constant, or setting it to zeroed memory.

1
2
3
4
5
6
7
8

/* Equivalent ways of initializing a GckBuilder */
GckBuilder builder = GCK_BUILDER_INIT;
GckBuilder builder2;
GckBuilder builder3;

gck_builder_init (&builder2);

memset (&builder3, 0, sizeof (builder3));

gck_builder_init_full ()

void                gck_builder_init_full               (GckBuilder *builder,
                                                         GckBuilderFlags flags);

Initialize a stack allocated builder, with the appropriate flags.

If the GCK_BUILDER_SECURE_MEMORY flag is specified then non-pageable memory will be used for the various values of the attributes in the builder

gck_builder_new ()

GckBuilder *        gck_builder_new                     (GckBuilderFlags flags);

Create a new GckBuilder not allocated on the stack, so it can be shared across a single scope, and referenced / unreferenced.

Normally a GckBuilder is created on the stack, and simply initialized.

If the GCK_BUILDER_SECURE_MEMORY flag is specified then non-pageable memory will be used for the various values of the attributes in the builder

gck_builder_add_boolean ()

void                gck_builder_add_boolean             (GckBuilder *builder,
                                                         gulong attr_type,
                                                         gboolean value);

Add a new attribute to the builder for the boolean value. Unconditionally adds a new attribute, even if one with the same attr_type already exists.

gck_builder_set_boolean ()

void                gck_builder_set_boolean             (GckBuilder *builder,
                                                         gulong attr_type,
                                                         gboolean value);

Set an attribute on the builder for the boolean value. If an attribute with attr_type already exists in the builder then it is changed to the new value, otherwise an attribute is added.

gck_builder_add_data ()

void                gck_builder_add_data                (GckBuilder *builder,
                                                         gulong attr_type,
                                                         const guchar *value,
                                                         gsize length);

Add a new attribute to the builder with an arbitrary value. Unconditionally adds a new attribute, even if one with the same attr_type already exists.

The memory in value is copied by the builder.

NULL may be specified for the value argument, in which case an empty attribute is created. GCK_INVALID may be specified for the length, in which case an invalid attribute is created in the PKCS#11 style.

gck_builder_set_data ()

void                gck_builder_set_data                (GckBuilder *builder,
                                                         gulong attr_type,
                                                         const guchar *value,
                                                         gsize length);

Set a new attribute to the builder with an arbitrary value. If an attribute with attr_type already exists in the builder then it is changed to the new value, otherwise an attribute is added.

The memory in value is copied by the builder.

NULL may be specified for the value argument, in which case an empty attribute is created. GCK_INVALID may be specified for the length, in which case an invalid attribute is created in the PKCS#11 style.

gck_builder_take_data ()

void                gck_builder_take_data               (GckBuilder *builder,
                                                         gulong attr_type,
                                                         guchar *value,
                                                         gsize length);

Add a new attribute to the builder with an arbitrary value. Unconditionally adds a new attribute, even if one with the same attr_type already exists.

Ownership of the value memory is taken by the builder, may be reallocated, and is eventually freed with g_free(). The memory must have been allocated using the standard GLib memory allocation routines.

NULL may be specified for the value argument, in which case an empty attribute is created. GCK_INVALID may be specified for the length, in which case an invalid attribute is created in the PKCS#11 style.

gck_builder_add_date ()

void                gck_builder_add_date                (GckBuilder *builder,
                                                         gulong attr_type,
                                                         const GDate *value);

Add a new attribute to the builder for the date value. Unconditionally adds a new attribute, even if one with the same attr_type already exists.

gck_builder_set_date ()

void                gck_builder_set_date                (GckBuilder *builder,
                                                         gulong attr_type,
                                                         const GDate *value);

Set an attribute on the builder for the date value. If an attribute with attr_type already exists in the builder then it is changed to the new value, otherwise an attribute is added.

gck_builder_add_string ()

void                gck_builder_add_string              (GckBuilder *builder,
                                                         gulong attr_type,
                                                         const gchar *value);

Add a new attribute to the builder for the string value or NULL. Unconditionally adds a new attribute, even if one with the same attr_type already exists.

gck_builder_set_string ()

void                gck_builder_set_string              (GckBuilder *builder,
                                                         gulong attr_type,
                                                         const gchar *value);

Set an attribute on the builder for the string value or NULL. If an attribute with attr_type already exists in the builder then it is changed to the new value, otherwise an attribute is added.

gck_builder_add_ulong ()

void                gck_builder_add_ulong               (GckBuilder *builder,
                                                         gulong attr_type,
                                                         gulong value);

Add a new attribute to the builder for the unsigned long value. Unconditionally adds a new attribute, even if one with the same attr_type already exists.

gck_builder_set_ulong ()

void                gck_builder_set_ulong               (GckBuilder *builder,
                                                         gulong attr_type,
                                                         gulong value);

Set an attribute on the builder for the unsigned long value. If an attribute with attr_type already exists in the builder then it is changed to the new value, otherwise an attribute is added.

gck_builder_add_empty ()

void                gck_builder_add_empty               (GckBuilder *builder,
                                                         gulong attr_type);

Add a new attribute to the builder that is empty. Unconditionally adds a new attribute, even if one with the same attr_type already exists.

gck_builder_set_empty ()

void                gck_builder_set_empty               (GckBuilder *builder,
                                                         gulong attr_type);

Set an attribute on the builder that is empty. If an attribute with attr_type already exists in the builder then it is changed to the new value, otherwise an attribute is added.

gck_builder_add_invalid ()

void                gck_builder_add_invalid             (GckBuilder *builder,
                                                         gulong attr_type);

Add a new attribute to the builder that is invalid in the PKCS#11 sense. Unconditionally adds a new attribute, even if one with the same attr_type already exists.

gck_builder_set_invalid ()

void                gck_builder_set_invalid             (GckBuilder *builder,
                                                         gulong attr_type);

Set an attribute on the builder that is invalid in the PKCS#11 sense. If an attribute with attr_type already exists in the builder then it is changed to the new value, otherwise an attribute is added.

gck_builder_add_attribute ()

void                gck_builder_add_attribute           (GckBuilder *builder,
                                                         const GckAttribute *attr);

Add an attribute to the builder. The attribute is added unconditionally whether or not an attribute with the same type already exists on the builder.

The attr attribute must have been created or owned by the Gck library. If you call this function on an arbitrary GckAttribute that is allocated on the stack or elsewhere, then this will result in undefined behavior.

As an optimization, the attribute memory value is automatically shared between the attribute and the builder.

gck_builder_add_all ()

void                gck_builder_add_all                 (GckBuilder *builder,
                                                         GckAttributes *attrs);

Add all the attrs attributes to the builder. The attributes are added uncondititionally whether or not attributes with the same types already exist in the builder.

As an optimization, the attribute memory values are automatically shared between the attributes and the builder.

gck_builder_set_all ()

void                gck_builder_set_all                 (GckBuilder *builder,
                                                         GckAttributes *attrs);

Set all the attrs attributes to the builder. If any attributes with the same types are already present in the builder, then those attributes are changed to the new values.

As an optimization, the attribute memory values are automatically shared between the attributes and the builder.

gck_builder_add_except ()

void                gck_builder_add_except              (GckBuilder *builder,
                                                         GckAttributes *attrs,
                                                         gulong except_type,
                                                         ...);

Add the attributes in attrs to the builder, with the exception of those in the argument list. The attributes are added uncondititionally whether or not attributes with the same types already exist in the builder.

The variable arguments must be unsigned longs.

1
2

/* Add all attributes in attrs except CKA_CLASS to the builder */
gck_builder_add_except (builder, attrs, CKA_CLASS, GCK_INVALID);

As an optimization, the attribute memory values are automatically shared between the attributes and the builder.

gck_builder_add_exceptv ()

void                gck_builder_add_exceptv             (GckBuilder *builder,
                                                         GckAttributes *attrs,
                                                         const gulong *except_types,
                                                         guint n_except_types);

Add the attributes in attrs to the builder, with the exception of those whose types are specified in except_types. The attributes are added uncondititionally whether or not attributes with the same types already exist in the builder.

1
2
3

/* Add all attributes in attrs except CKA_CLASS to the builder */
gulong except_types[] = { CKA_CLASS };
gck_builder_add_exceptv (builder, attrs, except_types, 1);

As an optimization, the attribute memory values are automatically shared between the attributes and the builder.

gck_builder_add_only ()

void                gck_builder_add_only                (GckBuilder *builder,
                                                         GckAttributes *attrs,
                                                         gulong only_type,
                                                         ...);

Add the attributes specified in the argument list from attrs to the builder. The attributes are added uncondititionally whether or not attributes with the same types already exist in the builder.

The variable arguments must be unsigned longs.

1
2

/* Add the CKA_ID and CKA_CLASS attributes from attrs to builder */
gck_builder_add_only (builder, attrs, CKA_ID, CKA_CLASS, GCK_INVALID);

As an optimization, the attribute memory values are automatically shared between the attributes and the builder.

gck_builder_add_onlyv ()

void                gck_builder_add_onlyv               (GckBuilder *builder,
                                                         GckAttributes *attrs,
                                                         const gulong *only_types,
                                                         guint n_only_types);

Add the attributes with the types in only_types from attrs to the builder. The attributes are added uncondititionally whether or not attributes with the same types already exist in the builder.

1
2
3

/* Add the CKA_ID and CKA_CLASS attributes from attrs to builder */
gulong only[] = { CKA_ID, CKA_CLASS };
gck_builder_add_onlyv (builder, attrs, only, 2);

As an optimization, the attribute memory values are automatically shared between the attributes and the builder.

Rename to: gck_builder_add_only

gck_builder_end ()

GckAttributes *     gck_builder_end                     (GckBuilder *builder);

Complete the GckBuilder, and return the attributes contained in the builder. The GckBuilder will be cleared after this function call, and it is no longer necessary to use gck_builder_clear() on it, although it is also permitted. The builder may be used again to build another set of attributes after this function call.

The returned set of attributes is floating, and should either be passed to another gck library function which consumes this floating reference, or if you wish to keep these attributes around you should ref them with gck_attributes_ref_sink() and unref them later with gck_attributes_unref().

gck_builder_clear ()

void                gck_builder_clear                   (GckBuilder *builder);

Clear the builder and release all allocated memory. The builder may be used again to build another set of attributes after this function call.

If memory is shared between this builder and other attributes, then that memory is only freed when both of them are cleared or unreferenced.

gck_builder_steal ()

GckAttributes *     gck_builder_steal                   (GckBuilder *builder);

Take the attributes that have been built in the GckBuilder. The builder will no longer contain any attributes after this function call.

The returned set of attributes is a full reference, not floating.

gck_builder_ref ()

GckBuilder *        gck_builder_ref                     (GckBuilder *builder);

Add a reference to a builder that was created with gck_builder_new(). The builder must later be unreferenced again with gck_builder_unref().

It is an error to use this function on builders that were allocated on the stack.

gck_builder_unref ()

void                gck_builder_unref                   (gpointer builder);

Unreferences a builder. If this was the last reference then the builder is freed.

It is an error to use this function on builders that were allocated on the stack.

gck_builder_copy ()

GckBuilder *        gck_builder_copy                    (GckBuilder *builder);

Make a copy of the builder and its state. The new builder is allocated with gck_builder_new() and should be freed with gck_builder_unref().

Attribute value memory is automatically shared between the two builders, and is only freed when both are gone.

gck_builder_find ()

const GckAttribute * gck_builder_find                   (GckBuilder *builder,
                                                         gulong attr_type);

Find an attribute in the builder. Both valid and invalid attributes (in the PKCS#11 sense) are returned. If multiple attributes exist for the given attribute type, then the first one is returned.

The returned GckAttribute is owned by the builder and may not be modified in any way. It is only valid until another attribute is added to or set on the builder, or until the builder is cleared or unreferenced.

gck_builder_find_boolean ()

gboolean            gck_builder_find_boolean            (GckBuilder *builder,
                                                         gulong attr_type,
                                                         gboolean *value);

Find a boolean attribute in the builder that has the type attr_type, is of the correct boolean size, and is not invalid in the PKCS#11 sense. If multiple attributes exist for the given attribute type, then the first\ one is returned.

gck_builder_find_date ()

gboolean            gck_builder_find_date               (GckBuilder *builder,
                                                         gulong attr_type,
                                                         GDate *value);

Find a date attribute in the builder that has the type attr_type, is of the correct date size, and is not invalid in the PKCS#11 sense. If multiple attributes exist for the given attribute type, then the first one is returned.

gck_builder_find_string ()

gboolean            gck_builder_find_string             (GckBuilder *builder,
                                                         gulong attr_type,
                                                         gchar **value);

Find a string attribute in the builder that has the type attr_type, has a non NULL value pointer, and is not invalid in the PKCS#11 sense. If multiple attributes exist for the given attribute type, then the first one is returned.

gck_builder_find_ulong ()

gboolean            gck_builder_find_ulong              (GckBuilder *builder,
                                                         gulong attr_type,
                                                         gulong *value);

Find a unsigned long attribute in the builder that has the type attr_type, is of the correct unsigned long size, and is not invalid in the PKCS#11 sense. If multiple attributes exist for the given attribute type, then the first\ one is returned.

gck_attributes_new ()

GckAttributes *     gck_attributes_new                  (gulong reserved);

Create a new empty GckAttributes array.

The returned set of attributes is floating, and should either be passed to another gck library function which consumes this floating reference, or if you wish to keep these attributes around you should ref them with gck_attributes_ref_sink() and unref them later with gck_attributes_unref().

gck_attributes_add ()

GckAttribute *      gck_attributes_add                  (GckAttributes *attrs,
                                                         GckAttribute *attr);

GckAttributes are now immutable. This method no longer does anything.

gck_attributes_add_all ()

void                gck_attributes_add_all              (GckAttributes *attrs,
                                                         GckAttributes *from);

GckAttributes are now immutable. This method no longer does anything.

gck_attributes_add_boolean ()

GckAttribute *      gck_attributes_add_boolean          (GckAttributes *attrs,
                                                         gulong attr_type,
                                                         gboolean value);

GckAttributes are now immutable. This method no longer does anything.

gck_attributes_add_data ()

GckAttribute *      gck_attributes_add_data             (GckAttributes *attrs,
                                                         gulong attr_type,
                                                         const guchar *value,
                                                         gsize length);

GckAttributes are now immutable. This method no longer does anything.

gck_attributes_add_date ()

GckAttribute *      gck_attributes_add_date             (GckAttributes *attrs,
                                                         gulong attr_type,
                                                         const GDate *value);

GckAttributes are now immutable. This method no longer does anything.

gck_attributes_add_empty ()

GckAttribute *      gck_attributes_add_empty            (GckAttributes *attrs,
                                                         gulong attr_type);

GckAttributes are now immutable. This method no longer does anything.

gck_attributes_add_invalid ()

GckAttribute *      gck_attributes_add_invalid          (GckAttributes *attrs,
                                                         gulong attr_type);

GckAttributes are now immutable. This method no longer does anything.

gck_attributes_add_string ()

GckAttribute *      gck_attributes_add_string           (GckAttributes *attrs,
                                                         gulong attr_type,
                                                         const gchar *value);

GckAttributes are now immutable. This method no longer does anything.

gck_attributes_add_ulong ()

GckAttribute *      gck_attributes_add_ulong            (GckAttributes *attrs,
                                                         gulong attr_type,
                                                         gulong value);

GckAttributes are now immutable. This method no longer does anything.

gck_attributes_dup ()

GckAttributes *     gck_attributes_dup                  (GckAttributes *attrs);

GckAttributes are now immutable, and can be used in mulitple places.

gck_attributes_new_full ()

GckAttributes *     gck_attributes_new_full             (GckAllocator allocator);

GckAttributes are now immutable. This method no longer does anything.

gck_attributes_set ()

void                gck_attributes_set                  (GckAttributes *attrs,
                                                         GckAttribute *attr);

GckAttributes are now immutable. This method no longer does anything.

gck_attributes_set_all ()

void                gck_attributes_set_all              (GckAttributes *attrs,
                                                         GckAttributes *from);

GckAttributes are now immutable. This method no longer does anything.

gck_attributes_set_boolean ()

void                gck_attributes_set_boolean          (GckAttributes *attrs,
                                                         gulong attr_type,
                                                         gboolean value);

GckAttributes are now immutable. This method no longer does anything.

gck_attributes_set_date ()

void                gck_attributes_set_date             (GckAttributes *attrs,
                                                         gulong attr_type,
                                                         const GDate *value);

GckAttributes are now immutable. This method no longer does anything.

gck_attributes_set_string ()

void                gck_attributes_set_string           (GckAttributes *attrs,
                                                         gulong attr_type,
                                                         const gchar *value);

GckAttributes are now immutable. This method no longer does anything.

gck_attributes_set_ulong ()

void                gck_attributes_set_ulong            (GckAttributes *attrs,
                                                         gulong attr_type,
                                                         gulong value);

GckAttributes are now immutable. This method no longer does anything.