CSV format for batch certificate enrollment
4 minute read
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 aunique_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 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"