Next: , Previous: , Up: X.509 certificates   [Contents][Index]


4.1.1.5 X.509 extensions

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 x509-ext.h. 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 case gnutls_x509_name_constraints_t to be initialized in order to store the parsed extension data.

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.

ExtensionOIDDescription
Subject key id2.5.29.14An identifier of the key of the subject.
Key usage2.5.29.15Constraints the key’s usage of the certificate.
Private key usage period2.5.29.16Constraints the validity time of the private key.
Subject alternative name2.5.29.17Alternative names to subject’s distinguished name.
Issuer alternative name2.5.29.18Alternative names to the issuer’s distinguished name.
Basic constraints2.5.29.19Indicates whether this is a CA certificate or not, and specify the maximum path lengths of certificate chains.
Name constraints2.5.29.30A field in CA certificates that restricts the scope of the name of issued certificates.
CRL distribution points2.5.29.31This extension is set by the CA, in order to inform about the location of issued Certificate Revocation Lists.
Certificate policy2.5.29.32This extension is set to indicate the certificate policy as object identifier and may contain a descriptive string or URL.
Extended key usage2.5.29.54Inhibit any policy extension. Constraints the any policy OID (GNUTLS_X509_OID_POLICY_ANY) use in the policy extension.
Authority key identifier2.5.29.35An identifier of the key of the issuer of the certificate. That is used to distinguish between different keys of the same issuer.
Extended key usage2.5.29.37Constraints the purpose of the certificate.
Authority information access1.3.6.1.5.5.7.1.1Information on services by the issuer of the certificate.
Proxy Certification Information1.3.6.1.5.5.7.1.14Proxy 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].

Table 4.3: Supported X.509 certificate extensions.

Note, that there are also direct APIs to access extensions that may be simpler to use for non-complex extensions. They are available in 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)

Next: , Previous: , Up: X.509 certificates   [Contents][Index]