Class: Gio::TlsCertificate

Inherits:
Object
  • Object
show all
Defined in:
(unknown)

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(data, length, password) ⇒ Gio::TlsCertificate

Creates a GTls::Certificate 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 GTls::Certificate: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 %G_TLS_ERROR_BAD_CERTIFICATE_PASSWORD.

This constructor requires support in the current GTls::Backend. If support is missing it will error with %G_IO_ERROR_NOT_SUPPORTED.

Other parsing failures will error with %G_TLS_ERROR_BAD_CERTIFICATE.

Parameters:

  • data (Array<Integer>) —

    DER-encoded PKCS #12 format certificate data

  • length (Integer) —

    the length of data

  • password (String) —

    optional password for encrypted certificate data

Class Method Details

.list_new_from_file(file) ⇒ GLib::List<Gio::TlsCertificate>

Creates one or more GTls::Certificates from the PEM-encoded data in file. If file cannot be read or parsed, the function will return nil and set error. If file does not contain any PEM-encoded certificates, this will return an empty list and not set error. #GList containing GTls::Certificate objects. You must free the list and its contents when you are done with it.

Parameters:

  • file (Gio::filename) —

    file containing PEM-encoded certificates to import

Returns:

Instance Method Details

#certificate ⇒ Gio::

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

Returns:

  • (Gio::) —

    certificate

#certificate=(certificate) ⇒ Gio::

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

Parameters:

Returns:

#certificate_pem ⇒ String

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

Returns:

  • (String) —

    certificate-pem

#certificate_pem=(certificate_pem) ⇒ String

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

Parameters:

  • certificate_pem (String)

Returns:

  • (String) —

    certificate-pem

  • (String) —

    certificate-pem

#dns_names ⇒ Gio::

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

Returns:

#dns_names=(dns_names) ⇒ Gio::

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

Parameters:

Returns:

#ip_addresses ⇒ Gio::

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

Returns:

  • (Gio::) —

    ip-addresses

#ip_addresses=(ip_addresses) ⇒ Gio::

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

Parameters:

Returns:

  • (Gio::) —

    ip-addresses

  • (Gio::) —

    ip-addresses

#is_same(cert_two) ⇒ Boolean

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

Parameters:

Returns:

  • (Boolean) —

    whether the same or not

#issuer ⇒ Gio::TlsCertificate

A GTls::Certificate representing the entity that issued this certificate. If nil, 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.

Returns:

#issuer=(issuer) ⇒ Gio::TlsCertificate

A GTls::Certificate representing the entity that issued this certificate. If nil, 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.

Parameters:

Returns:

#issuer_name ⇒ String

The issuer from the certificate, nil if unavailable.

Returns:

  • (String) —

    issuer-name

#issuer_name=(issuer_name) ⇒ String

The issuer from the certificate, nil if unavailable.

Parameters:

  • issuer_name (String)

Returns:

  • (String) —

    issuer-name

  • (String) —

    issuer-name

#not_valid_after ⇒ GLib::DateTime

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

Returns:

  • (GLib::DateTime) —

    not-valid-after

#not_valid_after=(not_valid_after) ⇒ GLib::DateTime

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

Parameters:

  • not_valid_after (GLib::DateTime)

Returns:

  • (GLib::DateTime) —

    not-valid-after

  • (GLib::DateTime) —

    not-valid-after

#not_valid_before ⇒ GLib::DateTime

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

Returns:

  • (GLib::DateTime) —

    not-valid-before

#not_valid_before=(not_valid_before) ⇒ GLib::DateTime

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

Parameters:

  • not_valid_before (GLib::DateTime)

Returns:

  • (GLib::DateTime) —

    not-valid-before

  • (GLib::DateTime) —

    not-valid-before

#password=(password) ⇒ String

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

Parameters:

  • password (String)

Returns:

  • (String) —

    password

#pkcs11_uri ⇒ String

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

If nil, the certificate is either not backed by PKCS #11 or the GTls::Backend does not support PKCS #11.

Returns:

  • (String) —

    pkcs11-uri

#pkcs11_uri=(pkcs11_uri) ⇒ String

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

If nil, the certificate is either not backed by PKCS #11 or the GTls::Backend does not support PKCS #11.

Parameters:

  • pkcs11_uri (String)

Returns:

  • (String) —

    pkcs11-uri

  • (String) —

    pkcs11-uri

#pkcs12_data=(pkcs12_data) ⇒ Gio::

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

See also: g_tls_certificate_new_from_pkcs12()

Parameters:

Returns:

  • (Gio::) —

    pkcs12-data

#private_key ⇒ Gio::

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 GTls::Certificate: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 nil. If so, the private key must be referenced via its PKCS #11 URI, GTls::Certificate: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.

Returns:

  • (Gio::) —

    private-key

#private_key=(private_key) ⇒ Gio::

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 GTls::Certificate: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 nil. If so, the private key must be referenced via its PKCS #11 URI, GTls::Certificate: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.

Parameters:

Returns:

#private_key_pem ⇒ String

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 GTls::Certificate: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 nil. If so, the private key must be referenced via its PKCS #11 URI, GTls::Certificate: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.

Returns:

  • (String) —

    private-key-pem

#private_key_pem=(private_key_pem) ⇒ String

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 GTls::Certificate: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 nil. If so, the private key must be referenced via its PKCS #11 URI, GTls::Certificate: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.

Parameters:

  • private_key_pem (String)

Returns:

  • (String) —

    private-key-pem

  • (String) —

    private-key-pem

#private_key_pkcs11_uri ⇒ String

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

Returns:

  • (String) —

    private-key-pkcs11-uri

#private_key_pkcs11_uri=(private_key_pkcs11_uri) ⇒ String

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

Parameters:

  • private_key_pkcs11_uri (String)

Returns:

  • (String) —

    private-key-pkcs11-uri

  • (String) —

    private-key-pkcs11-uri

#subject_name ⇒ String

The subject from the cert, nil if unavailable.

Returns:

  • (String) —

    subject-name

#subject_name=(subject_name) ⇒ String

The subject from the cert, nil if unavailable.

Parameters:

  • subject_name (String)

Returns:

  • (String) —

    subject-name

  • (String) —

    subject-name

#verify(identity, trusted_ca) ⇒ Gio::TlsCertificateFlags

This verifies cert and returns a set of GTls::CertificateFlags 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, %G_TLS_CERTIFICATE_NO_FLAGS is returned.

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

If trusted_ca is not nil, then cert (or one of the certificates in its chain) must be signed by it, or else %G_TLS_CERTIFICATE_UNKNOWN_CA will be set in the return value. If trusted_ca is nil, 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 %G_TLS_CERTIFICATE_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, GTls::Certificate may not perform as many checks on the certificates as GTls::Connection 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 GTls::Connection handle the verification.

Parameters:

Returns: