Data types and example templates for custom extensions

DigiCert uses the ASN.1 standard to define JSON-based templates for custom extensions in private certificates issued through DigiCert ONE CA Manager.

When creating your certificate profiles, you can define custom extensions that consist of a single value or a collection of values:

Use the basic data types to define a single value within a custom extension.
Use the constructed data types to define more complex template structures.

Type definitions

Each type definition in a custom extension can include the components shown below. Only the TYPE component is required.

"type" : "[[CLASS] [TAG]] [MODE] TYPE ['OPTIONAL']"

Explanations of these components:

[[CLASS] [TAG]]: Optional. Used to apply a tag and its corresponding class for more granular data identification.
[MODE]: Optional. Used to define the tagging mode (IMPLICIT or EXPLICIT). Default is IMPLICIT.
TYPE: Required. Defines the data type contained in the custom extension. See basic data types and constructed data types below for more details.
['OPTIONAL']: Optional. Enter OPTIONAL verbatim to mark a custom extension or custom extension field as optional.

Basic data types

Use any of these basic data types to create custom extensions:

AutoString: Value can be either a PrintableString or UTF8String.
AutoTime: Value can be either a UTCTime (years less than 2050) or GeneralizedTime (year 2050 or later).
BIT STRING: Binary string (Base64-encoded), including optional bit count after the value. If no bit count is provided, it is set to 8 times the length of the binary value.
BOOLEAN: True or false.
IA5String: String that contains only characters from the IA5/ASCII character set.
INTEGER: Either an integer or a string with an integer value.
NULL: No value.
NumericString: String that contains only digits and spaces.
OBJECT IDENTIFIER: OID value.
OCTET STRING: Binary string (Base64-encoded).
PrintableString: String that contains letters, digits, and a limited set of special characters.
UTF8String: String that can contain any of the Unicode characters.

Constructed data types

To define custom extensions with more complex collections of the basic data types, use one of the constructed data types below. Include a corresponding structure element in your JSON template to specify the underlying structure of the constructed type.

SEQUENCE
SEQUENCE OF
SET OF

Note

Visit the ITU-T website for more detailed information about the ASN.1 standard, including data types and allowed values for each.

Example templates with basic data types

Use the template JSON object to define the structure of a custom extension.

In the following examples, the custom extension consists of a single value. Note that:

The type property references a basic data type in these examples.
The value property defines a placeholder name that can be referenced to supply an actual value during enrollment.

Example 1

"template": {
    "type": "BOOLEAN",
    "value": "${is_staging_server}"
}

Defines a custom extension that contains a single boolean value. You would target the placeholder name is_staging_server to supply a value during enrollment.

Example 2

"template": {
    "type": "PrintableString OPTIONAL",
    "value": "${server_location}"
}

Defines a custom extension that contains a single string of type PrintableString, which is considered optional. You would target the placeholder name server_location to supply a value during enrollment. Since it's marked optional, administrators would not be strictly required to supply a value for this extension when enrolling a certificate via the Trust Lifecycle Manager user interface.

Example templates with constructed data types

To define custom extension templates with more complex data structures, use one of the constructed data types (SEQUENCE, SEQUENCE OF, or SET OF) and supply a corresponding structure object in the JSON to describe the collection of other data types.

Example 1 (flat)

"template": {
    "type": "SEQUENCE",
    "structure": [
      {
        "type": "PrintableString",
        "value": "${user_name}"
      },
      {
        "type": "BOOLEAN",
        "value": "${is_manager}"
      },
      {
        "type": "INTEGER",
        "value": 1
      },
      {
        "type": "UTF8String OPTIONAL",
        "value": "${user_background}"
      }
    ]
}

In this example:

The custom extension uses a flat structure consisting of various data fields.
The INTEGER field has a fixed value that will apply to all certificates.
All other fields have placeholder names that can be targeted to assign values dynamically during enrollment.
The UTF8String field (user_background) is marked as optional. Administrators will not be strictly required to supply a value for it when enrolling via the Trust Lifecycle Manager user interface.

Example 2 (nested)

"template": {
    "type": "SEQUENCE",
    "structure": [
      {
        "type": "INTEGER",
        "value": "${user_id_number}"
      },
      {
        "type": "SEQUENCE",
        "structure": [
            {
              "type": "PrintableString",
              "value": "${user_dob}"
            },
            {
              "type": "PrintableString",
              "value": "${user_security_clearance}"
            }
        ]
      }
   ]
}

In this example:

The custom extension uses a nested data structure.
The structure consists of an INTEGER field (user_id_number) plus a nested collection of two PrintableString fields (user_dob and user_security_clearance).
You would target the basic placeholder names to assign values to the fields during enrollment. In the resulting certificate, the custom extension values would be structured like in the template.