Unity Console Admin Guide

Introduction

The Bulk Revocation process in ADSS Server requires users to provide certificate details in a structured file so that multiple revocations can be carried out automatically. To achieve this, a Revocation Details CSV File is used. This document explains how to correctly create and format that file, ensuring that the revocation process runs smoothly and remains compliant with the Mozilla Root Store Policy and CA/Browser Forum standards.

Purpose of the CSV File

Since bulk revocation depends on accurate input, the CSV file plays a central role in preparing the data for processing. It ensures certificate information is properly structured, validated, and ready for execution. With this approach, ADSS Server can efficiently handle large-scale revocations without requiring manual intervention. 

The CSV file is required for:

• Preparing certificate revocation data in a structured, validated Excel sheet
• Executing large-scale revocations for thousands or millions of certificates efficiently

CSV File Structure

To enable the system to correctly interpret the data, the CSV file must follow a fixed structure. Each column serves a specific purpose, and the headers must be written exactly as expected by ADSS Server. This structure ensures that every certificate record is processed consistently and accurately. 

The CSV file must contain the following columns. Column headers are case-sensitive, and it is mandatory to use uppercase for consistency.

The columns must appear in the order listed below:

Rules and Validations

While the file structure lays the foundation, applying strict rules and validations ensures that the data is both correct and usable. These checks prevent errors during processing and help maintain the reliability of the revocation process. The following rules must be followed when creating the CSV file:

Mandatory Identifiers

To uniquely identify each certificate, at least one identifier must be included in each row. Without these identifiers, the system cannot match the revocation request to the correct certificate.

• At least one of the following must be provided per row:
• ALIAS
• SERIAL_NO
• CLIENT_ID
• If all three are missing, the row will be skipped and logged as invalid.
• For certificates created via Key Manager use KEY_MANAGER as Client ID.
• For certificates created via Manual Certification use MANUAL as Client ID.
• If only ALIAS is given for a row and multiple certificates are issued using the same alias for different clients, then all certificates found will be revoked.

Date Rules

Dates determine when the revocation becomes effective and, if provided, when the certificate is considered invalid. If these values are not included, the system defaults to the current date and time, ensuring revocations are not delayed.

• REVOCATION_DATE and INVALIDITY_DATE are optional.
• If missing, the current system date and time will be automatically used.
• Required format:
  DD/MM/YYYY HH:mm:ss
  Example: 27/08/2025 14:30:00

Revocation Reason

A revocation reason explains why a certificate is being revoked. Providing a reason improves auditability and ensures consistency with policy requirements:

• If REVOCATION_REASON is missing, it will default to:
  cessationOfOperation

Allowed Values for REVOCATION_REASON:

Hold Instruction Code

In certain cases, such as when a certificate is temporarily suspended, a hold instruction must accompany the revocation reason. This ensures that the system interprets the request correctly.

• Required only when REVOCATION_REASON = certificateHold.
• If missing when required, it defaults to:
  id-holdinstruction-none

Allowed Values for REVOCATION_REASON:

CSV File Formatting Rules

Proper formatting ensures that the file can be read and processed without errors. Even minor formatting issues, such as extra spaces or blank columns, can cause rows to fail during validation.

• File must be saved as Microsoft Excel Workbook (.CSV)
• Column headers must match exactly (case-sensitive, but no spaces or typos allowed).
• There should be no blank columns between the defined fields.
• Ensure there are no extra spaces before or after cell values.

Revoke All Certificates for a Specific Client

Sometimes, instead of revoking individual certificates, it may be necessary to revoke all certificates belonging to a specific client. The CSV file supports this by allowing a simple row entry with only the Client ID.

• Provide a single row with only the CLIENT_ID filled in
• Leave ALIAS and SERIAL_NO blank.
• ADSS Server will automatically revoke all certificates associated with that CLIENT_ID for the selected CA.

Example Row:

ALIAS,SERIAL_NO,CLIENT_ID,REVOCATION_DATE,REVOCATION_REASON,INVALIDITY_DATE

,,ClientXYZ,27/08/2025 12:00:00,cACompromise,27/08/2025 12:00:00

Data Quality Checks

To prevent duplicate or invalid entries from causing errors, the system enforces strict quality checks. These checks ensure that each row is unique and all data values meet the required format.

• Each row must be unique based on a combination of:
  ALIAS + SERIAL_NO + CLIENT_ID
• No duplicate rows are allowed.
• Date fields must match the required format.
• Revocation reason and hold instruction codes must be valid.

Error Handling

Even with structure and rules in place, errors may still occur during upload. To manage this, ADSS Server performs multiple layers of validation and provides detailed error logs. This allows users to quickly identify issues, correct them, and re-submit the file if needed.

Structural Validation

• Ensure all required columns are present.
• Verify there are no extra blank columns or mismatched headers.

Field Validation

• Validate at least one of ALIAS, SERIAL_NO, or CLIENT_ID is present.
• Check that date fields match the required format (DD/MM/YYYY HH:mm:ss).
• Ensure REVOCATION_REASON and HOLD_INSTRUCTION_CODE contain only allowed values.

Error Logging

• Invalid rows will be skipped and recorded in a log.
• Log includes:
• Row number
• Description of the issue