Functions

data_error_get_domain() → int
fingerprint_from_attributes(attrs: Attributes, checksum_type: ChecksumType) → bytes | 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 get_fingerprint() for.

Parameters:

  • attrs – attributes for key or certificate

  • checksum_type – the type of fingerprint to create

Returns:

the fingerprint or None if the input was invalid.

fingerprint_from_subject_public_key_info(key_info: Sequence[int], checksum_type: ChecksumType) → bytes | 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.

Parameters:

  • key_info – DER encoded subjectPublicKeyInfo structure

  • checksum_type – the type of fingerprint to create

Returns:

the fingerprint or None if the input was invalid.

importer_create_for_parsed(parsed: Parsed) → list[Importer]
Parameters:

parsed

importer_queue_and_filter_for_parsed(importers: list[Importer], parsed: Parsed) → list[Importer]
Parameters:

  • importers

  • parsed

importer_register(importer_type: type, attrs: Attributes) → None
Parameters:

  • importer_type

  • attrs

importer_register_well_known() → None
mock_prompter_disconnect() → None

Disconnect the mock prompter

mock_prompter_expect_close() → None

Queue an expected response on the mock prompter.

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

mock_prompter_expect_confirm_cancel() → None

Queue an expected response on the mock prompter.

Expects a confirmation prompt, and then cancels that prompt.

mock_prompter_expect_password_cancel() → None

Queue an expected response on the mock prompter.

Expects a password prompt, and then cancels that prompt.

mock_prompter_get_delay_msec() → int

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

Returns:

the delay

mock_prompter_is_expecting() → bool

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

Returns:

whether expecting a prompt

mock_prompter_is_prompting() → bool

Check if the mock prompter is showing any prompts.

Returns:

whether prompting

mock_prompter_set_delay_msec(delay_msec: int) → None

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

Parameters:

delay_msec – prompt response delay in milliseconds

mock_prompter_start() → str

Start the mock prompter. This is often used from the <literal>setup<!– –>()</literal> function of tests.

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

Returns:

the bus name that the mock prompter is listening on

mock_prompter_stop() → None

Stop the mock prompter. This is often used from the <literal>teardown<!– –>()</literal> function of tests.

pkcs11_add_module(module: Module) → None

Add a 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.

Parameters:

module – a Module

pkcs11_add_module_from_file(module_path: str, unused: None) → 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.

Parameters:

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

  • unused – unused

Returns:

whether the module was sucessfully added.

pkcs11_get_modules() → list[Module]

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

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

Returns:

a newly allocated list of Module objects

pkcs11_get_trust_lookup_slots() → list[Slot]

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

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

Returns:

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

pkcs11_get_trust_lookup_uris() → list[str] | None

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

Returns:

the uri which identifies trust storage slot

pkcs11_get_trust_store_slot() → Slot | 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 pkcs11_initialize method has been called.

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

Returns:

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

pkcs11_get_trust_store_uri() → str | None

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

Returns:

the uri which identifies trust storage slot

pkcs11_initialize(cancellable: Cancellable | None = None) → bool

Asynchronously initialize the registered PKCS#11 modules.

Parameters:

cancellable – optional cancellable used to cancel the operation

Returns:

whether the operation was successful or not.

pkcs11_initialize_async(cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

Asynchronously initialize the registered PKCS#11 modules.

Parameters:

  • cancellable – optional cancellable used to cancel the operation

  • callback – callback which will be called when the operation completes

  • user_data – data passed to the callback

pkcs11_initialize_finish(result: AsyncResult) → bool

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

Parameters:

result – the asynchronous result

Returns:

whether the operation was successful or not.

pkcs11_set_modules(modules: list[Module]) → None

Set the list of PKCS#11 modules that are used by the GCR library. Each module in the list is a 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.

Parameters:

modules – a list of PKCS#11 modules

pkcs11_set_trust_lookup_uris(pkcs11_uris: str | None = None) → None

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.

Parameters:

pkcs11_uris – the uris which identifies trust lookup slots

pkcs11_set_trust_store_uri(pkcs11_uri: str | None = None) → None

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.

Parameters:

pkcs11_uri – the uri which identifies trust storage slot

trust_add_pinned_certificate(certificate: Certificate, purpose: str, peer: str, cancellable: Cancellable | None = None) → 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 trust_add_pinned_certificate_async() for the non-blocking version.

Parameters:

  • certificate – a Certificate

  • purpose – the purpose string

  • peer – the peer for this pinned certificate

  • cancellable – a Cancellable

Returns:

True if the pinned certificate is recorded successfully

trust_add_pinned_certificate_async(certificate: Certificate, purpose: str, peer: str, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

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 trust_add_pinned_certificate_finish to get the result of the operation.

Parameters:

  • certificate – a Certificate

  • purpose – the purpose string

  • peer – the peer for this pinned certificate

  • cancellable – a Cancellable

  • callback – a AsyncReadyCallback to call when the operation completes

  • user_data – the data to pass to callback function

trust_add_pinned_certificate_finish(result: AsyncResult) → bool

Finishes an asynchronous operation started by trust_add_pinned_certificate_async().

Parameters:

result – the AsyncResult passed to the callback

Returns:

True if the pinned certificate is recorded successfully

trust_is_certificate_anchored(certificate: Certificate, purpose: str, cancellable: Cancellable | None = None) → 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 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.

Parameters:
Returns:

True if the certificate is a trust anchor

trust_is_certificate_anchored_async(certificate: Certificate, purpose: str, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

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 trust_is_certificate_anchored_finish() to get the result of the operation.

Parameters:

  • certificate – a Certificate to check

  • purpose – the purpose string

  • cancellable – a Cancellable

  • callback – a AsyncReadyCallback to call when the operation completes

  • user_data – the data to pass to callback function

trust_is_certificate_anchored_finish(result: AsyncResult) → bool

Finishes an asynchronous operation started by trust_is_certificate_anchored_async().

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

Parameters:

result – the AsyncResult passed to the callback

Returns:

True if the certificate is a trust anchor

trust_is_certificate_distrusted(serial_nr: Sequence[int], issuer: Sequence[int], cancellable: Cancellable | None = None) → 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 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.

Parameters:

  • serial_nr – The serial number of the certificate

  • issuer – The raw issuer

  • cancellable – a Cancellable or None

Returns:

True if the certificate is marked as distrusted

trust_is_certificate_distrusted_async(serial_nr: Sequence[int], issuer: Sequence[int], cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

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 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 trust_is_certificate_distrusted_finish to get the result of the operation.

Parameters:

  • serial_nr – The serial number of the certificate

  • issuer – The raw issuer

  • cancellable – a Cancellable or None

  • callback – a AsyncReadyCallback to call when the operation completes

  • user_data – the data to pass to callback function

trust_is_certificate_distrusted_finish(result: AsyncResult) → bool

Finishes an asynchronous operation started by trust_is_certificate_distrusted_async.

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

Parameters:

result – the AsyncResult passed to the callback

Returns:

True if the certificate is a trust anchor

trust_is_certificate_pinned(certificate: Certificate, purpose: str, peer: str, cancellable: Cancellable | None = None) → 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 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.

Parameters:

  • certificate – a Certificate to check

  • purpose – the purpose string

  • peer – the peer for this pinned

  • cancellable – a Cancellable

Returns:

True if the certificate is pinned for the host and purpose

trust_is_certificate_pinned_async(certificate: Certificate, purpose: str, peer: str, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

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 trust_is_certificate_pinned_finish to get the result of the operation.

Parameters:

  • certificate – a Certificate to check

  • purpose – the purpose string

  • peer – the peer for this pinned

  • cancellable – a Cancellable

  • callback – a AsyncReadyCallback to call when the operation completes

  • user_data – the data to pass to callback function

trust_is_certificate_pinned_finish(result: AsyncResult) → bool

Finishes an asynchronous operation started by trust_is_certificate_pinned_async().

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

Parameters:

result – the AsyncResult passed to the callback

Returns:

True if the certificate is pinned.

trust_remove_pinned_certificate(certificate: Certificate, purpose: str, peer: str, cancellable: Cancellable | None = None) → 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 trust_remove_pinned_certificate_async() for the non-blocking version.

Parameters:

  • certificate – a Certificate

  • purpose – the purpose string

  • peer – the peer for this pinned certificate

  • cancellable – a Cancellable

Returns:

True if the pinned certificate no longer exists

trust_remove_pinned_certificate_async(certificate: Certificate, purpose: str, peer: str, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) → None

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 trust_remove_pinned_certificate_finish() to get the result of the operation.

Parameters:

  • certificate – a Certificate

  • purpose – the purpose string

  • peer – the peer for this pinned certificate

  • cancellable – a Cancellable

  • callback – a AsyncReadyCallback to call when the operation completes

  • user_data – the data to pass to callback function

trust_remove_pinned_certificate_finish(result: AsyncResult) → bool

Finishes an asynchronous operation started by trust_remove_pinned_certificate_async().

Parameters:

result – the AsyncResult passed to the callback

Returns:

True if the pinned certificate no longer exists