ACME Certificate Issuance

Relevant source files

• internal/certacme/account.go
• internal/certacme/certifiers/sp_constellix.go
• internal/certacme/certifiers/sp_digitalocean.go
• internal/certacme/certifiers/sp_duckdns.go
• internal/certacme/certifiers/sp_googlecloud_dns.go
• internal/certacme/certifiers/sp_netlify.go
• internal/certacme/certifiers/sp_rfc2136.go
• internal/certacme/certifiers/sp_simplycom.go
• internal/certacme/certifiers/sp_xinnet.go
• internal/certacme/client.go
• internal/certacme/client_obtain.go
• internal/certificate/service.go
• internal/certmgmt/deployers/sp_cmcccloud_cdn.go
• internal/certmgmt/deployers/sp_googlecloud_certificatemanager.go
• internal/domain/acme_account.go
• internal/domain/certificate.go
• internal/repository/acme_account.go
• internal/repository/certificate.go
• migrations/1780934400_upgrade_v0.4.25.go
• pkg/core/certifier/challengers/dns01/cmcccloud/internal/lego.go
• pkg/core/certifier/challengers/dns01/conohavpsv3/conohavpsv3.go
• pkg/core/certifier/challengers/dns01/conohavpsv3/internal/lego.go
• pkg/core/certifier/challengers/dns01/constellix/constellix.go
• pkg/core/certifier/challengers/dns01/ctcccloud/internal/lego.go
• pkg/core/certifier/challengers/dns01/digitalocean/digitalocean.go
• pkg/core/certifier/challengers/dns01/duckdns/duckdns.go
• pkg/core/certifier/challengers/dns01/dynv6/internal/lego.go
• pkg/core/certifier/challengers/dns01/huaweicloud/huaweicloud.go
• pkg/core/certifier/challengers/dns01/linode/internal/lego.go
• pkg/core/certifier/challengers/dns01/linode/linode.go
• pkg/core/certifier/challengers/dns01/netlify/netlify.go
• pkg/core/certifier/challengers/dns01/qingcloud/internal/lego.go
• pkg/core/certifier/challengers/dns01/rfc2136/rfc2136.go
• pkg/core/certifier/challengers/dns01/simplycom/simplycom.go
• pkg/core/certifier/challengers/http01/ftp/internal/lego.go
• pkg/core/certifier/challengers/http01/local/local.go
• pkg/core/certifier/challengers/http01/s3/internal/lego.go
• pkg/core/certifier/challengers/http01/ssh/internal/ssh.go
• pkg/core/certifier/challengers/http01/ssh/ssh.go
• pkg/core/certmgr/providers/googlecloud-certificatemanager/googlecloud_certificatemanager.go
• pkg/core/certmgr/providers/googlecloud-certificatemanager/googlecloud_certificatemanager_test.go
• pkg/core/deployer/providers/cmcccloud-cdn/cmcccloud_cdn_test.go
• pkg/core/deployer/providers/cmcccloud-cdn/consts.go
• pkg/core/deployer/providers/googlecloud-certificatemanager/googlecloud_certificatemanager.go
• pkg/sdk3rd-trimmed/gitlab.ecloud.com/ecloud/ecloudsdkclouddns/client.go
• pkg/sdk3rd-trimmed/gitlab.ecloud.com/ecloud/ecloudsdkcmcdn/client.go
• pkg/sdk3rd/linode/api_create_domain_record.go
• pkg/utils/cert/converter.go
• pkg/utils/cert/key/key.go
• pkg/utils/filepath/path.go
• pkg/utils/ssh/io.go
• ui/public/imgs/providers/simplycom.png
• ui/src/components/access/forms/AccessConfigFieldsProviderRFC2136.tsx
• ui/src/components/access/forms/AccessConfigFieldsProviderSimplyCom.tsx
• ui/src/components/workflow/designer/forms/BizDeployNodeConfigFieldsProviderCMCCCloudCDN.tsx

The ACME (Automatic Certificate Management Environment) issuance subsystem is the core component responsible for automating the lifecycle of SSL/TLS certificates. It handles interactions with Certificate Authorities (CAs), manages domain validation challenges (DNS-01 and HTTP-01), and supports advanced features like External Account Binding (EAB) and ACME Renewal Information (ARI).

Architecture Overview

The issuance process is primarily driven by the bizApply node within the workflow engine. This node utilizes the internal/certacme package to interface with the lego library. To ensure system stability and credential isolation, Certimate can execute these requests in an isolated process via the intercmd certapply command using a specialized IPC mechanism, controlled by the CERTIMATE_WORKFLOW_MULTIPROC environment variable internal/workflow/engine/executor_bizapply.go27-31

Data Flow & Code Entity Mapping

This diagram illustrates the flow from a workflow execution to the final certificate storage, mapping high-level actions to specific code entities and packages.

Sources: internal/workflow/engine/executor_bizapply.go62-139 internal/certacme/client_obtain.go72-196 internal/repository/certificate.go77-126

---

Supported Certificate Authorities (CAs)

Certimate supports multiple CAs through the lego client. The CA configuration is resolved from the SettingsContentForSSLProvider or node-specific overrides.

CA Provider	EAB Support	Entity Reference
Let's Encrypt	No	CAProviderTypeLetsEncrypt
ZeroSSL	Yes	CAProviderTypeZeroSSL
Google Trust Services	Yes	CAProviderTypeGoogle
SSL.com	Yes	CAProviderTypeSSLCom
Actalis	Yes	CAProviderTypeActalis
DigiCert	Yes	CAProviderTypeDigiCert
GlobalSign Atlas	Yes	CAProviderTypeGlobalSign
Sectigo	Yes	CAProviderTypeSectigo
LiteSSL	Yes	CAProviderTypeLiteSSL

Configuration Logic: The bizApplyNodeExecutor retrieves global CA settings via settingsRepo.GetByName(SettingsNameSSLProvider). If EAB (External Account Binding) is required, the credentials (KID and HMAC Key) are provided to the ACME client to register or look up the ACMEAccount internal/certacme/account.go70-88 ACME account resources are persisted in the database with the resourceObj field containing the acme.Account JSON internal/repository/acme_account.go95-98

Sources: internal/certacme/account.go26-107 internal/repository/acme_account.go90-114

---

Challenge Types & Providers

Certimate implements two primary ACME challenge types, leveraging the lego library's provider ecosystem through a registry pattern.

1. DNS-01 Challenge

This method supports wildcard certificates by creating TXT records. Certimate integrates over 80 providers via ACMEDns01Registries.

• Implementation Pattern: Providers are registered in internal/certacme/certifiers. Each factory function maps AccessConfig to a core.ACMEChallenger (which wraps challenge.Provider) internal/certacme/certifiers/sp_googlecloud_dns.go13-26
• Expanded Provider Support: Support includes 35cn, 51dnscom, Beget, BookMyName, Dynadot, Dynu, Gandi, Hetzner, Hosting.de, Hostinger, Infomaniak, IONOS, Name.com, Namesilo, Netcup, NS1, Reg.ru, RU-CENTER, Spaceship, Technitium DNS, Todaynic, UCloud, Vultr, West.cn, Akamai EdgeDNS, CTCC Cloud SmartDNS, and Simply.com internal/certacme/certifiers/sp_simplycom.go13-25
• Provider Specifics:
  • RFC2136: Supports TSIG algorithms including HMAC-SHA-256 and GSS-TSIG for dynamic DNS updates ui/src/components/access/forms/AccessConfigFieldsProviderRFC2136.tsx47-58
  • Dynv6: Manages Zone and Record IDs internally to ensure clean cleanup pkg/core/certifier/challengers/dns01/dynv6/internal/lego.go39-168
  • CMCC Cloud: Uses ecloudsdkclouddns to manage TXT records with configurable propagation timeouts and polling intervals pkg/core/certifier/challengers/dns01/cmcccloud/internal/lego.go97-133
  • Google Cloud DNS: Configured via Project ID and Service Account Key internal/certacme/certifiers/sp_googlecloud_dns.go19-24

2. HTTP-01 Challenge

Used when DNS control is restricted. Supported via ACMEHttp01Registries.

• Implementation: Configured via ObtainCertificateRequest.ChallengeType = "http-01" internal/certacme/client_obtain.go114-131
• Methods: Supports file placement via SSH pkg/core/certifier/challengers/http01/ssh/ssh.go32-41 S3, FTP, and Local filesystem. The SSH provider supports jump servers (bastion hosts) for secure network traversal and can fall back to SCP if needed pkg/core/certifier/challengers/http01/ssh/ssh.go35-41

Sources: internal/certacme/client_obtain.go81-136 pkg/core/certifier/challengers/http01/ssh/ssh.go11-30 internal/certacme/certifiers/sp_googlecloud_dns.go12-29

---

ARI (ACME Renewal Information) & Renewal Logic

Certimate supports the ACME Renewal Information (ARI) extension to optimize certificate replacement.

1. Replacement Detection: When applying for a certificate, if a lastCertificate exists, its ACMECertificateUrl is passed as ReplacesCertID to the ACME request internal/certacme/client_obtain.go148-159
2. Retry Mechanism: If the CA returns an AlreadyReplacedError, Certimate automatically retries the request without the ARI extension to ensure issuance proceeds internal/certacme/client_obtain.go161-175
3. Status Tracking: If a certificate is successfully replaced via ARI, the IsRenewed flag is updated on the previous certificate record internal/workflow/engine/executor_bizapply.go128-131

Sources: internal/certacme/client_obtain.go158-175 internal/workflow/engine/executor_bizapply.go128-131

---

Multi-Process Isolation Pattern

To prevent long-running ACME operations or provider SDK crashes from affecting the main workflow engine, Certimate uses internal/tools/mproc for process isolation.

1. Isolation Trigger: Enabled via the CERTIMATE_WORKFLOW_MULTIPROC environment variable internal/workflow/engine/executor_bizapply.go30
2. Execution: The bizApply node invokes intercmd certapply. This subprocess initializes a mproc.Receiver to consume the encrypted ACME request, executes ObtainCertificate, and returns the certificate data via an encrypted response file internal/workflow/engine/executor_bizapply.go21-31
3. Compatibility: Lego v5 returns private keys in PKCS#8; Certimate converts these to PKCS#1 or SEC1 for broader compatibility before saving via xcert.ConvertPrivateKeyToPEM internal/certacme/client_obtain.go177-184

Sources: internal/workflow/engine/executor_bizapply.go27-31 internal/certacme/client_obtain.go177-184

---

Entity Relationship Diagram

This diagram maps the code entities involved in the ACME lifecycle to their roles in the system.

Sources: internal/domain/certificate.go18-43 internal/repository/acme_account.go90-114 internal/certacme/client_obtain.go26-59 internal/repository/certificate.go15-25