Certificate Lifecycle

Relevant source files

• go.mod
• go.sum
• internal/certacme/account.go
• internal/certacme/client.go
• internal/certacme/client_obtain.go
• internal/certificate/service.go
• internal/domain/access.go
• internal/domain/acme_account.go
• internal/domain/certificate.go
• internal/domain/provider.go
• internal/repository/acme_account.go
• internal/repository/certificate.go
• migrations/1780934400_upgrade_v0.4.25.go
• pkg/utils/cert/converter.go
• pkg/utils/cert/key/key.go
• ui/src/components/access/AccessForm.tsx
• ui/src/components/access/forms/AccessConfigFieldsProvider.tsx
• ui/src/components/workflow/designer/forms/BizDeployNodeConfigFieldsProvider.tsx
• ui/src/domain/access.ts
• ui/src/domain/provider.ts
• ui/src/i18n/resources/en/nls.access.json
• ui/src/i18n/resources/en/nls.provider.json
• ui/src/i18n/resources/en/nls.workflow.nodes.json
• ui/src/i18n/resources/zh/nls.access.json
• ui/src/i18n/resources/zh/nls.provider.json
• ui/src/i18n/resources/zh/nls.workflow.nodes.json

The certificate lifecycle in Certimate encompasses the automated process of obtaining, persisting, deploying, and monitoring SSL/TLS certificates. This lifecycle is orchestrated by the workflow engine, which transitions certificates through various states—from initial ACME challenge validation to final deployment on cloud infrastructure or local servers.

Lifecycle Overview

The lifecycle is primarily driven by Workflow Nodes that interact with the Access & Provider system. A typical lifecycle follows this path:

1. Issuance: Triggered by a bizApply node (WorkflowNodeTypeBizApply) using the ACME protocol.
2. Storage: Successful issuances are converted into a domain.Certificate entity internal/domain/certificate.go18-43 and stored in the certificate collection internal/domain/certificate.go16
3. Deployment: Handled by bizDeploy nodes (WorkflowNodeTypeBizDeploy) which push certificates to end-targets like Alibaba Cloud, AWS, or local servers.
4. Monitoring: Ongoing health checks via bizMonitor nodes (WorkflowNodeTypeBizMonitor) ensure certificates are valid and correctly installed.

Lifecycle Architecture

The following diagram maps the logical lifecycle stages to the specific code entities and data structures involved.

Certificate State & Entity Map

Sources: internal/domain/certificate.go18-43 internal/certificate/service.go22-38 internal/repository/certificate.go77-126

---

4.1 ACME Certificate Issuance

Certimate automates the issuance process using the ACME protocol via the internal/certacme package. The system manages the entire flow from ACME account registration to final certificate retrieval.

Key Features:

• DNS-01: Automates TXT record insertion via 80+ integrated DNS providers (e.g., Aliyun, Cloudflare, Huawei Cloud, and many new additions like 35cn, 51dnscom, and Akamai-EdgeDNS) using the lego library internal/certacme/client_obtain.go82-112
• HTTP-01: Validates domain control via web-based tokens, supported for both domain and IP address certificates internal/certacme/client_obtain.go114-132
• Smart Renewal (ARI): Supports ACME Renewal Information (ARI) to replace certificates when signaled by the CA internal/certacme/client_obtain.go158-175
• Account Management: Automatically creates and caches ACME accounts in the acme_accounts collection internal/domain/acme_account.go11 using the ACMEAccountRepository internal/repository/acme_account.go17-21
• Multi-process Isolation: ACME requests are executed in isolated processes to ensure system stability and prevent resource leaks.

For details, see ACME Certificate Issuance.

---

4.2 Certificate Deployment Providers

Once a certificate is issued and stored, it is deployed to targets via the bizDeploy node. This process involves retrieving the certificate from the CertificateRepository internal/repository/certificate.go15-19 and pushing it to remote providers.

Deployment Features:

• Provider Abstraction: Uses a unified deployer interface pkg/core/deployer/provider.go to support 130+ targets including cloud CDNs (e.g., Alibaba Cloud, AWS, Volcengine, JD Cloud, BytePlus), load balancers, and infrastructure targets like SSH, FTP, S3, or Kubernetes Secrets.
• Access Management: Credentials for deployment targets are managed through the Access system internal/domain/access.go9-16 which stores API keys, tokens, and SSH secrets.
• Target Diversity: Supports specialized targets like Nginx Proxy Manager, BaoTa Panel, 1Panel, RatPanel, and a vast array of cloud-native services including WAF, ALB, VOD, and Live Streaming across providers like Tencent Cloud, Huawei Cloud, and Google Cloud ui/src/components/workflow/designer/forms/BizDeployNodeConfigFieldsProvider.tsx5-80

For details, see Certificate Deployment Providers.

---

Management and Maintenance

Certimate provides built-in services for managing the ongoing validity of certificates and cleaning up history.

Certificate Service Operations

The CertificateService internal/certificate/service.go22-32 handles high-level operations including:

• Downloading: Exporting certificates in PEM, PFX, or JKS formats via DownloadCertificate internal/certificate/service.go42-217 It handles conversion using utilities like xcert.TransformCertificateFromPEMToPFX internal/certificate/service.go124 and xcert.TransformCertificateFromPEMToJKS internal/certificate/service.go175
• Revocation: Interacting with the CA's ACME server to revoke issued certificates using RevokeCertificate internal/certificate/service.go219-257 This requires valid ACME account metadata (ACMEAccountUrl) and the certificate URL (ACMECertificateUrl) internal/certificate/service.go225-240
• Retention: Automatic cleanup of expired certificates via cleanupExpiredCertificates, scheduled daily using the internal scheduler internal/certificate/service.go34-40

Data Interaction Model

Code Entity Interaction

Sources: internal/certificate/service.go42-217 internal/repository/certificate.go21-35 internal/domain/certificate.go84-97

Key Data Entities

• domain.Certificate: The central entity storing PEM data, serial numbers, subject names, and ACME metadata internal/domain/certificate.go18-43
• domain.ACMEAccount: Stores ACME account registration details, including the private key, directory URLs, and the ResourceObject (updated to resourceObj in v0.4.25) internal/domain/acme_account.go13-21
• CertificateRepository: Provides methods to retrieve certificates by ID, Workflow ID, or Workflow Run ID internal/repository/certificate.go21-75

Sources: internal/domain/certificate.go18-43 internal/certificate/service.go22-32 internal/repository/certificate.go15-19 internal/repository/acme_account.go17-21 internal/domain/acme_account.go13-21