CiscoCertificates

Table of Contents

1. Overview

CiscoCertificates is a Windows toolset that automates the entire lifecycle of TLS certificates for Cisco Unified Communications (UC) and Expressway systems. It includes two components:

• CiscoCertificates.Automation — A command-line engine that issues, deploys, and renews certificates automatically.
• CiscoCertificates.ConfigEditor — A graphical configuration editor (WPF) for managing the automation settings without editing JSON directly.

The automation engine handles the complete certificate lifecycle:

1. Issues trusted certificates from Let's Encrypt (free, automated, 90-day certs)
2. Deploys them to Cisco CUCM, IM&P, Unity Connection, Emergency Responder, and Expressway
3. Installs the Let's Encrypt CA trust chain on UC devices
4. Restarts the affected services (e.g., Cisco Tomcat) so the new cert takes effect
5. Notifies you via email when something succeeds or fails
6. Renews automatically before expiration when run on a schedule

You configure it once (using the Config Editor or by editing appsettings.json), schedule it with Windows Task Scheduler, and it handles everything from that point on.

Why Automate?

TLS certificate lifetimes are shrinking industry-wide. The CA/Browser Forum has voted to reduce maximum certificate lifetimes to 47 days by 2029. Let's Encrypt already issues 90-day certificates. Managing these manually across multiple Cisco UC clusters — where each product (CUCM, IM&P, CUC, CER) requires its own certificate with a device-generated CSR — becomes an unsustainable operational burden. This tool eliminates that burden entirely.

2. How It Works

2.1 Cisco UC (CUCM / IM&P / CUC / CER)

Cisco UC devices do not allow importing externally-generated private keys through their API. Instead, the device generates its own private key and Certificate Signing Request (CSR). The automation follows this device-CSR pattern:

1. The app connects to the publisher node and asks it to generate a CSR. With "CsrDistribution": "multi-server", the CSR includes all cluster node hostnames in the SAN.
2. The app sends the CSR to Let's Encrypt using the ACME protocol. Let's Encrypt verifies you own the domain by checking a DNS TXT record (created automatically via your configured DNS provider API or a custom script).
3. Let's Encrypt signs the CSR and returns a certificate chain (your cert + intermediate CA).
4. The app uploads the Let's Encrypt intermediate and root CA as trusted certificates on the publisher (so the cluster trusts the new cert chain).
5. The app uploads the signed certificate back to the publisher.
6. The publisher replicates the certificate to all subscriber nodes automatically via Cisco's internal database replication.
7. The app verifies that each subscriber received the cert by polling their API.
8. The app restarts Cisco Tomcat on the publisher first, then each subscriber, so the new cert takes effect.

2.2 Cisco Expressway

Expressway uses a different approach — it accepts both the certificate and private key uploaded via SSH/SFTP:

1. The app generates a private key and CSR locally.
2. Let's Encrypt signs it (same DNS validation process as above).
3. The app connects via SSH/SFTP, uploads the cert and key to temporary files on the Expressway.
4. The app runs an install command via SSH to activate the certificate.
5. The app deletes the temporary files and verifies the new cert via a TLS handshake.

3. Prerequisites

3.1 System Requirements

3.2 Cisco UC Requirements

• CUCM/IM&P/CUC/CER version 14.0 or newer (required for the Platform REST API)
• An Application User or OS Admin account on each UC node with permissions for:
  • Certificate management API (/platformcom/api/v1/certmgr/)
  • SSH access (for service restarts via utils service restart)

3.3 DNS Requirements

Let's Encrypt uses DNS-01 challenge to verify domain ownership. You need one of the following:

• Cloudflare — Zone ID and an API Token with Zone.DNS.Edit permission
• Amazon Route 53 — AWS Access Key with Route 53 permissions
• Azure DNS — Service principal with DNS Zone Contributor role
• Google Cloud DNS — Service account with DNS Administrator role
• DigitalOcean — API token with read/write DNS access
• Custom Script — PowerShell scripts that create and delete TXT records for any other DNS provider

3.4 Expressway Requirements (if applicable)

• Admin credentials with SSH access
• SSH and SFTP enabled on the Expressway

4. Installation

1. Copy the application files
   Extract the release ZIP to a folder on the server. A typical install location is:

   C:\CiscoCertAutomation

   The folder should contain CiscoCertificates.Automation.exe, CiscoCertificates.ConfigEditor.exe, appsettings.json, and supporting files.
2. Verify the automation engine
   Open a Command Prompt or PowerShell window and run:

   C:\CiscoCertAutomation\CiscoCertificates.Automation.exe --help

   You should see the usage text with available mode switches.
3. Verify the Configuration Editor
   Double-click CiscoCertificates.ConfigEditor.exe. The application window should open with the Fluent UI sidebar showing navigation items for each configuration section.
4. Edit the configuration
   Use the Config Editor (see Section 5) or manually edit appsettings.json (see Section 6) to configure the automation for your environment.

5. Configuration Editor (GUI)

The CiscoCertificates.ConfigEditor is a Windows desktop application that provides a visual interface for editing appsettings.json. It eliminates the need to edit JSON directly and validates your configuration as you work.

5.1 Getting Started

Launch CiscoCertificates.ConfigEditor.exe. The main window has three areas:

• Menu Bar — File menu with New, Open, Save, Save As, and Exit. Keyboard shortcuts: Ctrl+N (New), Ctrl+O (Open), Ctrl+S (Save), Ctrl+Shift+S (Save As).
• Sidebar Navigation — Seven pages, each covering a section of the configuration: ACME Settings, DNS Provider, UC Nodes, Expressway, Jobs, Notifications, and General.
• Content Area — The selected page's settings, with input fields, toggles, and lists.

The title bar shows the currently loaded file name and an unsaved-changes indicator. A status bar at the bottom displays operation feedback.

To create a new configuration:

1. Click File → New (or Ctrl+N). This creates a blank configuration with default values.
2. Work through each page in the sidebar, filling in your environment-specific settings.
3. Click File → Save As (Ctrl+Shift+S) to save to the appsettings.json file in your automation folder.

To edit an existing configuration:

1. Click File → Open (Ctrl+O) and navigate to your existing appsettings.json.
2. Make your changes on any page.
3. Click File → Save (Ctrl+S) to save in place.

5.2 ACME Settings Page

This page configures the ACME certificate authority connection. It has two sections:

Certificate Authority

• ACME Provider — Select from a dropdown:
  • Let's Encrypt Production — Issues real, browser-trusted certificates (default)
  • Let's Encrypt Staging — Issues test certificates with higher rate limits (recommended for initial testing)
  • ZeroSSL — Alternative free CA (requires EAB credentials)
  • Custom — Any ACME-compatible CA (shows a URL field)
• Contact Email — Your email address. The CA uses this to notify you about expiring certificates or policy changes.
• Account Key Path — File path for the ACME account key (auto-generated on first run). Default: acme-account-key.pem

ACME Timing

• DNS Propagation Wait — Seconds to wait after creating the DNS TXT record before asking the CA to validate. Default: 90 seconds.
• Authorization Poll Interval — Seconds between checks for authorization completion. Default: 15.
• Authorization Poll Max Attempts — Maximum number of polls before giving up. Default: 20.

5.3 DNS Provider Page

Select your DNS provider from the dropdown at the top. The page dynamically shows configuration fields specific to the selected provider:

5.4 UC Nodes Page

This page uses a split-panel layout. The left panel shows a list of all UC nodes with Add and Remove buttons. The right panel shows the details of the selected node.

Node Identity

• Name — A short label you choose (e.g., CUCM-PUB). Used in logs and reports. Must match the Node reference in certificate jobs.
• Host — The FQDN or IP address of the server. Must be reachable on HTTPS (443) and SSH (22).
• Product Type — Descriptive label (e.g., "Cisco Unified CM Publisher", "Cisco IM&P (CUPS)"). Used in reports only.
• Cluster Role — publisher or subscriber. Only publishers generate CSRs and receive cert uploads.
• Cluster Group — Groups nodes that belong to the same product cluster (e.g., cucm, cups, cuc, cer). Subscribers in the same group are polled for replication after the publisher gets its cert.

Credentials

• Username / Password — UC admin credentials for API and SSH access.
• Username Environment Variable / Password Environment Variable — Optional. Specify environment variable names to read credentials from instead of storing them in the config file.

Security

• Allow Untrusted Server Certificate — Enable if the UC node currently has a self-signed or expired HTTPS cert. Set to false after deploying valid certs.
• SSH Host Key Fingerprint — Expected SSH host key fingerprint for strict validation.
• Allow Untrusted SSH Host Key — Accept any SSH host key. For production, disable this and provide the fingerprint.

5.5 Expressway Nodes Page

Similar split-panel layout as UC Nodes. Configure each Expressway server:

Node Identity

• Name — Short label (e.g., EXP-E)
• Host — FQDN or IP address
• SSH Port — Default: 22
• TLS Port — Default: 443 (used for post-deployment TLS verification)

Credentials

• Username / Password — Expressway admin credentials with SSH access
• Environment variable overrides available (same as UC Nodes)

SSH Security

• Expected SSH Host Key Fingerprint — For strict host key validation
• Allow Untrusted SSH Host Key — Accept any host key
• SSH Command Timeout — Seconds before SSH commands time out. Default: 120.

Command Templates

• Install Command Template — The SSH command to install a certificate. Uses placeholders: {domain}, {certPath}, {keyPath}
• Verify Command Template — The SSH command to verify installation. Uses placeholder: {domain}

5.6 Certificate Jobs Page

This is the most detailed page. Each job represents one certificate to issue and deploy. The left panel shows the job list; the right panel shows the selected job's configuration.

Certificate Identity

• Job Name — Unique label (e.g., cucm-tomcat, cups-tomcat)
• Common Name (CN) — The primary hostname on the certificate (typically the publisher FQDN)
• Subject Alternative Names — All hostnames that should appear on the certificate. Enter one per line. Include the publisher and all subscriber FQDNs.

Key & Algorithm

• Key Algorithm — Select from RS256 (RSA 2048 — recommended for Cisco compatibility), ES256, ES384, or ES512
• Renew Before Days — Override the global DefaultRenewBeforeDays for this specific job

Device CSR

• Use Device CSR — Enable for all UC jobs. Disable for Expressway jobs.
• CSR Distribution — multi-server (includes all cluster hostnames in the CSR) or this-server (publisher hostname only)
• Replication Delay — Seconds to wait after publisher deployment before checking subscriber replication. Default: 60.

Deployment Targets

A data grid showing which nodes receive the certificate. Use the Add/Remove buttons to manage targets. Each target has:

• Type — uc or expressway
• Node — Must match a name from the UC Nodes or Expressway Nodes page
• Service — The UC certificate service (e.g., tomcat, CallManager)
• Restart Services — Cisco services to restart after deployment (e.g., Cisco Tomcat)
• Domain — (Expressway only) Domain for cert installation
• TLS Host / TLS Port — (Expressway only) For post-deployment TLS verification

Trust Chain

• Install Chain As Trust — Enable to upload the Let's Encrypt CA chain (intermediate + root) as trusted certificates on the UC device
• Trust Services — Comma-separated list of UC trust stores to upload the CA chain to (e.g., tomcat)

EKU Requirements

• Required Enhanced Key Usages — OIDs or friendly names (e.g., serverAuth, clientAuth) that the issued certificate must contain
• Fail If Required EKU Missing — When enabled, the job fails if the issued certificate lacks any required EKU (recommended)

5.7 Notifications Page

Configure email notifications. Settings cascade — additional fields appear as you enable features:

1. Enable Email Notifications (master toggle)
2. When enabled, SMTP server fields appear:
   • SMTP Host / Port — Your mail relay
   • Use STARTTLS — Encrypt the SMTP connection
   • Skip TLS Certificate Validation — For internal relays with self-signed certs
3. Use Authentication toggle — when enabled, shows Username and Password fields
4. Recipients:
   • From Address — Sender email
   • To Addresses — One recipient per line
   • Subject Prefix — Prepended to email subjects (default: [CiscoCertAutomation])
5. Send Success Summary — When disabled (default), emails are only sent on failure

5.8 General Settings Page

This page covers automation behavior settings organized into six cards:

6. Configuration (Manual JSON)

All configuration lives in appsettings.json. You can edit this file directly instead of using the Config Editor. The file has four main sections.

6.1 Automation Section

{
  "Automation": {
    "DefaultRenewBeforeDays": 30,
    "MaxParallelDeployments": 2,
    "ContinueOnTargetFailure": true,
    "StateDirectory": "state",
    "HttpTimeoutSeconds": 60,
    "HttpRetryCount": 4,
    "EnableStateTracking": true,
    "RestartAutomation": {
      "EnableUcAutomaticRestarts": true,
      "FailWhenRestartRequiredButNoServiceDetected": true,
      "UcSshPort": 22,
      "UcSshCommandTimeoutSeconds": 120,
      "UcSshConnectionTimeoutSeconds": 30,
      "DelayAfterRestartSeconds": 15,
      "UcRestartCommandTemplate": "utils service restart {service}"
    }
  }
}

6.2 Acme Section (Let's Encrypt)

{
  "Acme": {
    "ContactEmail": "admin@example.com",
    "AccountKeyPath": "acme-account-key.pem",
    "DnsProvider": "Cloudflare",
    "DnsPropagationWaitSeconds": 90,
    "AuthorizationPollSeconds": 15,
    "AuthorizationPollMaxAttempts": 20,
    "Cloudflare": {
      "ZoneId": "YOUR_ZONE_ID_HERE",
      "TtlSeconds": 120,
      "ApiToken": ""
    },
    "Command": {
      "PresentCommand": ".\\scripts\\dns-present.ps1 -RecordName {recordName} -RecordValue {recordValue}",
      "CleanupCommand": ".\\scripts\\dns-cleanup.ps1 -RecordName {recordName} -RecordValue {recordValue}",
      "ShellExecutable": "powershell",
      "ShellArgumentsTemplate": "-NoProfile -NonInteractive -Command '{command}'"
    }
  }
}

Settings you MUST change:

If using a custom DNS provider (not one of the built-in providers):

Set "DnsProvider": "Command" and write two PowerShell scripts:

• scripts\dns-present.ps1 — Creates a DNS TXT record. Receives -RecordName (e.g., _acme-challenge.server.example.com) and -RecordValue (the challenge token).
• scripts\dns-cleanup.ps1 — Deletes that same TXT record after validation.

6.3 Deployment Section

This is the largest section. It defines your Cisco nodes and the certificate jobs.

6.3.1 UC Nodes

List every Cisco UC server in your environment, even subscribers (they're needed for replication verification):

"UcNodes": [
  {
    "Name": "CUCM-PUB",
    "Host": "cucm-pub.example.com",
    "ProductType": "Cisco Unified CM Publisher",
    "ClusterRole": "publisher",
    "ClusterGroup": "cucm",
    "AllowUntrustedServerCertificate": true,
    "AllowUntrustedSshHostKey": true,
    "Username": "",
    "Password": ""
  },
  {
    "Name": "CUCM-SUB1",
    "Host": "cucm-sub1.example.com",
    "ProductType": "Cisco Unified CM Subscriber",
    "ClusterRole": "subscriber",
    "ClusterGroup": "cucm",
    "AllowUntrustedServerCertificate": true,
    "AllowUntrustedSshHostKey": true,
    "Username": "",
    "Password": ""
  }
]

6.3.2 Expressway Nodes (if applicable)

"ExpresswayNodes": [
  {
    "Name": "EXP-E",
    "Host": "expressway.example.com",
    "SshPort": 22,
    "TlsPort": 443,
    "AllowUntrustedSshHostKey": true,
    "SshCommandTimeoutSeconds": 120,
    "InstallCommandTemplate": "...",
    "VerifyCommandTemplate": "...",
    "Username": "",
    "Password": ""
  }
]

6.3.3 Certificate Jobs

Each job represents one certificate to issue and deploy. You need one job per Cisco product cluster.

Example: CUCM Tomcat certificate

{
  "Name": "cucm-tomcat",
  "CommonName": "cucm-pub.example.com",
  "SubjectAlternativeNames": [
    "cucm-pub.example.com",
    "cucm-sub1.example.com",
    "cucm-sub2.example.com"
  ],
  "RenewBeforeDays": 30,
  "KeyAlgorithm": "RS256",
  "UseDeviceCsr": true,
  "CsrDistribution": "multi-server",
  "Targets": [
    {
      "Service": "tomcat",
      "Node": "CUCM-PUB",
      "Type": "uc",
      "RestartServices": [ "Cisco Tomcat" ]
    }
  ],
  "InstallChainAsTrust": true,
  "TrustServices": [ "tomcat" ],
  "TrustCertificateDescription": "Managed by CiscoCertificates.Automation"
}

6.4 Notifications Section

{
  "Notifications": {
    "Enabled": true,
    "SendSuccessSummary": false,
    "SmtpHost": "smtp.example.com",
    "SmtpPort": 587,
    "FromAddress": "cert-automation@example.com",
    "ToAddresses": [ "voip-team@example.com" ],
    "UseStartTls": true,
    "UseAuthentication": false,
    "SubjectPrefix": "[CiscoCertAutomation]"
  }
}

6.5 Secrets & Credentials

Every credential field supports two methods:

The app checks in order: direct value → environment variable. The first non-empty value wins.

7. First-Run Walkthrough

Follow these steps in order for your first deployment. Each step validates one piece of the puzzle before moving to the next.

1 Edit appsettings.json

Use the Config Editor (see Section 5) or a text editor to fill in your environment-specific values:

• ACME contact email and DNS provider credentials
• All UC and Expressway node hostnames and credentials
• Certificate jobs (one per product cluster)
• Notification settings

Set "AllowUntrustedServerCertificate": true on any UC nodes that currently have self-signed certs.

2 Run API Preflight

CiscoCertificates.Automation.exe --api-preflight

This validates:

• Can the app reach each UC node's certificate API?
• Are the credentials correct?
• Can it connect via SSH for service restarts?
• Can it connect to Expressway via SSH/SFTP?

Fix any errors before proceeding. Common issues: wrong hostname, firewall blocking port 443 or 22, incorrect credentials.

3 Run Status Report

CiscoCertificates.Automation.exe --status-report

This reads the current certificate from each target and reports:

• Thumbprint
• Expiration date
• Days remaining

This confirms the app can successfully read certificates from your devices. No changes are made.

4 Test with Let's Encrypt Staging

Switch the ACME provider to "Let's Encrypt Staging" in the Config Editor, or add the staging directory URL in JSON:

"DirectoryUrl": "https://acme-staging-v02.api.letsencrypt.org/directory"

Then run:

CiscoCertificates.Automation.exe --issue-only

This will:

• Generate a CSR on the device (for UC jobs) or locally (for Expressway jobs)
• Create DNS TXT records for validation
• Get a staging certificate from Let's Encrypt
• Save the certificate locally without deploying

5 Test Full Deployment with Staging

If Step 4 succeeded, run the full production cycle (still using the staging server):

CiscoCertificates.Automation.exe --production

This performs the full deployment cycle including uploading the cert, installing trust chain, and restarting services. The cert won't be browser-trusted (it's from staging) but this validates the entire deployment pipeline end-to-end.

6 Switch to Production Let's Encrypt

Switch back to "Let's Encrypt Production" in the Config Editor (or remove the staging DirectoryUrl from JSON).

Run the full production cycle:

CiscoCertificates.Automation.exe --production

This issues real, browser-trusted certificates and deploys them. After completion:

• Open each server's web interface in a browser and verify the padlock shows a valid Let's Encrypt certificate
• Run --status-report again to confirm the new thumbprints and expiration dates

7 Set Up Scheduled Runs

See Section 9 for Task Scheduler setup. The app handles renewals automatically — it only issues a new cert when the existing one is within RenewBeforeDays of expiration.

8. Run Modes (Command-Line Switches)

CiscoCertificates.Automation.exe [mode] [options]

8.1 Modes

Exactly one mode is required. Modes are mutually exclusive.

You can also specify a mode using --mode <value> or --mode=<value> syntax (e.g., --mode production).

8.2 Options

These can be combined with any mode:

8.3 Config Overrides

Any additional argument in the format --Section:Key=Value is passed to the .NET configuration system. For example:

CiscoCertificates.Automation.exe --production --Logging:LogLevel:Default=Debug
CiscoCertificates.Automation.exe --production --Acme:DnsPropagationWaitSeconds=120

This overrides settings for a single run without changing appsettings.json.

9. Scheduling with Task Scheduler

9.1 Create a Scheduled Task

1. Open Task Scheduler (taskschd.msc)
2. Click Create Task (not "Create Basic Task")
3. General tab:
   • Name: CiscoCertificates.Automation
   • Check Run whether user is logged on or not
   • Check Run with highest privileges
   • Configure for: Windows Server 2016 (or your OS)
4. Triggers tab:
   • New trigger → Daily, recur every 1 day
   • Start at a time that avoids peak hours (e.g., 2:00 AM)
5. Actions tab:
   • Action: Start a program
   • Program: C:\CiscoCertAutomation\CiscoCertificates.Automation.exe
   • Arguments: --production
   • Start in: C:\CiscoCertAutomation
6. Settings tab:
   • Check If the task fails, restart every: 1 hour
   • Attempt to restart up to: 3 times
   • Stop the task if it runs longer than: 2 hours
   • Check If the running task does not end when requested, force it to stop
7. Click OK and enter the service account credentials

9.2 Weekly Status Report (Optional)

Create a second scheduled task for a weekly status report:

• Trigger: Weekly (e.g., every Monday at 7:00 AM)
• Program: C:\CiscoCertAutomation\CiscoCertificates.Automation.exe
• Arguments: --status-report

This sends a summary email showing the current certificate status on all devices, giving you early warning if anything looks wrong.

10. State & Recovery

10.1 State Directory

When EnableStateTracking is true (the default), the app saves state in the state/ folder:

state/
  acme-account-key.pem          ← Your Let's Encrypt account key (auto-generated)
  jobs/
    cucm_tomcat/
      state.json                ← Thumbprint, expiry, per-target deployment status
      certificate-chain.pem     ← The last issued certificate chain
      private-key.pem.protected ← DPAPI-encrypted private key (Expressway only)
    cups_tomcat/
      ...
  runs/
    20260215-020000/            ← Artifacts from each run (timestamped)
      cucm_tomcat/
        certificate-chain.pem
        private-key.pem.protected

10.2 What State Tracking Does

• Prevents re-issuance waste: If a cert was issued but deployment failed (e.g., one subscriber was unreachable), the next run reuses the cached cert instead of requesting a new one from Let's Encrypt.
• Per-target tracking: Tracks which targets got the cert and which failed. On retry, only failed targets are redeployed.
• Rate limit protection: Let's Encrypt limits you to ~5 duplicate certificates per week. State tracking prevents hitting this limit.

10.3 Forcing a Fresh Issuance

If you need to force a completely new certificate (e.g., after adding a new SAN):

1. Delete the job's state folder: state\jobs\cucm_tomcat\
2. Run --production

Or use --issue-only to issue without deploying.

10.4 Private Key Security

Private keys stored on disk are encrypted using Windows DPAPI (DataProtectionScope.LocalMachine). This means:

• The encrypted file can only be decrypted on the same Windows machine
• If you move the state folder to a different machine, the encrypted keys are unreadable
• The state directory is locked down with NTFS ACLs: only SYSTEM and Administrators have access

11. Troubleshooting

11.1 Common Issues

11.2 Enabling Debug Logging

For detailed output, run with debug logging:

CiscoCertificates.Automation.exe --production --Logging:LogLevel:Default=Debug

Or set it permanently in appsettings.json:

"Logging": {
  "LogLevel": {
    "Default": "Debug",
    "Microsoft": "Warning"
  }
}

11.3 Let's Encrypt Rate Limits

With state tracking enabled and normal daily runs, you'll never come close to these limits. The app only requests a new cert when the current one is near expiry.

Appendix A: Exit Codes

You can check the exit code in Task Scheduler's "Last Run Result" column, or in PowerShell with $LASTEXITCODE after a manual run.

Appendix B: Full Configuration Reference

Automation

Automation > RestartAutomation

Automation > RunLog

Acme

Deployment > UcNodes[]

Deployment > Jobs[]

Deployment > Jobs[] > Targets[]

Notifications