Skip to main content

CSV format for batch certificate enrollment

Learn how to format a CSV file for submitting a batch enrollment job with server-side keypair generation.

DigiCert​​®​​ IoT Trust Manager supports the option to create a batch certificate enrollment job by uploading a CSV file with details for each certificate request. When you submit a new batch enrollment job, DigiCert​​®​​ IoT Trust Manager uses the CSV data to create certificate requests, generate keypairs, and issue your certificates.

CSV format

The CSV file for a batch enrollment job has at least two rows:

  • A header row with values defining each field to include in the certificate requests. This row includes:

    • Unique identifier header (optional)

    • Certificate attribute headers

    • Device field headers (device and device field identifiers)

  • One or more rows with data for each certificate request.

CSV header

Unique identifier (optional)

To give each certificate request in a batch job a unique identifier, include the optional unique_identifier column header in the CSV file. Give each request a unique identifier to make it easier to identify the output keys and certificates when the request does not have unique certificate values.

By default, CSV batch jobs create private key and certificate files named after the certificate values in the request. For example, if the certificate value for an enrollment profile is mapped to the subject.common_name field:

  • Certificates are named <subject.common_name>.pem/der

  • Keys are named <subject.common_name>.key

If the CSV file includes multiple requests with the same certificate values, the output files are named using the unique_identifier value for the request.* For example:

  • Certificates are named <unique_identifier_value>.pem/der

  • Keys are named <unique_identifier_value>.key

Note

*If a certificate request does not have a unique_identifier value, DigiCert ONE appends a random value to the names of output files for requests that do not have unique certificate values. For example, if the duplicated certificate value is "example", the output files receive names like "example-803306". When this happens, the batch job report displays a status of WARNING. The description in the report includes the modified file names.

Certificate attributes

The CSV file includes column headers for each certificate attribute you need to provide a value for in your certificate requests, including:

  • Subject attributes

  • Subject alternative name (SAN) attributes

  • Extensions attributes

  • Key usage and extended key usage attributes

The configuration of the certificate profile determines which certificate attributes are required in the certificate requests. The following table describes the header value and cell contents for each certificate attribute:

Name

Cell value

Description

subject.common_name

Single value

Subject DN common name.

subject.organization_name

Single value

Subject DN organization name.

subject.organization_unit

Single or multiple values

Subject DN organization units.

subject.country

Single value

Subject DN country.

subject.state

Single value

Subject DN state.

subject.locality

Single value

Subject DN locality.

subject.street_address

Single value

Subject DN address.

subject.postal_code

Single value

Subject DN postal code.

subject.unique_identifier

Single value

Subject DN unique identifier.

subject.email

Single value

Subject DN email.

subject.domain_component

Single or multiple values

Subject DN domain components.

san.critical

Yes or no

If yes, SAN is critical. Otherwise, no.

san.dns_name

Single value

SAN DNS names.

san.user_principal_name

Single or multiple values

SAN user principal names (UPN).

san.email

Single or multiple values

SAN emails.

san.other_name

SAN other name value, formatted as a JSON string

SAN other name. To learn how to format this value, visit Subject directory attributes (SDA).

san.other_name.hardware_module_name.type

Single OID value

SAN hardware module name type.

san.other_name.hardware_module_name.serial_number

Single HEX string value

SAN hardware module name serial number.

extensions.subject_directory

Subject directory attribute value, formatted as a JSON string

Subject directory attributes value. To learn how to format this value, visit Subject directory attributes (SDA).

key_usage.critical

Yes or no

If yes, key usage is critical. Otherwise, no.

key_usage.rsa_additional_values

Single or multiple values

Key usage values for RSA key.

key_usage.ecdsa_additional_values

Single or multiple values

Key usage values for EC key.

extended_key_usage.critical

Yes or no

If yes, extended key usage is critical. Otherwise, no.

extended_key_usage.additional_values

Single or multiple values

Extended key usage values.

Device attributes

The CSV file includes column header values for each device attribute you need to provide a value for in your certificate requests. The configuration of the device profile determines which device attributes are required in certificate requests.

  • For the device identifier field, use the column header value device_identifier.

  • For custom device fields, use the unique UUID* for the custom field defined in the device profile. For example: 35db4faa-899f-4aff-b0a2-10f73d7b198c.

Tip

*To get the unique UUID value for custom device fields, submit a request to the Get enrollment profile specification endpoint in the DigiCert​​®​​ IoT Trust Manager REST API:

GET {base_url}/iot/api/v1/enrollment-profile/{enrollment_profile_id}/enrollment-specification

Certificate request rows

In the CSV file, each row that follows the header row represents an individual certificate request. Certificate request rows include values for each field in the header row.

There is no limit on the number of rows you can include in the CSV file. However, when you submit your batch enrollment job, the compressed ZIP file with your CSV data cannot exceed 200 MB.

Example CSV data

Example 1. Example CSV data
"unique_identifier","subject.common_name","subject.organization_name","subject.organization_unit","san.other_name.hardware_module_name.serial_number","device_identifier","35db4faa-899f-4aff-b0a2-10f73d7b198c"
"001","common name 01","Organization","Unit1,Unit2","AABBCCDD","Device01","Custom field value"
"002","common name 02","Organization","Unit1,Unit2","AABBCCDD","Device02","Custom field value" 
"003","common name 03","Organization","Unit1,Unit2","AABBCCDD","Device03","Custom field value"