Records are the fundamental unit used to store additional data attached to a certificate (e.g. roles, grants, user data, etc.) Records are key / value pairs. The key and value are both optional, and may contain either string or binary data.
Records are organised by section. Each section begins with a 'section header' record, which must use a NULL-terminated string containing the name of the section as its key.
Section names beginning with an underscore are reserved for internal use by the library.
If a section name is prefixed by '#x27;, then all records in that section (including the section header) must be signed. Certificates containing a NOSIGN record in such a section will not validate.
Create a new record. Returns a pointer to the new record, or NULL on failure. key must be a NULL-terminated string.
Records created with ec_record_create() must be freed using ec_record_destroy() once they are no longer required, unless they are attached to a certificate. All records attached to a certificate are automatically freed when the certificate is destroyed.
flags is used to set additional metadata on the record, according to the following table:
Record is a section header.
Client must understand this record. If it does not, the certificate must be treated as invalid.
If this record is a section header, then all records added to this section will inherit the same flags by default. Otherwise, this record will inherit its flags from the section header. Inheritance is defined as a bitwise OR with the section header for all inheritable flags.
This record will not be signed, and should be treated as untrustworthy. Intended for adding comments, internal metadata etc. to an already-signed certificate.
The key for this record will be automatically freed when the record is destroyed.
The key for this record will be copied, rather than added by reference. Implies EC_RECORD_KFREE.
The data for this record will be automatically freed when the record is destroyed.
The data for this record will be copied, rather than added by reference. Implies EC_RECORD_DFREE.
Allocate and initialise to zero a new buffer for the key. The value of key is ignored.
Allocate and initialise to zero a new buffer for the data. The value of data is ignored.
Used only as a match filter. If this flag is set, records with NOSIGN will not match.
Add a record to a certificate. Returns r on success, NULL otherwise.
The record will be added to the section referred to by section, and the section will be created if it does not already exist. If EC_RECORD_SECTION is set, then section will be ignored and the record will be treated as a section header.
Remove an entire section and all its child records from a certificate, if present.
If freefn is provided, it will be run once for each removed record, after that record is removed. If freefn is NULL, then nothing will be run on the removed records, and you should destroy them manually if they are no longer required.
Find the first matching record in a record list. key must be a NULL-terminated string. All provided flags must be present in a record for it to match. section must be defined unless searching for a section header, in which case it should be NULL.
Quickly get or create a record-backed buffer of at least length bytes. Returns NULL on error.
If the record already exists, but the buffer is smaller than length, or some of the flags are unset, this is considered an error. Otherwise, the existing record is used as-is without alteration, and the data buffer is returned.
If the record does not exist, then a new record is created with a zero-initialised buffer of the desired length, and flags will be added to the default.