Struct gio::TlsCertificate

pub struct TlsCertificate { /* private fields */ }

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).

This is an Abstract Base Class, you cannot instantiate it.

Properties

certificate

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

Readable | Writeable | Construct Only

certificate-pem

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

Readable | Writeable | Construct Only

dns-names

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

Readable

ip-addresses

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

Readable

issuer

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.

Readable | Writeable | Construct Only

issuer-name

The issuer from the certificate, None if unavailable.

Readable

not-valid-after

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

Readable

not-valid-before

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

Readable

password

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

Writeable | Construct Only

pkcs11-uri

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][crate::TlsBackend] does not support PKCS \11`.

Readable | Writeable | Construct Only

pkcs12-data

The PKCS 12 formatted data used to construct the object.

See also: TlsCertificate::from_pkcs12()

Writeable | Construct Only

private-key

The DER (binary) encoded representation of the certificate’s private key, in either [PKCS `1 format](https://datatracker.ietf.org/doc/html/rfc8017) or unencrypted [PKCS \8 format.](https://datatracker.ietf.org/doc/html/rfc5208) 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 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, [private-key-pkcs11-uri][struct@crate::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`.

Readable | Writeable | Construct Only

private-key-pem

The PEM (ASCII) encoded representation of the certificate’s private key in either [PKCS `1 format](https://datatracker.ietf.org/doc/html/rfc8017) ("BEGIN RSA PRIVATE KEY") or unencrypted [PKCS \8 format](https://datatracker.ietf.org/doc/html/rfc5208) ("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 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, [private-key-pkcs11-uri][struct@crate::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`.

Readable | Writeable | Construct Only

private-key-pkcs11-uri

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

Readable | Writeable | Construct Only

subject-name

The subject from the cert, None if unavailable.

Readable

Implements

TlsCertificateExt, glib::ObjectExt

Implementations

impl TlsCertificate

pub const NONE: Option<&'static TlsCertificate> = None

pub fn from_file(file: impl AsRef<Path>) -> Result<TlsCertificate, Error>

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 from_pkcs12() otherwise it is loaded by from_pem(). See those functions for exact details.

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

file

file containing a certificate to import

Returns

the new certificate, or None on error

pub fn from_file_with_password( file: impl AsRef<Path>, password: &str ) -> Result<TlsCertificate, Error>

Available on crate feature v2_72 only.

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::NotSupported. Currently only .p12 and .pfx files are supported. See from_pkcs12() for more details.

file

file containing a certificate to import

password

password for PKCS 12 files

Returns

the new certificate, or None on error

pub fn from_files( cert_file: impl AsRef<Path>, key_file: impl AsRef<Path> ) -> Result<TlsCertificate, Error>

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 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 from_pem().

cert_file

file containing one or more PEM-encoded certificates to import

key_file

file containing a PEM-encoded private key to import

Returns

the new certificate, or None on error

pub fn from_pem(data: &str) -> Result<TlsCertificate, Error>

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

data

PEM-encoded certificate data

length

the length of data, or -1 if it’s 0-terminated.

Returns

the new certificate, or None if data is invalid

pub fn from_pkcs11_uris( pkcs11_uri: &str, private_key_pkcs11_uri: Option<&str> ) -> Result<TlsCertificate, Error>

Available on crate feature v2_68 only.

Creates a TlsCertificate from a PKCS `11` URI.

An example pkcs11_uri would be pkcs11:model=Model;manufacturer=Manufacture;serial=1;token=My20Client20Certificate`;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.

pkcs11_uri

A PKCS `11` URI

private_key_pkcs11_uri

A PKCS `11` URI

Returns

the new certificate, or None on error

pub fn from_pkcs12( data: &[u8], password: Option<&str> ) -> Result<TlsCertificate, Error>

Available on crate feature v2_72 only.

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

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

Other parsing failures will error with TlsError::BadCertificate.

data

DER-encoded PKCS 12 format certificate data

password

optional password for encrypted certificate data

Returns

the new certificate, or None if data is invalid

pub fn list_new_from_file( file: impl AsRef<Path> ) -> Result<Vec<TlsCertificate>, Error>

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.

file

file containing PEM-encoded certificates to import

Returns

a GList containing TlsCertificate objects. You must free the list and its contents when you are done with it.

Trait Implementations

impl Clone for TlsCertificate

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TlsCertificate

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for TlsCertificate

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl HasParamSpec for TlsCertificate

type ParamSpec = ParamSpecObject

type SetValue = TlsCertificate

Preferred value to be used as setter for the associated ParamSpec.

type BuilderFn = fn(_: &str) -> ParamSpecObjectBuilder<'_, TlsCertificate>

fn param_spec_builder() -> Self::BuilderFn

impl Hash for TlsCertificate

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for TlsCertificate

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized + PartialOrd,

Restrict a value to a certain interval.

impl ParentClassIs for TlsCertificate

type Parent = Object

impl<OT: ObjectType> PartialEq<OT> for TlsCertificate

fn eq(&self, other: &OT) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<OT: ObjectType> PartialOrd<OT> for TlsCertificate

fn partial_cmp(&self, other: &OT) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for TlsCertificate

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for TlsCertificate