GckAttributes: Gck Library Reference Manual

## GckAttributes GckAttributes — A set of PKCS11 attributes. |

## Functions

GckAttributes * | gck_attributes_new_empty ()
const GckAttribute * | gck_attributes_at ()
const GckAttribute * | gck_attributes_find ()
gboolean | gck_attributes_find_boolean ()
gboolean | gck_attributes_find_ulong ()
gboolean | gck_attributes_find_string ()
gboolean | gck_attributes_find_date ()
gulong | gck_attributes_count ()
GckAttributes * | gck_attributes_ref ()
GckAttributes * | gck_attributes_ref_sink ()
void | gck_attributes_unref ()
gboolean | gck_attributes_contains ()
gchar * | gck_attributes_to_string ()
void | gck_attributes_dump ()
void | gck_builder_init ()
void | gck_builder_init_full ()
GckBuilder * | gck_builder_new ()
void | gck_builder_add_boolean ()
void | gck_builder_set_boolean ()
void | gck_builder_add_data ()
void | gck_builder_set_data ()
void | gck_builder_take_data ()
void | gck_builder_add_date ()
void | gck_builder_set_date ()
void | gck_builder_add_string ()
void | gck_builder_set_string ()
void | gck_builder_add_ulong ()
void | gck_builder_set_ulong ()
void | gck_builder_add_empty ()
void | gck_builder_set_empty ()
void | gck_builder_add_invalid ()
void | gck_builder_set_invalid ()
void | gck_builder_add_attribute ()
void | gck_builder_add_all ()
void | gck_builder_set_all ()
void | gck_builder_add_except ()
void | gck_builder_add_exceptv ()
void | gck_builder_add_only ()
void | gck_builder_add_onlyv ()
GckAttributes * | gck_builder_end ()
void | gck_builder_clear ()
GckAttributes * | gck_builder_steal ()
GckBuilder * | gck_builder_ref ()
void | gck_builder_unref ()
GckBuilder * | gck_builder_copy ()
const GckAttribute * | gck_builder_find ()
gboolean | gck_builder_find_boolean ()
gboolean | gck_builder_find_date ()
gboolean | gck_builder_find_string ()
gboolean | gck_builder_find_ulong ()
GckAttributes * | gck_attributes_new ()
GckAttribute * | gck_attributes_add ()
void | gck_attributes_add_all ()
GckAttribute * | gck_attributes_add_boolean ()
GckAttribute * | gck_attributes_add_data ()
GckAttribute * | gck_attributes_add_date ()
GckAttribute * | gck_attributes_add_empty ()
GckAttribute * | gck_attributes_add_invalid ()
GckAttribute * | gck_attributes_add_string ()
GckAttribute * | gck_attributes_add_ulong ()
GckAttributes * | gck_attributes_dup ()
GckAttributes * | gck_attributes_new_full ()
void | gck_attributes_set ()
void | gck_attributes_set_all ()
void | gck_attributes_set_boolean ()
void | gck_attributes_set_date ()
void | gck_attributes_set_string ()
void | gck_attributes_set_ulong ()

## Types and Values

| GckAttributes
struct | GckBuilder
enum | GckBuilderFlags
#define | GCK_BUILDER_INIT

## Object Hierarchy

        GBoxed
        ├── GckAttributes
        ╰── 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.

## Functions

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

attrs | The attributes array to search. |
attr_type | The type of attribute to find. |
value | The resulting gboolean value. | [out]

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

#### Parameters

attrs | The attributes array to search. |
attr_type | The type of attribute to find. |
value | The resulting gulong value. | [out]

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

#### Parameters

attrs | The attributes array to search. |
attr_type | The type of attribute to find. |
value | The resulting string value. | [out]

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

#### Parameters

attrs | The attributes array to search. |
attr_type | The type of attribute to find. |
value | The resulting GDate value. | [out]

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

attrs | the attributes |

#### Returns

a newly allocated string

### gck_attributes_dump ()

    void
    gck_attributes_dump (GckAttributes *attrs);

Dump the attributes using `g_printerr()`.

#### Parameters

attrs | The attributes |

### 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));

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

    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.

[skip]

#### Parameters

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.

    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.

[skip]

#### Parameters

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.

    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.

[skip]

#### Parameters

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.

    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]

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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);

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

#### Parameters

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);

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

#### Parameters

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);

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

#### Parameters

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);

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

#### Parameters

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);

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

#### Parameters

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);

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

#### Parameters

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);

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

#### Parameters

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);

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

#### Parameters

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);

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

#### Parameters

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);

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

#### Parameters

attrs | set of attributes to copy |

#### Returns

a new floating GckAttributes.

[transfer none]

### gck_attributes_new_full ()

    GckAttributes *
    gck_attributes_new_full (GckAllocator allocator);

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

[skip]

#### Parameters

allocator | memory allocator for attribute data, or `NULL` for default |

#### Returns

returns `NULL`

### gck_attributes_set ()

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

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

#### Parameters

attrs | attributes array to add to |
attr | attribute to set |

### gck_attributes_set_all ()

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

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

#### Parameters

attrs | set of attributes |
from | attributes to add |

### gck_attributes_set_boolean ()

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

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

#### Parameters

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);

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

#### Parameters

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);

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

#### Parameters

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);

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

#### Parameters

attrs | the attributes |
attr_type | the type of attribute to set |
value | gulong value to set |

## Types and Values

### GckAttributes

    typedef struct _GckAttributes GckAttributes;

A set of GckAttribute structures.

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

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

#### Members

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.

    1
    GckBuilder builder = GCK_BUILDER_INIT;