Gio.TlsCertificate¶
- Subclasses:
None
Methods¶
- Inherited:
- Structs:
class |
|
class |
|
class |
|
class |
|
class |
|
class |
|
class |
|
|
|
|
|
|
Virtual Methods¶
- Inherited:
|
Properties¶
Name |
Type |
Flags |
Short Description |
|---|---|---|---|
r/w/co |
The DER representation of the certificate |
||
r/w/co |
The PEM representation of the certificate |
||
r |
DNS Names listed on the cert. |
||
r |
IP Addresses listed on the cert. |
||
r/w/co |
The certificate for the issuing entity |
||
r |
The issuer from the certificate. |
||
r |
Cert should not be considered valid after this time. |
||
r |
Cert should not be considered valid before this time. |
||
w/co |
Password used when constructing from bytes |
||
r/w/co |
The PKCS #11 URI |
||
w/co |
The PKCS #12 data used for construction |
||
r/w/co |
The DER representation of the certificate’s private key |
||
r/w/co |
The PEM representation of the certificate’s private key |
||
r/w/co |
The PKCS #11 URI for a private key |
||
r |
The subject name from the certificate. |
Signals¶
- Inherited:
Fields¶
- Inherited:
Name |
Type |
Access |
Description |
|---|---|---|---|
parent_instance |
r |
Class Details¶
- class Gio.TlsCertificate(**kwargs)¶
- Bases:
- Abstract:
Yes
- Structure:
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
Gio.TlsServerConnection).New in version 2.28.
- classmethod list_new_from_file(file)[source]¶
- Parameters:
file (
str) – file containing PEM-encoded certificates to import- Raises:
- Returns:
a
GLib.ListcontainingGio.TlsCertificateobjects. You must free the list and its contents when you are done with it.- Return type:
Creates one or more
Gio.TlsCertificatesfrom the PEM-encoded data in file. If file cannot be read or parsed, the function will returnNoneand set error. If file does not contain any PEM-encoded certificates, this will return an empty list and not set error.New in version 2.28.
- classmethod new_from_file(file)[source]¶
- Parameters:
file (
str) – file containing a certificate to import- Raises:
- Returns:
the new certificate, or
Noneon error- Return type:
Creates a
Gio.TlsCertificatefrom the data in file.As of 2.72, if the filename ends in
.p12or.pfxthe data is loaded byGio.TlsCertificate.new_from_pkcs12() otherwise it is loaded byGio.TlsCertificate.new_from_pem(). See those functions for exact details.If file cannot be read or parsed, the function will return
Noneand set error.New in version 2.28.
- classmethod new_from_file_with_password(file, password)[source]¶
- Parameters:
- Raises:
- Returns:
the new certificate, or
Noneon error- Return type:
Creates a
Gio.TlsCertificatefrom the data in file.If file cannot be read or parsed, the function will return
Noneand set error.Any unknown file types will error with
Gio.IOErrorEnum.NOT_SUPPORTED. Currently only.p12and.pfxfiles are supported. SeeGio.TlsCertificate.new_from_pkcs12() for more details.New in version 2.72.
- classmethod new_from_files(cert_file, key_file)[source]¶
- Parameters:
- Raises:
- Returns:
the new certificate, or
Noneon error- Return type:
Creates a
Gio.TlsCertificatefrom 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 theGio.TlsCertificate:issuerproperty 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
Noneand set error. Otherwise, this behaves likeGio.TlsCertificate.new_from_pem().New in version 2.28.
- classmethod new_from_pem(data, length)[source]¶
- Parameters:
- Raises:
- Returns:
the new certificate, or
Noneif data is invalid- Return type:
Creates a
Gio.TlsCertificatefrom 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 theGio.TlsCertificate:private-key-pemproperty 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
Gio.TlsCertificate:issuerproperty 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.New in version 2.28.
- classmethod new_from_pkcs11_uris(pkcs11_uri, private_key_pkcs11_uri)[source]¶
- Parameters:
- Raises:
- Returns:
the new certificate, or
Noneon error- Return type:
Creates a
Gio.TlsCertificatefrom a PKCS #11 URI.An example pkcs11_uri would be
pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My%20Client%20Certificate;id=%01Where 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.
New in version 2.68.
- classmethod new_from_pkcs12(data, password)[source]¶
- Parameters:
- Raises:
- Returns:
the new certificate, or
Noneif data is invalid- Return type:
Creates a
Gio.TlsCertificatefrom 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
Gio.TlsCertificate:issuerproperty 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
Gio.TlsError.BAD_CERTIFICATE_PASSWORD.This constructor requires support in the current
Gio.TlsBackend. If support is missing it will error withGio.IOErrorEnum.NOT_SUPPORTED.Other parsing failures will error with
Gio.TlsError.BAD_CERTIFICATE.New in version 2.72.
- get_dns_names()[source]¶
- Returns:
A
GLib.PtrArrayofGLib.Byteselements, orNoneif it’s not available.- Return type:
[
GLib.Bytes] orNone
Gets the value of
Gio.TlsCertificate:dns-names.New in version 2.70.
- get_ip_addresses()[source]¶
- Returns:
A
GLib.PtrArrayofGio.InetAddresselements, orNoneif it’s not available.- Return type:
[
Gio.InetAddress] orNone
Gets the value of
Gio.TlsCertificate:ip-addresses.New in version 2.70.
- get_issuer()[source]¶
- Returns:
The certificate of self's issuer, or
Noneif self is self-signed or signed with an unknown certificate.- Return type:
Gets the
Gio.TlsCertificaterepresenting self's issuer, if knownNew in version 2.28.
- get_not_valid_after()[source]¶
- Returns:
The not-valid-after date, or
Noneif it’s not available.- Return type:
Returns the time at which the certificate became or will become invalid.
New in version 2.70.
- get_not_valid_before()[source]¶
- Returns:
The not-valid-before date, or
Noneif it’s not available.- Return type:
Returns the time at which the certificate became or will become valid.
New in version 2.70.
- is_same(cert_two)[source]¶
- Parameters:
cert_two (
Gio.TlsCertificate) – second certificate to compare- Returns:
whether the same or not
- Return type:
Check if two
Gio.TlsCertificateobjects 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 theirGio.TlsCertificate:issuer,Gio.TlsCertificate:private-key, orGio.TlsCertificate:private-key-pemproperties differ.New in version 2.34.
- verify(identity, trusted_ca)[source]¶
- Parameters:
identity (
Gio.SocketConnectableorNone) – the expected peer identitytrusted_ca (
Gio.TlsCertificateorNone) – the certificate of a trusted authority
- Returns:
the appropriate
Gio.TlsCertificateFlags- Return type:
This verifies self and returns a set of
Gio.TlsCertificateFlagsindicating 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 self is valid,
Gio.TlsCertificateFlags.NO_FLAGSis returned.If identity is not
None, self's name(s) will be compared against it, andGio.TlsCertificateFlags.BAD_IDENTITYwill be set in the return value if it does not match. If identity isNone, that bit will never be set in the return value.If trusted_ca is not
None, then self (or one of the certificates in its chain) must be signed by it, or elseGio.TlsCertificateFlags.UNKNOWN_CAwill be set in the return value. If trusted_ca isNone, 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
Gio.TlsCertificateFlags.EXPIREDif 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,
Gio.TlsCertificatemay not perform as many checks on the certificates asGio.TlsConnectionwould. 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 letGio.TlsConnectionhandle the verification.New in version 2.28.
- do_verify(identity, trusted_ca) virtual¶
- Parameters:
identity (
Gio.SocketConnectableorNone) – the expected peer identitytrusted_ca (
Gio.TlsCertificateorNone) – the certificate of a trusted authority
- Returns:
the appropriate
Gio.TlsCertificateFlags- Return type:
This verifies cert and returns a set of
Gio.TlsCertificateFlagsindicating 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,
Gio.TlsCertificateFlags.NO_FLAGSis returned.If identity is not
None, cert's name(s) will be compared against it, andGio.TlsCertificateFlags.BAD_IDENTITYwill be set in the return value if it does not match. If identity isNone, 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 elseGio.TlsCertificateFlags.UNKNOWN_CAwill be set in the return value. If trusted_ca isNone, 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
Gio.TlsCertificateFlags.EXPIREDif 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,
Gio.TlsCertificatemay not perform as many checks on the certificates asGio.TlsConnectionwould. 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 letGio.TlsConnectionhandle the verification.New in version 2.28.
Property Details¶
- Gio.TlsCertificate.props.certificate¶
- Name:
certificate- Type:
- Default Value:
- Flags:
The DER (binary) encoded representation of the certificate. This property and the
Gio.TlsCertificate:certificate-pemproperty represent the same data, just in different forms.New in version 2.28.
- Gio.TlsCertificate.props.certificate_pem¶
- Name:
certificate-pem- Type:
- Default Value:
- Flags:
The PEM (ASCII) encoded representation of the certificate. This property and the
Gio.TlsCertificate:certificateproperty represent the same data, just in different forms.New in version 2.28.
- Gio.TlsCertificate.props.dns_names¶
- Name:
dns-names- Type:
- Default Value:
- Flags:
The DNS names from the certificate’s Subject Alternative Names (SANs),
Noneif unavailable.New in version 2.70.
- Gio.TlsCertificate.props.ip_addresses¶
- Name:
ip-addresses- Type:
- Default Value:
- Flags:
The IP addresses from the certificate’s Subject Alternative Names (SANs),
Noneif unavailable.New in version 2.70.
- Gio.TlsCertificate.props.issuer¶
- Name:
issuer- Type:
- Default Value:
- Flags:
A
Gio.TlsCertificaterepresenting the entity that issued this certificate. IfNone, 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.
New in version 2.28.
- Gio.TlsCertificate.props.issuer_name¶
-
The issuer from the certificate,
Noneif unavailable.New in version 2.70.
- Gio.TlsCertificate.props.not_valid_after¶
- Name:
not-valid-after- Type:
- Default Value:
- Flags:
The time at which this cert is no longer valid,
Noneif unavailable.New in version 2.70.
- Gio.TlsCertificate.props.not_valid_before¶
- Name:
not-valid-before- Type:
- Default Value:
- Flags:
The time at which this cert is considered to be valid,
Noneif unavailable.New in version 2.70.
- Gio.TlsCertificate.props.password¶
- Name:
password- Type:
- Default Value:
- Flags:
An optional password used when constructed with
Gio.TlsCertificate:pkcs12-data.New in version 2.72.
- Gio.TlsCertificate.props.pkcs11_uri¶
- Name:
pkcs11-uri- Type:
- Default Value:
- Flags:
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 theGio.TlsBackenddoes not support PKCS \#11.New in version 2.68.
- Gio.TlsCertificate.props.pkcs12_data¶
- Name:
pkcs12-data- Type:
- Default Value:
- Flags:
The PKCS #12 formatted data used to construct the object.
See also:
Gio.TlsCertificate.new_from_pkcs12()New in version 2.72.
- Gio.TlsCertificate.props.private_key¶
- Name:
private-key- Type:
- Default Value:
- Flags:
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 rsatool to convert PKCS \#8 keys to PKCS \#1.This property (or the
Gio.TlsCertificate:private-key-pemproperty) 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 beNone. If so, the private key must be referenced via its PKCS \#11 URI,Gio.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.New in version 2.28.
- Gio.TlsCertificate.props.private_key_pem¶
- Name:
private-key-pem- Type:
- Default Value:
- Flags:
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 theopenssl rsatool to convert PKCS \#8 keys to PKCS \#1.This property (or the
Gio.TlsCertificate:private-keyproperty) 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 beNone. If so, the private key must be referenced via its PKCS \#11 URI,Gio.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.New in version 2.28.