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.
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.
1
#include<ec.h>
2
#include<time.h>
3
...
4
time_t from =time(NULL);
5
time_t until = from +(86400*365);//one year
6
ec_cert_t *c =ec_cert_create(from, until);
7
...
Copied!
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.
1
#include<ec.h>
2
...
3
ec_cert_t *c2 =ec_cert_copy(c1);
4
if(c ==NULL){
5
//failed to copy certificate
6
}
7
...
Copied!
ec_cert_destroy()
void ec_cert_destroy(ec_cert_t *c);
Destroy a certificate previously created with ec_cert_create().
1
#include<ec.h>
2
...
3
ec_cert_destroy(c);
4
...
Copied!
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:
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.
1
#include<ec.h>
2
...
3
if(ec_cert_sign(c, signer)!=0){
4
//signing succeeded
5
}
6
...
Copied!
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.
Flag
Implies
Context Required?
Tests
EC_CHECK_CERT
​
No
Certificate is the correct version, a valid public key is present, the current time falls within the certificate's validity period, any records present are of a valid length, any section records have a NULL-terminated string key.
EC_CHECK_SECRET
​
No
A secret key is present
EC_CHECK_SIGN
​
Yes1
Signer ID is present, signature is present, signer is available, validity period falls within signer validity period, signature passes cryptographic validation.
EC_CHECK_CHAIN2
EC_CHECK_SIGN
Yes
Certificate is not self-signed, signer also passes every check that certificate is required to pass, except for EC_CHECK_SECRET.
EC_CHECK_ROLE
EC_CHECK_CHAIN
Yes
Grant records have a valid string key, grant records match or are a subset of the signer's grant records unless EC_CERT_TRUSTED is set, role records have a valid string key, role records match or are a subset of the signer's grant records unless EC_CERT_TRUSTED is set.
EC_CHECK_REQUIRE
​
Yes
A validator function has been set, all records with EC_RECORD_REQUIRE are considered acceptable by the validator.
EC_CHECK_ALL
​
Yes
Every check listed above except for EC_CHECK_SECRET.
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.
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.
1
#include<ec.h>
2
...
3
ec_id_t id =ec_cert_id(c);
4
...
Copied!
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.
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.