shankar0123
d809874fa1
Per operator decision the framework-mapping docs are gone. They
were aspirational (no audit, no certification, no validated
mapping); keeping them around was misleading.
Files deleted (1,883 lines):
- docs/compliance/index.md
- docs/compliance/soc2.md
- docs/compliance/pci-dss.md
- docs/compliance/nist-sp-800-57.md
Hyperlinks removed:
- README.md: 'Auditor / compliance' row in the doc table; the
'(compliance mapping included)' parenthetical in the
positioning paragraph
- docs/README.md: the '## Compliance' section table; the
'Auditor / compliance team' reading-order-by-role row
Prose name-drops swept across 24 files:
- README.md: 'FedRAMP boundary CAs / financial-services policy
CAs' → '4-level boundary CAs / 3-level policy CAs';
'Compliance-grade for PCI-DSS Level 1, FedRAMP Moderate / High,
SOC 2 Type II, HIPAA' → cut entirely
- getting-started/{quickstart,concepts,examples,why-certctl,
advanced-demo}.md: 'compliance' → 'audit' / 'policy';
'PCI-DSS / SOC 2 / NIST SP 800-57' framework lists cut;
''pci': 'true'' tag example → ''environment': 'production''
- migration/cert-manager-coexistence.md: 'compliance rules' →
'policy rules'
- operator/approval-workflow.md: 'Compliance customers (PCI-DSS
Level 1, FedRAMP Moderate / High, SOC 2 Type II, HIPAA)' →
'Operators'; entire 'Compliance control mapping' table
(PCI-DSS §6.4.5 / NIST SP 800-53 SA-15 / SOC 2 Type II CC6.1
/ HIPAA §164.308(a)(4)) deleted; 'compliance contract' →
'two-person-integrity contract'; 'compliance auditors' →
'reviewers'
- operator/legacy-clients-tls-1.2.md: 'PCI-DSS v4.0 Req 4 §2.2.5'
audit-reference → CWE-326 (kept); 'PCI-DSS Req 4 §2.2.5
attestation' section retitled to 'TLS posture summary' and
rewritten without framework framing; 'PCI-DSS, NIST, and
major browsers will eventually deprecate TLS 1.2' →
'Major browsers and OS vendors will eventually deprecate
TLS 1.2'
- operator/database-tls.md: PCI-DSS Req 4 §2.2.5 audit-ref →
CWE-319 only; 'PCI-DSS scope' → 'sensitive data'; PCI-DSS
Req 4 v4.0 prose footing → cut
- operator/runbooks/disaster-recovery.md: 'SOC 2 / PCI
procurement-team deliverable' → 'on-call deliverable';
'compliance auditors' → 'reviewers'
- reference/connectors/{acme,aws-acm,azure-kv,globalsign,
local-ca,openssl,ssh,index}.md: 'compliance reporting
(PCI-DSS §3.6, HIPAA §164.312)' → 'audit reporting';
'Compliance environments (PCI-DSS Level 1, FedRAMP High,
HIPAA)' → 'Regulated environments'; 'compliance audits' →
'audit'; 'FedRAMP boundary CA' pattern names →
'4-level boundary CA' (technically descriptive)
- reference/protocols/est.md: 'compliance-hook seam' →
'device-state hook seam'; 'compliance gating' → 'device-state
gating'; 'est_compliance_failed' → 'est_device_state_failed'
- reference/protocols/scep-intune.md: 'Optional compliance
check' → 'Optional device-state check'; failure-counter
'compliance_failed' → 'device_state_failed'; 'Conditional
Access compliance gating' → 'Conditional Access
device-state gating'
- reference/intermediate-ca-hierarchy.md: 'FedRAMP boundary-CA
deployments where the regulator requires...' →
'Boundary-CA deployments where you want separation of policy
and issuing authorities'; pattern A retitled '4-level FedRAMP
boundary CA' → '4-level boundary CA'
- reference/architecture.md: broken Related-docs link to
compliance.md removed; the rest of that block had stale
pre-Phase-2 paths (quickstart.md, demo-advanced.md,
connectors.md, openapi.md, testing-guide.md, test-env.md) —
retargeted to current locations
- reference/deployment-model.md: 'SOC 2 evidence-report
generator' → 'Audit-evidence report generator'
- reference/vendor-matrix.md: 'SOC 2 / PCI auditors paste this
into evidence packs' → 'reviewers paste this into
vendor-evaluation packs'
- contributor/qa-test-suite.md: 'compliance exist' coverage
description cut; 'Compliance (PCI / SOC2 / HIPAA-relevant)'
risk-class label → 'Audit-relevant'
What was kept:
- CWE references (legitimate technical pointers)
- Microsoft API/feature names that happen to use 'compliance'
literally ('Microsoft Graph compliance API',
'device-compliance validators' — these are MS product names,
not framework name-drops)
- 'NIST PQC' on the landing page (Post-Quantum Cryptography is
the actual NIST standard family, not a compliance framework)
Verified: zero hyperlinks into docs/compliance/ remain. All 24
ci-guards/*.sh pass locally. qa-doc-seed-count.sh clean.
Net diff: 26 files / -1,883 deletions in compliance/ + -32 net
across the prose sweep.
Companion edits in cowork/ (CLAUDE.md doc-tree summary +
WORKSPACE-CHANGELOG.md retirement note) land separately.
4.9 KiB
GlobalSign Atlas HVCA Issuer Connector — Operator Deep-Dive
Last reviewed: 2026-05-05
Operator-grade documentation for the GlobalSign Atlas High Volume CA (HVCA) issuer connector. For the connector-development context (interface contract, registry, ports/adapters), see the connector index.
Overview
GlobalSign Atlas HVCA REST API with dual authentication: mTLS for the TLS handshake AND API key/secret headers for request authorization. Region-aware base URLs (EMEA, APAC, Americas).
Implementation lives at internal/connector/issuer/globalsign/
(mTLS keypair cache shared at
internal/connector/issuer/mtlscache/).
When to use this connector
Use the GlobalSign Atlas HVCA connector when:
- You're a GlobalSign Atlas customer issuing high volumes of publicly trusted certificates (the "HV" in HVCA).
- You want region-pinned issuance for regulatory or latency reasons (EMEA / APAC / Americas regional endpoints).
- You're prepared to manage both mTLS client certs AND API key/secret credentials in tandem.
Look elsewhere when:
- You only need DV public-trust and your CA is reachable via ACME — the ACME connector is simpler.
- The dual-auth burden (mTLS + API key + API secret) is heavier than your environment needs — DigiCert (API key only) or Entrust (mTLS only) are simpler to operate.
Configuration
| Setting | Required | Default | Description |
|---|---|---|---|
CERTCTL_GLOBALSIGN_API_URL |
Yes | — | Atlas HVCA API URL (region-specific) |
CERTCTL_GLOBALSIGN_API_KEY |
Yes | — | API key for request authentication |
CERTCTL_GLOBALSIGN_API_SECRET |
Yes | — | API secret for request authentication |
CERTCTL_GLOBALSIGN_CLIENT_CERT_PATH |
Yes | — | Path to mTLS client certificate PEM |
CERTCTL_GLOBALSIGN_CLIENT_KEY_PATH |
Yes | — | Path to mTLS client private key PEM |
CERTCTL_GLOBALSIGN_SERVER_CA_PATH |
No | system trust store | PEM bundle used to verify the Atlas API server certificate. Set this for private/lab Atlas deployments whose server TLS chain is not in the host's default trust bundle. |
CERTCTL_GLOBALSIGN_POLL_MAX_WAIT_SECONDS |
No | 600 (10m) |
Bounded-polling deadline for GetOrderStatus. GlobalSign tracks orders by serial number rather than order ID; the polling shape is identical. |
Authentication
Dual — mTLS client certificate for TLS handshake plus X-API-Key
and X-API-Secret headers on every request. Both must be valid
or the request fails.
TLS verification
The connector always verifies the server certificate. When
server_ca_path is set, the PEM bundle at that path is used as
the trust anchor; otherwise the host's system trust store is
used. TLS 1.2 is the minimum protocol version.
Issuance model
POST /v2/certificates returns a serial number. Certificate PEM
is available after validation completes. Typically resolves
within seconds for DV. GetOrderStatus polls the certificate
endpoint.
mTLS keypair caching (audit fix #10)
The parsed client certificate plus a precomputed *http.Transport
(with ServerCAPath pinning preserved when configured) are cached
on the connector after the first API call. Steady-state calls
reuse the cached transport — no per-call disk read or
tls.X509KeyPair parse.
Rotation is picked up automatically via mtime polling: when the cert file's mtime advances beyond the last-loaded value, the next API call re-parses and rebuilds the transport.
Operator workflow: mv -f new.crt /etc/certctl/globalsign/client.crt
(mtime changes), no process restart required, takes effect on the
next API call. os.Stat errors during rotation surface as
connector errors rather than silently serving stale credentials.
Revocation
CRL and OCSP are managed by GlobalSign. certctl records
revocations locally and notifies GlobalSign via
PUT /v2/certificates/{serial}/revoke.
Operator playbook
Rotating mTLS client material
Same flow as the Entrust connector: place the new
cert at the configured path, mtime changes, next API call picks
up the new keypair. ServerCAPath pin (when configured) is
preserved across the rebuild.
Rotating API key / secret
Rotate in the Atlas dashboard, then either restart certctl-server
or hot-swap via PUT /api/v1/issuers/{id}. The registry's
Rebuild path replaces the connector with the new credentials. The
mTLS transport cache stays warm across the swap (mTLS material
hasn't changed) — only the per-request headers are new.
Region selection
Atlas HVCA has region-specific base URLs. Use the URL that matches your account's contracted region; the connector does no region-routing on its own.
Related docs
- Connector index — interface contract, registry, port/adapter wiring
- Entrust connector — mTLS-only commercial alternative
- DigiCert connector — API-key-only commercial alternative
- Async CA polling — the bounded-polling primitive