GMimeCertificate: GMime 3.0 Reference Manual

## GMimeCertificate

GMimeCertificate — Digital certificates

## Functions

GMimeCertificate * | g_mime_certificate_new ()
GMimePubKeyAlgo | g_mime_certificate_get_pubkey_algo ()
void | g_mime_certificate_set_pubkey_algo ()
GMimeDigestAlgo | g_mime_certificate_get_digest_algo ()
void | g_mime_certificate_set_digest_algo ()
const char * | g_mime_certificate_get_issuer_serial ()
void | g_mime_certificate_set_issuer_serial ()
const char * | g_mime_certificate_get_issuer_name ()
void | g_mime_certificate_set_issuer_name ()
const char * | g_mime_certificate_get_fingerprint ()
void | g_mime_certificate_set_fingerprint ()
time_t | g_mime_certificate_get_created ()
void | g_mime_certificate_set_created ()
gint64 | g_mime_certificate_get_created64 ()
time_t | g_mime_certificate_get_expires ()
void | g_mime_certificate_set_expires ()
gint64 | g_mime_certificate_get_expires64 ()
const char * | g_mime_certificate_get_key_id ()
void | g_mime_certificate_set_key_id ()
GMimeTrust | g_mime_certificate_get_trust ()
void | g_mime_certificate_set_trust ()
const char * | g_mime_certificate_get_email ()
void | g_mime_certificate_set_email ()
const char * | g_mime_certificate_get_name ()
void | g_mime_certificate_set_name ()
const char * | g_mime_certificate_get_user_id ()
void | g_mime_certificate_set_user_id ()
GMimeValidity | g_mime_certificate_get_id_validity ()
void | g_mime_certificate_set_id_validity ()
GMimeCertificateList * | g_mime_certificate_list_new ()
int | g_mime_certificate_list_length ()
void | g_mime_certificate_list_clear ()
int | g_mime_certificate_list_add ()
void | g_mime_certificate_list_insert ()
gboolean | g_mime_certificate_list_remove ()
gboolean | g_mime_certificate_list_remove_at ()
gboolean | g_mime_certificate_list_contains ()
int | g_mime_certificate_list_index_of ()
GMimeCertificate * | g_mime_certificate_list_get_certificate ()
void | g_mime_certificate_list_set_certificate ()

## Types and Values

enum | GMimePubKeyAlgo
enum | GMimeDigestAlgo
enum | GMimeTrust
enum | GMimeValidity
struct | GMimeCertificate
struct | GMimeCertificateList

## Object Hierarchy

        GObject
        ├── GMimeCertificate
        ╰── GMimeCertificateList

## Description

A GMimeCertificate is an object containing useful information about a digital certificate as used in signing and encrypting data.

## Functions

### g_mime_certificate_new ()

    GMimeCertificate *
    g_mime_certificate_new (void);

Creates a new GMimeCertificate object.

#### Returns

a new GMimeCertificate object.

### g_mime_certificate_get_pubkey_algo ()

    GMimePubKeyAlgo
    g_mime_certificate_get_pubkey_algo (GMimeCertificate *cert);

Get the public-key algorithm used by the certificate.

#### Parameters

cert | a GMimeCertificate |

#### Returns

the public-key algorithm used by the certificate or GMIME_PUBKEY_ALGO_DEFAULT if unspecified.

### g_mime_certificate_set_pubkey_algo ()

    void
    g_mime_certificate_set_pubkey_algo (GMimeCertificate *cert,
                                        GMimePubKeyAlgo algo);

Set the public-key algorithm used by the certificate.

#### Parameters

cert | a GMimeCertificate |
algo | a GMimePubKeyAlgo |

### g_mime_certificate_get_digest_algo ()

    GMimeDigestAlgo
    g_mime_certificate_get_digest_algo (GMimeCertificate *cert);

Get the digest algorithm used by the certificate.

#### Parameters

cert | a GMimeCertificate |

#### Returns

the digest algorithm used by the certificate or GMIME_DIGEST_ALGO_DEFAULT if unspecified.

### g_mime_certificate_set_digest_algo ()

    void
    g_mime_certificate_set_digest_algo (GMimeCertificate *cert,
                                        GMimeDigestAlgo algo);

Set the digest algorithm used by the certificate.

#### Parameters

cert | a GMimeCertificate |
algo | a GMimeDigestAlgo |

### g_mime_certificate_get_issuer_serial ()

    const char *
    g_mime_certificate_get_issuer_serial (GMimeCertificate *cert);

Get the certificate's issuer serial.

#### Parameters

cert | a GMimeCertificate |

#### Returns

the certificate's issuer serial or `NULL` if unspecified.

### g_mime_certificate_set_issuer_serial ()

    void
    g_mime_certificate_set_issuer_serial (GMimeCertificate *cert,
                                          const char *issuer_serial);

Set the certificate's issuer serial.

#### Parameters

cert | a GMimeCertificate |
issuer_serial | certificate's issuer serial |

### g_mime_certificate_get_issuer_name ()

    const char *
    g_mime_certificate_get_issuer_name (GMimeCertificate *cert);

Get the certificate's issuer name.

#### Parameters

cert | a GMimeCertificate |

#### Returns

the certificate's issuer name or `NULL` if unspecified.

### g_mime_certificate_set_issuer_name ()

    void
    g_mime_certificate_set_issuer_name (GMimeCertificate *cert,
                                        const char *issuer_name);

Set the certificate's issuer name.

#### Parameters

cert | a GMimeCertificate |
issuer_name | certificate's issuer name |

### g_mime_certificate_get_fingerprint ()

    const char *
    g_mime_certificate_get_fingerprint (GMimeCertificate *cert);

Get the certificate's key fingerprint.

#### Parameters

cert | a GMimeCertificate |

#### Returns

the certificate's key fingerprint or `NULL` if unspecified.

### g_mime_certificate_set_fingerprint ()

    void
    g_mime_certificate_set_fingerprint (GMimeCertificate *cert,
                                        const char *fingerprint);

Set the certificate's key fingerprint.

#### Parameters

cert | a GMimeCertificate |
fingerprint | fingerprint string |

### g_mime_certificate_get_created ()

    time_t
    g_mime_certificate_get_created (GMimeCertificate *cert);

Get the creation date of the certificate's key.

#### Parameters

cert | a GMimeCertificate |

#### Returns

the creation date of the certificate's key or `-1` if unknown.

### g_mime_certificate_set_created ()

    void
    g_mime_certificate_set_created (GMimeCertificate *cert,
                                    time_t created);

Set the creation date of the certificate's key.

#### Parameters

cert | a GMimeCertificate |
created | creation date |

### g_mime_certificate_get_created64 ()

    gint64
    g_mime_certificate_get_created64 (GMimeCertificate *cert);

Get the creation date of the certificate's key in seconds since the UNIX epoch, represented as a 64-bit signed integer.

#### Parameters

cert | a GMimeCertificate |

#### Returns

the creation date of the certificate's key or `-1` if unknown.

### g_mime_certificate_get_expires ()

    time_t
    g_mime_certificate_get_expires (GMimeCertificate *cert);

Get the expiration date of the certificate's key. A value of `0` means the certificate never expires.

#### Parameters

cert | a GMimeCertificate |

#### Returns

the expiration date of the certificate's key or `-1` if unknown.

### g_mime_certificate_set_expires ()

    void
    g_mime_certificate_set_expires (GMimeCertificate *cert,
                                    time_t expires);

Set the expiration date of the certificate's key. A value of `0` means the certificate never expires.

#### Parameters

cert | a GMimeCertificate |
expires | expiration date |

### g_mime_certificate_get_expires64 ()

    gint64
    g_mime_certificate_get_expires64 (GMimeCertificate *cert);

Get the expiration date of the certificate's key in seconds since the UNIX epoch, represented as a 64-bit signed integer. A value of `0` means the certificate never expires.

#### Parameters

cert | a GMimeCertificate |

#### Returns

the expiration date of the certificate's key or `-1` if unknown.

### g_mime_certificate_get_key_id ()

    const char *
    g_mime_certificate_get_key_id (GMimeCertificate *cert);

Get the certificate's key id.

#### Parameters

cert | a GMimeCertificate |

#### Returns

the certificate's key id or `NULL` if unspecified.

### g_mime_certificate_set_key_id ()

    void
    g_mime_certificate_set_key_id (GMimeCertificate *cert,
                                   const char *key_id);

Set the certificate's key id.

#### Parameters

cert | a GMimeCertificate |
key_id | key id |

### g_mime_certificate_get_trust ()

    GMimeTrust
    g_mime_certificate_get_trust (GMimeCertificate *cert);

Get the certificate trust.

#### Parameters

cert | a GMimeCertificate |

#### Returns

the certificate trust.

### g_mime_certificate_set_trust ()

    void
    g_mime_certificate_set_trust (GMimeCertificate *cert,
                                  GMimeTrust trust);

Set the certificate trust.

#### Parameters

cert | a GMimeCertificate |
trust | a GMimeTrust value |

### g_mime_certificate_get_email ()

    const char *
    g_mime_certificate_get_email (GMimeCertificate *cert);

Get the email address associated with the certificate. If the certificate contains more than one email address with different validities, the email address with the highest validity is returned. If more than one email address appears in the certificate with the same (highest) validity, the first such email address will be returned.

#### Parameters

cert | a GMimeCertificate |

#### Returns

the relevant e-mail address, or `NULL` if unspecified.

### g_mime_certificate_set_email ()

    void
    g_mime_certificate_set_email (GMimeCertificate *cert,
                                  const char *email);

Set the email address associated with the certificate. (e.g. "jane@example.org")

#### Parameters

cert | a GMimeCertificate |
email | certificate's email |

### g_mime_certificate_get_name ()

    const char *
    g_mime_certificate_get_name (GMimeCertificate *cert);

Get the name associated with the certificate. For email certificates, this is usually the name of the person who controls the certificate (encoded in UTF-8). If the certificate contains more than one name with different validities, the name with the highest validity is returned. If more than one name appears in the certificate with the same (highest) validity, the first such name will be returned.

#### Parameters

cert | a GMimeCertificate |

#### Returns

the the relevant name or `NULL` if unspecified.

### g_mime_certificate_set_name ()

    void
    g_mime_certificate_set_name (GMimeCertificate *cert,
                                 const char *name);

Set the name associated with the certificate. For email certificates, this is usually the name of the person who controls the certificate (encoded in UTF-8). (e.g. "Jane Doe")

#### Parameters

cert | a GMimeCertificate |
name | certificate's name |

### g_mime_certificate_get_user_id ()

    const char *
    g_mime_certificate_get_user_id (GMimeCertificate *cert);

Get the certificate's full User ID. If the certificate contains more than one User ID with different validities, the User ID with the highest validity is returned. If more than one User ID appears in the certificate with the same (highest) validity, the first such User ID will be returned.

#### Parameters

cert | a GMimeCertificate |

#### Returns

the relevant User ID or `NULL` if unspecified.

### g_mime_certificate_set_user_id ()

    void
    g_mime_certificate_set_user_id (GMimeCertificate *cert,
                                    const char *user_id);

Set the certificate's full User ID. By convention, this is usually a mail name-addr as described in RFC 5322. (e.g. "Jane Doe <jane@example.org>")

#### Parameters

cert | a GMimeCertificate |
user_id | the full User ID for a certificate |

### g_mime_certificate_get_id_validity ()

    GMimeValidity
    g_mime_certificate_get_id_validity (GMimeCertificate *cert);

Get the validity of the certificate's identity information. This validity applies to the name, email, and user_id fields associated with the certificate.

#### Parameters

cert | a GMimeCertificate |

#### Returns

the identity validity of the certificate.

### g_mime_certificate_set_id_validity ()

    void
    g_mime_certificate_set_id_validity (GMimeCertificate *cert,
                                        GMimeValidity validity);

Set the validity associated with the certificate's name, email, and user_id.

#### Parameters

cert | a GMimeCertificate |
validity | a GMimeValidity representing the validity of the certificate's identity information. |

### g_mime_certificate_list_new ()

    GMimeCertificateList *
    g_mime_certificate_list_new (void);

Creates a new GMimeCertificateList.

#### Returns

a new GMimeCertificateList.

### g_mime_certificate_list_length ()

    int
    g_mime_certificate_list_length (GMimeCertificateList *list);

Gets the length of the list.

#### Parameters

list | a GMimeCertificateList |

#### Returns

the number of GMimeCertificate objects in the list.

### g_mime_certificate_list_clear ()

    void
    g_mime_certificate_list_clear (GMimeCertificateList *list);

Clears the list of certificates.

#### Parameters

list | a GMimeCertificateList |

### g_mime_certificate_list_add ()

    int
    g_mime_certificate_list_add (GMimeCertificateList *list,
                                 GMimeCertificate *cert);

Adds a GMimeCertificate to the GMimeCertificateList.

#### Parameters

list | a GMimeCertificateList |
cert | a GMimeCertificate |

#### Returns

the index of the added GMimeCertificate.

### g_mime_certificate_list_insert ()

    void
    g_mime_certificate_list_insert (GMimeCertificateList *list,
                                    int index,
                                    GMimeCertificate *cert);

Inserts a GMimeCertificate into the GMimeCertificateList at the specified index.

#### Parameters

list | a GMimeCertificateList |
index | index to insert at |
cert | a GMimeCertificate |

### g_mime_certificate_list_remove ()

    gboolean
    g_mime_certificate_list_remove (GMimeCertificateList *list,
                                    GMimeCertificate *cert);

Removes a GMimeCertificate from the GMimeCertificateList.

#### Parameters

list | a GMimeCertificateList |
cert | a GMimeCertificate |

#### Returns

`TRUE` if the specified GMimeCertificate was removed or `FALSE` otherwise.

### g_mime_certificate_list_remove_at ()

    gboolean
    g_mime_certificate_list_remove_at (GMimeCertificateList *list,
                                       int index);

Removes a GMimeCertificate from the GMimeCertificateList at the specified index.

#### Parameters

list | a GMimeCertificateList |
index | index of the certificate to remove |

#### Returns

`TRUE` if a GMimeCertificate was removed or `FALSE` otherwise.

### g_mime_certificate_list_contains ()

    gboolean
    g_mime_certificate_list_contains (GMimeCertificateList *list,
                                      GMimeCertificate *cert);

Checks whether or not the specified GMimeCertificate is contained within the GMimeCertificateList.

#### Parameters

list | a GMimeCertificateList |
cert | a GMimeCertificate |

#### Returns

`TRUE` if the specified GMimeCertificate is contained within the specified GMimeCertificateList or `FALSE` otherwise.

### g_mime_certificate_list_index_of ()

    int
    g_mime_certificate_list_index_of (GMimeCertificateList *list,
                                      GMimeCertificate *cert);

Gets the index of the specified GMimeCertificate inside the GMimeCertificateList.

#### Parameters

list | a GMimeCertificateList |
cert | a GMimeCertificate |

#### Returns

the index of the requested GMimeCertificate within the GMimeCertificateList or `-1` if it is not contained within the GMimeCertificateList.

### g_mime_certificate_list_get_certificate ()

    GMimeCertificate *
    g_mime_certificate_list_get_certificate
                                   (GMimeCertificateList *list,
                                    int index);

Gets the GMimeCertificate at the specified index.

#### Parameters

list | a GMimeCertificateList |
index | index of GMimeCertificate to get |

#### Returns

the GMimeCertificate at the specified index or `NULL` if the index is out of range.

[transfer full]

### g_mime_certificate_list_set_certificate ()

    void
    g_mime_certificate_list_set_certificate
                                   (GMimeCertificateList *list,
                                    int index,
                                    GMimeCertificate *cert);

Sets the GMimeCertificate at the specified index to `cert` .

#### Parameters

list | a GMimeCertificateList |
index | index of GMimeCertificate to set |
cert | a GMimeCertificate |

## Types and Values

### enum GMimePubKeyAlgo

A public-key algorithm.

#### Members

GMIME_PUBKEY_ALGO_DEFAULT | The default public-key algorithm. |
GMIME_PUBKEY_ALGO_RSA | The RSA algorithm. |
GMIME_PUBKEY_ALGO_RSA_E | An encryption-only RSA algorithm. |
GMIME_PUBKEY_ALGO_RSA_S | A signature-only RSA algorithm. |
GMIME_PUBKEY_ALGO_ELG_E | An encryption-only ElGamal algorithm. |
GMIME_PUBKEY_ALGO_DSA | The DSA algorithm. |
GMIME_PUBKEY_ALGO_ECC | The Eliptic Curve algorithm. |
GMIME_PUBKEY_ALGO_ELG | The ElGamal algorithm. |
GMIME_PUBKEY_ALGO_ECDSA | The Eliptic Curve + DSA algorithm. |
GMIME_PUBKEY_ALGO_ECDH | The Eliptic Curve + Diffie Helman algorithm. |
GMIME_PUBKEY_ALGO_EDDSA | The Eliptic Curve + DSA algorithm. |

### enum GMimeDigestAlgo

A hash algorithm.

#### Members

GMIME_DIGEST_ALGO_DEFAULT | The default hash algorithm. |
GMIME_DIGEST_ALGO_MD5 | The MD5 hash algorithm. |
GMIME_DIGEST_ALGO_SHA1 | The SHA-1 hash algorithm. |
GMIME_DIGEST_ALGO_RIPEMD160 | The RIPEMD-160 hash algorithm. |
GMIME_DIGEST_ALGO_MD2 | The MD2 hash algorithm. |
GMIME_DIGEST_ALGO_TIGER192 | The TIGER-192 hash algorithm. |
GMIME_DIGEST_ALGO_HAVAL5160 | The HAVAL-5-160 hash algorithm. |
GMIME_DIGEST_ALGO_SHA256 | The SHA-256 hash algorithm. |
GMIME_DIGEST_ALGO_SHA384 | The SHA-384 hash algorithm. |
GMIME_DIGEST_ALGO_SHA512 | The SHA-512 hash algorithm. |
GMIME_DIGEST_ALGO_SHA224 | The SHA-224 hash algorithm. |
GMIME_DIGEST_ALGO_MD4 | The MD4 hash algorithm. |
GMIME_DIGEST_ALGO_CRC32 | The CRC32 hash algorithm. |
GMIME_DIGEST_ALGO_CRC32_RFC1510 | The rfc1510 CRC32 hash algorithm. |
GMIME_DIGEST_ALGO_CRC32_RFC2440 | The rfc2440 CRC32 hash algorithm. |

### enum GMimeTrust

The trust level of a certificate. Trust level tries to answer the question: "How much is the user willing to rely on cryptographic identity assertions made by the owner of this certificate?"

By way of comparison with web browser X.509 certificate validation stacks, the certificate of a "Root CA" has `GMIME_TRUST_ULTIMATE` , while the certificate of an intermediate CA has `GMIME_TRUST_FULL` , and an end-entity certificate (e.g., with CA:FALSE set) would have `GMIME_TRUST_NEVER` .

#### Members

GMIME_TRUST_UNKNOWN | We do not know whether to rely on identity assertions made by the certificate. |
GMIME_TRUST_UNDEFINED | We do not have enough information to decide whether to rely on identity assertions made by the certificate. |
GMIME_TRUST_NEVER | We should never rely on identity assertions made by the certificate. |
GMIME_TRUST_MARGINAL | We can rely on identity assertions made by this certificate as long as they are corroborated by other marginally-trusted certificates. |
GMIME_TRUST_FULL | We can rely on identity assertions made by this certificate. |
GMIME_TRUST_ULTIMATE | This certificate is an undeniable root of trust (e.g. normally, this is a certificate controlled by the user themselves). |

### enum GMimeValidity

The validity level of a certificate's User ID. Validity level tries to answer the question: "How strongly do we believe that this certificate belongs to the party it says it belongs to?"

Note that some OpenPGP certificates have multiple User IDs, and each User ID may have a different validity level (e.g. depending on which third parties have certified which User IDs, and which third parties the local user has chosen to trust).

Similarly, an X.509 certificate can have multiple SubjectAltNames, and each name may also have a different validity level (e.g. if the issuing CA is bound by name constraints).

Note that the GMime API currently only exposes the highest-validty User ID for any given certificate.

#### Members

GMIME_VALIDITY_UNKNOWN | The User ID of the certificate is of unknown validity. |
GMIME_VALIDITY_UNDEFINED | The User ID of the certificate is undefined. |
GMIME_VALIDITY_NEVER | The User ID of the certificate is never to be treated as valid. |
GMIME_VALIDITY_MARGINAL | The User ID of the certificate is marginally valid (e.g. it has been certified by only one marginally-trusted party). |
GMIME_VALIDITY_FULL | The User ID of the certificate is fully valid. |
GMIME_VALIDITY_ULTIMATE | The User ID of the certificate is ultimately valid (i.e., usually the certificate belongs to the local user themselves). |

### struct GMimeCertificate

    struct GMimeCertificate;

An object containing useful information about a certificate.

#### Members

### struct GMimeCertificateList

    struct GMimeCertificateList;

A collection of GMimeCertificate objects.

#### Members