GckAttributes

GckAttributes — A set of PKCS11 attributes.

Synopsis

                    GckAttributes;
GckAttributes *     gck_attributes_new_empty            (gulong first_type,
                                                         ...);
const GckAttribute * gck_attributes_at                  (GckAttributes *attrs,
                                                         guint index);
const GckAttribute * gck_attributes_find                (GckAttributes *attrs,
                                                         gulong attr_type);
gboolean            gck_attributes_find_boolean         (GckAttributes *attrs,
                                                         gulong attr_type,
                                                         gboolean *value);
gboolean            gck_attributes_find_ulong           (GckAttributes *attrs,
                                                         gulong attr_type,
                                                         gulong *value);
gboolean            gck_attributes_find_string          (GckAttributes *attrs,
                                                         gulong attr_type,
                                                         gchar **value);
gboolean            gck_attributes_find_date            (GckAttributes *attrs,
                                                         gulong attr_type,
                                                         GDate *value);
gulong              gck_attributes_count                (GckAttributes *attrs);
GckAttributes *     gck_attributes_ref                  (GckAttributes *attrs);
GckAttributes *     gck_attributes_ref_sink             (GckAttributes *attrs);
void                gck_attributes_unref                (gpointer attrs);
gboolean            gck_attributes_contains             (GckAttributes *attrs,
                                                         const GckAttribute *match);
gchar *             gck_attributes_to_string            (GckAttributes *attrs);
void                gck_attributes_dump                 (GckAttributes *attrs);
struct              GckBuilder;
enum                GckBuilderFlags;
#define             GCK_BUILDER_INIT
void                gck_builder_init                    (GckBuilder *builder);
void                gck_builder_init_full               (GckBuilder *builder,
                                                         GckBuilderFlags flags);
GckBuilder *        gck_builder_new                     (GckBuilderFlags flags);
void                gck_builder_add_boolean             (GckBuilder *builder,
                                                         gulong attr_type,
                                                         gboolean value);
void                gck_builder_set_boolean             (GckBuilder *builder,
                                                         gulong attr_type,
                                                         gboolean value);
void                gck_builder_add_data                (GckBuilder *builder,
                                                         gulong attr_type,
                                                         const guchar *value,
                                                         gsize length);
void                gck_builder_set_data                (GckBuilder *builder,
                                                         gulong attr_type,
                                                         const guchar *value,
                                                         gsize length);
void                gck_builder_take_data               (GckBuilder *builder,
                                                         gulong attr_type,
                                                         guchar *value,
                                                         gsize length);
void                gck_builder_add_date                (GckBuilder *builder,
                                                         gulong attr_type,
                                                         const GDate *value);
void                gck_builder_set_date                (GckBuilder *builder,
                                                         gulong attr_type,
                                                         const GDate *value);
void                gck_builder_add_string              (GckBuilder *builder,
                                                         gulong attr_type,
                                                         const gchar *value);
void                gck_builder_set_string              (GckBuilder *builder,
                                                         gulong attr_type,
                                                         const gchar *value);
void                gck_builder_add_ulong               (GckBuilder *builder,
                                                         gulong attr_type,
                                                         gulong value);
void                gck_builder_set_ulong               (GckBuilder *builder,
                                                         gulong attr_type,
                                                         gulong value);
void                gck_builder_add_empty               (GckBuilder *builder,
                                                         gulong attr_type);
void                gck_builder_set_empty               (GckBuilder *builder,
                                                         gulong attr_type);
void                gck_builder_add_invalid             (GckBuilder *builder,
                                                         gulong attr_type);
void                gck_builder_set_invalid             (GckBuilder *builder,
                                                         gulong attr_type);
void                gck_builder_add_attribute           (GckBuilder *builder,
                                                         const GckAttribute *attr);
void                gck_builder_add_all                 (GckBuilder *builder,
                                                         GckAttributes *attrs);
void                gck_builder_set_all                 (GckBuilder *builder,
                                                         GckAttributes *attrs);
void                gck_builder_add_except              (GckBuilder *builder,
                                                         GckAttributes *attrs,
                                                         gulong except_type,
                                                         ...);
void                gck_builder_add_exceptv             (GckBuilder *builder,
                                                         GckAttributes *attrs,
                                                         const gulong *except_types,
                                                         guint n_except_types);
void                gck_builder_add_only                (GckBuilder *builder,
                                                         GckAttributes *attrs,
                                                         gulong only_type,
                                                         ...);
void                gck_builder_add_onlyv               (GckBuilder *builder,
                                                         GckAttributes *attrs,
                                                         const gulong *only_types,
                                                         guint n_only_types);
GckAttributes *     gck_builder_end                     (GckBuilder *builder);
void                gck_builder_clear                   (GckBuilder *builder);
GckAttributes *     gck_builder_steal                   (GckBuilder *builder);
GckBuilder *        gck_builder_ref                     (GckBuilder *builder);
void                gck_builder_unref                   (gpointer builder);
GckBuilder *        gck_builder_copy                    (GckBuilder *builder);
const GckAttribute * gck_builder_find                   (GckBuilder *builder,
                                                         gulong attr_type);
gboolean            gck_builder_find_boolean            (GckBuilder *builder,
                                                         gulong attr_type,
                                                         gboolean *value);
gboolean            gck_builder_find_date               (GckBuilder *builder,
                                                         gulong attr_type,
                                                         GDate *value);
gboolean            gck_builder_find_string             (GckBuilder *builder,
                                                         gulong attr_type,
                                                         gchar **value);
gboolean            gck_builder_find_ulong              (GckBuilder *builder,
                                                         gulong attr_type,
                                                         gulong *value);
GckAttributes *     gck_attributes_new                  (gulong reserved);
GckAttribute *      gck_attributes_add                  (GckAttributes *attrs,
                                                         GckAttribute *attr);
void                gck_attributes_add_all              (GckAttributes *attrs,
                                                         GckAttributes *from);
GckAttribute *      gck_attributes_add_boolean          (GckAttributes *attrs,
                                                         gulong attr_type,
                                                         gboolean value);
GckAttribute *      gck_attributes_add_data             (GckAttributes *attrs,
                                                         gulong attr_type,
                                                         const guchar *value,
                                                         gsize length);
GckAttribute *      gck_attributes_add_date             (GckAttributes *attrs,
                                                         gulong attr_type,
                                                         const GDate *value);
GckAttribute *      gck_attributes_add_empty            (GckAttributes *attrs,
                                                         gulong attr_type);
GckAttribute *      gck_attributes_add_invalid          (GckAttributes *attrs,
                                                         gulong attr_type);
GckAttribute *      gck_attributes_add_string           (GckAttributes *attrs,
                                                         gulong attr_type,
                                                         const gchar *value);
GckAttribute *      gck_attributes_add_ulong            (GckAttributes *attrs,
                                                         gulong attr_type,
                                                         gulong value);
GckAttributes *     gck_attributes_dup                  (GckAttributes *attrs);
GckAttributes *     gck_attributes_new_full             (GckAllocator allocator);
void                gck_attributes_set                  (GckAttributes *attrs,
                                                         GckAttribute *attr);
void                gck_attributes_set_all              (GckAttributes *attrs,
                                                         GckAttributes *from);
void                gck_attributes_set_boolean          (GckAttributes *attrs,
                                                         gulong attr_type,
                                                         gboolean value);
void                gck_attributes_set_date             (GckAttributes *attrs,
                                                         gulong attr_type,
                                                         const GDate *value);
void                gck_attributes_set_string           (GckAttributes *attrs,
                                                         gulong attr_type,
                                                         const gchar *value);
void                gck_attributes_set_ulong            (GckAttributes *attrs,
                                                         gulong attr_type,
                                                         gulong value);

Object Hierarchy

  GBoxed
   +----GckAttributes
  GBoxed
   +----GckBuilder

Description

A set of GckAttribute structures. These attributes contain information about a PKCS11 object. Use gck_object_get() or gck_object_set() to set and retrieve attributes on an object.

Details

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

first_type :

the first empty attribute type

... :

the other empty attribute types

Returns :

a floating reference to an empty set of attributes. [transfer none]

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.

attrs :

The attributes array.

index :

The attribute index to retrieve.

Returns :

the specified attribute. [transfer none]

gck_attributes_find ()

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

Find an attribute with the specified type in the array.

attrs :

The attributes array to search.

attr_type :

The type of attribute to find.

Returns :

the first attribute found with the specified type, or NULL. [transfer none]

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.

attrs :

The attributes array to search.

attr_type :

The type of attribute to find.

value :

The resulting gboolean value.

Returns :

Whether a value was found or not.

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.

attrs :

The attributes array to search.

attr_type :

The type of attribute to find.

value :

The resulting gulong value.

Returns :

Whether a value was found or not.

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

attrs :

The attributes array to search.

attr_type :

The type of attribute to find.

value :

The resulting string value.

Returns :

Whether a value was found or not.

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.

attrs :

The attributes array to search.

attr_type :

The type of attribute to find.

value :

The resulting GDate value.

Returns :

Whether a value was found or not.

gck_attributes_count ()

gulong              gck_attributes_count                (GckAttributes *attrs);

Get the number of attributes in this attribute array.

attrs :

The attributes array to count.

Returns :

The number of contained attributes.

gck_attributes_ref ()

GckAttributes *     gck_attributes_ref                  (GckAttributes *attrs);

Reference this attributes array.

attrs :

An attribute array

Returns :

the attributes

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.

attrs :

an attribute array

Returns :

the referenced attributes

gck_attributes_unref ()

void                gck_attributes_unref                (gpointer attrs);

Unreference this attribute array.

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

attrs :

(type Gck.Attributes): An attribute array. [allow-none]

gck_attributes_contains ()

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

Check whether the attributes contain a certain attribute.

attrs :

The attributes to check

match :

The attribute to find

Returns :

TRUE if the attributes contain the 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.

attrs :

the attributes

Returns :

a newly allocated string

gck_attributes_dump ()

void                gck_attributes_dump                 (GckAttributes *attrs);

Dump the attributes using g_printerr().

attrs :

The attributes

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_NONE

no special flags

GCK_BUILDER_SECURE_MEMORY

use non-pageable memory for the values of the attributes

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.

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.

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

gck_builder_init (&builder2);

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

builder :

the builder

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

builder :

the builder

flags :

the flags for the new 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

flags :

flags for the new builder

Returns :

a new builder, to be freed with gck_builder_unref(). [transfer full]

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.

builder :

the builder

attr_type :

the new attribute type

value :

the attribute value

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.

builder :

the builder

attr_type :

the new attribute type

value :

the attribute value

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.

builder :

the builder

attr_type :

the new attribute type

value :

(allow-none): the new attribute memory. [array length=length]

length :

the length of the memory

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.

builder :

the builder

attr_type :

the attribute type

value :

(allow-none): the new attribute memory. [array length=length]

length :

the length of the memory

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.

builder :

the builder

attr_type :

the new attribute type

value :

(array length=length): (allow-none): the new attribute memory. [transfer full]

length :

the length of the memory

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.

builder :

the builder

attr_type :

the new attribute type

value :

the attribute value

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.

builder :

the builder

attr_type :

the new attribute type

value :

the attribute value

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.

builder :

the builder

attr_type :

the new attribute type

value :

the attribute value. [allow-none]

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.

builder :

the builder

attr_type :

the new attribute type

value :

the attribute value

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.

builder :

the builder

attr_type :

the new attribute type

value :

the attribute value

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.

builder :

the builder

attr_type :

the new attribute type

value :

the attribute value

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.

builder :

the builder

attr_type :

the new attribute type

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.

builder :

the builder

attr_type :

the attribute type

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.

builder :

the builder

attr_type :

the new attribute type

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.

builder :

the builder

attr_type :

the attribute type

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.

builder :

the builder

attr :

the attribute to add

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.

builder :

the builder

attrs :

the attributes to add

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.

builder :

the builder

attrs :

the attributes to set

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.

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

builder :

the builder

attrs :

the attributes to add

except_type :

the first type of attribute to to exclude

... :

the remaining attribute types to exclude, ending with GCK_INVALID

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.

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

builder :

the builder

attrs :

the attributes to add

except_types :

the except types. [array length=n_except_types]

n_except_types :

the number of except types

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.

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

builder :

the builder

attrs :

the attributes to add

only_type :

the first type of attribute to add

... :

the remaining attribute types to add, ending with GCK_INVALID

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.

/* 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

builder :

the builder

attrs :

the attributes to add

only_types :

the types of attributes to add. [array length=n_only_types]

n_only_types :

the number of attributes

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

builder :

the builder

Returns :

a floating reference to the attributes created in the builder. [transfer none]

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.

builder :

the builder

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.

builder :

the builder

Returns :

the stolen attributes, which should be freed with gck_attributes_unref(). [transfer full]

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.

builder :

the builder

Returns :

the builder

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.

builder :

the builder

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.

builder :

the builder to copy

Returns :

the builder copy, which should be freed with gck_builder_unref(). [transfer full]

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.

builder :

the builder

attr_type :

the type of attribute to find

Returns :

the attribute or NULL if not found

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.

builder :

the builder

attr_type :

the type of attribute to find

value :

the location to place the found value. [out]

Returns :

whether a valid boolean attribute was found

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.

builder :

the builder

attr_type :

the type of attribute to find

value :

the location to place the found value. [out]

Returns :

whether a valid date attribute was found

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.

builder :

the builder

attr_type :

the type of attribute to find

value :

the location to place the found value. [out]

Returns :

whether a valid string attribute was found

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.

builder :

the builder

attr_type :

the type of attribute to find

value :

the location to place the found value. [out]

Returns :

whether a valid unsigned long attribute was found

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

reserved :

Should be set to always be GCK_INVALID

Returns :

a floating reference to the new attributes array; when done with the array release it with gck_attributes_unref(). [transfer none]

gck_attributes_add ()

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

Warning

gck_attributes_add has been deprecated since version 3.4 and should not be used in newly-written code. Use gck_builder_set_all() instead.

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

attrs :

the attributes array to add to

attr :

the attribute to add

Returns :

returns NULL. [transfer none]

gck_attributes_add_all ()

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

Warning

gck_attributes_add_all has been deprecated since version 3.4 and should not be used in newly-written code. Use gck_builder_add_all() instead.

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

attrs :

a set of attributes

from :

attributes to add

gck_attributes_add_boolean ()

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

Warning

gck_attributes_add_boolean has been deprecated since version 3.4 and should not be used in newly-written code. Use gck_builder_add_boolean() instead.

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

attrs :

the attributes array to add to

attr_type :

the type of attribute to add

value :

the boolean value to add

Returns :

returns NULL. [transfer none]

gck_attributes_add_data ()

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

Warning

gck_attributes_add_data has been deprecated since version 3.4 and should not be used in newly-written code. Use gck_builder_add_data() instead.

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

attrs :

The attributes array to add to.

attr_type :

The type of attribute to add.

value :

the raw memory of the attribute value. [array length=length]

length :

The length of the attribute value.

Returns :

returns NULL. [transfer none]

gck_attributes_add_date ()

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

Warning

gck_attributes_add_date has been deprecated since version 3.4 and should not be used in newly-written code. Use gck_builder_add_date() instead.

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

attrs :

the attributes array to add to

attr_type :

the type of attribute to add

value :

the GDate value to add

Returns :

returns NULL. [transfer none]

gck_attributes_add_empty ()

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

Warning

gck_attributes_add_empty has been deprecated since version 3.4 and should not be used in newly-written code. Use gck_builder_add_empty() instead.

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

attrs :

The attributes array to add.

attr_type :

The type of attribute to add.

Returns :

returns NULL. [transfer none]

gck_attributes_add_invalid ()

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

Warning

gck_attributes_add_invalid has been deprecated since version 3.4 and should not be used in newly-written code. Use gck_builder_add_invalid() instead

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

attrs :

The attributes array to add to.

attr_type :

The type of attribute to add.

Returns :

returns NULL. [transfer none]

gck_attributes_add_string ()

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

Warning

gck_attributes_add_string has been deprecated since version 3.4 and should not be used in newly-written code. Use gck_builder_add_string() instead.

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

attrs :

the attributes array to add to

attr_type :

the type of attribute to add

value :

the null terminated string value to add

Returns :

returns NULL. [transfer none]

gck_attributes_add_ulong ()

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

Warning

gck_attributes_add_ulong has been deprecated since version 3.4 and should not be used in newly-written code. Use gck_builder_add_ulong() instead.

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

attrs :

the attributes array to add to

attr_type :

the type of attribute to add

value :

the gulong value to add

Returns :

returns NULL. [transfer none]

gck_attributes_dup ()

GckAttributes *     gck_attributes_dup                  (GckAttributes *attrs);

Warning

gck_attributes_dup has been deprecated since version 3.4 and should not be used in newly-written code. Use gck_attributes_ref() or gck_builder_add_all() instead.

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

attrs :

set of attributes to copy

Returns :

a new floating GckAttributes. [transfer none]

gck_attributes_new_full ()

GckAttributes *     gck_attributes_new_full             (GckAllocator allocator);

Warning

gck_attributes_new_full has been deprecated since version 3.4 and should not be used in newly-written code. Use gck_builder_set_all() instead.

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

allocator :

memory allocator for attribute data, or NULL for default

Returns :

returns NULL

gck_attributes_set ()

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

Warning

gck_attributes_set has been deprecated since version 3.4 and should not be used in newly-written code. Use gck_builder_set_data() instead.

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

attrs :

attributes array to add to

attr :

attribute to set

gck_attributes_set_all ()

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

Warning

gck_attributes_set_all has been deprecated since version 3.4 and should not be used in newly-written code. Use gck_builder_set_all() instead.

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

attrs :

set of attributes

from :

attributes to add

gck_attributes_set_boolean ()

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

Warning

gck_attributes_set_boolean has been deprecated since version 3.4 and should not be used in newly-written code. Use gck_builder_set_boolean() instead.

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

attrs :

the attributes

attr_type :

the type of attribute to set

value :

boolean value to set

gck_attributes_set_date ()

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

Warning

gck_attributes_set_date has been deprecated since version 3.4 and should not be used in newly-written code. Use gck_builder_set_date() instead.

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

attrs :

the attributes

attr_type :

the type of attribute to set

value :

date value to set

gck_attributes_set_string ()

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

Warning

gck_attributes_set_string has been deprecated since version 3.4 and should not be used in newly-written code. Use gck_builder_set_string() instead.

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

attrs :

the attributes

attr_type :

the type of attribute to set

value :

null terminated string value to set

gck_attributes_set_ulong ()

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

Warning

gck_attributes_set_ulong has been deprecated since version 3.4 and should not be used in newly-written code. Use gck_builder_set_ulong() instead.

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

attrs :

the attributes

attr_type :

the type of attribute to set

value :

gulong value to set