X.509 version 3 certificates include a list of extensions that can be used to obtain additional information on the subject or the issuer of the certificate. Those may be e-mail addresses, flags that indicate whether the belongs to a CA etc. All the supported X.509 version 3 extensions are shown in Table 4.3.
The certificate extensions access is split into two parts. The first requires to retrieve the extension, and the second is the parsing part.
To enumerate and retrieve the DER-encoded extension data available in a certificate the following two functions are available.
int gnutls_x509_crt_get_extension_info (gnutls_x509_crt_t cert, unsigned indx, void * oid, size_t * oid_size, unsigned int * critical)
int gnutls_x509_crt_get_extension_data2 (gnutls_x509_crt_t cert, unsigned indx, gnutls_datum_t * data)
int gnutls_x509_crt_get_extension_by_oid2 (gnutls_x509_crt_t cert, const char * oid, unsigned indx, gnutls_datum_t * output, unsigned int * critical)
After a supported DER-encoded extension is retrieved it can be parsed using the APIs in
Complex extensions may require initializing an intermediate structure that holds the
parsed extension data. Examples of simple parsing functions are shown below.
int gnutls_x509_ext_import_basic_constraints (const gnutls_datum_t * ext, unsigned int * ca, int * pathlen)
int gnutls_x509_ext_export_basic_constraints (unsigned int ca, int pathlen, gnutls_datum_t * ext)
int gnutls_x509_ext_import_key_usage (const gnutls_datum_t * ext, unsigned int * key_usage)
int gnutls_x509_ext_export_key_usage (unsigned int usage, gnutls_datum_t * ext)
More complex extensions, such as Name Constraints, require an intermediate structure, in that
gnutls_x509_name_constraints_t to be initialized in order to store the parsed
int gnutls_x509_ext_import_name_constraints (const gnutls_datum_t * ext, gnutls_x509_name_constraints_t nc, unsigned int flags)
int gnutls_x509_ext_export_name_constraints (gnutls_x509_name_constraints_t nc, gnutls_datum_t * ext)
After the name constraints are extracted in the structure, the following functions can be used to access them.
int gnutls_x509_name_constraints_get_permitted (gnutls_x509_name_constraints_t nc, unsigned idx, unsigned * type, gnutls_datum_t * name)
int gnutls_x509_name_constraints_get_excluded (gnutls_x509_name_constraints_t nc, unsigned idx, unsigned * type, gnutls_datum_t * name)
int gnutls_x509_name_constraints_add_permitted (gnutls_x509_name_constraints_t nc, gnutls_x509_subject_alt_name_t type, const gnutls_datum_t * name)
int gnutls_x509_name_constraints_add_excluded (gnutls_x509_name_constraints_t nc, gnutls_x509_subject_alt_name_t type, const gnutls_datum_t * name)
unsigned gnutls_x509_name_constraints_check (gnutls_x509_name_constraints_t nc, gnutls_x509_subject_alt_name_t type, const gnutls_datum_t * name)
unsigned gnutls_x509_name_constraints_check_crt (gnutls_x509_name_constraints_t nc, gnutls_x509_subject_alt_name_t type, gnutls_x509_crt_t cert)
Other utility functions are listed below.
int gnutls_x509_name_constraints_init (gnutls_x509_name_constraints_t * nc)
void gnutls_x509_name_constraints_deinit (gnutls_x509_name_constraints_t nc)
Similar functions exist for all of the other supported extensions, listed in Table 4.3.
|Subject key id||22.214.171.124||An identifier of the key of the subject.|
|Key usage||126.96.36.199||Constraints the key’s usage of the certificate.|
|Private key usage period||188.8.131.52||Constraints the validity time of the private key.|
|Subject alternative name||184.108.40.206||Alternative names to subject’s distinguished name.|
|Issuer alternative name||220.127.116.11||Alternative names to the issuer’s distinguished name.|
|Basic constraints||18.104.22.168||Indicates whether this is a CA certificate or not, and specify the maximum path lengths of certificate chains.|
|Name constraints||22.214.171.124||A field in CA certificates that restricts the scope of the name of issued certificates.|
|CRL distribution points||126.96.36.199||This extension is set by the CA, in order to inform about the issued CRLs.|
|Certificate policy||188.8.131.52||This extension is set to indicate the certificate policy as object identifier and may contain a descriptive string or URL.|
|Authority key identifier||184.108.40.206||An identifier of the key of the issuer of the certificate. That is used to distinguish between different keys of the same issuer.|
|Extended key usage||220.127.116.11||Constraints the purpose of the certificate.|
|Authority information access||18.104.22.168.22.214.171.124.1||Information on services by the issuer of the certificate.|
|Proxy Certification Information||126.96.36.199.188.8.131.52.14||Proxy Certificates includes this extension that contains the OID of the proxy policy language used, and can specify limits on the maximum lengths of proxy chains. Proxy Certificates are specified in [RFC3820].|
Note, that there are also direct APIs to access extensions that may
be simpler to use for non-complex extensions. They are available
x509.h and some examples are listed below.
int gnutls_x509_crt_get_basic_constraints (gnutls_x509_crt_t cert, unsigned int * critical, unsigned int * ca, int * pathlen)
int gnutls_x509_crt_set_basic_constraints (gnutls_x509_crt_t crt, unsigned int ca, int pathLenConstraint)
int gnutls_x509_crt_get_key_usage (gnutls_x509_crt_t cert, unsigned int * key_usage, unsigned int * critical)
int gnutls_x509_crt_set_key_usage (gnutls_x509_crt_t crt, unsigned int usage)