GP11Attribute
3
GP11 Library

# GP11Attribute

A PKCS11 attribute.

## Synopsis

                        GP11Attribute;
    void                gp11_attribute_init                 (GP11Attribute *attr,
                                                             gulong attr_type,
                                                             gconstpointer value,
                                                             gsize length);
    void                gp11_attribute_init_invalid         (GP11Attribute *attr,
                                                             gulong attr_type);
    void                gp11_attribute_init_empty           (GP11Attribute *attr,
                                                             gulong attr_type);
    void                gp11_attribute_init_boolean         (GP11Attribute *attr,
                                                             gulong attr_type,
                                                             gboolean value);
    void                gp11_attribute_init_date            (GP11Attribute *attr,
                                                             gulong attr_type,
                                                             const GDate *value);
    void                gp11_attribute_init_ulong           (GP11Attribute *attr,
                                                             gulong attr_type,
                                                             gulong value);
    void                gp11_attribute_init_string          (GP11Attribute *attr,
                                                             gulong attr_type,
                                                             const gchar *value);
    void                gp11_attribute_init_copy            (GP11Attribute *dest,
                                                             const GP11Attribute *src);
    GP11Attribute*      gp11_attribute_new                  (gulong attr_type,
                                                             gpointer value,
                                                             gsize length);
    GP11Attribute*      gp11_attribute_new_invalid          (gulong attr_type);
    GP11Attribute*      gp11_attribute_new_empty            (gulong attr_type);
    GP11Attribute*      gp11_attribute_new_boolean          (gulong attr_type,
                                                             gboolean value);
    GP11Attribute*      gp11_attribute_new_date             (gulong attr_type,
                                                             const GDate *value);
    GP11Attribute*      gp11_attribute_new_ulong            (gulong attr_type,
                                                             gulong value);
    GP11Attribute*      gp11_attribute_new_string           (gulong attr_type,
                                                             const gchar *value);
    gboolean            gp11_attribute_is_invalid           (GP11Attribute *attr);
    gboolean            gp11_attribute_get_boolean          (GP11Attribute *attr);
    gulong              gp11_attribute_get_ulong            (GP11Attribute *attr);
    gchar*              gp11_attribute_get_string           (GP11Attribute *attr);
    void                gp11_attribute_get_date             (GP11Attribute *attr,
                                                             GDate *value);
    GP11Attribute*      gp11_attribute_dup                  (GP11Attribute *attr);
    void                gp11_attribute_clear                (GP11Attribute *attr);
    void                gp11_attribute_free                 (GP11Attribute *attr);

## Description

This structure represents a PKCS11 CK_ATTRIBUTE. These attributes contain information about a PKCS11 object. Use `gp11_object_get()` or `gp11_object_set()` to set and retrieve attributes on an object.

## Details

### GP11Attribute

    typedef struct {
    	gulong type;
    	guchar *value;
    	gulong length;
    } GP11Attribute;

This structure represents a PKCS11 CK_ATTRIBUTE.

gulong type;

  The attribute type, such as CKA_LABEL.

guchar *value;

  The value of the attribute. May be NULL.

gulong length;

  The length of the attribute. May be G_MAXULONG if the attribute is invalid.

### gp11_attribute_init ()

    void                gp11_attribute_init                 (GP11Attribute *attr,
                                                             gulong attr_type,
                                                             gconstpointer value,
                                                             gsize length);

Initialize a PKCS11 attribute. This copies the value memory into an internal buffer.

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

`attr` :

  An uninitialized attribute.

`attr_type` :

  The PKCS11 attribute type to set on the attribute.

`value` :

  The raw value of the attribute.

`length` :

  The length of the raw value.

### gp11_attribute_init_invalid ()

    void                gp11_attribute_init_invalid         (GP11Attribute *attr,
                                                             gulong attr_type);

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

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

`attr` :

  An uninitialized attribute.

`attr_type` :

  The PKCS11 attribute type to set on the attribute.

### gp11_attribute_init_empty ()

    void                gp11_attribute_init_empty           (GP11Attribute *attr,
                                                             gulong attr_type);

Initialize a PKCS11 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 `gp11_attribute_clear()` to free the internal memory.

`attr` :

  An uninitialized attribute.

`attr_type` :

  The PKCS11 attribute type to set on the attribute.

### gp11_attribute_init_boolean ()

    void                gp11_attribute_init_boolean         (GP11Attribute *attr,
                                                             gulong attr_type,
                                                             gboolean value);

Initialize a PKCS11 attribute to boolean. This will result in a CK_BBOOL attribute from the PKCS11 specs.

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

`attr` :

  An uninitialized attribute.

`attr_type` :

  The PKCS11 attribute type to set on the attribute.

`value` :

  The boolean value of the attribute.

### gp11_attribute_init_date ()

    void                gp11_attribute_init_date            (GP11Attribute *attr,
                                                             gulong attr_type,
                                                             const GDate *value);

Initialize a PKCS11 attribute to a date. This will result in a CK_DATE attribute from the PKCS11 specs.

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

`attr` :

  An uninitialized attribute.

`attr_type` :

  The PKCS11 attribute type to set on the attribute.

`value` :

  The date value of the attribute.

### gp11_attribute_init_ulong ()

    void                gp11_attribute_init_ulong           (GP11Attribute *attr,
                                                             gulong attr_type,
                                                             gulong value);

Initialize a PKCS11 attribute to a unsigned long. This will result in a CK_ULONG attribute from the PKCS11 specs.

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

`attr` :

  An uninitialized attribute.

`attr_type` :

  The PKCS11 attribute type to set on the attribute.

`value` :

  The ulong value of the attribute.

### gp11_attribute_init_string ()

    void                gp11_attribute_init_string          (GP11Attribute *attr,
                                                             gulong attr_type,
                                                             const gchar *value);

Initialize a PKCS11 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 `gp11_attribute_clear()` to free the internal memory.

`attr` :

  An uninitialized attribute.

`attr_type` :

  The PKCS11 attribute type to set on the attribute.

`value` :

  The null terminated string value of the attribute.

### gp11_attribute_init_copy ()

    void                gp11_attribute_init_copy            (GP11Attribute *dest,
                                                             const GP11Attribute *src);

Initialize a PKCS11 attribute as a copy of another attribute. This copies the value memory as well.

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

`dest` :

  An uninitialized attribute.

`src` :

  An attribute to copy.

### gp11_attribute_new ()

    GP11Attribute*      gp11_attribute_new                  (gulong attr_type,
                                                             gpointer value,
                                                             gsize length);

Create a new PKCS11 attribute. The value will be copied into the new attribute.

`attr_type` :

  The PKCS11 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 `gp11_attribute_free()` to free it.

### gp11_attribute_new_invalid ()

    GP11Attribute*      gp11_attribute_new_invalid          (gulong attr_type);

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

`attr_type` :

  The PKCS11 attribute type to set on the attribute.

Returns :

  The new attribute. When done with the attribute use `gp11_attribute_free()` to free it.

### gp11_attribute_new_empty ()

    GP11Attribute*      gp11_attribute_new_empty            (gulong attr_type);

Create a new PKCS11 attribute with empty data.

`attr_type` :

  The PKCS11 attribute type to set on the attribute.

Returns :

  The new attribute. When done with the attribute use `gp11_attribute_free()` to free it.

### gp11_attribute_new_boolean ()

    GP11Attribute*      gp11_attribute_new_boolean          (gulong attr_type,
                                                             gboolean value);

Initialize a PKCS11 attribute to boolean. This will result in a CK_BBOOL attribute from the PKCS11 specs.

`attr_type` :

  The PKCS11 attribute type to set on the attribute.

`value` :

  The boolean value of the attribute.

Returns :

  The new attribute. When done with the attribute use `gp11_attribute_free()` to free it.

### gp11_attribute_new_date ()

    GP11Attribute*      gp11_attribute_new_date             (gulong attr_type,
                                                             const GDate *value);

Initialize a PKCS11 attribute to a date. This will result in a CK_DATE attribute from the PKCS11 specs.

`attr_type` :

  The PKCS11 attribute type to set on the attribute.

`value` :

  The date value of the attribute.

Returns :

  The new attribute. When done with the attribute use `gp11_attribute_free()` to free it.

### gp11_attribute_new_ulong ()

    GP11Attribute*      gp11_attribute_new_ulong            (gulong attr_type,
                                                             gulong value);

Initialize a PKCS11 attribute to a unsigned long. This will result in a CK_ULONG attribute from the PKCS11 specs.

`attr_type` :

  The PKCS11 attribute type to set on the attribute.

`value` :

  The ulong value of the attribute.

Returns :

  The new attribute. When done with the attribute use `gp11_attribute_free()` to free it.

### gp11_attribute_new_string ()

    GP11Attribute*      gp11_attribute_new_string           (gulong attr_type,
                                                             const gchar *value);

Initialize a PKCS11 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.

`attr_type` :

  The PKCS11 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 use `gp11_attribute_free()` to free it.

### gp11_attribute_is_invalid ()

    gboolean            gp11_attribute_is_invalid           (GP11Attribute *attr);

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

`attr` :

  The attribute to check.

Returns :

  Whether the attribute represents invalid or not.

### gp11_attribute_get_boolean ()

    gboolean            gp11_attribute_get_boolean          (GP11Attribute *attr);

Get the CK_BBOOL of a PKCS11 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.

`attr` :

  The attribute to retrieve value from.

Returns :

  The boolean value of the attribute.

### gp11_attribute_get_ulong ()

    gulong              gp11_attribute_get_ulong            (GP11Attribute *attr);

Get the CK_ULONG value of a PKCS11 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.

`attr` :

  The attribute to retrieve value from.

Returns :

  The ulong value of the attribute.

### gp11_attribute_get_string ()

    gchar*              gp11_attribute_get_string           (GP11Attribute *attr);

Get the string value of a PKCS11 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.

`attr` :

  The attribute to retrieve value from.

Returns :

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

### gp11_attribute_get_date ()

    void                gp11_attribute_get_date             (GP11Attribute *attr,
                                                             GDate *value);

Get the CK_DATE of a PKCS11 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.

`attr` :

  The attribute to retrieve value from.

`value` :

  The date value to fill in with the parsed date.

### gp11_attribute_dup ()

    GP11Attribute*      gp11_attribute_dup                  (GP11Attribute *attr);

Duplicate the PKCS11 attribute. All value memory is also copied.

`attr` :

  The attribute to duplicate.

Returns :

  The duplicated attribute. Use `gp11_attribute_free()` to free it.

### gp11_attribute_clear ()

    void                gp11_attribute_clear                (GP11Attribute *attr);

Clear allocated memory held by a statically allocated attribute. These are usually initialized with `gp11_attribute_init()` or a similar function.

The type of the attribute will remain set.

`attr` :

  Attribute to clear.

### gp11_attribute_free ()

    void                gp11_attribute_free                 (GP11Attribute *attr);

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

`attr` :

  Attribute to free.