Gck.Builder¶

Fields¶

Name	Type	Access	Description
x	[`int`]	r

Methods¶

class	`new` (flags)
	`add_all` (attrs)
	`add_attribute` (attr)
	`add_boolean` (attr_type, value)
	`add_data` (attr_type, value)
	`add_date` (attr_type, value)
	`add_empty` (attr_type)
	`add_invalid` (attr_type)
	`add_only` (attrs, only_types)
	`add_string` (attr_type, value)
	`add_ulong` (attr_type, value)
	`clear` ()
	`copy` ()
	`end` ()
	`find` (attr_type)
	`find_boolean` (attr_type)
	`find_date` (attr_type)
	`find_string` (attr_type)
	`find_ulong` (attr_type)
	`init` ()
	`init_full` (flags)
	`ref` ()
	`set_all` (attrs)
	`set_boolean` (attr_type, value)
	`set_data` (attr_type, value)
	`set_date` (attr_type, value)
	`set_empty` (attr_type)
	`set_invalid` (attr_type)
	`set_string` (attr_type, value)
	`set_ulong` (attr_type, value)
	`take_data` (attr_type, value)
	`unref` ()

Details¶

class Gck.Builder¶

A builder for a set of attributes. Add attributes to a builder, and then use [method`Builder`.end] to get the completed [struct`Attributes`].

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

classmethod new(flags)[source]¶

Parameters:: flags (Gck.BuilderFlags) – flags for the new builder
Returns:: a new builder, to be freed with Gck.Builder.unref()
Return type:: Gck.Builder

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.BuilderFlags.SECURE_MEMORY flag is specified then non-pageable memory will be used for the various values of the attributes in the builder

add_all(attrs)[source]¶

Parameters:: attrs (Gck.Attributes) – the attributes to add

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.

add_attribute(attr)[source]¶

Parameters:: attr (Gck.Attribute) – the attribute to add

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.

add_boolean(attr_type, value)[source]¶

Parameters:

attr_type (int) – the new attribute type
value (bool) – the attribute 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.

add_data(attr_type, value)[source]¶

Parameters:

attr_type (int) – the new attribute type
value (bytes or None) – the new attribute memory

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.

None may be specified for the value argument, in which case an empty attribute is created. [constINVALID] may be specified for the length, in which case an invalid attribute is created in the PKCS#11 style.

add_date(attr_type, value)[source]¶

Parameters:

attr_type (int) – the new attribute type
value (GLib.Date) – the attribute 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.

add_empty(attr_type)[source]¶

Parameters:: attr_type (int) – the new attribute 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.

add_invalid(attr_type)[source]¶

Parameters:: attr_type (int) – the new attribute 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.

add_only(attrs, only_types)[source]¶

Parameters:

attrs (Gck.Attributes) – the attributes to add
only_types ([int]) – the types of attributes to add

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.

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

add_string(attr_type, value)[source]¶

Parameters:

attr_type (int) – the new attribute type
value (str or None) – the attribute value

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

add_ulong(attr_type, value)[source]¶

Parameters:

attr_type (int) – the new attribute type
value (int) – the attribute 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.

clear()[source]¶

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.

copy()[source]¶

Returns:: the builder copy, which should be freed with Gck.Builder.unref().
Return type:: Gck.Builder

Make a copy of the builder and its state. The new builder is allocated with [ctor`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.

end()[source]¶

Returns:: the attributes, which should be freed with Gck.Attributes.unref()
Return type:: Gck.Attributes

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

find(attr_type)[source]¶

Parameters:: attr_type (int) – the type of attribute to find
Returns:: the attribute or None if not found
Return type:: Gck.Attribute

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 [struct`Attribute`] 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.

find_boolean(attr_type)[source]¶

Parameters:

attr_type (int) – the type of attribute to find

Returns:

whether a valid boolean attribute was found

value:: the location to place the found value

Return type:

(bool, value: bool)

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.

find_date(attr_type)[source]¶

Parameters:

attr_type (int) – the type of attribute to find

Returns:

whether a valid date attribute was found

value:: the location to place the found value

Return type:

(bool, value: GLib.Date)

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.

find_string(attr_type)[source]¶

Parameters:

attr_type (int) – the type of attribute to find

Returns:

whether a valid string attribute was found

value:: the location to place the found value

Return type:

(bool, value: str)

Find a string attribute in the builder that has the type attr_type, has a non None 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.

find_ulong(attr_type)[source]¶

Parameters:

attr_type (int) – the type of attribute to find

Returns:

whether a valid unsigned long attribute was found

value:: the location to place the found value

Return type:

(bool, value: int)

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.

init()[source]¶

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.

```c // Equivalent ways of initializing a Gck.Builder Gck.Builder builder = GCK_BUILDER_INIT; Gck.Builder builder2; Gck.Builder builder3;

Gck.Builder.init (&builder2);

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

init_full(flags)[source]¶

Parameters:: flags (Gck.BuilderFlags) – the flags for the new builder

Initialize a stack allocated builder, with the appropriate flags.

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

ref()[source]¶

Returns:: the builder
Return type:: Gck.Builder

Add a reference to a builder that was created with [ctor`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.

set_all(attrs)[source]¶

Parameters:: attrs (Gck.Attributes) – the attributes to set

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.

set_boolean(attr_type, value)[source]¶

Parameters:

attr_type (int) – the new attribute type
value (bool) – the attribute 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.

set_data(attr_type, value)[source]¶

Parameters:

attr_type (int) – the attribute type
value (bytes or None) – the new attribute memory

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.

None may be specified for the value argument, in which case an empty attribute is created. [constINVALID] may be specified for the length, in which case an invalid attribute is created in the PKCS#11 style.

set_date(attr_type, value)[source]¶

Parameters:

attr_type (int) – the new attribute type
value (GLib.Date) – the attribute 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.

set_empty(attr_type)[source]¶

Parameters:: attr_type (int) – the attribute 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.

set_invalid(attr_type)[source]¶

Parameters:: attr_type (int) – the attribute 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.

set_string(attr_type, value)[source]¶

Parameters:

attr_type (int) – the new attribute type
value (str) – the attribute value

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

set_ulong(attr_type, value)[source]¶

Parameters:

attr_type (int) – the new attribute type
value (int) – the attribute 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.

take_data(attr_type, value)[source]¶

Parameters:

attr_type (int) – the new attribute type
value (bytes or None) – the new attribute memory

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 GLib.free(). The memory must have been allocated using the standard GLib memory allocation routines.

None may be specified for the value argument, in which case an empty attribute is created. [constINVALID] may be specified for the length, in which case an invalid attribute is created in the PKCS#11 style.

unref()[source]¶

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.