Struct 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 #GTlsCertificate: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 #GTlsCertificate: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 #GTlsCertificate 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 #GTlsBackend does not support PKCS #11.

Readable | Writeable | Construct Only

pkcs12-data

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

See also: g_tls_certificate_new_from_pkcs12()

Writeable | Construct Only

private-key

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 #GTlsCertificate: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, #GTlsCertificate: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 (“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 #GTlsCertificate: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, #GTlsCertificate: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, [trait@glib::ObjectExt]

GLib type: GObject with reference counted clone semantics.

Implementations

impl TlsCertificate

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

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

Creates a #GTlsCertificate from the data in @file.

As of 2.72, if the filename ends in .p12 or .pfx the data is loaded by g_tls_certificate_new_from_pkcs12() otherwise it is loaded by g_tls_certificate_new_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 #GTlsCertificate 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 g_tls_certificate_new_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 #GTlsCertificate 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 #GTlsCertificate: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 g_tls_certificate_new_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 #GTlsCertificate 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 #GTlsCertificate: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 #GTlsCertificate: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 #GTlsCertificate 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 #GTlsCertificate 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 #GTlsCertificate: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 #GTlsBackend. 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 #GTlsCertificate 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

Makes a clone of this shared reference.

This increments the strong reference count of the object. Dropping the object will decrement it again.

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

Hashes the memory address of this object.

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

Comparison for two GObjects.

Compares the memory addresses of the provided objects.

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,

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

Equality for two GObjects.

Two GObjects are equal if their memory addresses are equal.

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

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>

Partial comparison for two GObjects.

Compares the memory addresses of the provided objects.

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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