Functions

	data_error_get_domain ()
	fingerprint_from_attributes (attrs, checksum_type)
	fingerprint_from_subject_public_key_info (key_info, checksum_type)
	importer_create_for_parsed (parsed)
	importer_queue_and_filter_for_parsed (importers, parsed)
	importer_register (importer_type, attrs)
	importer_register_well_known ()
	mock_prompter_disconnect ()
	mock_prompter_expect_close ()
	mock_prompter_expect_confirm_cancel ()
	mock_prompter_expect_password_cancel ()
	mock_prompter_get_delay_msec ()
	mock_prompter_is_expecting ()
	mock_prompter_is_prompting ()
	mock_prompter_set_delay_msec (delay_msec)
	mock_prompter_start ()
	mock_prompter_stop ()
	parsed_unref (parsed)
	pkcs11_add_module (module)
	pkcs11_add_module_from_file (module_path, unused)
	pkcs11_get_modules ()
	pkcs11_get_trust_lookup_slots ()
	pkcs11_get_trust_lookup_uris ()
	pkcs11_get_trust_store_slot ()
	pkcs11_get_trust_store_uri ()
	pkcs11_initialize (cancellable)
	pkcs11_initialize_async (cancellable, callback, *user_data)
	pkcs11_initialize_finish (result)
	pkcs11_set_modules (modules)
	pkcs11_set_trust_lookup_uris (pkcs11_uris)
	pkcs11_set_trust_store_uri (pkcs11_uri)
	trust_add_pinned_certificate (certificate, purpose, peer, cancellable)
	trust_add_pinned_certificate_async (certificate, purpose, peer, cancellable, callback, *user_data)
	trust_add_pinned_certificate_finish (result)
	trust_is_certificate_anchored (certificate, purpose, cancellable)
	trust_is_certificate_anchored_async (certificate, purpose, cancellable, callback, *user_data)
	trust_is_certificate_anchored_finish (result)
	trust_is_certificate_distrusted (serial_nr, issuer, cancellable)
	trust_is_certificate_distrusted_async (serial_nr, issuer, cancellable, callback, *user_data)
	trust_is_certificate_distrusted_finish (result)
	trust_is_certificate_pinned (certificate, purpose, peer, cancellable)
	trust_is_certificate_pinned_async (certificate, purpose, peer, cancellable, callback, *user_data)
	trust_is_certificate_pinned_finish (result)
	trust_remove_pinned_certificate (certificate, purpose, peer, cancellable)
	trust_remove_pinned_certificate_async (certificate, purpose, peer, cancellable, callback, *user_data)
	trust_remove_pinned_certificate_finish (result)

Details

Gcr.data_error_get_domain()

Return type:

int

Gcr.fingerprint_from_attributes(attrs, checksum_type)

Parameters:

• attrs (Gck.Attributes) – attributes for key or certificate

• checksum_type (GLib.ChecksumType) – the type of fingerprint to create

Returns:

the fingerprint or None if the input was invalid.

Return type:

bytes or None

Create a key fingerprint for a certificate, public key or private key. Note that this is not a fingerprint of certificate data, which you would use Gcr.Certificate.get_fingerprint() for.

Gcr.fingerprint_from_subject_public_key_info(key_info, checksum_type)

Parameters:

• key_info (bytes) – DER encoded subjectPublicKeyInfo structure

• checksum_type (GLib.ChecksumType) – the type of fingerprint to create

Returns:

the fingerprint or None if the input was invalid.

Return type:

bytes or None

Create a key fingerprint for a DER encoded subjectPublicKeyInfo. The fingerprint is created so that it will be identical for a key and its corresponding certificate.

Note that in the case of certificates this is not a fingerprint of the actual certificate data, but rather of the public key contained in a certificate.

Gcr.importer_create_for_parsed(parsed)

Parameters:

parsed (Gcr.Parsed) – a parser with a parsed item to import

Returns:

a list of importers which can import the parsed item, which should be freed with GObject.Object.unref(), or None if no types of importers can be created

Return type:

[Gcr.Importer]

Create a set of importers which can import this parsed item. The parsed item is represented by the state of the Gcr.Parser at the time of calling this method.

Gcr.importer_queue_and_filter_for_parsed(importers, parsed)

Parameters:

• importers ([Gcr.Importer]) – a set of importers

• parsed (Gcr.Parsed) – a parsed item

Returns:

a new set of importers that queued the item.

Return type:

[Gcr.Importer]

Queues an additional item to be imported in all compattible importers in the set. The parsed item is represented by the state of the Gcr.Parser at the time of calling this method.

If the parsed item is incompatible with an importer, then that the item will not be queued on that importer.

Gcr.importer_register(importer_type, attrs)

Parameters:

• importer_type (GObject.GType) – the GObject.GType of the importer being registered

• attrs (Gck.Attributes) – the attributes that this importer is compatible with

Register an importer to handle parsed items that match the given attributes.

Gcr.importer_register_well_known()

Register built-in PKCS#11 and GnuPG importers.

Gcr.mock_prompter_disconnect()

Disconnect the mock prompter

Gcr.mock_prompter_expect_close()

Queue an expected response on the mock prompter.

Expects any prompt, and closes the prompt when it gets it.

Gcr.mock_prompter_expect_confirm_cancel()

Queue an expected response on the mock prompter.

Expects a confirmation prompt, and then cancels that prompt.

Gcr.mock_prompter_expect_password_cancel()

Queue an expected response on the mock prompter.

Expects a password prompt, and then cancels that prompt.

Gcr.mock_prompter_get_delay_msec()

Returns:

the delay

Return type:

int

Get the delay in milliseconds before the mock prompter completes an expected prompt.

Gcr.mock_prompter_is_expecting()

Returns:

whether expecting a prompt

Return type:

bool

Check if the mock prompter is expecting a response. This will be True when one of the gcr_mock_prompter_expect_xxx() functions have been used to queue an expected prompt, but that prompt response has not be ‘used’ yet.

Gcr.mock_prompter_is_prompting()

Returns:

whether prompting

Return type:

bool

Check if the mock prompter is showing any prompts.

Gcr.mock_prompter_set_delay_msec(delay_msec)

Parameters:

delay_msec (int) – prompt response delay in milliseconds

Set the delay in milliseconds before the mock prompter completes an expected prompt.

Gcr.mock_prompter_start()

Returns:

the bus name that the mock prompter is listening on

Return type:

str

Start the mock prompter. This is often used from the setup() function of tests.

Starts the mock prompter in an additional thread. Use the returned DBus bus name with Gcr.SystemPrompt.open_for_prompter() to connect to this prompter.

Gcr.mock_prompter_stop()

Stop the mock prompter. This is often used from the teardown() function of tests.

Gcr.parsed_unref(parsed)

Parameters:

parsed (object or None) – a parsed item

Unreferences a parsed item which was referenced with Gcr.Parsed.ref()

Gcr.pkcs11_add_module(module)

Parameters:

module (Gck.Module) – a Gck.Module

Add a Gck.Module to the list of PKCS#11 modules that are used by the GCR library.

It is not normally necessary to call this function. The available PKCS#11 modules installed on the system are automatically loaded by the GCR library.

Gcr.pkcs11_add_module_from_file(module_path, unused)

Parameters:

• module_path (str) – the full file path of the PKCS#11 module

• unused (object or None) – unused

Raises:

GLib.Error

Returns:

whether the module was sucessfully added.

Return type:

bool

Initialize a PKCS#11 module and add it to the modules that are used by the GCR library. Note that is an error to initialize the same PKCS#11 module twice.

It is not normally necessary to call this function. The available PKCS#11 modules installed on the system are automatically loaded by the GCR library.

Gcr.pkcs11_get_modules()

Returns:

a newly allocated list of Gck.Module objects

Return type:

[Gck.Module]

List all the PKCS#11 modules that are used by the GCR library. Each module is a [class`Gck`.Module] object.

An empty list of modules will be returned if [func`pkcs11_set_modules`], or [func`pkcs11_initialize`] has not yet run.

Gcr.pkcs11_get_trust_lookup_slots()

Returns:

a list of Gck.Slot objects to use for lookup of trust, or the empty list if not initialized or no appropriate trust stores could be found.

Return type:

[Gck.Slot]

List all the PKCS#11 slots that are used by the GCR library for lookup of trust assertions. Each slot is a [class`Gck`.Slot] object.

This will return an empty list if the [func`pkcs11_initialize`] function has not yet been called.

Gcr.pkcs11_get_trust_lookup_uris()

Returns:

the uri which identifies trust storage slot

Return type:

[str] or None

Get the PKCS#11 URIs that are used to identify which slots to use for lookup trust assertions.

Gcr.pkcs11_get_trust_store_slot()

Returns:

the Gck.Slot to use for trust assertions, or null if not initialized or no appropriate trust store could be found.

Return type:

Gck.Slot or None

Selects an appropriate PKCS#11 slot to store trust assertions. The slot to use is normally configured automatically by the system.

This will only return a valid result after the [func`pkcs11_initialize`] method has been called.

When done with the Gck.Slot, use GObject.Object.unref() to release it.

Gcr.pkcs11_get_trust_store_uri()

Returns:

the uri which identifies trust storage slot

Return type:

str or None

Get the PKCS#11 URI that is used to identify which slot to use for storing trust storage.

Gcr.pkcs11_initialize(cancellable)

Parameters:

cancellable (Gio.Cancellable or None) – optional cancellable used to cancel the operation

Raises:

GLib.Error

Returns:

whether the operation was successful or not.

Return type:

bool

Asynchronously initialize the registered PKCS#11 modules.

Gcr.pkcs11_initialize_async(cancellable, callback, *user_data)

Parameters:

• cancellable (Gio.Cancellable or None) – optional cancellable used to cancel the operation

• callback (Gio.AsyncReadyCallback or None) – callback which will be called when the operation completes

• user_data (object or None) – data passed to the callback

Asynchronously initialize the registered PKCS#11 modules.

Gcr.pkcs11_initialize_finish(result)

Parameters:

result (Gio.AsyncResult) – the asynchronous result

Raises:

GLib.Error

Returns:

whether the operation was successful or not.

Return type:

bool

Complete the asynchronous operation to initialize the registered PKCS#11 modules.

Gcr.pkcs11_set_modules(modules)

Parameters:

modules ([Gck.Module]) – a list of PKCS#11 modules

Set the list of PKCS#11 modules that are used by the GCR library. Each module in the list is a [class`Gck`.Module] object.

It is not normally necessary to call this function. The available PKCS#11 modules installed on the system are automatically loaded by the GCR library.

Gcr.pkcs11_set_trust_lookup_uris(pkcs11_uris)

Parameters:

pkcs11_uris (str or None) – the uris which identifies trust lookup slots

Set the PKCS#11 URIs that are used to identify which slots to use for lookup of trust assertions.

It is not normally necessary to call this function. The relevant PKCS#11 slots are automatically configured by the GCR library.

Gcr.pkcs11_set_trust_store_uri(pkcs11_uri)

Parameters:

pkcs11_uri (str or None) – the uri which identifies trust storage slot

Set the PKCS#11 URI that is used to identify which slot to use for storing trust assertions.

It is not normally necessary to call this function. The relevant PKCS#11 slot is automatically configured by the GCR library.

Gcr.trust_add_pinned_certificate(certificate, purpose, peer, cancellable)

Parameters:

• certificate (Gcr.Certificate) – a Gcr.Certificate

• purpose (str) – the purpose string

• peer (str) – the peer for this pinned certificate

• cancellable (Gio.Cancellable or None) – a Gio.Cancellable

Raises:

GLib.Error

Returns:

True if the pinned certificate is recorded successfully

Return type:

bool

Add a pinned certificate for connections to peer for purpose. A pinned certificate overrides all other certificate verification and should be used with care.

If the same pinned certificate already exists, then this operation does not add another, and succeeds without error.

This call may block, see Gcr.trust_add_pinned_certificate_async() for the non-blocking version.

Gcr.trust_add_pinned_certificate_async(certificate, purpose, peer, cancellable, callback, *user_data)

Parameters:

• certificate (Gcr.Certificate) – a Gcr.Certificate

• purpose (str) – the purpose string

• peer (str) – the peer for this pinned certificate

• cancellable (Gio.Cancellable or None) – a Gio.Cancellable

• callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the operation completes

• user_data (object or None) – the data to pass to callback function

Add a pinned certificate for communication with peer for purpose. A pinned certificate overrides all other certificate verification and should be used with care.

If the same pinned certificate already exists, then this operation does not add another, and succeeds without error.

When the operation is finished, callback will be called. You can then call [func`Gcr`.trust_add_pinned_certificate_finish] to get the result of the operation.

Gcr.trust_add_pinned_certificate_finish(result)

Parameters:

result (Gio.AsyncResult) – the Gio.AsyncResult passed to the callback

Raises:

GLib.Error

Returns:

True if the pinned certificate is recorded successfully

Return type:

bool

Finishes an asynchronous operation started by Gcr.trust_add_pinned_certificate_async().

Gcr.trust_is_certificate_anchored(certificate, purpose, cancellable)

Parameters:

• certificate (Gcr.Certificate) – a Gcr.Certificate to check

• purpose (str) – the purpose string

• cancellable (Gio.Cancellable or None) – a Gio.Cancellable

Raises:

GLib.Error

Returns:

True if the certificate is a trust anchor

Return type:

bool

Check if the certificate is a trust anchor for the given purpose. A trust anchor is used to verify the signatures on other certificates when verifying a certificate chain. Also known as a trusted certificate authority.

This call may block, see [func`Gcr`.trust_is_certificate_anchored_async] for the non-blocking version.

In the case of an error, False is also returned. Check error to detect if an error occurred.

Gcr.trust_is_certificate_anchored_async(certificate, purpose, cancellable, callback, *user_data)

Parameters:

• certificate (Gcr.Certificate) – a Gcr.Certificate to check

• purpose (str) – the purpose string

• cancellable (Gio.Cancellable or None) – a Gio.Cancellable

• callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the operation completes

• user_data (object or None) – the data to pass to callback function

Check if the certificate is a trust anchor for the given purpose. A trust anchor is used to verify the signatures on other certificates when verifying a certificate chain. Also known as a trusted certificate authority.

When the operation is finished, callback will be called. You can then call Gcr.trust_is_certificate_anchored_finish() to get the result of the operation.

Gcr.trust_is_certificate_anchored_finish(result)

Parameters:

result (Gio.AsyncResult) – the Gio.AsyncResult passed to the callback

Raises:

GLib.Error

Returns:

True if the certificate is a trust anchor

Return type:

bool

Finishes an asynchronous operation started by Gcr.trust_is_certificate_anchored_async().

In the case of an error, False is also returned. Check error to detect if an error occurred.

Gcr.trust_is_certificate_distrusted(serial_nr, issuer, cancellable)

Parameters:

• serial_nr (bytes) – The serial number of the certificate

• issuer (bytes) – The raw issuer

• cancellable (Gio.Cancellable or None) – a Gio.Cancellable or None

Raises:

GLib.Error

Returns:

True if the certificate is marked as distrusted

Return type:

bool

Checks whether the certificate that can be uniquely identified with the given serial_nr and issuer is marked as distrusted (for example by the user, or because it’s part of a CRL).

Since we can’t directly use [iface`Certificate`] to fetch these values, you need to call these with the raw serial number and issuer as provided by the PKCS#11 fields CKA_SERIAL_NR and CKA_ISSUER.

Gcr.trust_is_certificate_distrusted_async(serial_nr, issuer, cancellable, callback, *user_data)

Parameters:

• serial_nr (bytes) – The serial number of the certificate

• issuer (bytes) – The raw issuer

• cancellable (Gio.Cancellable or None) – a Gio.Cancellable or None

• callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the operation completes

• user_data (object or None) – the data to pass to callback function

Asynchronously checks whether the certificate that can be uniquely identified with the given serial_nr and issuer is marked as distrusted (for example by the user, or because it’s part of a CRL).

Since we can’t directly use [iface`Certificate`] to fetch these values, you need to call these with the raw serial number and issuer as provided by the PKCS#11 fields CKA_SERIAL_NR and CKA_ISSUER.

When the operation is finished, callback will be called. You can then call [func`trust_is_certificate_distrusted_finish`] to get the result of the operation.

Gcr.trust_is_certificate_distrusted_finish(result)

Parameters:

result (Gio.AsyncResult) – the Gio.AsyncResult passed to the callback

Raises:

GLib.Error

Returns:

True if the certificate is a trust anchor

Return type:

bool

Finishes an asynchronous operation started by [func`trust_is_certificate_distrusted_async`].

In the case of an error, False is also returned. Check error to detect if an error occurred.

Gcr.trust_is_certificate_pinned(certificate, purpose, peer, cancellable)

Parameters:

• certificate (Gcr.Certificate) – a Gcr.Certificate to check

• purpose (str) – the purpose string

• peer (str) – the peer for this pinned

• cancellable (Gio.Cancellable or None) – a Gio.Cancellable

Raises:

GLib.Error

Returns:

True if the certificate is pinned for the host and purpose

Return type:

bool

Check if certificate is pinned for purpose to communicate with peer. A pinned certificate overrides all other certificate verification.

This call may block, see Gcr.trust_is_certificate_pinned_async() for the non-blocking version.

In the case of an error, False is also returned. Check error to detect if an error occurred.

Gcr.trust_is_certificate_pinned_async(certificate, purpose, peer, cancellable, callback, *user_data)

Parameters:

• certificate (Gcr.Certificate) – a Gcr.Certificate to check

• purpose (str) – the purpose string

• peer (str) – the peer for this pinned

• cancellable (Gio.Cancellable or None) – a Gio.Cancellable

• callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the operation completes

• user_data (object or None) – the data to pass to callback function

Check if certificate is pinned for purpose to communicate with peer. A pinned certificate overrides all other certificate verification.

When the operation is finished, callback will be called. You can then call [func`Gcr`.trust_is_certificate_pinned_finish] to get the result of the operation.

Gcr.trust_is_certificate_pinned_finish(result)

Parameters:

result (Gio.AsyncResult) – the Gio.AsyncResult passed to the callback

Raises:

GLib.Error

Returns:

True if the certificate is pinned.

Return type:

bool

Finishes an asynchronous operation started by Gcr.trust_is_certificate_pinned_async().

In the case of an error, False is also returned. Check error to detect if an error occurred.

Gcr.trust_remove_pinned_certificate(certificate, purpose, peer, cancellable)

Parameters:

• certificate (Gcr.Certificate) – a Gcr.Certificate

• purpose (str) – the purpose string

• peer (str) – the peer for this pinned certificate

• cancellable (Gio.Cancellable or None) – a Gio.Cancellable

Raises:

GLib.Error

Returns:

True if the pinned certificate no longer exists

Return type:

bool

Remove a pinned certificate for communication with peer for purpose.

If the same pinned certificate does not exist, or was already removed, then this operation succeeds without error.

This call may block, see Gcr.trust_remove_pinned_certificate_async() for the non-blocking version.

Gcr.trust_remove_pinned_certificate_async(certificate, purpose, peer, cancellable, callback, *user_data)

Parameters:

• certificate (Gcr.Certificate) – a Gcr.Certificate

• purpose (str) – the purpose string

• peer (str) – the peer for this pinned certificate

• cancellable (Gio.Cancellable or None) – a Gio.Cancellable

• callback (Gio.AsyncReadyCallback or None) – a Gio.AsyncReadyCallback to call when the operation completes

• user_data (object or None) – the data to pass to callback function

Remove a pinned certificate for communication with peer for purpose.

If the same pinned certificate does not exist, or was already removed, then this operation succeeds without error.

When the operation is finished, callback will be called. You can then call Gcr.trust_remove_pinned_certificate_finish() to get the result of the operation.

Gcr.trust_remove_pinned_certificate_finish(result)

Parameters:

result (Gio.AsyncResult) – the Gio.AsyncResult passed to the callback

Raises:

GLib.Error

Returns:

True if the pinned certificate no longer exists

Return type:

bool

Finishes an asynchronous operation started by Gcr.trust_remove_pinned_certificate_async().