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. EnterOPTIONAL
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 |
---|---|
| Value can be either a |
| Value can be either a |
| 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. |
| True or false. |
| Binary DER data (Base64-encoded). |
| String that contains only characters from the IA5/ASCII character set. |
| Either an integer or a string with an integer value. |
| No value. |
| String that contains only digits and spaces. |
| OID value. |
| Binary string (Base64-encoded). |
| String that contains letters, digits, and a limited set of special characters. |
| 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 twoPrintableString
fields (user_dob
anduser_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.