Top | ![]() |
![]() |
![]() |
![]() |
Certificate utility functionsCertificate utility functions — Helper functions to read and write information from X.509 certificates. |
These functions are utility functions that can be used when dealing with certificates, private key and Diffie-Hellman parameters for key exchange. The functionality these functions provide include creating, reading and writing these data structures to disk in PEM format, or to read values from certificates.
gnutls_dh_params_t
inf_cert_util_create_dh_params (GError **error
);
Creates new, random Diffie-Hellman parameters.
gnutls_dh_params_t inf_cert_util_read_dh_params (const gchar *filename
,GError **error
);
Reads the Diffie-Hellman parameters located at filename
into a
gnutls_dh_params_t structure.
gboolean inf_cert_util_write_dh_params (gnutls_dh_params_t params
,const gchar *filename
,GError **error
);
Writes the given Diffie-Hellman parameters to the given path on the
filesystem. If an error occurs, error
is set and FALSE
is returned.
gnutls_x509_privkey_t inf_cert_util_create_private_key (gnutls_pk_algorithm_t algo
,unsigned int bits
,GError **error
);
Generates a new, random X.509 private key. This function is a thin
wrapper around gnutls_x509_privkey_generate()
which provides GError-style
error reporting.
gnutls_x509_privkey_t inf_cert_util_read_private_key (const gchar *filename
,GError **error
);
Reads the key located at filename
into a gnutls_x509_privkey_t
structure.
gboolean inf_cert_util_write_private_key (gnutls_x509_privkey_t key
,const gchar *filename
,GError **error
);
Writes key
to the location specified by filename
on the filesystem.
If an error occurs, the function returns FALSE
and error
is set.
gnutls_x509_crt_t inf_cert_util_create_certificate (gnutls_x509_privkey_t key
,const InfCertUtilDescription *desc
,GError **error
);
Creates a new X.509 certificate with the given key and properties. If
an error occurs the function returns NULL
and error
is set. The
returned certificate will not be signed.
gnutls_x509_crt_t inf_cert_util_create_signed_certificate (gnutls_x509_privkey_t key
,const InfCertUtilDescription *desc
,gnutls_x509_crt_t sign_cert
,gnutls_x509_privkey_t sign_key
,GError **error
);
Creates a new X.509 certificate with the given key and properties. If
an error occurs the function returns NULL
and error
is set. The
returned certificate will be signed by sign_cert
.
key |
The private key to be used for the new certificate. |
[transfer none] |
desc |
The certificate properties. |
|
sign_cert |
A certificate used to sign the newly created certificate. |
[transfer none] |
sign_key |
The private key for |
[transfer none] |
error |
Location to store error information, if any, or |
gnutls_x509_crt_t inf_cert_util_create_self_signed_certificate (gnutls_x509_privkey_t key
,const InfCertUtilDescription *desc
,GError **error
);
Creates a new X.509 certificate with the given key and properties. If
an error occurs the function returns NULL
and error
is set. The
returned certificate will be signed by itself.
GPtrArray * inf_cert_util_read_certificate (const gchar *filename
,GPtrArray *current
,GError **error
);
Loads X.509 certificates in PEM format from the file at filename
. There
can be any number of certificates in the file. If current
is not NULL
,
the new certificates are appended to the array. Otherwise, a new array
with the read certificates is returned.
If an error occurs, the function returns NULL
and error
is set. If
current
is non-NULL
and the function succeeds, the return value is the
same as current
.
gboolean inf_cert_util_write_certificate (gnutls_x509_crt_t *certs
,guint n_certs
,const gchar *filename
,GError **error
);
This function writes the certificates in the array certs
to disk, in
PEM format. If an error occurs the function returns FALSE
and error
is set.
gchar * inf_cert_util_write_certificate_mem (gnutls_x509_crt_t *certs
,guint n_certs
,GError **error
);
This function writes the certificates in the array certs
into memory, in
PEM format. If an error occurs the function returns NULL
and error
is set.
gboolean inf_cert_util_write_certificate_with_key (gnutls_x509_privkey_t key
,gnutls_x509_crt_t *certs
,guint n_certs
,const gchar *filename
,GError **error
);
This function writes both the private key key
as well as the
certificates in the array certs
to disk, in PEM format. If an error
occurs the function returns FALSE
and error
is set.
key |
An initialized gnutls_x509_privkey_t structure. |
[transfer none] |
certs |
An array of gnutls_x509_crt_t objects. |
[transfer none][array length=n_certs] |
n_certs |
Number of certificates in the error. |
|
filename |
The path at which to store the certificates. |
[type filename] |
error |
Location to store error information, if any. |
gnutls_x509_crt_t inf_cert_util_copy_certificate (gnutls_x509_crt_t src
,GError **error
);
Creates a copy of the certificate src
and returns the copy. If the
function fails FALSE
is returned and error
is set.
GHashTable * inf_cert_util_read_certificate_map (const gchar *filename
,GError **error
);
Reads a certificate map, i.e. a mapping from hostname to certificate, from the given file. The format of the file is expected to be one entry per line, where each entry consists of the hostname, then a colon character (':'), and then the base64-encoded certificate in DER format.
If the file with the given filename does not exist, an empty hash table is returned and the function succeeds.
gboolean inf_cert_util_write_certificate_map (GHashTable *cert_map
,const gchar *filename
,GError **error
);
Writes the given certificate mapping to a file with the given filename.
See inf_cert_util_read_certificate_map()
for the format of the written
file. If an error occurs, error
is set and the function returns FALSE
.
This function can be useful to implement trust-on-first-use (TOFU) semantics.
gboolean inf_cert_util_check_certificate_key (gnutls_x509_crt_t cert
,gnutls_x509_privkey_t key
);
This function returns TRUE
if key
is the private key belonging to cert
,
or FALSE
otherwise.
gboolean inf_cert_util_compare_fingerprint (gnutls_x509_crt_t cert1
,gnutls_x509_crt_t cert2
,GError **error
);
Checks whether the SHA-256 fingerprints of the two given certificates are
identical or not. If a fingerprint cannot be obtained, the function
returns FALSE
and error
is set.
gchar *
inf_cert_util_get_dn (gnutls_x509_crt_t cert
);
Retrieves the full distinguished name (DN) from the certificate, allocating memory for the return value.
gchar * inf_cert_util_get_dn_by_oid (gnutls_x509_crt_t cert
,const char *oid
,unsigned int index
);
Retrieves the given item from the certificate. This function is a thin
wrapper around gnutls_x509_crt_get_dn_by_oid()
, allocating memory for the
return value. The function returns NULL
if there is no such entry in the
certificate.
gchar * inf_cert_util_get_issuer_dn_by_oid (gnutls_x509_crt_t cert
,const char *oid
,unsigned int index
);
Retrieves the given item from the issuer of the certificate. This function
is a thin wrapper around gnutls_x509_crt_get_issuer_dn_by_oid()
,
allocating memory for the return value. The functions returns NULL
if
there is no such entry in the certificate.
gchar *
inf_cert_util_get_hostname (gnutls_x509_crt_t cert
);
Attempts to read the hostname of a certificate. This is done by looking at the DNS name and IP address SANs. If both are not available, the common name of the certificate is returned.
gchar *
inf_cert_util_get_serial_number (gnutls_x509_crt_t cert
);
Read the serial number of a certificate and return it in hexadecimal
format. If the serial number cannot be read NULL
is returned.
gchar * inf_cert_util_get_fingerprint (gnutls_x509_crt_t cert
,gnutls_digest_algorithm_t algo
);
Returns the fingerprint of the certificate hashed with the specified
algorithm, in hexadecimal format. If the fingerprint cannot be read NULL
is returned.
gchar *
inf_cert_util_get_activation_time (gnutls_x509_crt_t cert
);
Returns the activation time of the certificate as a string in
human-readable format. If the activation time cannot be read NULL
is
returned.
struct InfCertUtilDescription { guint64 validity; const gchar* dn_common_name; const gchar* san_dnsname; };
This structure contains information that is used to generate a certificate
with the inf_cert_util_create_certificate()
,
inf_cert_util_create_self_signed_certificate()
and
inf_cert_util_create_signed_certificate()
functions.