Certificates are represented by the ec_cert_t type, and are created by ec_cert_create(). All certificates must be freed once they are no longer required using ec_cert_destroy().

If a certificate has been saved using ec_ctx_save(), then it will be destroyed automatically once it is removed, overwritten, or the context it was saved to is destroyed.

API

• ​ec_cert_create()​

• ​ec_cert_copy()​

• ​ec_cert_destroy()​

• ​ec_cert_strip()​

• ​ec_cert_sign()​

• ​ec_cert_check()​

• ​ec_cert_id()​

• ​ec_cert_records()​

• ​ec_cert_lock()​

• ​ec_cert_unlock()​

ec_cert_create()

ec_cert_t *ec_cert_create(time_t valid_from, time_t valid_until);

Create a new certificate, and return a pointer to it. Returns NULL on failure. valid_from and valid_until define the certificate's validity period - if the validity period does not fall entirely within the valitity period of its signer, then the timestamp which violates this constraint will be adjusted to match that of the signer.

Timestamps are handled as seconds since 1970-01-01 00:00:00. The current time can be obtained using time() (see time.h).

Certificates created using this function must be destroyed using ec_cert_destroy() when they are no longer required.

#include <ec.h>
#include <time.h>
...
time_t from = time(NULL);
time_t until = from + (86400 * 365); //one year
ec_cert_t *c = ec_cert_create(from, until);
...

ec_cert_copy()

ec_cert_t *ec_cert_copy(ec_cert_t *c);

Copy a certificate. Returns a new copy of c, or NULL on failure.

#include <ec.h>
...
ec_cert_t *c2 = ec_cert_copy(c1);
if(c == NULL) {
    //failed to copy certificate
}
...

ec_cert_destroy()

void ec_cert_destroy(ec_cert_t *c);

Destroy a certificate previously created with ec_cert_create().

#include <ec.h>
...
ec_cert_destroy(c);
...

ec_cert_strip()

void ec_cert_strip(ec_cert_t *c, int what);

Strip unwanted data from a certificate, specified by when. Possible flags are listed below:

#include <ec.h>
...
ec_cert_strip(c, EC_STRIP_SECRET | EC_STRIP_RECORD);
...

ec_cert_sign()

ec_err_t ec_cert_sign(ec_cert_t *c, ec_cert_t *signer);

Sign a certificate using another certificate. Returns a nonzero error code on failure.

The signer must have a valid secret key available, and both certificates must pass the following checks prior to signing:

ec_cert_check(NULL, c, EC_CHECK_CERT);
ec_cert_check(NULL, signer, EC_CHECK_CERT | EC_CHECK_SECRET);

If the certificate's validity falls outside that of the signer, the appropriate timestamp on the certificate will be adjusted to match that of the signer.

#include <ec.h>
...
if(ec_cert_sign(c, signer) != 0) {
    //signing succeeded
}
...

ec_cert_check()

ec_err_t ec_cert_check(ec_ctx_t *ctx, ec_cert_t *c, int flags);

Ensure that a certificate passes a given set of tests. Returns a nonzero error code on failure.

All tests which require a valid trust chain to be present must also provide a context where the trust chain may be found. Tests which apply only to the certificate may pass NULL instead.

The flags parameter is used to set which tests are run, according to the following table. Checks are run in the order that they are listed here.

1 Context is not required if the certificate is self-signed. 2 EC_CHECK_CHAIN always passes if EC_CERT_TRUSTED is set on the certificate.

#include <ec.h>
...
if(ec_cert_check(ctx, c, EC_CHECK_CERT | EC_CHECK_ROLE) != 0) {
    //certificate passes the defined checks
}
...

ec_cert_id()

ec_id_t ec_cert_id(ec_cert_t *c);

Get a unique ID for a certificate. This ID is based on the certificate's public key, and will not change if the certificate is modified by e.g. signing, adding records etc.

This ID is used for things like retrieving a certificate from a context store, identifying a signer, etc.

#include <ec.h>
...
ec_id_t id = ec_cert_id(c);
...

ec_cert_records()

ec_record_t *ec_cert_records(ec_cert_t *c);

Get the records list for a certificate. Returns NULL if there are no records present.

#include <ec.h>
...
ec_record_t *list = ec_cert_records(c);
if(list == NULL) {
    //no records present
}
...

ec_cert_lock()

ec_err_t ec_cert_lock(ec_cert_t *c, char *password);

Encrypt a certificate's secret key using a password. Returns zero on success, or a nonzero error code otherwise.

If the secret key is encrypted successfully, EC_CERT_CRYPTSK will be set.

#include <ec.h>
...
if(ec_cert_lock(c, "mySuperSecretPassword") != 0) {
    //unable to encrypt secret key
}
...

ec_cert_unlock()

ec_err_t ec_cert_unlock(ec_cert_t *c, char *password);

Decrypt a certificate's secret key using a password. Returns zero on success, or a nonzero error code otherwise. If the secret key is not encrypted, then this function will take no action and return zero anyway.

If the secret key is decrypted successfully, then EC_CERT_CRYPTSK will be cleared.

Note that using an incorrect password is not considered an error, but the resulting secret key will be unusable, and any attempts to sign something with it will fail.

#include <ec.h>
...
if(ec_cert_unlock(c, "mySuperSecretPassword") != 0) {
    //unable to decrypt secret key
}
...