Functions#
- 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_queue_and_filter_for_parsed(importers: list[Importer], parsed: Parsed) list[Importer] #
- Parameters:
importers
parsed
- 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
, orpkcs11_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
, useunref()
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 topeer
forpurpose
. 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
forpurpose
. 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 completesuser_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 givenpurpose
. 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. Checkerror
to detect if an error occurred.- Parameters:
certificate – a
Certificate
to checkpurpose – the purpose string
cancellable – a
Cancellable
- 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 givenpurpose
. 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 checkpurpose – the purpose string
cancellable – a
Cancellable
callback – a
AsyncReadyCallback
to call when the operation completesuser_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. Checkerror
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
andissuer
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 fieldsCKA_SERIAL_NR
andCKA_ISSUER
.- Parameters:
serial_nr – The serial number of the certificate
issuer – The raw issuer
cancellable – a
Cancellable
orNone
- 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
andissuer
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 fieldsCKA_SERIAL_NR
andCKA_ISSUER
.When the operation is finished,
callback
will be called. You can then calltrust_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
orNone
callback – a
AsyncReadyCallback
to call when the operation completesuser_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. Checkerror
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 forpurpose
to communicate withpeer
. 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. Checkerror
to detect if an error occurred.- Parameters:
certificate – a
Certificate
to checkpurpose – 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 forpurpose
to communicate withpeer
. 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 checkpurpose – the purpose string
peer – the peer for this pinned
cancellable – a
Cancellable
callback – a
AsyncReadyCallback
to call when the operation completesuser_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. Checkerror
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
forpurpose
.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
forpurpose
.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 completesuser_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