class Gio::TlsCertificate

Overview

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

Defined in:

lib/gi-crystal/src/auto/gio-2.0/tls_certificate.cr

Constructors

Class Method Summary

Instance Method Summary

Instance methods inherited from class GObject::Object

==(other : self) ==, bind_property(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags) : GObject::Binding bind_property, bind_property_full(source_property : String, target : GObject::Object, target_property : String, flags : GObject::BindingFlags, transform_to : GObject::Closure, transform_from : GObject::Closure) : GObject::Binding bind_property_full, data(key : String) : Pointer(Void) | Nil data, finalize finalize, freeze_notify : Nil freeze_notify, getv(names : Enumerable(String), values : Enumerable(_)) : Nil getv, hash(hasher) hash, notify(property_name : String) : Nil notify, notify_by_pspec(pspec : GObject::ParamSpec) : Nil notify_by_pspec, notify_signal notify_signal, property(property_name : String, value : _) : Nil property, qdata(quark : UInt32) : Pointer(Void) | Nil qdata, ref_count : UInt32 ref_count, run_dispose : Nil run_dispose, set_data(key : String, data : Pointer(Void) | Nil) : Nil set_data, set_property(property_name : String, value : _) : Nil set_property, steal_data(key : String) : Pointer(Void) | Nil steal_data, steal_qdata(quark : UInt32) : Pointer(Void) | Nil steal_qdata, thaw_notify : Nil thaw_notify, to_unsafe : Pointer(Void) to_unsafe, watch_closure(closure : GObject::Closure) : Nil watch_closure

Constructor methods inherited from class GObject::Object

cast(obj : GObject::Object) : self cast, new(pointer : Pointer(Void), transfer : GICrystal::Transfer)
new new, newv(object_type : UInt64, parameters : Enumerable(GObject::Parameter)) : self newv

Class methods inherited from class GObject::Object

cast?(obj : GObject::Object) : self | Nil cast?, compat_control(what : UInt64, data : Pointer(Void) | Nil) : UInt64 compat_control, g_type : UInt64 g_type, interface_find_property(g_iface : GObject::TypeInterface, property_name : String) : GObject::ParamSpec interface_find_property, interface_list_properties(g_iface : GObject::TypeInterface) : Enumerable(GObject::ParamSpec) interface_list_properties

Macros inherited from class GObject::Object

previous_vfunc(*args) previous_vfunc, previous_vfunc!(*args) previous_vfunc!, signal(signature) signal

Constructor Detail

def self.new #

Initialize a new TlsCertificate.


[View source]
def self.new(*, certificate : Bytes | Nil = nil, certificate_pem : String | Nil = nil, dns_names : Enumerable(Pointer(Void)) | Nil = nil, ip_addresses : Enumerable(Pointer(Void)) | Nil = nil, issuer : Gio::TlsCertificate | Nil = nil, issuer_name : String | Nil = nil, not_valid_after : GLib::DateTime | Nil = nil, not_valid_before : GLib::DateTime | Nil = nil, password : String | Nil = nil, pkcs11_uri : String | Nil = nil, pkcs12_data : Bytes | Nil = nil, private_key : Bytes | Nil = nil, private_key_pem : String | Nil = nil, private_key_pkcs11_uri : String | Nil = nil, subject_name : String | Nil = nil) #

[View source]
def self.new_from_file(file : String) : self #

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 nil and set error.


[View source]
def self.new_from_file_with_password(file : String, password : String) : self #

Creates a #GTlsCertificate from the data in file.

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

Any unknown file types will error with %G_IO_ERROR_NOT_SUPPORTED. Currently only .p12 and .pfx files are supported. See g_tls_certificate_new_from_pkcs12() for more details.


[View source]
def self.new_from_files(cert_file : String, key_file : String) : self #

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 nil and set error. Otherwise, this behaves like g_tls_certificate_new_from_pem().


[View source]
def self.new_from_pem(data : String, length : Int64) : self #

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.


[View source]
def self.new_from_pkcs11_uris(pkcs11_uri : String, private_key_pkcs11_uri : String | Nil) : self #

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


[View source]
def self.new_from_pkcs12(data : Bytes, password : String | Nil) : self #

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

This constructor requires support in the current #GTlsBackend. If support is missing it will error with %G_IO_ERROR_NOT_SUPPORTED.

Other parsing failures will error with %G_TLS_ERROR_BAD_CERTIFICATE.


[View source]

Class Method Detail

def self.g_type : UInt64 #

Returns the type id (GType) registered in GLib type system.


[View source]

Instance Method Detail

def ==(other : self) #
Description copied from class Reference

Returns true if this reference is the same as other. Invokes same?.


def certificate : Bytes #

[View source]
def certificate=(value : Bytes) : Bytes #

[View source]
def certificate_pem : String #

[View source]
def certificate_pem=(value : String) : String #

[View source]
def certificate_pem=(value : Nil) : Nil #

Set #certificate_pem property to nil.


[View source]
def certificate_pem? : String | Nil #

Same as #certificate_pem, but can return nil.


[View source]
def dns_names : Enumerable(GLib::Bytes) | Nil #

Gets the value of #GTlsCertificate:dns-names.


[View source]
def hash(hasher) #
Description copied from class Reference

See Object#hash(hasher)


def ip_addresses : Enumerable(Gio::InetAddress) | Nil #

Gets the value of #GTlsCertificate:ip-addresses.


[View source]
def is_same(cert_two : Gio::TlsCertificate) : Bool #

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


[View source]
def issuer : Gio::TlsCertificate | Nil #

Gets the #GTlsCertificate representing cert's issuer, if known


[View source]
def issuer=(value : Gio::TlsCertificate | Nil) : Gio::TlsCertificate | Nil #

[View source]
def issuer_name : String | Nil #

Returns the issuer name from the certificate.


[View source]
def issuer_name? : String | Nil #

Same as #issuer_name, but can return nil.


[View source]
def list_new_from_file(file : String) : GLib::List #

[View source]
def not_valid_after : GLib::DateTime | Nil #

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


[View source]
def not_valid_before : GLib::DateTime | Nil #

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


[View source]
def password=(value : String) : String #

[View source]
def password=(value : Nil) : Nil #

Set #password property to nil.


[View source]
def pkcs11_uri : String #

[View source]
def pkcs11_uri=(value : String) : String #

[View source]
def pkcs11_uri=(value : Nil) : Nil #

Set #pkcs11_uri property to nil.


[View source]
def pkcs11_uri? : String | Nil #

Same as #pkcs11_uri, but can return nil.


[View source]
def pkcs12_data=(value : Bytes) : Bytes #

[View source]
def private_key : Bytes #

[View source]
def private_key=(value : Bytes) : Bytes #

[View source]
def private_key_pem : String #

[View source]
def private_key_pem=(value : String) : String #

[View source]
def private_key_pem=(value : Nil) : Nil #

Set #private_key_pem property to nil.


[View source]
def private_key_pem? : String | Nil #

Same as #private_key_pem, but can return nil.


[View source]
def private_key_pkcs11_uri : String #

[View source]
def private_key_pkcs11_uri=(value : String) : String #

[View source]
def private_key_pkcs11_uri=(value : Nil) : Nil #

Set #private_key_pkcs11_uri property to nil.


[View source]
def private_key_pkcs11_uri? : String | Nil #

Same as #private_key_pkcs11_uri, but can return nil.


[View source]
def subject_name : String | Nil #

Returns the subject name from the certificate.


[View source]
def subject_name? : String | Nil #

Same as #subject_name, but can return nil.


[View source]
def verify(identity : Gio::SocketConnectable | Nil, trusted_ca : Gio::TlsCertificate | Nil) : Gio::TlsCertificateFlags #

This verifies cert and returns a set of #GTlsCertificateFlags 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 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, #GTlsCertificate may not perform as many checks on the certificates as #GTlsConnection 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 #GTlsConnection handle the verification.


[View source]