Functions
=========

.. currentmodule:: gi.repository.Gcr



.. function:: data_error_get_domain() -> int

   










.. function:: fingerprint_from_attributes(attrs: ~gi.repository.Gck.Attributes, checksum_type: ~gi.repository.GLib.ChecksumType) -> list[int] | 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 :func:`~gi.repository.Gcr.Certificate.get_fingerprint` for.






   :param attrs: attributes for key or certificate

   :param checksum_type: the type of fingerprint to create


   :return: the
               fingerprint or :const:`None` if the input was invalid.




.. function:: fingerprint_from_subject_public_key_info(key_info: list[int], checksum_type: ~gi.repository.GLib.ChecksumType) -> list[int] | 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.






   :param key_info: DER encoded subjectPublicKeyInfo structure

   :param checksum_type: the type of fingerprint to create


   :return: the
               fingerprint or :const:`None` if the input was invalid.




.. function:: importer_create_for_parsed(parsed: ~gi.repository.Gcr.Parsed) -> list[~gi.repository.Gcr.Importer]

   






   :param parsed: 





.. function:: importer_queue_and_filter_for_parsed(importers: list[~gi.repository.Gcr.Importer], parsed: ~gi.repository.Gcr.Parsed) -> list[~gi.repository.Gcr.Importer]

   






   :param importers: 

   :param parsed: 





.. function:: importer_register(importer_type: ~gobject.GType, attrs: ~gi.repository.Gck.Attributes) -> None

   






   :param importer_type: 

   :param attrs: 





.. function:: importer_register_well_known() -> None

   










.. function:: mock_prompter_disconnect() -> None

   Disconnect the mock prompter










.. function:: mock_prompter_expect_close() -> None

   Queue an expected response on the mock prompter.

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










.. function:: mock_prompter_expect_confirm_cancel() -> None

   Queue an expected response on the mock prompter.

   Expects a confirmation prompt, and then cancels that prompt.










.. function:: mock_prompter_expect_password_cancel() -> None

   Queue an expected response on the mock prompter.

   Expects a password prompt, and then cancels that prompt.










.. function:: mock_prompter_get_delay_msec() -> int

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







   :return: the delay




.. function:: mock_prompter_is_expecting() -> bool

   Check if the mock prompter is expecting a response. This will be :const:`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.







   :return: whether expecting a prompt




.. function:: mock_prompter_is_prompting() -> bool

   Check if the mock prompter is showing any prompts.







   :return: whether prompting




.. function:: mock_prompter_set_delay_msec(delay_msec: int) -> None

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






   :param delay_msec: prompt response delay in milliseconds





.. function:: 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 :func:`~gi.repository.Gcr.SystemPrompt.open_for_prompter` to connect to this prompter.







   :return: the bus name that the mock prompter is listening on




.. function:: mock_prompter_stop() -> None

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










.. function:: pkcs11_add_module(module: ~gi.repository.Gck.Module) -> None

   Add a :obj:`~gi.repository.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.






   :param module: a :obj:`~gi.repository.Gck.Module`





.. function:: pkcs11_add_module_from_file(module_path: str, unused: ~typing.Any = 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.






   :param module_path: the full file path of the PKCS``11`` module

   :param unused: unused


   :return: whether the module was sucessfully added.




.. function:: pkcs11_get_modules() -> list[~gi.repository.Gck.Module]

   List all the PKCS``11`` modules that are used by the GCR library.
   Each module is a :obj:`~gi.repository.Gck.Module` object.

   An empty list of modules will be returned if :obj:`~gi.repository.Gcr.pkcs11_set_modules`\,
   or :obj:`~gi.repository.Gcr.pkcs11_initialize` has not yet run.







   :return: a newly allocated list
               of :obj:`~gi.repository.Gck.Module` objects




.. function:: pkcs11_get_trust_lookup_slots() -> list[~gi.repository.Gck.Slot]

   List all the PKCS``11`` slots that are used by the GCR library for lookup
   of trust assertions. Each slot is a :obj:`~gi.repository.Gck.Slot` object.

   This will return an empty list if the :obj:`~gi.repository.Gcr.pkcs11_initialize` function has
   not yet been called.







   :return: a list of :obj:`~gi.repository.Gck.Slot`
               objects to use for lookup of trust, or the empty list if not
               initialized or no appropriate trust stores could be found.




.. function:: 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.







   :return: the uri which identifies trust storage slot




.. function:: pkcs11_get_trust_store_slot() -> ~gi.repository.Gck.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 :obj:`~gi.repository.Gcr.pkcs11_initialize`
   method has been called.

   When done with the :obj:`~gi.repository.Gck.Slot`\, use :func:`~gi.repository.GObject.GObject.Object.unref` to release it.







   :return: the :obj:`~gi.repository.Gck.Slot` to use for trust
               assertions, or null if not initialized or no appropriate
               trust store could be found.




.. function:: 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.







   :return: the uri which identifies trust storage slot




.. function:: pkcs11_initialize(cancellable: ~gi.repository.Gio.Cancellable | None = None) -> bool

   Asynchronously initialize the registered PKCS``11`` modules.






   :param cancellable: optional cancellable used to cancel the operation


   :return: whether the operation was successful or not.




.. function:: pkcs11_initialize_async(cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None

   Asynchronously initialize the registered PKCS``11`` modules.






   :param cancellable: optional cancellable used to cancel the operation

   :param callback: callback which will be called when the operation completes

   :param user_data: data passed to the callback





.. function:: pkcs11_initialize_finish(result: ~gi.repository.Gio.AsyncResult) -> bool

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






   :param result: the asynchronous result


   :return: whether the operation was successful or not.




.. function:: pkcs11_set_modules(modules: list[~gi.repository.Gck.Module]) -> None

   Set the list of PKCS``11`` modules that are used by the GCR library.
   Each module in the list is a :obj:`~gi.repository.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.






   :param modules: a list of PKCS``11`` modules





.. function:: 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.






   :param pkcs11_uris: the uris which identifies trust lookup slots





.. function:: 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.






   :param pkcs11_uri: the uri which identifies trust storage slot





.. function:: trust_add_pinned_certificate(certificate: ~gi.repository.Gcr.Certificate, purpose: str, peer: str, cancellable: ~gi.repository.Gio.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 :func:`~gi.repository.Gcr.trust_add_pinned_certificate_async` for the
   non-blocking version.






   :param certificate: a :obj:`~gi.repository.Gcr.Certificate`

   :param purpose: the purpose string

   :param peer: the peer for this pinned certificate

   :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`


   :return: :const:`True` if the pinned certificate is recorded successfully




.. function:: trust_add_pinned_certificate_async(certificate: ~gi.repository.Gcr.Certificate, purpose: str, peer: str, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> 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
   :obj:`~gi.repository.Gcr.trust_add_pinned_certificate_finish` to get the result of the
   operation.






   :param certificate: a :obj:`~gi.repository.Gcr.Certificate`

   :param purpose: the purpose string

   :param peer: the peer for this pinned certificate

   :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`

   :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback` to call when the operation completes

   :param user_data: the data to pass to callback function





.. function:: trust_add_pinned_certificate_finish(result: ~gi.repository.Gio.AsyncResult) -> bool

   Finishes an asynchronous operation started by
   :func:`~gi.repository.Gcr.trust_add_pinned_certificate_async`.






   :param result: the :obj:`~gi.repository.Gio.AsyncResult` passed to the callback


   :return: :const:`True` if the pinned certificate is recorded successfully




.. function:: trust_is_certificate_anchored(certificate: ~gi.repository.Gcr.Certificate, purpose: str, cancellable: ~gi.repository.Gio.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 :obj:`~gi.repository.Gcr.trust_is_certificate_anchored_async` for
   the non-blocking version.

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






   :param certificate: a :obj:`~gi.repository.Gcr.Certificate` to check

   :param purpose: the purpose string

   :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`


   :return: :const:`True` if the certificate is a trust anchor




.. function:: trust_is_certificate_anchored_async(certificate: ~gi.repository.Gcr.Certificate, purpose: str, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> 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
   :func:`~gi.repository.Gcr.trust_is_certificate_anchored_finish` to get the result of the operation.






   :param certificate: a :obj:`~gi.repository.Gcr.Certificate` to check

   :param purpose: the purpose string

   :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`

   :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback` to call when the operation completes

   :param user_data: the data to pass to callback function





.. function:: trust_is_certificate_anchored_finish(result: ~gi.repository.Gio.AsyncResult) -> bool

   Finishes an asynchronous operation started by
   :func:`~gi.repository.Gcr.trust_is_certificate_anchored_async`.

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






   :param result: the :obj:`~gi.repository.Gio.AsyncResult` passed to the callback


   :return: :const:`True` if the certificate is a trust anchor




.. function:: trust_is_certificate_distrusted(serial_nr: list[int], issuer: list[int], cancellable: ~gi.repository.Gio.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 :obj:`~gi.repository.Gcr.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``\.






   :param serial_nr: The serial number of the certificate

   :param issuer: The raw issuer

   :param cancellable: a :obj:`~gi.repository.Gio.Cancellable` or :const:`None`


   :return: :const:`True` if the certificate is marked as distrusted




.. function:: trust_is_certificate_distrusted_async(serial_nr: list[int], issuer: list[int], cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> 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 :obj:`~gi.repository.Gcr.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
   :obj:`~gi.repository.Gcr.trust_is_certificate_distrusted_finish` to get the result of the
   operation.






   :param serial_nr: The serial number of the certificate

   :param issuer: The raw issuer

   :param cancellable: a :obj:`~gi.repository.Gio.Cancellable` or :const:`None`

   :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback` to call when the operation completes

   :param user_data: the data to pass to callback function





.. function:: trust_is_certificate_distrusted_finish(result: ~gi.repository.Gio.AsyncResult) -> bool

   Finishes an asynchronous operation started by
   :obj:`~gi.repository.Gcr.trust_is_certificate_distrusted_async`\.

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






   :param result: the :obj:`~gi.repository.Gio.AsyncResult` passed to the callback


   :return: :const:`True` if the certificate is a trust anchor




.. function:: trust_is_certificate_pinned(certificate: ~gi.repository.Gcr.Certificate, purpose: str, peer: str, cancellable: ~gi.repository.Gio.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 :func:`~gi.repository.Gcr.trust_is_certificate_pinned_async` for the
   non-blocking version.

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






   :param certificate: a :obj:`~gi.repository.Gcr.Certificate` to check

   :param purpose: the purpose string

   :param peer: the peer for this pinned

   :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`


   :return: :const:`True` if the certificate is pinned for the host and purpose




.. function:: trust_is_certificate_pinned_async(certificate: ~gi.repository.Gcr.Certificate, purpose: str, peer: str, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> 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
   :obj:`~gi.repository.Gcr.trust_is_certificate_pinned_finish` to get the result of the
   operation.






   :param certificate: a :obj:`~gi.repository.Gcr.Certificate` to check

   :param purpose: the purpose string

   :param peer: the peer for this pinned

   :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`

   :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback` to call when the operation completes

   :param user_data: the data to pass to callback function





.. function:: trust_is_certificate_pinned_finish(result: ~gi.repository.Gio.AsyncResult) -> bool

   Finishes an asynchronous operation started by
   :func:`~gi.repository.Gcr.trust_is_certificate_pinned_async`.

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






   :param result: the :obj:`~gi.repository.Gio.AsyncResult` passed to the callback


   :return: :const:`True` if the certificate is pinned.




.. function:: trust_remove_pinned_certificate(certificate: ~gi.repository.Gcr.Certificate, purpose: str, peer: str, cancellable: ~gi.repository.Gio.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 :func:`~gi.repository.Gcr.trust_remove_pinned_certificate_async` for the
   non-blocking version.






   :param certificate: a :obj:`~gi.repository.Gcr.Certificate`

   :param purpose: the purpose string

   :param peer: the peer for this pinned certificate

   :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`


   :return: :const:`True` if the pinned certificate no longer exists




.. function:: trust_remove_pinned_certificate_async(certificate: ~gi.repository.Gcr.Certificate, purpose: str, peer: str, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> 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
   :func:`~gi.repository.Gcr.trust_remove_pinned_certificate_finish` to get the result of the
   operation.






   :param certificate: a :obj:`~gi.repository.Gcr.Certificate`

   :param purpose: the purpose string

   :param peer: the peer for this pinned certificate

   :param cancellable: a :obj:`~gi.repository.Gio.Cancellable`

   :param callback: a :obj:`~gi.repository.Gio.AsyncReadyCallback` to call when the operation completes

   :param user_data: the data to pass to callback function





.. function:: trust_remove_pinned_certificate_finish(result: ~gi.repository.Gio.AsyncResult) -> bool

   Finishes an asynchronous operation started by
   :func:`~gi.repository.Gcr.trust_remove_pinned_certificate_async`.






   :param result: the :obj:`~gi.repository.Gio.AsyncResult` passed to the callback


   :return: :const:`True` if the pinned certificate no longer exists