Skip to content

Gio.TlsCertificate

class — extends 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 TlsServerConnection).

Constructors

new_from_file

@classmethod
def new_from_file(cls, file: str | bytes | os.PathLike[str] | os.PathLike[bytes]) -> TlsCertificate

Creates a TlsCertificate from the data in file.

As of 2.72, if the filename ends in .p12 or .pfx the data is loaded by TlsCertificate.new_from_pkcs12 otherwise it is loaded by TlsCertificate.new_from_pem. See those functions for exact details.

If file cannot be read or parsed, the function will return None and set error.

Parameters:

  • file — file containing a certificate to import

new_from_file_with_password

@classmethod
def new_from_file_with_password(cls, file: str | bytes | os.PathLike[str] | os.PathLike[bytes], password: str) -> TlsCertificate

Creates a TlsCertificate from the data in file.

If file cannot be read or parsed, the function will return None and set error.

Any unknown file types will error with IOErrorEnum.NOT_SUPPORTED. Currently only .p12 and .pfx files are supported. See TlsCertificate.new_from_pkcs12 for more details.

Parameters:

  • file — file containing a certificate to import
  • password — password for PKCS #12 files

new_from_files

@classmethod
def new_from_files(cls, cert_file: str | bytes | os.PathLike[str] | os.PathLike[bytes], key_file: str | bytes | os.PathLike[str] | os.PathLike[bytes]) -> TlsCertificate

Creates a 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 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 None and set error. Otherwise, this behaves like TlsCertificate.new_from_pem.

Parameters:

  • cert_file — file containing one or more PEM-encoded certificates to import
  • key_file — file containing a PEM-encoded private key to import

new_from_pem

@classmethod
def new_from_pem(cls, data: str, length: int) -> TlsCertificate

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

Parameters:

  • data — PEM-encoded certificate data
  • length — the length of data, or -1 if it's 0-terminated.

new_from_pkcs11_uris

@classmethod
def new_from_pkcs11_uris(cls, pkcs11_uri: str, private_key_pkcs11_uri: str | None = ...) -> TlsCertificate

Creates a 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:

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.

Parameters:

  • pkcs11_uri — A PKCS #11 URI
  • private_key_pkcs11_uri — A PKCS #11 URI

new_from_pkcs12

@classmethod
def new_from_pkcs12(cls, data: list[int], password: str | None = ...) -> TlsCertificate

Creates a 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 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 TlsError.BAD_CERTIFICATE_PASSWORD.

This constructor requires support in the current TlsBackend. If support is missing it will error with IOErrorEnum.NOT_SUPPORTED.

Other parsing failures will error with TlsError.BAD_CERTIFICATE.

Parameters:

  • data — DER-encoded PKCS #12 format certificate data
  • password — optional password for encrypted certificate data

Methods

get_dns_names

def get_dns_names(self) -> list[bytes] | None

Gets the value of TlsCertificate:dns-names.

get_ip_addresses

def get_ip_addresses(self) -> list[InetAddress] | None

Gets the value of TlsCertificate:ip-addresses.

get_issuer

def get_issuer(self) -> TlsCertificate | None

Gets the TlsCertificate representing cert's issuer, if known

get_issuer_name

def get_issuer_name(self) -> str | None

Returns the issuer name from the certificate.

get_not_valid_after

def get_not_valid_after(self) -> GLib.DateTime | None

Returns the time at which the certificate became or will become invalid.

get_not_valid_before

def get_not_valid_before(self) -> GLib.DateTime | None

Returns the time at which the certificate became or will become valid.

get_subject_name

def get_subject_name(self) -> str | None

Returns the subject name from the certificate.

is_same

def is_same(self, cert_two: TlsCertificate) -> bool

Check if two 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 TlsCertificate:issuer, TlsCertificate:private-key, or TlsCertificate:private-key-pem properties differ.

Parameters:

  • cert_two — second certificate to compare

verify

def verify(self, identity: SocketConnectable | None = ..., trusted_ca: TlsCertificate | None = ...) -> TlsCertificateFlags

This verifies cert and returns a set of 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, TlsCertificateFlags.NO_FLAGS is returned.

If identity is not None, cert's name(s) will be compared against it, and TlsCertificateFlags.BAD_IDENTITY will be set in the return value if it does not match. If identity is None, that bit will never be set in the return value.

If trusted_ca is not None, then cert (or one of the certificates in its chain) must be signed by it, or else TlsCertificateFlags.UNKNOWN_CA will be set in the return value. If trusted_ca is 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 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, TlsCertificate may not perform as many checks on the certificates as 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 TlsConnection handle the verification.

Parameters:

  • identity — the expected peer identity
  • trusted_ca — the certificate of a trusted authority

Static functions

list_new_from_file

@staticmethod
def list_new_from_file(file: str | bytes | os.PathLike[str] | os.PathLike[bytes]) -> list[TlsCertificate]

Creates one or more GTlsCertificates from the PEM-encoded data in file. If file cannot be read or parsed, the function will return None and set error. If file does not contain any PEM-encoded certificates, this will return an empty list and not set error.

Parameters:

  • file — file containing PEM-encoded certificates to import

Virtual methods

do_verify

def do_verify(self, identity: SocketConnectable | None = ..., trusted_ca: TlsCertificate | None = ...) -> TlsCertificateFlags

This verifies cert and returns a set of 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, TlsCertificateFlags.NO_FLAGS is returned.

If identity is not None, cert's name(s) will be compared against it, and TlsCertificateFlags.BAD_IDENTITY will be set in the return value if it does not match. If identity is None, that bit will never be set in the return value.

If trusted_ca is not None, then cert (or one of the certificates in its chain) must be signed by it, or else TlsCertificateFlags.UNKNOWN_CA will be set in the return value. If trusted_ca is 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 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, TlsCertificate may not perform as many checks on the certificates as 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 TlsConnection handle the verification.

Parameters:

  • identity — the expected peer identity
  • trusted_ca — the certificate of a trusted authority

Properties

certificate

certificate: list[int]  # read/write

The DER (binary) encoded representation of the certificate. This property and the TlsCertificate:certificate-pem property represent the same data, just in different forms.

certificate_pem

certificate_pem: str  # read/write

The PEM (ASCII) encoded representation of the certificate. This property and the TlsCertificate:certificate property represent the same data, just in different forms.

dns_names

dns_names: list[int]  # read-only

The DNS names from the certificate's Subject Alternative Names (SANs), None if unavailable.

ip_addresses

ip_addresses: list[int]  # read-only

The IP addresses from the certificate's Subject Alternative Names (SANs), None if unavailable.

issuer

issuer: TlsCertificate  # read/write

A TlsCertificate representing the entity that issued this certificate. If None, this means that the certificate is either self-signed, or else the certificate of the issuer is not available.

Beware the issuer certificate may not be the same as the certificate that would actually be used to construct a valid certification path during certificate verification. RFC 4158 explains why an issuer certificate cannot be naively assumed to be part of the the certification path (though GLib's TLS backends may not follow the path building strategies outlined in this RFC). Due to the complexity of certification path building, GLib does not provide any way to know which certification path will actually be used. Accordingly, this property cannot be used to make security-related decisions. Only GLib itself should make security decisions about TLS certificates.

issuer_name

issuer_name: str  # read-only

The issuer from the certificate, None if unavailable.

not_valid_after

not_valid_after: GLib.DateTime  # read-only

The time at which this cert is no longer valid, None if unavailable.

not_valid_before

not_valid_before: GLib.DateTime  # read-only

The time at which this cert is considered to be valid, None if unavailable.

password

password: str  # read/write

An optional password used when constructed with GTlsCertificate:pkcs12-data.

pkcs11_uri

pkcs11_uri: str  # read/write

A URI referencing the PKCS #11 objects containing an X.509 certificate and optionally a private key.

If None, the certificate is either not backed by PKCS #11 or the TlsBackend does not support PKCS #11.

pkcs12_data

pkcs12_data: list[int]  # read/write

The PKCS #12 formatted data used to construct the object.

See also: TlsCertificate.new_from_pkcs12

private_key

private_key: list[int]  # read/write

The DER (binary) encoded representation of the certificate's private key, in either PKCS #1 format or unencrypted PKCS #8 format. PKCS #8 format is supported since 2.32; earlier releases only support PKCS #1. You can use the openssl rsa tool to convert PKCS #8 keys to PKCS #1.

This property (or the TlsCertificate:private-key-pem property) can be set when constructing a key (for example, from a file). Since GLib 2.70, it is now also readable; however, be aware that if the private key is backed by a PKCS #11 URI – for example, if it is stored on a smartcard – then this property will be None. If so, the private key must be referenced via its PKCS #11 URI, TlsCertificate:private-key-pkcs11-uri. You must check both properties to see if the certificate really has a private key. When this property is read, the output format will be unencrypted PKCS #8.

private_key_pem

private_key_pem: str  # read/write

The PEM (ASCII) encoded representation of the certificate's private key in either PKCS #1 format ("BEGIN RSA PRIVATE KEY") or unencrypted PKCS #8 format ("BEGIN PRIVATE KEY"). PKCS #8 format is supported since 2.32; earlier releases only support PKCS #1. You can use the openssl rsa tool to convert PKCS #8 keys to PKCS #1.

This property (or the TlsCertificate:private-key property) can be set when constructing a key (for example, from a file). Since GLib 2.70, it is now also readable; however, be aware that if the private key is backed by a PKCS #11 URI - for example, if it is stored on a smartcard - then this property will be None. If so, the private key must be referenced via its PKCS #11 URI, TlsCertificate:private-key-pkcs11-uri. You must check both properties to see if the certificate really has a private key. When this property is read, the output format will be unencrypted PKCS #8.

private_key_pkcs11_uri

private_key_pkcs11_uri: str  # read/write

A URI referencing a PKCS #11 object containing a private key.

subject_name

subject_name: str  # read-only

The subject from the cert, None if unavailable.