GTlsCertificate

GTlsCertificate — TLS certificate

Functions

Properties

GByteArray * certificate Read / Write / Construct Only
char * certificate-pem Read / Write / Construct Only
GPtrArray * dns-names Read
GPtrArray * ip-addresses Read
GTlsCertificate * issuer Read / Write / Construct Only
char * issuer-name Read
GDateTime * not-valid-after Read
GDateTime * not-valid-before Read
char * pkcs11-uri Read / Write / Construct Only
GByteArray * private-key Read / Write / Construct Only
char * private-key-pem Read / Write / Construct Only
char * private-key-pkcs11-uri Read / Write / Construct Only
char * subject-name Read

Types and Values

Object Hierarchy

    GObject
    ╰── GTlsCertificate

Includes

#include <gio/gio.h>

Description

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

Functions

g_tls_certificate_new_from_pem ()

GTlsCertificate *
g_tls_certificate_new_from_pem (const gchar *data,
                                gssize length,
                                GError **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 “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.

Parameters

data

PEM-encoded certificate data

 

length

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

 

error

GError for error reporting, or NULL to ignore.

 

Returns

the new certificate, or NULL if data is invalid

Since: 2.28


g_tls_certificate_new_from_file ()

GTlsCertificate *
g_tls_certificate_new_from_file (const gchar *file,
                                 GError **error);

Creates a GTlsCertificate from the PEM-encoded data in file . The returned certificate will be the first certificate found in file . As of GLib 2.44, if 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 file cannot be read or parsed, the function will return NULL and set error . Otherwise, this behaves like g_tls_certificate_new_from_pem().

Parameters

file

file containing a PEM-encoded certificate to import.

[type filename]

error

GError for error reporting, or NULL to ignore.

 

Returns

the new certificate, or NULL on error

Since: 2.28


g_tls_certificate_new_from_files ()

GTlsCertificate *
g_tls_certificate_new_from_files (const gchar *cert_file,
                                  const gchar *key_file,
                                  GError **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 “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 NULL and set error . Otherwise, this behaves like g_tls_certificate_new_from_pem().

Parameters

cert_file

file containing one or more PEM-encoded certificates to import.

[type filename]

key_file

file containing a PEM-encoded private key to import.

[type filename]

error

GError for error reporting, or NULL to ignore.

 

Returns

the new certificate, or NULL on error

Since: 2.28


g_tls_certificate_new_from_pkcs11_uris ()

GTlsCertificate *
g_tls_certificate_new_from_pkcs11_uris
                               (const gchar *pkcs11_uri,
                                const gchar *private_key_pkcs11_uri,
                                GError **error);

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:

1
2
3
4
5
6
7
8
9
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.

Parameters

pkcs11_uri

A PKCS #11 URI

 

private_key_pkcs11_uri

A PKCS #11 URI.

[nullable]

error

GError for error reporting, or NULL to ignore.

 

Returns

the new certificate, or NULL on error.

[transfer full]

Since: 2.68


g_tls_certificate_list_new_from_file ()

GList *
g_tls_certificate_list_new_from_file (const gchar *file,
                                      GError **error);

Creates one or more GTlsCertificates from the PEM-encoded data in file . If file cannot be read or parsed, the function will return NULL and set error . If file does not contain any PEM-encoded certificates, this will return an empty list and not set error .

Parameters

file

file containing PEM-encoded certificates to import.

[type filename]

error

GError for error reporting, or NULL to ignore.

 

Returns

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

[element-type Gio.TlsCertificate][transfer full]

Since: 2.28


g_tls_certificate_get_dns_names ()

GPtrArray *
g_tls_certificate_get_dns_names (GTlsCertificate *cert);

Gets the value of “dns-names”.

Parameters

cert

a GTlsCertificate

 

Returns

A GPtrArray of GBytes elements, or NULL if it's not available.

[nullable][element-type GBytes][transfer container]

Since: 2.70


g_tls_certificate_get_ip_addresses ()

GPtrArray *
g_tls_certificate_get_ip_addresses (GTlsCertificate *cert);

Gets the value of “ip-addresses”.

Parameters

cert

a GTlsCertificate

 

Returns

A GPtrArray of GInetAddress elements, or NULL if it's not available.

[nullable][element-type GInetAddress][transfer container]

Since: 2.70


g_tls_certificate_get_issuer ()

GTlsCertificate *
g_tls_certificate_get_issuer (GTlsCertificate *cert);

Gets the GTlsCertificate representing cert 's issuer, if known

Parameters

cert

a GTlsCertificate

 

Returns

The certificate of cert 's issuer, or NULL if cert is self-signed or signed with an unknown certificate.

[nullable][transfer none]

Since: 2.28


g_tls_certificate_get_issuer_name ()

gchar *
g_tls_certificate_get_issuer_name (GTlsCertificate *cert);

Returns the issuer name from the certificate.

Parameters

cert

a GTlsCertificate

 

Returns

The issuer name, or NULL if it's not available.

[nullable][transfer full]

Since: 2.70


g_tls_certificate_get_not_valid_before ()

GDateTime *
g_tls_certificate_get_not_valid_before
                               (GTlsCertificate *cert);

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

Parameters

cert

a GTlsCertificate

 

Returns

The not-valid-before date, or NULL if it's not available.

[nullable][transfer full]

Since: 2.70


g_tls_certificate_get_not_valid_after ()

GDateTime *
g_tls_certificate_get_not_valid_after (GTlsCertificate *cert);

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

Parameters

cert

a GTlsCertificate

 

Returns

The not-valid-after date, or NULL if it's not available.

[nullable][transfer full]

Since: 2.70


g_tls_certificate_get_subject_name ()

gchar *
g_tls_certificate_get_subject_name (GTlsCertificate *cert);

Returns the subject name from the certificate.

Parameters

cert

a GTlsCertificate

 

Returns

The subject name, or NULL if it's not available.

[nullable][transfer full]

Since: 2.70


g_tls_certificate_verify ()

GTlsCertificateFlags
g_tls_certificate_verify (GTlsCertificate *cert,
                          GSocketConnectable *identity,
                          GTlsCertificate *trusted_ca);

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 NULL, 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 NULL, that bit will never be set in the return value.

If trusted_ca is not NULL, 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 NULL, that bit will never be set in the return value.

(All other GTlsCertificateFlags values will always be set or unset as appropriate.)

Parameters

cert

a GTlsCertificate

 

identity

the expected peer identity.

[nullable]

trusted_ca

the certificate of a trusted authority.

[nullable]

Returns

the appropriate GTlsCertificateFlags

Since: 2.28


g_tls_certificate_is_same ()

gboolean
g_tls_certificate_is_same (GTlsCertificate *cert_one,
                           GTlsCertificate *cert_two);

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 “issuer”, “private-key”, or “private-key-pem” properties differ.

Parameters

cert_one

first certificate to compare

 

cert_two

second certificate to compare

 

Returns

whether the same or not

Since: 2.34

Types and Values

GTlsCertificate

typedef struct _GTlsCertificate GTlsCertificate;

Abstract base class for TLS certificate types.

Since: 2.28

Property Details

The “certificate” property

  “certificate”              GByteArray *

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

Owner: GTlsCertificate

Flags: Read / Write / Construct Only

Since: 2.28


The “certificate-pem” property

  “certificate-pem”          char *

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

Owner: GTlsCertificate

Flags: Read / Write / Construct Only

Default value: NULL

Since: 2.28


The “dns-names” property

  “dns-names”                GPtrArray *

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

[transfer container]

Owner: GTlsCertificate

Flags: Read

Since: 2.70


The “ip-addresses” property

  “ip-addresses”             GPtrArray *

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

[transfer container]

Owner: GTlsCertificate

Flags: Read

Since: 2.70


The “issuer” property

  “issuer”                   GTlsCertificate *

A GTlsCertificate representing the entity that issued this certificate. If NULL, this means that the certificate is either self-signed, or else the certificate of the issuer is not available.

Owner: GTlsCertificate

Flags: Read / Write / Construct Only

Since: 2.28


The “issuer-name” property

  “issuer-name”              char *

The issuer from the certificate, NULL if unavailable.

[nullable]

Owner: GTlsCertificate

Flags: Read

Default value: NULL

Since: 2.70


The “not-valid-after” property

  “not-valid-after”          GDateTime *

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

[nullable]

Owner: GTlsCertificate

Flags: Read

Since: 2.70


The “not-valid-before” property

  “not-valid-before”         GDateTime *

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

[nullable]

Owner: GTlsCertificate

Flags: Read

Since: 2.70


The “pkcs11-uri” property

  “pkcs11-uri”               char *

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

If NULL, the certificate is either not backed by PKCS #11 or the GTlsBackend does not support PKCS #11.

[nullable]

Owner: GTlsCertificate

Flags: Read / Write / Construct Only

Default value: NULL

Since: 2.68


The “private-key” property

  “private-key”              GByteArray *

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

[nullable]

Owner: GTlsCertificate

Flags: Read / Write / Construct Only

Since: 2.28


The “private-key-pem” property

  “private-key-pem”          char *

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

[nullable]

Owner: GTlsCertificate

Flags: Read / Write / Construct Only

Default value: NULL

Since: 2.28


The “private-key-pkcs11-uri” property

  “private-key-pkcs11-uri”   char *

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

[nullable]

Owner: GTlsCertificate

Flags: Read / Write / Construct Only

Default value: NULL

Since: 2.68


The “subject-name” property

  “subject-name”             char *

The subject from the cert, NULL if unavailable.

[nullable]

Owner: GTlsCertificate

Flags: Read

Default value: NULL

Since: 2.70

See Also

GTlsConnection