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:
Flag
Meaning
EC_RECORD_SECTION
Record is a section header.
EC_RECORD_REQUIRE
Client must understand this record. If it does not, the certificate must be treated as invalid.
EC_RECORD_INHERIT
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.
EC_RECORD_NOSIGN
This record will not be signed, and should be treated as untrustworthy. Intended for adding comments, internal metadata etc. to an already-signed certificate.
EC_RECORD_KFREE
The key for this record will be automatically freed when the record is destroyed.
EC_RECORD_KCOPY
The key for this record will be copied, rather than added by reference. Implies EC_RECORD_KFREE.
EC_RECORD_DFREE
The data for this record will be automatically freed when the record is destroyed.
EC_RECORD_DCOPY
The data for this record will be copied, rather than added by reference. Implies EC_RECORD_DFREE.
EC_RECORD_KALLOC
Allocate and initialise to zero a new buffer for the key. The value of key is ignored.
EC_RECORD_DALLOC
Allocate and initialise to zero a new buffer for the data. The value of data is ignored.
EC_RECORD_SIGNED
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.
Get the name for the section to which the record belongs. Returns the section name if present, or NULL if the record is not associated with a section, or is a section header.
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.