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 DigiCert Private CA.

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.

Data type	Description	Expected format in output certificate
`AutoString`	Value can be either a `PrintableString` or `UTF8String`.	ASN.1 `PrintableString` or `UTF8String`, the same as supplied in the request.
`AutoTime`	Value can be either a `UTCTime` (years before 2050) or `GeneralizedTime` (year 2050 or later). Value should always comply with the RFC 3339 time format.	ASN.1 `UTCTime` (years before 2050) or `GeneralizedTime` (year 2050 or later). The value is derived from the RFC 3339 value supplied in the request.
`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.	ASN.1 `BIT STRING`, using the same value supplied in the request.
`BMPString`	String that contains Unicode characters from the Basic Multilingual Plane (BMP).	ASN.1 `BMPString`, using the same value supplied in the request.
`BOOLEAN`	`true` or `false`.	ASN.1 `BOOLEAN`, DER-encoded from the logical value supplied in the request.
`DER ENCODED`	Base64-encoded ASN.1 DER object.	DER object, generated from the Base64-decoded value supplied in the request.
`IA5String`	String that contains only characters from the IA5/ASCII character set.	ASN.1 `IA5String`, using the same value supplied in the request.
`INTEGER`	Either an integer or a string with an integer value.	ASN.1 `INTEGER`, DER-encoded from the integer value supplied in the request.
`NumericString`	String that contains only digits and spaces.	ASN.1 `NumericString`, using the same value supplied in the request.
`OBJECT IDENTIFIER`	OID value.	ASN.1 `OBJECT IDENTIFIER`, DER-encoded from the OID value supplied in the request.
`OCTET STRING`	Base64-encoded raw bytes.	ASN.1 `OCTET STRING`, generated from the Base64-decoded raw bytes supplied in the request.
`PrintableString`	String that contains letters, digits, and a limited set of special characters.	ASN.1 `PrintableString`, using the same value supplied in the request.
`UTF8String`	String that can contain any Unicode characters.	ASN.1 `UTF8String,` using the same value supplied in the request.

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

Let op

Go to 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:

Opmerking

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 applies 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.

In deze sectie: