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 ONE IoT Device 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 ONE 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 or multiple values 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 IoT Device 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

generic
"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"