GTlsCertificate

## GTlsCertificate GTlsCertificate — TLS certificate |

## Synopsis

                        GTlsCertificate;
    GTlsCertificate *   g_tls_certificate_new_from_pem      (const gchar *data,
                                                             gssize length,
                                                             GError **error);
    GTlsCertificate *   g_tls_certificate_new_from_file     (const gchar *file,
                                                             GError **error);
    GTlsCertificate *   g_tls_certificate_new_from_files    (const gchar *cert_file,
                                                             const gchar *key_file,
                                                             GError **error);
    GList *             g_tls_certificate_list_new_from_file
                                                            (const gchar *file,
                                                             GError **error);
    GTlsCertificate *   g_tls_certificate_get_issuer        (GTlsCertificate *cert);
    GTlsCertificateFlags g_tls_certificate_verify           (GTlsCertificate *cert,
                                                             GSocketConnectable *identity,
                                                             GTlsCertificate *trusted_ca);
    gboolean            g_tls_certificate_is_same           (GTlsCertificate *cert_one,
                                                             GTlsCertificate *cert_two);

## Object Hierarchy

      GObject
       +----GTlsCertificate

## Properties

      "certificate"              GByteArray*           : Read / Write / Construct Only
      "certificate-pem"          gchar*                : Read / Write / Construct Only
      "issuer"                   GTlsCertificate*      : Read / Write / Construct Only
      "private-key"              GByteArray*           : Write / Construct Only
      "private-key-pem"          gchar*                : Write / Construct Only

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

## Details

### GTlsCertificate

    typedef struct _GTlsCertificate GTlsCertificate;

Abstract base class for TLS certificate types.

Since 2.28

### g_tls_certificate_new_from_pem ()

    GTlsCertificate *   g_tls_certificate_new_from_pem      (const gchar *data,
                                                             gssize length,
                                                             GError **error);

Creates a new 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.)

If `data` includes multiple certificates, only the first one will be parsed.

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

`file` : | file containing a PEM-encoded certificate to import
`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`. 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()`.

`cert_file` : | file containing a PEM-encoded certificate to import
`key_file` : | file containing a PEM-encoded private key to import
`error` : | GError for error reporting, or `NULL` to ignore.
Returns : | the new certificate, or `NULL` on error

Since 2.28

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

`file` : | file containing PEM-encoded certificates to import
`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_issuer ()

    GTlsCertificate *   g_tls_certificate_get_issuer        (GTlsCertificate *cert);

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

`cert` : | a GTlsCertificate
Returns : | The certificate of `cert`'s issuer, or `NULL` if `cert` is self-signed or signed with an unknown certificate. [transfer none]

Since 2.28

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

`cert` : | a GTlsCertificate
`identity` : | the expected peer identity. [allow-none]
`trusted_ca` : | the certificate of a trusted authority. [allow-none]
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.

`cert_one` : | first certificate to compare
`cert_two` : | second certificate to compare
Returns : | whether the same or not

Since 2.34

## Property Details

### The `"certificate"` property

      "certificate"              GByteArray*           : Read / Write / Construct Only

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

Since 2.28

### The `"certificate-pem"` property

      "certificate-pem"          gchar*                : Read / Write / Construct Only

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

Default value: NULL

Since 2.28

### The `"issuer"` property

      "issuer"                   GTlsCertificate*      : Read / Write / Construct Only

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.

Since 2.28

### The `"private-key"` property

      "private-key"              GByteArray*           : Write / Construct Only

The DER (binary) encoded representation of the certificate's private key, in either PKCS#1 format or unencrypted PKCS#8 format. This property (or the "private-key-pem" property) can be set when constructing a key (eg, from a file), but cannot be read.

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.

Since 2.28

### The `"private-key-pem"` property

      "private-key-pem"          gchar*                : Write / Construct Only

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`"). This property (or the "private-key" property) can be set when constructing a key (eg, from a file), but cannot be read.

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.

Default value: NULL

Since 2.28

## See Also

GTlsConnection