mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 13:51:36 +00:00
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.
123 lines
4.9 KiB
Markdown
123 lines
4.9 KiB
Markdown
# 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](index.md).
|
|
|
|
## 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](acme.md) 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](entrust.md): 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](index.md) — interface contract, registry, port/adapter wiring
|
|
- [Entrust connector](entrust.md) — mTLS-only commercial alternative
|
|
- [DigiCert connector](digicert.md) — API-key-only commercial alternative
|
|
- [Async CA polling](../protocols/async-ca-polling.md) — the bounded-polling primitive
|