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.
New dhparams to be freed
with gnutls_dh_params_deinit()
, or NULL
in case of error.
[transfer full]
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.
filename |
A path to a DH parameters file. |
[type filename] |
error |
Location to store error information, if any. |
New dhparams to be freed with
gnutls_dh_params_deinit()
, or NULL
in case of error.
[transfer full]
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.
params |
An initialized gnutls_dh_params_t structure. |
[transfer none] |
filename |
The path at which so store |
[type filename] |
error |
Location to store error information, if any. |
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.
algo |
The key algorithm to use (RSA or DSA). |
|
bits |
The length of the key to generate. |
|
error |
Location to store error information, if any. |
A new key to be freed with
gnutls_x509_privkey_deinit()
, or NULL
if an error occured.
[transfer full]
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.
key |
An initialized gnutls_x509_privkey_t structure. |
[transfer none] |
filename |
The path at which so store the key. |
[type filename] |
error |
Location to store error information, if any. |
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.
key |
The private key to be used for the new certificate. |
[transfer none] |
desc |
The certificate properties. |
|
error |
Location to store error information, if any, or |
A new gnutls_x509_crt_t, or NULL
.
Free with gnutls_x509_crt_deinit()
when no longer needed.
[transfer full]
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 |
A new gnutls_x509_crt_t, or NULL
.
Free with gnutls_x509_crt_deinit()
when no longer needed.
[transfer full]
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.
key |
The private key to be used for the new certificate. |
[transfer none] |
desc |
The certificate properties. |
|
error |
Location to store error information, if any, or |
A new gnutls_x509_crt_t, or NULL
.
Free with gnutls_x509_crt_deinit()
when no longer needed.
[transfer full]
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
.
filename |
A path to a X.509 certificate file. |
[type filename] |
current |
An
array of gnutls_x509_crt_t objects, or |
[element-type gnutls_x509_crt_t][allow-none][transfer full] |
error |
Location to store error information, if any. |
An array of the
read certificates, or NULL
on error.
[transfer full][element-type gnutls_x509_crt_t]
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.
certs |
An array of gnutls_x509_crt_t objects. |
[array length=n_certs][transfer none] |
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. |
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.
certs |
An array of gnutls_x509_crt_t objects. |
[transfer none] |
n_certs |
Number of certificates in the error. |
|
error |
Location to store error information, if any. |
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.
src |
The certificate to copy. |
[transfer none] |
error |
Location to store error information, if any. |
A copy of src
, or NULL
on error. Free
with gnutls_x509_crt_deinit()
when no longer in use.
[transfer full]
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.
filename |
The filename to read the certificate map from. |
|
error |
Location to store error information, if any. |
A hash table with the read mapping, or NULL
on error. Use
g_hash_table_unref()
to free the hash table when no longer needed.
[transfer container][element-type string gnutls_x509_crt_t]
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.
cert_map |
A certificate mapping, i.e. a hash table mapping hostname strings to gnutls_x509_crt_t instances. |
[transfer none][element-type string gnutls_x509_crt_t] |
filename |
The name of the file to write the mapping to. |
|
error |
Location to store error information, if any. |
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.
cert |
An initialized gnutls_x509_crt_t. |
[transfer none] |
oid |
The name of the requested entry. |
|
index |
Index of the entry to retrieve. |
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.
cert |
An initialized gnutls_x509_crt_t. |
[transfer none] |
oid |
The name of the requested entry. |
|
index |
Index of the entry to retrieve. |
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.
cert |
An initialized gnutls_x509_crt_t. |
[transfer none] |
algo |
The hashing algorithm to use. |
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.
gchar *
inf_cert_util_get_expiration_time (gnutls_x509_crt_t cert
);
Returns the expiration time of the certificate as a string in
human-readable format. If the expiration 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.