GckAttribute: Gck Library Reference Manual

## GckAttribute GckAttribute — A PKCS11 attribute. |

## Functions

gboolean | gck_attribute_is_invalid ()
gboolean | gck_attribute_get_boolean ()
gulong | gck_attribute_get_ulong ()
gchar * | gck_attribute_get_string ()
void | gck_attribute_get_date ()
const guchar * | gck_attribute_get_data ()
void | gck_attribute_dump ()
gboolean | gck_attribute_equal ()
guint | gck_attribute_hash ()
void | gck_attribute_init ()
void | gck_attribute_init_boolean ()
void | gck_attribute_init_date ()
void | gck_attribute_init_string ()
void | gck_attribute_init_ulong ()
void | gck_attribute_init_empty ()
void | gck_attribute_init_invalid ()
void | gck_attribute_init_copy ()
GckAttribute * | gck_attribute_new ()
GckAttribute * | gck_attribute_new_boolean ()
GckAttribute * | gck_attribute_new_date ()
GckAttribute * | gck_attribute_new_string ()
GckAttribute * | gck_attribute_new_ulong ()
GckAttribute * | gck_attribute_new_empty ()
GckAttribute * | gck_attribute_new_invalid ()
GckAttribute * | gck_attribute_dup ()
void | gck_attribute_clear ()
void | gck_attribute_free ()

## Types and Values

struct | GckAttribute

## Description

This structure represents a PKCS11 CK_ATTRIBUTE. These attributes contain i about a PKCS11 object. Use `gck_object_get()` or `gck_object_set()` to set and attributes on an object.

Although you are free to allocate a GckAttribute in your own code, no functions in this library will operate on such an attribute.

## Functions

### gck_attribute_is_invalid ()

    gboolean
    gck_attribute_is_invalid (const GckAttribute *attr);

Check if the PKCS#11 attribute represents 'invalid' or 'not found' according to the PKCS#11 spec. That is, having length of (CK_ULONG)-1.

#### Parameters

attr | The attribute to check. |

#### Returns

Whether the attribute represents invalid or not.

### gck_attribute_get_boolean ()

    gboolean
    gck_attribute_get_boolean (const GckAttribute *attr);

Get the CK_BBOOL of a PKCS#11 attribute. No conversion is performed. It is an error to pass an attribute to this function unless you're know it's supposed to contain a boolean value.

#### Parameters

attr | The attribute to retrieve value from. |

#### Returns

The boolean value of the attribute.

### gck_attribute_get_ulong ()

    gulong
    gck_attribute_get_ulong (const GckAttribute *attr);

Get the CK_ULONG value of a PKCS#11 attribute. No conversion is performed. It is an error to pass an attribute to this function unless you're know it's supposed to contain a value of the right type.

#### Parameters

attr | The attribute to retrieve value from. |

#### Returns

The ulong value of the attribute.

### gck_attribute_get_string ()

    gchar *
    gck_attribute_get_string (const GckAttribute *attr);

Get the string value of a PKCS#11 attribute. No conversion is performed. It is an error to pass an attribute to this function unless you're know it's supposed to contain a value of the right type.

#### Parameters

attr | The attribute to retrieve value from. |

#### Returns

a null terminated string, to be freed with `g_free()`, or `NULL` if the value was invalid.

[allow-none]

### gck_attribute_get_date ()

    void
    gck_attribute_get_date (const GckAttribute *attr,
                            GDate *value);

Get the CK_DATE of a PKCS#11 attribute. No conversion is performed. It is an error to pass an attribute to this function unless you're know it's supposed to contain a value of the right type.

#### Parameters

attr | The attribute to retrieve value from. |
value | The date value to fill in with the parsed date. |

### gck_attribute_get_data ()

    const guchar *
    gck_attribute_get_data (const GckAttribute *attr,
                            gsize *length);

Get the raw value in the attribute.

This is useful from scripting languages. C callers will generally access the GckAttribute struct directly.

This function will `NULL` if the attribute contains empty or invalid data. The returned data must not be modified and is only valid as long as this `attribute` .

#### Parameters

attr | an attribute |
length | the length of the returned data |

#### Returns

the value data or `NULL`.

[transfer none][array length=length]

### gck_attribute_dump ()

    void
    gck_attribute_dump (const GckAttribute *attr);

Dump the specified attribute using `g_printerr()`.

#### Parameters

attr | The attribute |

### gck_attribute_equal ()

    gboolean
    gck_attribute_equal (gconstpointer attr1,
                         gconstpointer attr2);

Compare two attributes. Useful with `GHashTable`.

#### Parameters

attr1 | first attribute to compare. | [type Gck.Attribute]
attr2 | second attribute to compare. | [type Gck.Attribute]

#### Returns

`TRUE` if the attributes are equal.

### gck_attribute_hash ()

    guint
    gck_attribute_hash (gconstpointer attr);

Hash an attribute for use in `GHashTable` keys.

#### Parameters

attr | attribute to hash. | [type Gck.Attribute]

#### Returns

the hash code

### gck_attribute_init ()

    void
    gck_attribute_init (GckAttribute *attr,
                        gulong attr_type,
                        const guchar *value,
                        gsize length);

Initialize a PKCS#11 attribute. This copies the value memory into an internal buffer.

When done with the attribute you should use `gck_attribute_clear()` to free the internal memory.

[skip]

#### Parameters

attr | an uninitialized attribute |
attr_type | the PKCS#11 attribute type to set on the attribute |
value | The raw value of the attribute. | [array length=length]
length | The length of the raw value. |

### gck_attribute_init_boolean ()

    void
    gck_attribute_init_boolean (GckAttribute *attr,
                                gulong attr_type,
                                gboolean value);

Initialize a PKCS#11 attribute to boolean. This will result in a CK_BBOOL attribute from the PKCS#11 specs.

When done with the attribute you should use `gck_attribute_clear()` to free the internal memory.

[skip]

#### Parameters

attr | an uninitialized attribute |
attr_type | the PKCS#11 attribute type to set on the attribute |
value | the boolean value of the attribute |

### gck_attribute_init_date ()

    void
    gck_attribute_init_date (GckAttribute *attr,
                             gulong attr_type,
                             const GDate *value);

Initialize a PKCS#11 attribute to a date. This will result in a CK_DATE attribute from the PKCS#11 specs.

When done with the attribute you should use `gck_attribute_clear()` to free the internal memory.

[skip]

#### Parameters

attr | an uninitialized attribute |
attr_type | the PKCS#11 attribute type to set on the attribute |
value | the date value of the attribute |

### gck_attribute_init_string ()

    void
    gck_attribute_init_string (GckAttribute *attr,
                               gulong attr_type,
                               const gchar *value);

Initialize a PKCS#11 attribute to a string. This will result in an attribute containing the text, but not the null terminator. The text in the attribute will be of the same encoding as you pass to this function.

When done with the attribute you should use `gck_attribute_clear()` to free the internal memory.

[skip]

#### Parameters

attr | an uninitialized attribute |
attr_type | the PKCS#11 attribute type to set on the attribute |
value | the null terminated string value of the attribute |

### gck_attribute_init_ulong ()

    void
    gck_attribute_init_ulong (GckAttribute *attr,
                              gulong attr_type,
                              gulong value);

Initialize a PKCS#11 attribute to a unsigned long. This will result in a CK_ULONG attribute from the PKCS#11 specs.

When done with the attribute you should use `gck_attribute_clear()` to free the internal memory.

[skip]

#### Parameters

attr | an uninitialized attribute |
attr_type | the PKCS#11 attribute type to set on the attribute |
value | the ulong value of the attribute |

### gck_attribute_init_empty ()

    void
    gck_attribute_init_empty (GckAttribute *attr,
                              gulong attr_type);

Initialize a PKCS#11 attribute to an empty state. The attribute type will be set, but no data will be set.

When done with the attribute you should use `gck_attribute_clear()` to free the internal memory.

[skip]

#### Parameters

attr | an uninitialized attribute |
attr_type | the PKCS#11 attribute type to set on the attribute |

### gck_attribute_init_invalid ()

    void
    gck_attribute_init_invalid (GckAttribute *attr,
                                gulong attr_type);

Initialize a PKCS#11 attribute to an 'invalid' or 'not found' state. Specifically this sets the value length to (CK_ULONG)-1 as specified in the PKCS#11 specification.

When done with the attribute you should use `gck_attribute_clear()` to free the internal memory.

[skip]

#### Parameters

attr | an uninitialized attribute |
attr_type | the PKCS#11 attribute type to set on the attribute |

### gck_attribute_init_copy ()

    void
    gck_attribute_init_copy (GckAttribute *dest,
                             const GckAttribute *src);

Initialize a PKCS#11 attribute as a copy of another attribute. This copies the value memory as well.

When done with the copied attribute you should use `gck_attribute_clear()` to free the internal memory.

#### Parameters

dest | An uninitialized attribute. |
src | An attribute to copy. |

### gck_attribute_new ()

    GckAttribute *
    gck_attribute_new (gulong attr_type,
                       const guchar *value,
                       gsize length);

Create a new PKCS#11 attribute. The value will be copied into the new attribute.

#### Parameters

attr_type | the PKCS#11 attribute type to set on the attribute |
value | the raw value of the attribute |
length | the length of the attribute |

#### Returns

the new attribute; when done with the attribute use `gck_attribute_free()` to free it.

[transfer full]

### gck_attribute_new_boolean ()

    GckAttribute *
    gck_attribute_new_boolean (gulong attr_type,
                               gboolean value);

Initialize a PKCS#11 attribute to boolean. This will result in a CK_BBOOL attribute from the PKCS#11 specs.

#### Parameters

attr_type | the PKCS#11 attribute type to set on the attribute |
value | the boolean value of the attribute |

#### Returns

the new attribute; when done with the attribute u `gck_attribute_free()` to free it.

[transfer full]

### gck_attribute_new_date ()

    GckAttribute *
    gck_attribute_new_date (gulong attr_type,
                            const GDate *value);

Initialize a PKCS#11 attribute to a date. This will result in a CK_DATE attribute from the PKCS#11 specs.

#### Parameters

attr_type | the PKCS#11 attribute type to set on the attribute |
value | the date value of the attribute |

#### Returns

the new attribute; when done with the attribute u `gck_attribute_free()` to free it.

[transfer full]

### gck_attribute_new_string ()

    GckAttribute *
    gck_attribute_new_string (gulong attr_type,
                              const gchar *value);

Initialize a PKCS#11 attribute to a string. This will result in an attribute containing the text, but not the null terminator. The text in the attribute will be of the same encoding as you pass to this function.

#### Parameters

attr_type | the PKCS#11 attribute type to set on the attribute |
value | the null-terminated string value of the attribute |

#### Returns

the new attribute; when done with the attribute u `gck_attribute_free()` to free it.

[transfer full]

### gck_attribute_new_ulong ()

    GckAttribute *
    gck_attribute_new_ulong (gulong attr_type,
                             gulong value);

Initialize a PKCS#11 attribute to a unsigned long. This will result in a CK_ULONG attribute from the PKCS#11 specs.

#### Parameters

attr_type | the PKCS#11 attribute type to set on the attribute |
value | the ulong value of the attribute |

#### Returns

the new attribute; when done with the attribute u `gck_attribute_free()` to free it.

[transfer full]

### gck_attribute_new_empty ()

    GckAttribute *
    gck_attribute_new_empty (gulong attr_type);

Create a new PKCS#11 attribute with empty data.

#### Parameters

attr_type | the PKCS#11 attribute type to set on the attribute |

#### Returns

the new attribute; when done with the attribute use `gck_attribute_free()` to free it.

[transfer full]

### gck_attribute_new_invalid ()

    GckAttribute *
    gck_attribute_new_invalid (gulong attr_type);

Create a new PKCS#11 attribute as 'invalid' or 'not found' state. Specifically this sets the value length to (CK_ULONG)-1 as specified in the PKCS#11 specification.

#### Parameters

attr_type | the PKCS#11 attribute type to set on the attribute |

#### Returns

the new attribute; when done with the attribute use `gck_attribute_free()` to free it.

[transfer full]

### gck_attribute_dup ()

    GckAttribute *
    gck_attribute_dup (const GckAttribute *attr);

Duplicate the PKCS#11 attribute. All value memory is also copied.

The `attr` must have been allocated or initialized by a Gck function or the results of this function are undefined.

#### Parameters

attr | the attribute to duplicate |

#### Returns

the duplicated attribute; use `gck_attribute_free()` to free it.

[transfer full]

### gck_attribute_clear ()

    void
    gck_attribute_clear (GckAttribute *attr);

Clear allocated memory held by a GckAttribute.

This attribute must have been allocated by a Gck library function, or the results of this method are undefined.

The type of the attribute will remain set.

#### Parameters

attr | Attribute to clear. |

### gck_attribute_free ()

    void
    gck_attribute_free (gpointer attr);

Free an attribute and its allocated memory. These is usually used with attributes that are allocated by `gck_attribute_new()` or a similar function.

#### Parameters

attr | attribute to free. | [type Gck.Attribute]

## Types and Values

### struct GckAttribute

    struct GckAttribute {
    	gulong type;
    	guchar *value;
    	gulong length;
    };

This structure represents a PKCS11 CK_ATTRIBUTE.

#### Members

gulong `type`; | The attribute type, such as CKA_LABEL. |
guchar *`value`; | The value of the attribute. May be NULL. | [array length=length]
gulong `length`; | The length of the attribute. May be GCK_INVALID if the attribute is invalid. |