:right-sidebar: True TlsCertificate =================================================================== .. currentmodule:: gi.repository.Gio .. versionadded:: 2.28 .. class:: TlsCertificate(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` A certificate used for TLS authentication and encryption. This can represent either a certificate only (eg, the certificate received by a client from a server), or the combination of a certificate and a private key (which is needed when acting as a :obj:`~gi.repository.Gio.TlsServerConnection`\). Constructors ------------ .. rst-class:: interim-class .. class:: TlsCertificate :no-index: .. classmethod:: new_from_file(file: str) -> ~gi.repository.Gio.TlsCertificate Creates a :obj:`~gi.repository.Gio.TlsCertificate` from the data in ``file``\. As of 2.72, if the filename ends in ``.p12`` or ``.pfx`` the data is loaded by :func:`~gi.repository.Gio.TlsCertificate.new_from_pkcs12` otherwise it is loaded by :func:`~gi.repository.Gio.TlsCertificate.new_from_pem`. See those functions for exact details. If ``file`` cannot be read or parsed, the function will return :const:`None` and set ``error``\. .. versionadded:: 2.28 :param file: file containing a certificate to import .. classmethod:: new_from_file_with_password(file: str, password: str) -> ~gi.repository.Gio.TlsCertificate Creates a :obj:`~gi.repository.Gio.TlsCertificate` from the data in ``file``\. If ``file`` cannot be read or parsed, the function will return :const:`None` and set ``error``\. Any unknown file types will error with :const:`~gi.repository.Gio.IOErrorEnum.NOT_SUPPORTED`. Currently only ``.p12`` and ``.pfx`` files are supported. See :func:`~gi.repository.Gio.TlsCertificate.new_from_pkcs12` for more details. .. versionadded:: 2.72 :param file: file containing a certificate to import :param password: password for PKCS ``12`` files .. classmethod:: new_from_files(cert_file: str, key_file: str) -> ~gi.repository.Gio.TlsCertificate Creates a :obj:`~gi.repository.Gio.TlsCertificate` from the PEM-encoded data in ``cert_file`` and ``key_file``\. The returned certificate will be the first certificate found in ``cert_file``\. As of GLib 2.44, if ``cert_file`` contains more certificates it will try to load a certificate chain. All certificates will be verified in the order found (top-level certificate should be the last one in the file) and the :obj:`~gi.repository.Gio.TlsCertificate`\:issuer property of each certificate will be set accordingly if the verification succeeds. If any certificate in the chain cannot be verified, the first certificate in the file will still be returned. If either file cannot be read or parsed, the function will return :const:`None` and set ``error``\. Otherwise, this behaves like :func:`~gi.repository.Gio.TlsCertificate.new_from_pem`. .. versionadded:: 2.28 :param cert_file: file containing one or more PEM-encoded certificates to import :param key_file: file containing a PEM-encoded private key to import .. classmethod:: new_from_pem(data: str, length: int) -> ~gi.repository.Gio.TlsCertificate Creates a :obj:`~gi.repository.Gio.TlsCertificate` from the PEM-encoded data in ``data``\. If ``data`` includes both a certificate and a private key, then the returned certificate will include the private key data as well. (See the :obj:`~gi.repository.Gio.TlsCertificate`\:private-key-pem property for information about supported formats.) The returned certificate will be the first certificate found in ``data``\. As of GLib 2.44, if ``data`` contains more certificates it will try to load a certificate chain. All certificates will be verified in the order found (top-level certificate should be the last one in the file) and the :obj:`~gi.repository.Gio.TlsCertificate`\:issuer property of each certificate will be set accordingly if the verification succeeds. If any certificate in the chain cannot be verified, the first certificate in the file will still be returned. .. versionadded:: 2.28 :param data: PEM-encoded certificate data :param length: the length of ``data``\, or -1 if it's 0-terminated. .. classmethod:: new_from_pkcs11_uris(pkcs11_uri: str, private_key_pkcs11_uri: str | None = None) -> ~gi.repository.Gio.TlsCertificate Creates a :obj:`~gi.repository.Gio.TlsCertificate` from a `PKCS #11 `__ URI. An example ``pkcs11_uri`` would be ``pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01`` Where the token’s layout is: .. code-block:: :dedent: Object 0: URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01;object=private%20key;type=private Type: Private key (RSA-2048) ID: 01 Object 1: URL: pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01;object=Certificate%20for%20Authentication;type=cert Type: X.509 Certificate (RSA-2048) ID: 01 In this case the certificate and private key would both be detected and used as expected. ``pkcs_uri`` may also just reference an X.509 certificate object and then optionally ``private_key_pkcs11_uri`` allows using a private key exposed under a different URI. Note that the private key is not accessed until usage and may fail or require a PIN later. .. versionadded:: 2.68 :param pkcs11_uri: A PKCS #11 URI :param private_key_pkcs11_uri: A PKCS #11 URI .. classmethod:: new_from_pkcs12(data: list[int], password: str | None = None) -> ~gi.repository.Gio.TlsCertificate Creates a :obj:`~gi.repository.Gio.TlsCertificate` from the data in ``data``\. It must contain a certificate and matching private key. If extra certificates are included they will be verified as a chain and the :obj:`~gi.repository.Gio.TlsCertificate`\:issuer property will be set. All other data will be ignored. You can pass as single password for all of the data which will be used both for the PKCS ``12`` container as well as encrypted private keys. If decryption fails it will error with :const:`~gi.repository.Gio.TlsError.BAD_CERTIFICATE_PASSWORD`. This constructor requires support in the current :obj:`~gi.repository.Gio.TlsBackend`\. If support is missing it will error with :const:`~gi.repository.Gio.IOErrorEnum.NOT_SUPPORTED`. Other parsing failures will error with :const:`~gi.repository.Gio.TlsError.BAD_CERTIFICATE`. .. versionadded:: 2.72 :param data: DER-encoded PKCS ``12`` format certificate data :param password: optional password for encrypted certificate data Methods ------- .. rst-class:: interim-class .. class:: TlsCertificate :no-index: .. method:: do_verify(self, identity: ~gi.repository.Gio.SocketConnectable | None = None, trusted_ca: ~gi.repository.Gio.TlsCertificate | None = None) -> ~gi.repository.Gio.TlsCertificateFlags :param identity: :param trusted_ca: .. method:: get_dns_names() -> list[~gi.repository.GLib.Bytes] | None Gets the value of :obj:`~gi.repository.Gio.TlsCertificate`\:dns-names. .. versionadded:: 2.70 .. method:: get_ip_addresses() -> list[~gi.repository.Gio.InetAddress] | None Gets the value of :obj:`~gi.repository.Gio.TlsCertificate`\:ip-addresses. .. versionadded:: 2.70 .. method:: get_issuer() -> ~gi.repository.Gio.TlsCertificate | None Gets the :obj:`~gi.repository.Gio.TlsCertificate` representing ``cert``\'s issuer, if known .. versionadded:: 2.28 .. method:: get_issuer_name() -> str | None Returns the issuer name from the certificate. .. versionadded:: 2.70 .. method:: get_not_valid_after() -> ~gi.repository.GLib.DateTime | None Returns the time at which the certificate became or will become invalid. .. versionadded:: 2.70 .. method:: get_not_valid_before() -> ~gi.repository.GLib.DateTime | None Returns the time at which the certificate became or will become valid. .. versionadded:: 2.70 .. method:: get_subject_name() -> str | None Returns the subject name from the certificate. .. versionadded:: 2.70 .. method:: is_same(cert_two: ~gi.repository.Gio.TlsCertificate) -> bool Check if two :obj:`~gi.repository.Gio.TlsCertificate` objects represent the same certificate. The raw DER byte data of the two certificates are checked for equality. This has the effect that two certificates may compare equal even if their :obj:`~gi.repository.Gio.TlsCertificate`\:issuer, :obj:`~gi.repository.Gio.TlsCertificate`\:private-key, or :obj:`~gi.repository.Gio.TlsCertificate`\:private-key-pem properties differ. .. versionadded:: 2.34 :param cert_two: second certificate to compare .. classmethod:: list_new_from_file() -> list[~gi.repository.Gio.TlsCertificate] Creates one or more :obj:`~gi.repository.Gio.TlsCertificate` from the PEM-encoded data in ``file``\. If ``file`` cannot be read or parsed, the function will return :const:`None` and set ``error``\. If ``file`` does not contain any PEM-encoded certificates, this will return an empty list and not set ``error``\. .. versionadded:: 2.28 .. method:: verify(identity: ~gi.repository.Gio.SocketConnectable | None = None, trusted_ca: ~gi.repository.Gio.TlsCertificate | None = None) -> ~gi.repository.Gio.TlsCertificateFlags This verifies ``cert`` and returns a set of :obj:`~gi.repository.Gio.TlsCertificateFlags` indicating any problems found with it. This can be used to verify a certificate outside the context of making a connection, or to check a certificate against a CA that is not part of the system CA database. If ``cert`` is valid, :const:`~gi.repository.Gio.TlsCertificateFlags.NO_FLAGS` is returned. If ``identity`` is not :const:`None`, ``cert``\'s name(s) will be compared against it, and :const:`~gi.repository.Gio.TlsCertificateFlags.BAD_IDENTITY` will be set in the return value if it does not match. If ``identity`` is :const:`None`, that bit will never be set in the return value. If ``trusted_ca`` is not :const:`None`, then ``cert`` (or one of the certificates in its chain) must be signed by it, or else :const:`~gi.repository.Gio.TlsCertificateFlags.UNKNOWN_CA` will be set in the return value. If ``trusted_ca`` is :const:`None`, that bit will never be set in the return value. GLib guarantees that if certificate verification fails, at least one error will be set in the return value, but it does not guarantee that all possible errors will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to mask :const:`~gi.repository.Gio.TlsCertificateFlags.EXPIRED` if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate. Because TLS session context is not used, :obj:`~gi.repository.Gio.TlsCertificate` may not perform as many checks on the certificates as :obj:`~gi.repository.Gio.TlsConnection` would. For example, certificate constraints may not be honored, and revocation checks may not be performed. The best way to verify TLS certificates used by a TLS connection is to let :obj:`~gi.repository.Gio.TlsConnection` handle the verification. .. versionadded:: 2.28 :param identity: the expected peer identity :param trusted_ca: the certificate of a trusted authority Properties ---------- .. rst-class:: interim-class .. class:: TlsCertificate :no-index: .. attribute:: props.certificate :type: list[int] The type of the None singleton. .. versionadded:: 2.28 .. attribute:: props.certificate_pem :type: str The type of the None singleton. .. versionadded:: 2.28 .. attribute:: props.dns_names :type: list[~typing.Any] The type of the None singleton. .. versionadded:: 2.70 .. attribute:: props.ip_addresses :type: list[~typing.Any] The type of the None singleton. .. versionadded:: 2.70 .. attribute:: props.issuer :type: ~gi.repository.Gio.TlsCertificate The type of the None singleton. .. versionadded:: 2.28 .. attribute:: props.issuer_name :type: str The type of the None singleton. .. versionadded:: 2.70 .. attribute:: props.not_valid_after :type: ~gi.repository.GLib.DateTime The type of the None singleton. .. versionadded:: 2.70 .. attribute:: props.not_valid_before :type: ~gi.repository.GLib.DateTime The type of the None singleton. .. versionadded:: 2.70 .. attribute:: props.password :type: str The type of the None singleton. .. versionadded:: 2.72 .. attribute:: props.pkcs11_uri :type: str The type of the None singleton. .. versionadded:: 2.68 .. attribute:: props.pkcs12_data :type: list[int] The type of the None singleton. .. versionadded:: 2.72 .. attribute:: props.private_key :type: list[int] The type of the None singleton. .. versionadded:: 2.28 .. attribute:: props.private_key_pem :type: str The type of the None singleton. .. versionadded:: 2.28 .. attribute:: props.private_key_pkcs11_uri :type: str The type of the None singleton. .. versionadded:: 2.68 .. attribute:: props.subject_name :type: str The type of the None singleton. .. versionadded:: 2.70 Virtual Methods --------------- .. rst-class:: interim-class .. class:: TlsCertificate :no-index: .. method:: do_verify(identity: ~gi.repository.Gio.SocketConnectable | None = None, trusted_ca: ~gi.repository.Gio.TlsCertificate | None = None) -> ~gi.repository.Gio.TlsCertificateFlags This verifies ``cert`` and returns a set of :obj:`~gi.repository.Gio.TlsCertificateFlags` indicating any problems found with it. This can be used to verify a certificate outside the context of making a connection, or to check a certificate against a CA that is not part of the system CA database. If ``cert`` is valid, :const:`~gi.repository.Gio.TlsCertificateFlags.NO_FLAGS` is returned. If ``identity`` is not :const:`None`, ``cert``\'s name(s) will be compared against it, and :const:`~gi.repository.Gio.TlsCertificateFlags.BAD_IDENTITY` will be set in the return value if it does not match. If ``identity`` is :const:`None`, that bit will never be set in the return value. If ``trusted_ca`` is not :const:`None`, then ``cert`` (or one of the certificates in its chain) must be signed by it, or else :const:`~gi.repository.Gio.TlsCertificateFlags.UNKNOWN_CA` will be set in the return value. If ``trusted_ca`` is :const:`None`, that bit will never be set in the return value. GLib guarantees that if certificate verification fails, at least one error will be set in the return value, but it does not guarantee that all possible errors will be set. Accordingly, you may not safely decide to ignore any particular type of error. For example, it would be incorrect to mask :const:`~gi.repository.Gio.TlsCertificateFlags.EXPIRED` if you want to allow expired certificates, because this could potentially be the only error flag set even if other problems exist with the certificate. Because TLS session context is not used, :obj:`~gi.repository.Gio.TlsCertificate` may not perform as many checks on the certificates as :obj:`~gi.repository.Gio.TlsConnection` would. For example, certificate constraints may not be honored, and revocation checks may not be performed. The best way to verify TLS certificates used by a TLS connection is to let :obj:`~gi.repository.Gio.TlsConnection` handle the verification. .. versionadded:: 2.28 :param identity: the expected peer identity :param trusted_ca: the certificate of a trusted authority Fields ------ .. rst-class:: interim-class .. class:: TlsCertificate :no-index: .. attribute:: parent_instance .. attribute:: priv