diff --git a/.gitignore b/.gitignore index 609bcd8..68b2f86 100644 --- a/.gitignore +++ b/.gitignore @@ -36,4 +36,10 @@ terraform/terraform.tfvars # Analysis / scratch — never commit analysis/ - +issues/ +.claude/ +.codex/ +CLAUDE.md +AGENTS.md +/logs*/ +*.log diff --git a/CERTInext.IntegrationTests/CERTInext.IntegrationTests.csproj b/CERTInext.IntegrationTests/CERTInext.IntegrationTests.csproj index bd3ec73..6ecc7fa 100644 --- a/CERTInext.IntegrationTests/CERTInext.IntegrationTests.csproj +++ b/CERTInext.IntegrationTests/CERTInext.IntegrationTests.csproj @@ -6,9 +6,9 @@ 12.0 false true - - false + + true $(DefineConstants);SUPPORTS_DCV @@ -16,14 +16,17 @@ - + + + + diff --git a/CERTInext.IntegrationTests/CloudflareDomainValidator.cs b/CERTInext.IntegrationTests/CloudflareDomainValidator.cs index 89c01eb..db56616 100644 --- a/CERTInext.IntegrationTests/CloudflareDomainValidator.cs +++ b/CERTInext.IntegrationTests/CloudflareDomainValidator.cs @@ -23,7 +23,7 @@ namespace Keyfactor.Extensions.CAPlugin.CERTInext.IntegrationTests /// Credentials are read from the : /// CERTINEXT_CF_API_TOKEN and CERTINEXT_CF_ZONE_ID. /// - internal sealed class CloudflareDomainValidator : IDomainValidator + internal sealed class CloudflareDomainValidator : IDomainValidator, IDisposable { private const string CfApiBase = "https://api.cloudflare.com/client/v4"; @@ -113,11 +113,13 @@ public async Task CleanupValidation(string key, Cancella public Task ValidateConfiguration(Dictionary configuration) => Task.CompletedTask; public Dictionary GetDomainValidatorAnnotations() => new(); public string GetValidationType() => "dns-01"; + + public void Dispose() => _http.Dispose(); } - internal sealed class CloudflareDomainValidatorFactory : IDomainValidatorFactory + internal sealed class CloudflareDomainValidatorFactory : IDomainValidatorFactory, IDisposable { - private readonly IDomainValidator _validator; + private readonly CloudflareDomainValidator _validator; public CloudflareDomainValidatorFactory(string apiToken, string zoneId) { @@ -125,5 +127,7 @@ public CloudflareDomainValidatorFactory(string apiToken, string zoneId) } public IDomainValidator ResolveDomainValidator(string domain, string validationType) => _validator; + + public void Dispose() => _validator.Dispose(); } } diff --git a/CERTInext.IntegrationTests/DcvLifecycleTests.cs b/CERTInext.IntegrationTests/DcvLifecycleTests.cs index 24ba0f1..5f2d57e 100644 --- a/CERTInext.IntegrationTests/DcvLifecycleTests.cs +++ b/CERTInext.IntegrationTests/DcvLifecycleTests.cs @@ -40,10 +40,11 @@ namespace Keyfactor.Extensions.CAPlugin.CERTInext.IntegrationTests /// CERTINEXT_DCV_DOMAIN=<subdomain to use, e.g. dcv-test.example.com> /// /// - public class DcvLifecycleTests : IClassFixture + public class DcvLifecycleTests : IClassFixture, IDisposable { private readonly IntegrationTestFixture _fixture; private readonly ITestOutputHelper _output; + private readonly List _toDispose = new List(); public DcvLifecycleTests(IntegrationTestFixture fixture, ITestOutputHelper output) { @@ -51,6 +52,13 @@ public DcvLifecycleTests(IntegrationTestFixture fixture, ITestOutputHelper outpu _output = output; } + public void Dispose() + { + foreach (var d in _toDispose) + d.Dispose(); + _toDispose.Clear(); + } + // --------------------------------------------------------------------------- // Helpers // --------------------------------------------------------------------------- @@ -69,11 +77,17 @@ private static string GenerateCsrPem(string commonName) + "\n-----END CERTIFICATE REQUEST-----"; } - private IDomainValidatorFactory BuildDnsFactory() => - _fixture.IsCloudflareConfigured - ? (IDomainValidatorFactory)new CloudflareDomainValidatorFactory( - _fixture.CloudflareApiToken, _fixture.CloudflareZoneId) - : new StubDomainValidatorFactory(); + private IDomainValidatorFactory BuildDnsFactory() + { + if (_fixture.IsCloudflareConfigured) + { + var factory = new CloudflareDomainValidatorFactory( + _fixture.CloudflareApiToken, _fixture.CloudflareZoneId); + _toDispose.Add(factory); + return factory; + } + return new StubDomainValidatorFactory(); + } /// /// Runs plugin.Synchronize and returns every record that came out of the @@ -88,6 +102,7 @@ private static async Task> RunSyncAsync(CERTInextCA var syncTask = Task.Run(async () => { await plugin.Synchronize(buffer, lastSync: null, fullSync: true, cancelToken: System.Threading.CancellationToken.None); + // Synchronize calls CompleteAdding() in its finally block; guard against double-call. if (!buffer.IsAddingCompleted) buffer.CompleteAdding(); }); @@ -655,7 +670,6 @@ public async Task BulkDvEnrollment_AllOrdersIssue_AndPaginationWorks() List synced = null; System.Diagnostics.Stopwatch syncPhaseSw = System.Diagnostics.Stopwatch.StartNew(); int passesUsed = 0; - int finalNotIssued = -1; for (int pass = 1; pass <= maxSyncPasses; pass++) { @@ -664,13 +678,27 @@ public async Task BulkDvEnrollment_AllOrdersIssue_AndPaginationWorks() synced = await RunSyncAsync(plugin); passSw.Stop(); + // Classify enrolled orders by their current status so that FAILED orders + // are not silently counted as still-pending, which would burn the full + // pass budget before producing a misleading "expected 0" assertion. int generated = synced.Count(r => enrolledIds.Contains(r.CARequestID) && r.Status == (int)EndEntityStatus.GENERATED); - int pending = enrolledIds.Count - generated; - finalNotIssued = pending; + int failed = synced.Count(r => enrolledIds.Contains(r.CARequestID) && r.Status == (int)EndEntityStatus.FAILED); + int pending = enrolledIds.Count - generated - failed; _output.WriteLine( $"--- Sync pass #{pass}: returned {synced.Count} records, {generated}/{enrolledIds.Count} GENERATED, " + - $"{pending} still pending, elapsed={passSw.Elapsed:mm\\:ss} ---"); + $"{failed} FAILED, {pending} still pending, elapsed={passSw.Elapsed:mm\\:ss} ---"); + + if (failed > 0) + { + var failedIds = synced + .Where(r => enrolledIds.Contains(r.CARequestID) && r.Status == (int)EndEntityStatus.FAILED) + .Select(r => r.CARequestID) + .Take(5); + Assert.Fail( + $"Pass #{pass}: {failed} order(s) reached FAILED status and will never issue: " + + string.Join(", ", failedIds)); + } if (pending == 0) break; @@ -696,10 +724,14 @@ public async Task BulkDvEnrollment_AllOrdersIssue_AndPaginationWorks() $"{string.Join(", ", missing.Take(5))}{(missing.Count > 5 ? ", ..." : "")}"); // Final assertion — every enrolled order must be GENERATED after the polling window. - var lookup = synced.ToDictionary(r => r.CARequestID, r => r); + // Filter null CARequestIDs before building the lookup (guards against any CA response + // that omits the ID, which would otherwise throw ArgumentNullException in ToDictionary). + var lookup = synced + .Where(r => r.CARequestID != null) + .ToDictionary(r => r.CARequestID, r => r); var notIssued = enrolledIds + .Where(id => lookup.TryGetValue(id, out var rec) && rec.Status != (int)EndEntityStatus.GENERATED) .Select(id => lookup[id]) - .Where(r => r.Status != (int)EndEntityStatus.GENERATED) .ToList(); if (notIssued.Count > 0) @@ -711,7 +743,7 @@ public async Task BulkDvEnrollment_AllOrdersIssue_AndPaginationWorks() notIssued.Should().BeEmpty( $"every enrolled DV order should auto-issue on the new sandbox after {maxSyncPasses} sync passes; " + - $"{notIssued.Count} did not (last pass: {finalNotIssued} pending)."); + $"{notIssued.Count} did not."); _output.WriteLine($"--- SUCCESS: {count}/{count} DV orders enrolled, synced, and issued in {passesUsed} sync pass(es). " + $"Enroll={sw.Elapsed:mm\\:ss} SyncPhase={syncPhaseSw.Elapsed:mm\\:ss} Total={(sw.Elapsed + syncPhaseSw.Elapsed):mm\\:ss} ---"); diff --git a/CERTInext.IntegrationTests/INTEGRATION_TESTING.md b/CERTInext.IntegrationTests/INTEGRATION_TESTING.md index 441f573..80e1f1a 100644 --- a/CERTInext.IntegrationTests/INTEGRATION_TESTING.md +++ b/CERTInext.IntegrationTests/INTEGRATION_TESTING.md @@ -1,155 +1,212 @@ -# CERTInext Integration Tests +# CERTInext Integration Tests — Setup and Running -This project contains xUnit integration tests that exercise the CERTInext plugin against -the live CERTInext REST API. All tests skip automatically when credentials are absent, -so the project is safe to include in CI pipelines that do not have API access. +This project contains xUnit integration tests that exercise the CERTInext plugin against the +live CERTInext REST API (V1 and V2). Every test skips automatically when credentials are absent, +so the project is safe to include in CI pipelines that have no API access. Tests that place +orders, publish DNS records, or cancel orders are additionally gated behind opt-in environment +flags. For the list of tests and what each checks, see [TESTING.md](TESTING.md). --- ## Prerequisites -- .NET 8 or .NET 10 SDK -- Access to a CERTInext account (sandbox or production) -- An API Access Key generated in the CERTInext portal under **Integrations → APIs** +- .NET 10 SDK (the test project targets `net8.0`) +- Access to a CERTInext account (a sandbox account is recommended) +- For V1 tests: an API Access Key from the CERTInext portal under **Integrations → APIs** +- For V2 tests: an OAuth-mode credential (client ID and secret) from the same page +- For DNS-01 DCV tests: a Cloudflare API token and zone ID for a domain you control --- ## Credential Setup -Create the file `~/.env_certinext` with the following content: +### V1: `~/.env_certinext` ```sh -# CERTInext API credentials -CERTINEXT_API_URL=https://api.certinext.io/emSignHub-API/ +# CERTInext V1 API credentials +CERTINEXT_API_URL=https://sandbox-us-api.certinext.io/emSignHub-API/ CERTINEXT_ACCESS_KEY=your-access-key-here CERTINEXT_ACCOUNT_NUMBER=your-account-number CERTINEXT_GROUP_NUMBER=your-group-number CERTINEXT_ORG_NUMBER=your-org-number -CERTINEXT_PRODUCT_CODE=838 +CERTINEXT_PRODUCT_CODE=842 CERTINEXT_REQUESTOR_EMAIL=you@example.com CERTINEXT_REQUESTOR_NAME=Your Name ``` -### Field reference - | Variable | Required | Description | |----------|----------|-------------| -| `CERTINEXT_API_URL` | Yes | Base URL of the CERTInext API, e.g. `https://api.certinext.io/emSignHub-API/` | -| `CERTINEXT_ACCESS_KEY` | Yes | REST API Access Key from the CERTInext portal (Integrations → APIs) | +| `CERTINEXT_API_URL` | Yes | V1 base URL, including the `/emSignHub-API` path segment | +| `CERTINEXT_ACCESS_KEY` | Yes | REST API Access Key from the CERTInext portal | | `CERTINEXT_ACCOUNT_NUMBER` | Yes | Your CERTInext account number (numeric string) | -| `CERTINEXT_GROUP_NUMBER` | No | Group number for order filtering | -| `CERTINEXT_ORG_NUMBER` | No | Organization number for order placement | -| `CERTINEXT_PRODUCT_CODE` | No | Default product code (e.g. `838` for DV SSL) | -| `CERTINEXT_REQUESTOR_EMAIL` | No | Email submitted with test orders | -| `CERTINEXT_REQUESTOR_NAME` | No | Name submitted with test orders | - -### API URL reference - -| Environment | URL | -|-------------|-----| +| `CERTINEXT_GROUP_NUMBER` | No | Group number for order placement and `GetProductDetails`; some accounts need it for the product list to be non-empty | +| `CERTINEXT_ORG_NUMBER` | No | Pre-vetted organization number for OV/EV order placement | +| `CERTINEXT_PRODUCT_CODE` | For order-placing tests | Numeric product code for your account. **Product codes are per account** — find yours with `make get-product-details-group` or `make probe-products` | +| `CERTINEXT_REQUESTOR_EMAIL`, `CERTINEXT_REQUESTOR_NAME` | For order-placing tests | Requestor submitted with test orders; the email must be registered in the account | +| `CERTINEXT_CF_API_TOKEN`, `CERTINEXT_CF_ZONE_ID` | For DNS-01 DCV tests | Cloudflare token with DNS edit permission on the zone, and the zone ID | +| `CERTINEXT_DCV_DOMAIN` | For DNS-01 DCV tests | A domain inside that zone that test orders use | +| `CERTINEXT_ORDER_ID` | For `SmokeTests` order lookups | An existing order number | + +| Environment | V1 `CERTINEXT_API_URL` | +|-------------|------------------------| | Sandbox (US) | `https://sandbox-us-api.certinext.io/emSignHub-API/` | | Production (US) | `https://us-api.certinext.io/emSignHub-API/` | | Production (Global/India) | `https://api.certinext.io/emSignHub-API/` | -### Credential file format - -The file is parsed line by line: -- Lines starting with `#` are treated as comments and ignored. -- Blank lines are ignored. -- Each line must be in `KEY=VALUE` format. -- Values are not quoted — do not surround values with `"` or `'`. -- Real environment variables override file values (useful for CI injection). - ---- - -## Running the Tests +### V2: `~/.env_certinext_v2` -### Using dotnet CLI +The V2 tests read this file themselves. ```sh -dotnet test CERTInext.IntegrationTests/ --verbosity normal +# CERTInext V2 API credentials +CERTINEXT_API_URL=https://sandbox-us-api.certinext.io # V2 base URL: no /emSignHub-API suffix +CERTINEXT_CLIENT_ID=your-oauth-client-id +CERTINEXT_CLIENT_SECRET=your-oauth-client-secret +CERTINEXT_USE_V2_API=1 # any non-empty value enables the V2 tests +CERTINEXT_PRODUCT_CODE=842 # optional; V2 catalog code, default 842 ``` -### Using the Makefile +The V2 file reuses key names from the V1 file (`CERTINEXT_API_URL`, `CERTINEXT_PRODUCT_CODE`, the +Cloudflare keys, `CERTINEXT_DCV_DOMAIN`) with V2 values, so source only `~/.env_certinext` into +your shell and never `~/.env_certinext_v2`. The V2 test classes never write those shared keys +into the process environment. -```sh -make integration-test -``` +### File format -### From the solution root (all tests including unit tests) - -```sh -dotnet test certinext-caplugin.sln --verbosity normal -``` +- Lines starting with `#` and blank lines are ignored. +- Each line is `KEY=VALUE`. One pair of matching surrounding single or double quotes is stripped from the value. +- Real environment variables override values from the V1 file, which makes CI injection easy. +- The V1 fixture fails fast, with an actionable message, if the resolved `CERTINEXT_API_URL` lacks + `/emSignHub-API`, which indicates a V2 URL leaked into the V1 side. +- When running from a shell that needs the opt-in flags below, load the V1 file with + `set -a; . ~/.env_certinext; set +a`. --- -## Skip Behaviour +## Running the Tests -Each test calls `IntegrationSkip.IfNotConfigured(fixture)` at the top of the test method. -When `~/.env_certinext` is absent or either `CERTINEXT_API_URL` or `CERTINEXT_ACCESS_KEY` -is empty, every test is reported as **Skipped** rather than Failed. +```sh +# all integration tests (live tests skip when credentials are absent) +dotnet test CERTInext.IntegrationTests/CERTInext.IntegrationTests.csproj -c Release --verbosity normal -This makes the test project safe to include in CI pipelines where live credentials are -not available — the tests show up in the results as skipped rather than causing a -pipeline failure. +# or via the Makefile +make integration-test ---- +# a single class +dotnet test CERTInext.IntegrationTests/ --filter "FullyQualifiedName~LifecycleTests" -v normal + +# from the solution root, including the unit tests +dotnet test certinext-caplugin.sln --verbosity normal +``` -## Test Classes +The DCV test classes compile into the default build; no build flag is needed. -### `ConnectivityTests` +### V2: pinned and unpinned ("V2 template") runs -| Test | What it checks | -|------|---------------| -| `Ping_ReturnsSuccess` | Calls `ValidateCredentials` endpoint; asserts no exception is thrown | +Every V2 test that enrolls a product runs twice, mirroring the two gateway template sets that +`scripts/register/` registers (see [scripts/register/README.md](../scripts/register/README.md)): -### `ProductTests` +| Row (`mode:`) | `ProductID` | `ProductCode` parameter | Plugin sends `X-Product-Code` | +|---|---|---|---| +| `Pinned` | product name, e.g. `DV SSL` | the product's code | yes | +| `V2Template` (unpinned) | same product name | none | no, CERTInext resolves the product | -| Test | What it checks | -|------|---------------| -| `GetProductDetails_ReturnsProducts` | Calls `GetProductDetails`; asserts the call succeeds; when products are returned, asserts product code `838` is present | +Select a set with `--filter "DisplayName~Pinned"` or `--filter "DisplayName~V2Template"`. Pinned +codes default to the sandbox catalog (DV SSL 842, DV Wildcard 843, DV UCC 844, DV Wildcard UCC 845, +OV 846-849 in the same order, EV SSL 850, EV UCC 851); override with `CERTINEXT_PRODUCT_CODE` (DV SSL +only) or `CERTINEXT_PRODUCT_CODE_MAP_JSON` (for example `{"OV SSL":"900"}`). On the sandbox the +unpinned DV product currently resolves to a product that rejects the CSR at submit, so `V2Template` +rows that issue are expected to fail until CERTInext fixes the account; that is a product finding, not +a test bug. Tests handed an existing order through an env variable (`CERTINEXT_V2_ORDER_ID`, +`CERTINEXT_V2_ISSUED_ORDER_ID`) do not enroll, so only their `Pinned` row runs. -> Note: some CERTInext accounts return an empty list from `GetProductDetails` even though -> orders using those product codes are visible in `GetOrderReport`. An empty list is -> treated as acceptable in this test — only the absence of an exception is mandatory. +--- -### `OrderReportTests` +## Skip Behaviour -| Test | What it checks | -|------|---------------| -| `GetOrderReport_ReturnsOrders` | Fetches page 1; asserts at least one order is returned | -| `GetOrderReport_AllOrders_HaveRequiredFields` | For each order on page 1: `requestNumber`, `productCode`, and `orderDate` are non-empty | +- **V1 tests** call `IntegrationSkip.IfNotConfigured(fixture)` first. When `~/.env_certinext` is + absent, or `CERTINEXT_API_URL` or `CERTINEXT_ACCESS_KEY` is empty, the test is reported as + **Skipped**, not failed. +- **V2 tests** skip unless `CERTINEXT_USE_V2_API`, `CERTINEXT_API_URL`, `CERTINEXT_CLIENT_ID`, and + `CERTINEXT_CLIENT_SECRET` are all set (in `~/.env_certinext_v2` or the environment). +- **DCV tests** additionally skip unless the Cloudflare token and zone ID are set. +- Some tests skip when the account lacks the state they need, such as no existing orders or an + order that has not yet reached an issued state. + +### Opt-in flags + +Tests that place real orders, publish DNS records, or cancel orders only run when you export the +matching flag in your shell. These flags are deliberately **not** read from `~/.env_certinext` or +`~/.env_certinext_v2`, so a flag left in a file can't arm them on every run. + +| Flag | Arms | +|------|------| +| `CERTINEXT_ALGO_MATRIX=1` | `AlgorithmMatrixTests.Enroll_AcceptsKeyAlgorithm` — one sandbox order per key algorithm | +| `CERTINEXT_ALGO_MATRIX_DCV=1` | `DcvLifecycleTests.EnrollWithDcvOn_IssuesPerKeyAlgorithm` (also needs Cloudflare) | +| `CERTINEXT_RUN_BULK_TEST=1` | `DcvLifecycleTests.BulkDvEnrollment_AllOrdersIssue_AndPaginationWorks` (also needs Cloudflare); tune with `CERTINEXT_BULK_TEST_COUNT` and `CERTINEXT_BULK_TEST_PARALLEL` | +| `CERTINEXT_COMPLETE_PENDING=1` | `DcvLifecycleTests.CompleteAllPendingDvOrders` (also needs Cloudflare) — repeated full syncs until no DV order is pending | +| `CERTINEXT_V2_ALGO_MATRIX=1` | `V2DcvLifecycleTests.EnrollWithDcvOn_V2_IssuesPerKeyAlgorithm` (also needs Cloudflare) | +| `CERTINEXT_V2_RUN_BULK_TEST=1` | `V2DcvLifecycleTests.BulkV2Enrollment_AllOrdersIssue_AndPaginationWorks` (also needs Cloudflare); tune with `CERTINEXT_V2_BULK_TEST_COUNT` and `CERTINEXT_V2_BULK_TEST_PARALLEL` | +| `CERTINEXT_V2_LIFECYCLE_DV_UCC=1`, `_OV=1`, `_OV_UCC=1`, `_EV=1`, `_WILDCARD_DV=1`, `_RENEW_REISSUE=1` | The matching `V2FullLifecycleTests` method; the OV and OV UCC tests also need `CERTINEXT_ORG_NUMBER`, and the EV test needs its own pre-vetted `CERTINEXT_EV_ORG_NUMBER` | +| `CERTINEXT_V2_LIFECYCLE_FRESH_DCV=1` | `V2FreshDomainDcvLifecycleTests` (also needs Cloudflare and `CERTINEXT_V2_FRESH_DCV_PARENT`, the parent domain that fresh subdomains are created under) | +| `CERTINEXT_V2_INLINE_CSR=0` | Not a test gate: runs the V2 enrollment tests (`V2LifecycleTests`, `V2FullLifecycleTests`, `V2DcvLifecycleTests`, `V2FreshDomainDcvLifecycleTests`, `PrivatePkiV2LiveTests`) with the `V2InlineCsr` connector setting off (SSL/TLS two-call: create, then submit CSR). Unset runs the default single-call flow; run the suite once in each mode. Private PKI stays two-call either way | +| `CERTINEXT_PRIVATE_PKI_LIVE=1` | `PrivatePkiV2LiveTests.PrivatePki_V2_EnrollIntranetSsl_ThenRevoke_Live`; override the product code and CN with `CERTINEXT_PRIVATE_PKI_PRODUCT_CODE` and `CERTINEXT_PRIVATE_PKI_CN` | +| `CERTINEXT_V2_OPS_TESTS=1` | `V2OrderWindowSweepTests` — see below | + +Further variables select existing orders for specific tests: `CERTINEXT_PENDING_ORDER_ID` +(`DcvLifecycleTests.GetSingleRecord_DrivesDcvForPendingOrder`), `CERTINEXT_V2_PENDING_ORDER_ID`, +`CERTINEXT_V2_ORDER_ID`, `CERTINEXT_V2_ISSUED_ORDER_ID`, and `CERTINEXT_REVOKE_ORDER_ID` (V2 +lifecycle and revoke tests), and `CERTINEXT_V2_FULL_SYNC_TEST` (any value enables the V2 full-history +sync test, which can be slow on a shared account). + +### Operations and diagnostic tests + +Two opt-in tests are maintenance tools rather than checks: + +- **`V2OrderWindowSweepTests`** lists every V2 order in a date window and can cancel specific + orders. It needs `CERTINEXT_V2_OPS_TESTS=1`, `CERTINEXT_V2_SWEEP_FROM` and `CERTINEXT_V2_SWEEP_TO` + (UTC ISO-8601 timestamps), and is read-only unless `CERTINEXT_V2_SWEEP_CANCEL_IDS` lists order + IDs, in which case it cancels exactly those orders if they are found in the window and not already + in a terminal state. +- **`PendingDvDiagnosticsTests`** dumps the DCV state of pending V1 orders. It needs + `CERTINEXT_DIAG_ORDER_IDS="orderId|domain,orderId|domain"` and makes read-only calls. + +### Completing pending DV orders + +To drive every pending DV order on a sandbox account to issuance (needs a DNS provider, so the +Cloudflare variables): -### `PluginSmokeTests` +```sh +set -a; . ~/.env_certinext; set +a +export CERTINEXT_COMPLETE_PENDING=1 +dotnet test CERTInext.IntegrationTests/CERTInext.IntegrationTests.csproj -c Release \ + --filter "FullyQualifiedName~CompleteAllPendingDvOrders" \ + --logger "console;verbosity=detailed" > /tmp/dvrun.log 2>&1 +``` -End-to-end tests exercising `CERTInextCAPlugin` via the `IAnyCAPlugin` interface with -a live `CERTInextClient` injected through the `(ICERTInextClient, CERTInextConfig)` -test constructor. +xUnit buffers test output until the test ends, so read the per-pass report at the end of the log. +Run only one full-history synchronization at a time against a shared account; full syncs are +slow. -| Test | What it checks | -|------|---------------| -| `Ping_ThroughPlugin_Succeeds` | Calls `IAnyCAPlugin.Ping()`; asserts no exception | -| `GetProductIds_ReturnsAtLeastOneProduct` | Calls `IAnyCAPlugin.GetProductIds()`; asserts a non-null list is returned without throwing | -| `Synchronize_ReturnsAtLeastOneRecord` | Runs a full sync; asserts at least one `AnyCAPluginCertificate` record is produced | +`CompleteAllPendingDvOrders` builds a **V1** plugin (`UseV2Api` defaults to `false`), so it syncs and +runs DCV through V1, and it sweeps every pending DV order in the account. For one **V2** order, use +`V2DcvLifecycleTests.GetSingleRecord_V2_DrivesDcvForPendingOrder` with +`CERTINEXT_V2_PENDING_ORDER_ID=`. That test writes the plugin's log to the test output. --- ## Authentication -The CERTInext API uses HMAC-SHA256 authentication computed for every request: +V1 uses the AccessKey digest the plugin computes for every request: ``` authKey = SHA256(accessKey + ts + txn) (lowercase hex) ``` -Where: -- `accessKey` is the raw API Access Key from `CERTINEXT_ACCESS_KEY` -- `ts` is the current timestamp in ISO 8601 format -- `txn` is a random numeric transaction ID - -The `CERTInextClient` handles this computation automatically. The raw access key is -never transmitted over the wire — only the derived `authKey` hash is sent. +`accessKey` is `CERTINEXT_ACCESS_KEY`, `ts` is the current ISO 8601 timestamp, and `txn` is a random +numeric transaction ID. The client computes this itself, and the raw access key is never transmitted. +V2 tests authenticate with OAuth2 `client_credentials` using `CERTINEXT_CLIENT_ID` and +`CERTINEXT_CLIENT_SECRET`. --- @@ -157,7 +214,39 @@ never transmitted over the wire — only the derived `authKey` hash is sent. | Symptom | Likely cause | Fix | |---------|-------------|-----| -| All tests skipped | Missing or empty `~/.env_certinext` | Create the file with required variables | -| `Ping` fails with 401 | Wrong `CERTINEXT_ACCESS_KEY` | Regenerate the key in the CERTInext portal | -| `Ping` fails with timeout | Wrong `CERTINEXT_API_URL` | Verify the URL matches your account region | -| `GetOrderReport` returns 0 orders | Account has no orders | Place a test order first (see `make generate-order` in the project Makefile) | +| All tests skipped | Missing or empty `~/.env_certinext` (V1) or `~/.env_certinext_v2` (V2) | Create the file with the required variables | +| V1 fixture throws about `/emSignHub-API` | A V2 `CERTINEXT_API_URL` leaked into the shell | Run `unset CERTINEXT_API_URL`, or open a fresh shell, and source only `~/.env_certinext` | +| `Ping` fails with 401/403 | Wrong `CERTINEXT_ACCESS_KEY` | Regenerate the key under Integrations → APIs | +| `Ping` fails with a timeout or 404 | Wrong `CERTINEXT_API_URL` | Check the URL against your account's region (V1 needs the `/emSignHub-API` path) | +| V2 token request fails with 401 | Wrong client ID or secret | Check `CERTINEXT_CLIENT_ID` and `CERTINEXT_CLIENT_SECRET` | +| V2 token request fails with 403 | Key not generated in OAuth mode | Create a new OAuth-mode key in the portal | +| `Enroll` fails with "Invalid Product Code" (EMS-1162) | `CERTINEXT_PRODUCT_CODE` isn't provisioned for the account | Run `make probe-products` and use a code the account accepts | +| `GetProductDetails` returns an empty list | `CERTINEXT_GROUP_NUMBER` not set | Add your group number; some accounts need it | +| `Enroll` fails with "Invalid Organization Number" (EMS-1073) | OV/EV order with an unregistered organization | Use a DV product for automated tests, or register and approve the organization | +| Revoke step skips with "not GENERATED" | A sandbox DV order needs domain validation before it is issued | Expected without DCV; run the DCV tests with Cloudflare configured, or approve the order in the portal | +| `OrderReportTests` skip | The account has no orders | Run `LifecycleTests` first to place one | + +## Triaging live V2 failures + +Sandbox behaviour changes without notice, and several CERTInext errors look like plugin bugs. Check +these before changing code. + +**Get the plugin's own log first.** `TestOutputLogging.RouteTo(_output)` routes `LogHandler` to the test +output; `V2LifecycleTests.Enroll_V2_ReturnsCARequestID` and +`V2DcvLifecycleTests.GetSingleRecord_V2_DrivesDcvForPendingOrder` already do. Set +`CERTINEXT_TEST_LOG_LEVEL=Trace` to add the redacted request and response payloads. Without this, a +test that "passes" with the order still pending tells you nothing. + +| Symptom | Likely cause | How to confirm | +|---|---|---| +| Order `issued` but Download Certificate returns 422 `EMS-1165`, and stays that way | The CA approved the order but hasn't generated the certificate (`certificateState: "Approved by System"`). This normally clears in about 20 s; on the sandbox it stalled from 2026-10-13. | Track Order shows `certificateState`. `GET /reports/orders?status=issued` lists only orders whose certificate was actually generated ("Certificate Downloaded"); if the newest is old, generation has stopped CA-side. | +| No `X-Product-Code`: two-call CSR submit returns 422 "PFX based certificate orders are not allowed" | CERTInext resolved the product to one that doesn't take a client CSR (on the sandbox, DV resolves to `917`, not `842`) | The create response's `resolvedProductCode` (logged as `ResolvedProductCode=`). Pin `ProductCode` on the template. | +| No `X-Product-Code`: `GET .../dcv` returns 422 `EMS-1164 Domain Name is not matching`, and `certificateState` is "System Error" | Same product resolution as the row above. It isn't the domain or its letter case. | Pin 842 on the same domain shape; the order issues. | +| Two-call, pinned: `PUT .../csr` returns 422 "Something went Wrong." | The domain is already validated, so the create came back `issued` with `csrSubmitted: false` and the order won't accept a CSR | Trace payloads show the create response. Use `V2InlineCsr=true`, the default since 2.0. | +| `V2 OAuth2 token acquisition failed ... HttpStatus=0` (enroll, sync, or config save returns 500 "could not connect to CERTInext") | A transient transport failure to the token endpoint. The plugin currently logs no transport detail and doesn't retry the token request; a fix is planned. | Retry once. From a gateway pod, test with `curl --cacert /etc/pki/tls/certs/ca-bundle.crt` (the lab pod's `SSL_CERT_FILE` trusts only the lab CA, so plain curl fails TLS even when .NET works). | +| Unpinned (`V2Template`) rows fail while pinned rows pass | Expected on the sandbox until CERTInext changes how it resolves DV | See the 917 rows above. | + +Before blaming the plugin, separate CA-side from plugin-side failures: run the same request **pinned**, +on a **fresh** name under the validated parent zone, and with the CSR **inline**. Change one variable +at a time. Record confirmed spec-vs-live discrepancies as dated Findings in the CERTInext +support-questions list kept with the maintainers. diff --git a/CERTInext.IntegrationTests/IntegrationTestFixture.cs b/CERTInext.IntegrationTests/IntegrationTestFixture.cs index 8e4f637..b7df75d 100644 --- a/CERTInext.IntegrationTests/IntegrationTestFixture.cs +++ b/CERTInext.IntegrationTests/IntegrationTestFixture.cs @@ -1,6 +1,9 @@ // Copyright 2024 Keyfactor // Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. -// At http://www.apache.org/licenses/LICENSE-2.0 +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. using System; using System.Collections.Generic; @@ -20,6 +23,95 @@ namespace Keyfactor.Extensions.CAPlugin.CERTInext.IntegrationTests /// public sealed class IntegrationTestFixture : IDisposable { + // --------------------------------------------------------------------------- + // Opt-in guard + // --------------------------------------------------------------------------- + + /// + /// Env-var keys that must be set explicitly in the shell and must NOT be + /// auto-promoted from either env file. These gate destructive or mutating tests + /// so a developer cannot accidentally arm them by leaving flags in ~/.env_certinext + /// OR ~/.env_certinext_v2. Exposed internal (rather than private) so + /// can exclude the same names from its own + /// promotion of ~/.env_certinext_v2 — without that, a flag left in the V2 file would + /// be read as unset by the first test class constructed in a run, then promoted into + /// process env, silently arming every later test in the same run. + /// + internal static readonly System.Collections.Generic.HashSet _optInOnlyFlags = + new System.Collections.Generic.HashSet(StringComparer.OrdinalIgnoreCase) + { + "CERTINEXT_COMPLETE_PENDING", + "CERTINEXT_RUN_BULK_TEST", + "CERTINEXT_V2_RUN_BULK_TEST", + "CERTINEXT_PRIVATE_PKI_LIVE", + "CERTINEXT_V2_OPS_TESTS", + // V2 full-lifecycle readiness suite (DV UCC / OV / OV UCC / EV / wildcard DV / + // renew+reissue / fresh-domain DCV) — each places real sandbox orders and must + // be armed individually in the real shell, never left in either env file. + "CERTINEXT_V2_LIFECYCLE_DV_UCC", + "CERTINEXT_V2_LIFECYCLE_OV", + "CERTINEXT_V2_LIFECYCLE_OV_UCC", + "CERTINEXT_V2_LIFECYCLE_EV", + "CERTINEXT_V2_LIFECYCLE_WILDCARD_DV", + "CERTINEXT_V2_LIFECYCLE_RENEW_REISSUE", + "CERTINEXT_V2_LIFECYCLE_FRESH_DCV", + // Selects the V2InlineCsr connector setting for the V2 enrollment tests (see V2EnvHelper). + "CERTINEXT_V2_INLINE_CSR", + // Issue 0090 V2 place-order latency experiment (places real sandbox orders). + "CERTINEXT_V2_LATENCY_EXPERIMENT", + // Explicit-ID V2 sandbox order cleanup (revokes/cancels the listed orders). + "CERTINEXT_V2_CLEANUP_ORDERS", + // Issues 0062/0090 V2 inline-CSR vs two-call issuance experiment (places real sandbox orders). + "CERTINEXT_V2_INLINE_CSR_EXPERIMENT", + // V2 certificate-lifetime probe (V2ValidityProbeTests) — places real sandbox orders. + "CERTINEXT_PROBE_VALIDITY", + }; + + // --------------------------------------------------------------------------- + // V1 env keys + // --------------------------------------------------------------------------- + + internal const string ApiUrlKey = "CERTINEXT_API_URL"; + internal const string AccessKeyKey = "CERTINEXT_ACCESS_KEY"; + internal const string AccountNumberKey = "CERTINEXT_ACCOUNT_NUMBER"; + internal const string GroupNumberKey = "CERTINEXT_GROUP_NUMBER"; + internal const string OrgNumberKey = "CERTINEXT_ORG_NUMBER"; + internal const string ProductCodeKey = "CERTINEXT_PRODUCT_CODE"; + internal const string RequestorEmailKey = "CERTINEXT_REQUESTOR_EMAIL"; + internal const string RequestorNameKey = "CERTINEXT_REQUESTOR_NAME"; + internal const string CloudflareApiTokenKey = "CERTINEXT_CF_API_TOKEN"; + internal const string CloudflareZoneIdKey = "CERTINEXT_CF_ZONE_ID"; + + /// + /// Path segment every V1 (emSignHub-API) base URL carries. A resolved + /// without it is almost always the V2 base URL from + /// ~/.env_certinext_v2. + /// + internal const string V1ApiPathSegment = "/emSignHub-API"; + + /// + /// Every env key the V1 side of the harness reads: the keys this fixture resolves, plus + /// CERTINEXT_DCV_DOMAIN, which V1 DcvLifecycleTests reads straight from + /// process env. must never write these into + /// process env, because real env vars take precedence over ~/.env_certinext here + /// and the V2 file defines the same names with V2 values. + /// + internal static readonly IReadOnlySet V1EnvKeys = + new HashSet(StringComparer.OrdinalIgnoreCase) + { + ApiUrlKey, + AccessKeyKey, + AccountNumberKey, + GroupNumberKey, + OrgNumberKey, + ProductCodeKey, + RequestorEmailKey, + RequestorNameKey, + CloudflareApiTokenKey, + CloudflareZoneIdKey, + "CERTINEXT_DCV_DOMAIN", + }; + // --------------------------------------------------------------------------- // Credential properties // --------------------------------------------------------------------------- @@ -83,29 +175,41 @@ public IntegrationTestFixture() var env = LoadEnvFile(envPath); - // Promote env-file values into the process environment so that any code - // calling System.Environment.GetEnvironmentVariable() picks them up. - foreach (var kv in env) - if (System.Environment.GetEnvironmentVariable(kv.Key) == null) - System.Environment.SetEnvironmentVariable(kv.Key, kv.Value); + ApiUrl = GetEnvValue(env, ApiUrlKey); + AccessKey = GetEnvValue(env, AccessKeyKey); + AccountNumber = GetEnvValue(env, AccountNumberKey); + GroupNumber = GetEnvValue(env, GroupNumberKey); + OrgNumber = GetEnvValue(env, OrgNumberKey); + ProductCode = GetEnvValue(env, ProductCodeKey); + RequestorEmail = GetEnvValue(env, RequestorEmailKey); + RequestorName = GetEnvValue(env, RequestorNameKey); - ApiUrl = GetEnvValue(env, "CERTINEXT_API_URL"); - AccessKey = GetEnvValue(env, "CERTINEXT_ACCESS_KEY"); - AccountNumber = GetEnvValue(env, "CERTINEXT_ACCOUNT_NUMBER"); - GroupNumber = GetEnvValue(env, "CERTINEXT_GROUP_NUMBER"); - OrgNumber = GetEnvValue(env, "CERTINEXT_ORG_NUMBER"); - ProductCode = GetEnvValue(env, "CERTINEXT_PRODUCT_CODE"); - RequestorEmail = GetEnvValue(env, "CERTINEXT_REQUESTOR_EMAIL"); - RequestorName = GetEnvValue(env, "CERTINEXT_REQUESTOR_NAME"); - - CloudflareApiToken = GetEnvValue(env, "CERTINEXT_CF_API_TOKEN"); - CloudflareZoneId = GetEnvValue(env, "CERTINEXT_CF_ZONE_ID"); + CloudflareApiToken = GetEnvValue(env, CloudflareApiTokenKey); + CloudflareZoneId = GetEnvValue(env, CloudflareZoneIdKey); IsCloudflareConfigured = !string.IsNullOrWhiteSpace(CloudflareApiToken) && !string.IsNullOrWhiteSpace(CloudflareZoneId); IsConfigured = !string.IsNullOrWhiteSpace(ApiUrl) && !string.IsNullOrWhiteSpace(AccessKey); + // Fail fast (before promoting anything into process env and before any + // client/network call) when a V2 base URL has leaked into the V1 fixture. Only + // checked when the fixture would otherwise be configured, so an unconfigured run + // still skips cleanly. + if (IsConfigured) + EnsureV1ApiUrl(ApiUrl, + fromProcessEnvironment: System.Environment.GetEnvironmentVariable(ApiUrlKey) != null); + + // Promote env-file values into the process environment so that any code + // calling System.Environment.GetEnvironmentVariable() picks them up. + // Opt-in destructive-test flags are deliberately excluded: they must be + // set explicitly in the shell so a developer who leaves them in the file + // does not accidentally arm bulk/mutating tests on every bare `dotnet test`. + foreach (var kv in env) + if (System.Environment.GetEnvironmentVariable(kv.Key) == null + && !_optInOnlyFlags.Contains(kv.Key)) + System.Environment.SetEnvironmentVariable(kv.Key, kv.Value); + if (IsConfigured) { Config = new CERTInextConfig @@ -141,8 +245,11 @@ public void Dispose() { } /// /// Reads a KEY=VALUE file, stripping blank lines and lines starting with '#'. /// Real environment variables overlay the file so CI overrides always win. + /// defaults to the real process environment; unit + /// tests pass their own so they never have to mutate shared process state. /// - private static Dictionary LoadEnvFile(string path) + internal static Dictionary LoadEnvFile( + string path, System.Collections.IDictionary processEnvironment = null) { var result = new Dictionary(StringComparer.OrdinalIgnoreCase); @@ -165,7 +272,8 @@ private static Dictionary LoadEnvFile(string path) } // Real environment variables take precedence over the file - foreach (System.Collections.DictionaryEntry de in System.Environment.GetEnvironmentVariables()) + foreach (System.Collections.DictionaryEntry de in + processEnvironment ?? System.Environment.GetEnvironmentVariables()) { string k = de.Key?.ToString(); string v = de.Value?.ToString(); @@ -198,6 +306,36 @@ internal static string ParseEnvValue(string rawValue) return val; } + /// + /// Throws when lacks + /// the V1 , i.e. a V2 base URL has leaked into the V1 + /// fixture. Left unchecked, every V1 call 404s and surfaces as a misleading + /// "unrecognised error body". The message names the key and where it came from, and + /// shows only scheme/host/path — never credentials, userinfo, or query strings. + /// Exposed internal for direct unit-testing. + /// + internal static void EnsureV1ApiUrl(string apiUrl, bool fromProcessEnvironment) + { + if (string.IsNullOrWhiteSpace(apiUrl) || + apiUrl.IndexOf(V1ApiPathSegment, StringComparison.OrdinalIgnoreCase) >= 0) + return; + + string shown = Uri.TryCreate(apiUrl.Trim(), UriKind.Absolute, out Uri uri) + ? $"{uri.Scheme}://{uri.Authority}{uri.AbsolutePath}" + : "(not an absolute URL)"; + string source = fromProcessEnvironment + ? "the process environment (real env vars override ~/.env_certinext)" + : "~/.env_certinext"; + + throw new InvalidOperationException( + $"IntegrationTestFixture: {ApiUrlKey} resolved to '{shown}' (from {source}), which lacks " + + $"the V1 path segment '{V1ApiPathSegment}'. This looks like a CERTInext V2 base URL leaking " + + "into the V1 fixture; V1 calls against it fail with 'unrecognised error body'. " + + "Source only ~/.env_certinext into the shell (set -a; . ~/.env_certinext; set +a), never " + + "~/.env_certinext_v2 — the V2 tests read that file from disk themselves. In an already-" + + $"polluted shell, run 'unset {ApiUrlKey}' or open a fresh shell."); + } + private static string GetEnvValue(Dictionary env, string key) { return env.TryGetValue(key, out string val) ? val : string.Empty; diff --git a/CERTInext.IntegrationTests/KfclabCsrEmitterTests.cs b/CERTInext.IntegrationTests/KfclabCsrEmitterTests.cs new file mode 100644 index 0000000..159cb8f --- /dev/null +++ b/CERTInext.IntegrationTests/KfclabCsrEmitterTests.cs @@ -0,0 +1,82 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// At http://www.apache.org/licenses/LICENSE-2.0 +// +// Utility: emit BouncyCastle-generated PKCS#10 CSRs (CN + DNS SANs) to disk for manual +// Command-driven lab enrollments (e.g. Command Reissue via /Enrollment/CSR, UCC multi-SAN +// checks). Makes no CA calls. Opt-in: set CERTINEXT_EMIT_CSR_DIR (output directory) and +// CERTINEXT_EMIT_CSR_SPEC, a ';'-separated list of "=[,...]". +// The CN is always included as the first DNS SAN. +// +// Example: +// CERTINEXT_EMIT_CSR_DIR=/tmp/csrs \ +// CERTINEXT_EMIT_CSR_SPEC="reissue=a.example.com;ucc=b.example.com,c.example.com" \ +// dotnet test --filter FullyQualifiedName~KfclabCsrEmitterTests + +using System; +using System.Collections.Generic; +using System.IO; +using System.Linq; +using Org.BouncyCastle.Asn1; +using Org.BouncyCastle.Asn1.Pkcs; +using Org.BouncyCastle.Asn1.X509; +using Org.BouncyCastle.Crypto; +using Org.BouncyCastle.Crypto.Generators; +using Org.BouncyCastle.Pkcs; +using Org.BouncyCastle.Security; +using Xunit; +using Xunit.Abstractions; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.IntegrationTests +{ + public class KfclabCsrEmitterTests + { + private readonly ITestOutputHelper _out; + + public KfclabCsrEmitterTests(ITestOutputHelper output) + { + _out = output; + } + + private static string GenerateCsrPem(string cn, IReadOnlyList dnsSans) + { + var keyGen = new RsaKeyPairGenerator(); + keyGen.Init(new KeyGenerationParameters(new SecureRandom(), 2048)); + var kp = keyGen.GenerateKeyPair(); + + var names = new GeneralNames(dnsSans.Select(s => new GeneralName(GeneralName.DnsName, s)).ToArray()); + var extGen = new X509ExtensionsGenerator(); + extGen.AddExtension(X509Extensions.SubjectAlternativeName, false, names); + var attrs = new DerSet(new AttributePkcs( + PkcsObjectIdentifiers.Pkcs9AtExtensionRequest, new DerSet(extGen.Generate()))); + + var csr = new Pkcs10CertificationRequest( + "SHA256withRSA", new X509Name($"CN={cn}"), kp.Public, attrs, kp.Private); + return "-----BEGIN CERTIFICATE REQUEST-----\n" + + Convert.ToBase64String(csr.GetEncoded(), Base64FormattingOptions.InsertLineBreaks) + + "\n-----END CERTIFICATE REQUEST-----\n"; + } + + [SkippableFact] + public void EmitCsrs() + { + string dir = Environment.GetEnvironmentVariable("CERTINEXT_EMIT_CSR_DIR"); + string spec = Environment.GetEnvironmentVariable("CERTINEXT_EMIT_CSR_SPEC"); + Skip.If(string.IsNullOrWhiteSpace(dir) || string.IsNullOrWhiteSpace(spec), + "Set CERTINEXT_EMIT_CSR_DIR and CERTINEXT_EMIT_CSR_SPEC to emit CSRs."); + + Directory.CreateDirectory(dir); + foreach (string entry in spec.Split(';', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries)) + { + string[] kv = entry.Split('=', 2); + Assert.True(kv.Length == 2, $"Bad CSR spec entry '{entry}' (expected =[,...])."); + string[] hosts = kv[1].Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries); + Assert.NotEmpty(hosts); + + string path = Path.Combine(dir, kv[0] + ".csr"); + File.WriteAllText(path, GenerateCsrPem(hosts[0], hosts)); + _out.WriteLine($"{path}: CN={hosts[0]} SANs={string.Join(",", hosts)}"); + } + } + } +} diff --git a/CERTInext.IntegrationTests/OrderDateFormatProbeTests.cs b/CERTInext.IntegrationTests/OrderDateFormatProbeTests.cs new file mode 100644 index 0000000..713d61e --- /dev/null +++ b/CERTInext.IntegrationTests/OrderDateFormatProbeTests.cs @@ -0,0 +1,60 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System.Collections.Generic; +using System.Linq; +using System.Text.RegularExpressions; +using System.Threading; +using System.Threading.Tasks; +using Xunit; +using Xunit.Abstractions; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.IntegrationTests +{ + /// + /// Read-only guard (issue 0090, V1 sync hold-back): GetOrderReport's per-row orderDate + /// must stay "yyyy-MM-dd HH:mm:ss" (whole seconds, no zone marker; read as UTC, verified + /// 2026-10-15 against plugin and gateway UTC log timestamps). The sync hold-back measures an + /// order's age from it. No orders are created. + /// + public class OrderDateFormatProbeTests : IClassFixture + { + private readonly IntegrationTestFixture _fixture; + private readonly ITestOutputHelper _output; + + public OrderDateFormatProbeTests(IntegrationTestFixture fixture, ITestOutputHelper output) + { + _fixture = fixture; + _output = output; + } + + [SkippableFact] + public async Task GetOrderReport_OrderDate_IsSecondPrecisionWithoutZoneMarker() + { + IntegrationSkip.IfNotConfigured(_fixture); + + var shapes = new Dictionary(); + int total = 0; + await foreach (var entry in _fixture.Client.ListOrdersAsync( + orderDateFrom: null, pageSize: 100, ct: CancellationToken.None)) + { + total++; + // Digits masked so the output records the wire shape, not the data. + string shape = Regex.Replace(entry.OrderDate ?? "(null)", @"\d", "9"); + shapes[shape] = shapes.TryGetValue(shape, out var n) ? n + 1 : 1; + if (total >= 300) break; + } + + _output.WriteLine($"rows={total}"); + foreach (var kv in shapes.OrderByDescending(k => k.Value)) + _output.WriteLine($"orderDate shape '{kv.Key}' x{kv.Value}"); + + Skip.If(total == 0, "account has no orders"); + Assert.All(shapes.Keys, k => Assert.Equal("9999-99-99 99:99:99", k)); + } + } +} diff --git a/CERTInext.IntegrationTests/PendingDvDiagnosticsTests.cs b/CERTInext.IntegrationTests/PendingDvDiagnosticsTests.cs new file mode 100644 index 0000000..49fa064 --- /dev/null +++ b/CERTInext.IntegrationTests/PendingDvDiagnosticsTests.cs @@ -0,0 +1,123 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// At http://www.apache.org/licenses/LICENSE-2.0 +// +// Read-only diagnostic for pending-DV orders that won't advance through sync-DCV. +// For each "orderId|domain" pair in CERTINEXT_DIAG_ORDER_IDS (comma-separated), it +// dumps the TrackOrder DCV state and probes GetDcv to determine whether CERTInext +// has actually exposed a DCV challenge for the order — the question that decides +// whether the plugin's deferred-DCV retry can ever complete it. +// +// Run: +// export CERTINEXT_DIAG_ORDER_IDS="9937569678|bulk-0b3cbd54.scrup.org,6373633518|bulk-49818a84.scrup.org" +// dotnet test --filter FullyQualifiedName~PendingDvDiagnostics + +using System; +using System.Linq; +using System.Threading; +using System.Threading.Tasks; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Xunit; +using Xunit.Abstractions; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.IntegrationTests +{ + public class PendingDvDiagnosticsTests : IClassFixture + { + private readonly IntegrationTestFixture _fixture; + private readonly ITestOutputHelper _out; + + public PendingDvDiagnosticsTests(IntegrationTestFixture fixture, ITestOutputHelper output) + { + _fixture = fixture; + _out = output; + } + + [SkippableFact] + public async Task PendingDvDiagnostics_DumpDcvState() + { + IntegrationSkip.IfNotConfigured(_fixture); + + string raw = Environment.GetEnvironmentVariable("CERTINEXT_DIAG_ORDER_IDS"); + Skip.If(string.IsNullOrWhiteSpace(raw), + "Set CERTINEXT_DIAG_ORDER_IDS=\"orderId|domain,orderId|domain,...\" to run the diagnostic."); + + var pairs = raw.Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries) + .Select(p => + { + var bits = p.Split('|', 2); + return (Id: bits[0].Trim(), Domain: bits.Length > 1 ? bits[1].Trim() : null); + }) + .ToList(); + + var ct = CancellationToken.None; + int challengeReady = 0, challengeNotReady = 0, alreadyValidated = 0, errored = 0; + + foreach (var (id, domain) in pairs) + { + _out.WriteLine($"==================== Order {id} ({domain ?? "?"}) ===================="); + ICERTInextClient client = _fixture.Client; + + try + { + var track = await client.TrackOrderAsync(id, ct); + var od = track.OrderDetails; + _out.WriteLine($" OrderStatus: {od?.OrderStatus} (id={od?.OrderStatusId})"); + _out.WriteLine($" CertStatus: {od?.CertificateStatus} (id={od?.CertificateStatusId})"); + + var dv = od?.DomainVerification; + if (dv == null) + { + _out.WriteLine(" DomainVerification: (CERTInext has NOT exposed a DCV challenge slot)"); + } + else + { + _out.WriteLine($" DomainVerification.status: '{dv.Status}' (0=Pending,1=Validated,2=Rejected)"); + var entries = dv.GetDomainEntries(); + if (entries.Count == 0) + _out.WriteLine(" per-domain entries: "); + foreach (var kv in entries) + _out.WriteLine( + $" [{kv.Key}] dcvMethod='{kv.Value.DcvMethod}' dcvStatus='{kv.Value.DcvStatus}' " + + $"status='{kv.Value.Status}' caaStatus='{kv.Value.CaaStatus}' verifiedDate='{kv.Value.VerifiedDate}'"); + + if (dv.Status == Constants.Dcv.StatusValidated || + entries.Values.All(e => e.DcvStatus == Constants.Dcv.StatusValidated)) + alreadyValidated++; + } + + // Probe GetDcv — the decisive test: does CERTInext hand back a challenge token? + if (!string.IsNullOrWhiteSpace(domain)) + { + try + { + var dcv = await client.GetDcvAsync(id, domain, Constants.Dcv.MethodDnsTxt, ct); + bool tokenPresent = !string.IsNullOrWhiteSpace(dcv.DcvDetails?.Token); + _out.WriteLine($" GetDcv: tokenPresent={tokenPresent}"); + if (tokenPresent) challengeReady++; + } + catch (Exception gex) + { + _out.WriteLine($" GetDcv: FAILED -> {gex.Message}"); + if (gex.Message.Contains("956", StringComparison.OrdinalIgnoreCase) || + gex.Message.Contains("not ready", StringComparison.OrdinalIgnoreCase)) + challengeNotReady++; + else + errored++; + } + } + } + catch (Exception ex) + { + _out.WriteLine($" TrackOrder FAILED: {ex.Message}"); + errored++; + } + } + + _out.WriteLine(""); + _out.WriteLine($"=== SUMMARY over {pairs.Count} orders: " + + $"challengeReady={challengeReady}, challengeNotReady={challengeNotReady}, " + + $"alreadyValidated={alreadyValidated}, errored={errored} ==="); + } + } +} diff --git a/CERTInext.IntegrationTests/PrivatePkiV2LiveTests.cs b/CERTInext.IntegrationTests/PrivatePkiV2LiveTests.cs new file mode 100644 index 0000000..ad8aa96 --- /dev/null +++ b/CERTInext.IntegrationTests/PrivatePkiV2LiveTests.cs @@ -0,0 +1,474 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Generic; +using System.Linq; +using System.Net; +using System.Reflection; +using System.Runtime.ExceptionServices; +using System.Text.Json; +using System.Text.RegularExpressions; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Org.BouncyCastle.Asn1; +using Org.BouncyCastle.Asn1.Pkcs; +using Org.BouncyCastle.Asn1.X509; +using Org.BouncyCastle.Crypto; +using Org.BouncyCastle.Crypto.Generators; +using Org.BouncyCastle.Pkcs; +using Org.BouncyCastle.Security; +using Org.BouncyCastle.X509; +using Org.BouncyCastle.X509.Extension; +using Xunit; +using Xunit.Abstractions; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.IntegrationTests +{ + /// + /// Opt-in live verification of the V2 private-pki enrollment path end to end through + /// the real plugin surface: plugin.Enroll with + /// ProductFamily=private-pki / ProductVariant=intranet-ssl against the CERTInext + /// sandbox, then plugin.Revoke (CRL reason 4, superseded) in cleanup. + /// + /// PLACES EXACTLY ONE REAL ORDER. Gated behind CERTINEXT_PRIVATE_PKI_LIVE=1, which must be + /// exported in the shell (it is read from the process environment before the V2 env file is + /// promoted). Skips with no network calls when the flag or the V2 OAuth2 credentials are absent. + /// No retries anywhere: a thrown or FAILED enroll is reported, never re-attempted. + /// + /// Env: + /// CERTINEXT_PRIVATE_PKI_LIVE=1 required opt-in + /// CERTINEXT_PRIVATE_PKI_PRODUCT_CODE default 149 (Sandbox emSign Intranet SSL 1 Year) + /// CERTINEXT_PRIVATE_PKI_CN default pki0033-<UTC MMddHHmm>.intranet.lab + /// V2 creds (CERTINEXT_API_URL / CERTINEXT_CLIENT_ID / CERTINEXT_CLIENT_SECRET) are loaded + /// from ~/.env_certinext_v2 by , same as . + /// + [Collection(PrivatePkiV2LiveCollection.Name)] + public class PrivatePkiV2LiveTests : IClassFixture + { + private const string OptInFlag = "CERTINEXT_PRIVATE_PKI_LIVE"; + private const string IpSan = "10.0.0.50"; + + private readonly IntegrationTestFixture _fixture; + private readonly ITestOutputHelper _output; + + private readonly bool _optedIn; + private readonly string _v2ApiUrl; + private readonly string _v2ClientId; + private readonly string _v2ClientSecret; + private readonly string _productCode; + private readonly string _cnOverride; + private readonly bool _v2CredsPresent; + + public PrivatePkiV2LiveTests(IntegrationTestFixture fixture, ITestOutputHelper output) + { + _fixture = fixture; + _output = output; + + // Read the opt-in flag from the real process environment BEFORE promoting the V2 env + // file, so leaving the flag in ~/.env_certinext_v2 cannot arm this order-placing test. + _optedIn = Environment.GetEnvironmentVariable(OptInFlag)?.Trim() == "1"; + + var env = V2EnvHelper.LoadAndPromote(); + _v2ApiUrl = V2EnvHelper.GetEnv(env, "CERTINEXT_API_URL"); + _v2ClientId = V2EnvHelper.GetEnv(env, "CERTINEXT_CLIENT_ID"); + _v2ClientSecret = V2EnvHelper.GetEnv(env, "CERTINEXT_CLIENT_SECRET"); + _productCode = V2EnvHelper.GetEnv(env, "CERTINEXT_PRIVATE_PKI_PRODUCT_CODE", "149"); + _cnOverride = V2EnvHelper.GetEnv(env, "CERTINEXT_PRIVATE_PKI_CN"); + + _v2CredsPresent = !string.IsNullOrWhiteSpace(_v2ApiUrl) + && !string.IsNullOrWhiteSpace(_v2ClientId) + && !string.IsNullOrWhiteSpace(_v2ClientSecret); + } + + /// + /// V2 config for the private-pki order: mirrors V2LifecycleTests.BuildV2Config (V2 + /// mode, no V1-only fields, requestor placeholders) with DCV disabled. Private PKI has no DCV + /// anyway; disabling it keeps the no-DCV and DCV builds on the same path. + /// + private CERTInextConfig BuildV2Config() => new CERTInextConfig + { + ApiUrl = _v2ApiUrl, + UseV2Api = true, + V2InlineCsr = V2EnvHelper.InlineCsrFromEnv, // default single-call; CERTINEXT_V2_INLINE_CSR=0 selects two-call + OAuthClientId = _v2ClientId, + OAuthClientSecret = _v2ClientSecret, + + RequestorName = _fixture.IsConfigured ? _fixture.Config.RequestorName : "Keyfactor Test", + RequestorEmail = _fixture.IsConfigured ? _fixture.Config.RequestorEmail : "test@example.com", + RequestorIsdCode = "1", + RequestorMobileNumber = "0000000000", + SignerPlace = "Gateway Lab", + SignerIp = "127.0.0.1", + PageSize = 100, + + DcvEnabled = false + }; + + /// + /// BouncyCastle-only RSA-2048 PKCS#10 CSR with a SAN extension request. Same construction as + /// KfclabCsrEmitterTests.GenerateCsrPem (which is private and DNS-only), extended to + /// carry IP SANs. + /// + private static string GenerateCsrPem(string cn, IReadOnlyList dnsSans, IReadOnlyList ipSans) + { + var keyGen = new RsaKeyPairGenerator(); + keyGen.Init(new KeyGenerationParameters(new SecureRandom(), 2048)); + var kp = keyGen.GenerateKeyPair(); + + var generalNames = dnsSans.Select(d => new GeneralName(GeneralName.DnsName, d)) + .Concat(ipSans.Select(ip => new GeneralName(GeneralName.IPAddress, ip))) + .ToArray(); + var extGen = new X509ExtensionsGenerator(); + extGen.AddExtension(X509Extensions.SubjectAlternativeName, false, new GeneralNames(generalNames)); + var attrs = new DerSet(new AttributePkcs( + PkcsObjectIdentifiers.Pkcs9AtExtensionRequest, new DerSet(extGen.Generate()))); + + var csr = new Pkcs10CertificationRequest( + "SHA256withRSA", new X509Name($"CN={cn}"), kp.Public, attrs, kp.Private); + return "-----BEGIN CERTIFICATE REQUEST-----\n" + + Convert.ToBase64String(csr.GetEncoded(), Base64FormattingOptions.InsertLineBreaks) + + "\n-----END CERTIFICATE REQUEST-----\n"; + } + + /// Parses the first (leaf) PEM block of a possibly chained PEM string. + private static X509Certificate ParseLeaf(string pem) + { + var m = Regex.Match(pem ?? string.Empty, + @"-----BEGIN CERTIFICATE-----(.*?)-----END CERTIFICATE-----", RegexOptions.Singleline); + if (!m.Success) return null; + string b64 = m.Groups[1].Value.Replace("\r", string.Empty).Replace("\n", string.Empty).Trim(); + return new X509CertificateParser().ReadCertificate(Convert.FromBase64String(b64)); + } + + /// SAN entries as ("dns"|"ip"|"other:<tag>", value), read with BouncyCastle. + private static List<(string Type, string Value)> ReadSans(X509Certificate cert) + { + var result = new List<(string, string)>(); + var ext = cert.GetExtensionValue(X509Extensions.SubjectAlternativeName); + if (ext == null) return result; + + var names = GeneralNames.GetInstance(X509ExtensionUtilities.FromExtensionValue(ext)); + foreach (var gn in names.GetNames()) + { + switch (gn.TagNo) + { + case GeneralName.DnsName: + result.Add(("dns", DerIA5String.GetInstance(gn.Name).GetString())); + break; + case GeneralName.IPAddress: + // IPAddress parses raw octets only (no crypto) — not a BCL-crypto dependency. + result.Add(("ip", new IPAddress(Asn1OctetString.GetInstance(gn.Name).GetOctets()).ToString())); + break; + default: + result.Add(($"other:{gn.TagNo}", gn.Name.ToString())); + break; + } + } + return result; + } + + [SkippableFact] + public async Task PrivatePki_V2_EnrollIntranetSsl_ThenRevoke_Live() + { + Skip.If(!_optedIn, + $"{OptInFlag} is not set to 1 — this test places ONE real private-pki order; skipping (no network calls)."); + Skip.If(!_v2CredsPresent, + "V2 OAuth2 credentials (CERTINEXT_API_URL / CERTINEXT_CLIENT_ID / CERTINEXT_CLIENT_SECRET) not configured — skipping (no network calls)."); + + string cn = string.IsNullOrWhiteSpace(_cnOverride) + ? $"pki0033-{DateTime.UtcNow:MMddHHmm}.intranet.lab" + : _cnOverride.Trim(); + + var config = BuildV2Config(); + var realClient = new CERTInextClient(config); + // Pass-through proxy around the real client: records the order id the moment + // PlaceOrderV2Async returns, so cleanup still knows the order if a later step inside + // Enroll (track, download) throws before an EnrollmentResult exists. The CSR goes inline on the create call. + var recorder = OrderIdRecordingClientProxy.Wrap(realClient, out ICERTInextClient proxiedClient); + var plugin = new CERTInextCAPlugin(proxiedClient, config); + + var productInfo = new EnrollmentProductInfo + { + ProductID = _productCode, + ProductParameters = new Dictionary + { + [Constants.EnrollmentParam.ProductFamily] = "private-pki", + [Constants.EnrollmentParam.ProductVariant] = Constants.ApiV2.PrivatePkiVariantIntranetSsl, + [Constants.EnrollmentParam.ProductCode] = _productCode, + } + }; + // Gateway SAN dictionary exactly as Command sends it ("dnsname" / "ipaddress" keys). + var san = new Dictionary + { + ["dnsname"] = new[] { cn }, + ["ipaddress"] = new[] { IpSan }, + }; + + _output.WriteLine("=== private-pki live enrollment (ONE order, no retries) ==="); + _output.WriteLine($"Family=private-pki, Variant={Constants.ApiV2.PrivatePkiVariantIntranetSsl}, ProductCode={_productCode}"); + _output.WriteLine($"CN={cn}, SANs: dnsname=[{cn}], ipaddress=[{IpSan}]"); + + string orderId = null; + // Set only once Enroll returned GENERATED with a certificate body; cleanup revokes an + // issued order and cancels anything else. + bool issued = false; + try + { + EnrollmentResult result = null; + Exception enrollEx = null; + try + { + result = await plugin.Enroll( + csr: GenerateCsrPem(cn, new[] { cn }, new[] { IpSan }), + subject: $"CN={cn}", + san: san, + productInfo: productInfo, + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + } + catch (Exception ex) + { + enrollEx = ex; + } + + orderId = !string.IsNullOrWhiteSpace(result?.CARequestID) ? result.CARequestID : recorder.PlacedOrderId; + + // Order id first — before anything below that can fail. + _output.WriteLine($"CARequestID (order id): {orderId ?? ""}"); + _output.WriteLine($" (recorded from PlaceOrderV2Async: {recorder.PlacedOrderId ?? ""}, " + + $"initial CA status: {recorder.PlacedOrderStatus ?? ""})"); + + if (enrollEx != null) + { + _output.WriteLine($"Enroll THREW {enrollEx.GetType().Name}: {enrollEx.Message}"); + _output.WriteLine("Not retrying. NOTE: a client-side timeout does not prove no order exists — if the " + + "order id above is , check the CERTInext portal for a private-pki order " + + $"with hostname '{cn}'."); + ExceptionDispatchInfo.Capture(enrollEx).Throw(); + } + + if (result == null) + { + _output.WriteLine("Enroll returned a null EnrollmentResult. Not retrying."); + Assert.Fail("private-pki Enroll returned a null EnrollmentResult."); + return; // unreachable + } + + _output.WriteLine($"Enroll status: {result.Status} ({(EndEntityStatus)result.Status})"); + _output.WriteLine($"Enroll message: {result.StatusMessage}"); + + if (result.Status == (int)EndEntityStatus.FAILED) + { + _output.WriteLine("Enroll returned FAILED. Not retrying; no further order will be placed."); + Assert.Fail($"private-pki Enroll returned FAILED: {result.StatusMessage}"); + } + + if (result.Status != (int)EndEntityStatus.GENERATED || string.IsNullOrWhiteSpace(result.Certificate)) + { + _output.WriteLine($"Order {orderId} is still pending (not issued within the plugin's pickup poll). " + + "Not polling further; cleanup below will cancel it once and otherwise print " + + "manual-cleanup instructions."); + Assert.Fail($"INCONCLUSIVE: private-pki order '{orderId}' did not issue within the pickup poll " + + $"(status {result.Status}); end-to-end issuance not verified."); + } + + issued = true; + var leaf = ParseLeaf(result.Certificate); + leaf.Should().NotBeNull("the GENERATED result must carry a parseable leaf certificate PEM"); + + var sans = ReadSans(leaf); + _output.WriteLine($"Issued subject: {leaf.SubjectDN}"); + _output.WriteLine($"Issued issuer: {leaf.IssuerDN}"); + _output.WriteLine($"Issued serial: {leaf.SerialNumber.ToString(16).ToUpperInvariant()}"); + _output.WriteLine($"Issued SANs: [{string.Join(", ", sans.Select(s => $"{s.Type}:{s.Value}"))}]"); + _output.WriteLine($"Validity: {leaf.NotBefore:o} .. {leaf.NotAfter:o}"); + + sans.Should().Contain(s => s.Type == "ip" && s.Value == IpSan, + "the IP SAN submitted via additionalHosts must appear on the issued certificate"); + sans.Should().Contain(s => s.Type == "dns" && string.Equals(s.Value, cn, StringComparison.OrdinalIgnoreCase), + "the CN (sent as hostname) must appear as a DNS SAN on the issued certificate"); + } + finally + { + await CleanupAsync(plugin, realClient, orderId, cn, issued); + realClient.Dispose(); + } + } + + /// + /// Best-effort cleanup: exactly one cleanup action, never retried, never throwing (a cleanup + /// failure must not mask the test's own result). An issued order is revoked via + /// plugin.Revoke (CRL reason 4, superseded); any other order is cancelled via + /// on the private-pki family + /// (plugin.Revoke refuses non-issued orders). Manual-cleanup instructions are printed + /// only when that action fails. Finishes with one + /// read-only GET on the private-pki order. + /// + private async Task CleanupAsync(CERTInextCAPlugin plugin, CERTInextClient client, string orderId, string cn, bool issued) + { + _output.WriteLine("--- Cleanup ---"); + if (string.IsNullOrWhiteSpace(orderId)) + { + _output.WriteLine("No order id captured — nothing to revoke or cancel. If Enroll threw after sending the " + + $"create request, check the CERTInext portal for a private-pki order with hostname '{cn}'."); + return; + } + + bool cleanedUp = false; + if (issued) + { + try + { + int revokeResult = await plugin.Revoke(orderId, hexSerialNumber: string.Empty, revocationReason: 4 /* superseded */); + _output.WriteLine($"Revoke(order={orderId}, reason=4 superseded) returned {revokeResult} ({(EndEntityStatus)revokeResult})."); + cleanedUp = true; + } + catch (Exception ex) + { + _output.WriteLine($"Revoke FAILED for order {orderId}: {ex.GetType().Name}: {ex.Message}"); + } + } + else + { + try + { + var outcome = await client.CancelOrderV2Async( + Constants.ApiV2.FamilyPrivatePki, orderId, "Keyfactor plugin live test cleanup."); + _output.WriteLine($"CancelOrderV2Async(private-pki, order={orderId}) returned {outcome}" + + (outcome == V2CancelOrderOutcome.AlreadyTerminal + ? " (HTTP 422: already in a terminal state; nothing cancelled)." + : " (HTTP 2xx: order cancelled).")); + cleanedUp = outcome == V2CancelOrderOutcome.Cancelled; + } + catch (Exception ex) + { + _output.WriteLine($"Cancel FAILED for order {orderId}: {ex.GetType().Name}: {ex.Message}"); + } + } + + if (!cleanedUp) + { + _output.WriteLine("Not retrying. Unless the track below shows the order cancelled or revoked, MANUAL " + + "CLEANUP REQUIRED: in the CERTInext portal, cancel (if pending) or revoke (if issued) " + + $"order id {orderId}, product family private-pki " + + $"({Constants.ApiV2.PrivatePkiCertificatesPath}/{orderId})."); + } + + try + { + var (status, _, body) = await client.ProbeV2GetAsync($"{Constants.ApiV2.PrivatePkiCertificatesPath}/{orderId}"); + _output.WriteLine($"Post-cleanup track (read-only GET, private-pki): HTTP {status}, " + + $"status={Field(body, "status")}, certificateState={Field(body, "certificateState")}, " + + $"orderState={Field(body, "orderState")}, revocation.status={Field(body, "revocation", "status")}, " + + $"revocation.reason={Field(body, "revocation", "reason")}"); + } + catch (Exception ex) + { + _output.WriteLine($"Post-cleanup track failed (read-only; not retried): {ex.GetType().Name}: {ex.Message}"); + } + } + + /// Reads a (nested) string field from a JSON body; "<none>" when absent/unparseable. + private static string Field(string json, params string[] path) + { + if (string.IsNullOrWhiteSpace(json)) return ""; + try + { + using var doc = JsonDocument.Parse(json); + var el = doc.RootElement; + foreach (var p in path) + { + if (el.ValueKind != JsonValueKind.Object || !el.TryGetProperty(p, out el)) + return ""; + } + return el.ValueKind == JsonValueKind.String ? el.GetString() : el.ToString(); + } + catch (JsonException) + { + return ""; + } + } + + /// + /// Offline sanity check (no network): the recording proxy can be generated for + /// . A generation failure would otherwise only surface inside + /// the live test, after the opt-in. + /// + [Fact] + public void PrivatePki_V2_RecordingProxy_BuildsOffline() + { + using var client = new CERTInextClient(new CERTInextConfig { UseV2Api = true, ApiUrl = "https://invalid.example" }); + var recorder = OrderIdRecordingClientProxy.Wrap(client, out ICERTInextClient proxied); + proxied.Should().NotBeNull(); + recorder.PlacedOrderId.Should().BeNull(); + } + } + + /// + /// Pass-through over a real that + /// records the order id returned by any PlaceOrderV2Async overload. Changes no behavior: + /// every call is forwarded unchanged and its result/exception returned as-is. + /// + public class OrderIdRecordingClientProxy : DispatchProxy + { + private ICERTInextClient _inner; + + public string PlacedOrderId { get; private set; } + public string PlacedOrderStatus { get; private set; } + + public static OrderIdRecordingClientProxy Wrap(ICERTInextClient inner, out ICERTInextClient proxied) + { + proxied = Create(); + var recorder = (OrderIdRecordingClientProxy)(object)proxied; + recorder._inner = inner; + return recorder; + } + + protected override object Invoke(MethodInfo targetMethod, object[] args) + { + object result; + try + { + result = targetMethod.Invoke(_inner, args); + } + catch (TargetInvocationException tie) when (tie.InnerException != null) + { + ExceptionDispatchInfo.Capture(tie.InnerException).Throw(); + throw; // unreachable + } + + if (targetMethod.Name == nameof(ICERTInextClient.PlaceOrderV2Async) + && result is Task placeTask) + return RecordAsync(placeTask); + + return result; + } + + private async Task RecordAsync(Task placeTask) + { + var resp = await placeTask; + PlacedOrderId = resp?.OrderId; + PlacedOrderStatus = resp?.Status; + return resp; + } + } + + /// + /// Runs alone: its constructor promotes ~/.env_certinext_v2 + /// into process env (). + /// + [CollectionDefinition(Name, DisableParallelization = true)] + public sealed class PrivatePkiV2LiveCollection + { + public const string Name = "PrivatePkiV2Live-NoParallel"; + } +} diff --git a/CERTInext.IntegrationTests/ProductTests.cs b/CERTInext.IntegrationTests/ProductTests.cs index 99f45f3..6ea9b88 100644 --- a/CERTInext.IntegrationTests/ProductTests.cs +++ b/CERTInext.IntegrationTests/ProductTests.cs @@ -2,11 +2,13 @@ // Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. // At http://www.apache.org/licenses/LICENSE-2.0 +using System; using System.Collections.Generic; using System.Linq; using System.Threading; using System.Threading.Tasks; using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; using Keyfactor.Extensions.CAPlugin.CERTInext.API; using Xunit; @@ -73,5 +75,40 @@ await act.Should().NotThrowAsync( "in the account's product list when GetProductDetails returns results"); } } + + /// + /// Drives + /// + /// (not just the client method) through the plugin, the same path AnyGatewayREST's + /// ConfigurationValidator exercises when a template is saved. V1 mode (the + /// default, UseV2Api unset) must be unaffected by V2-specific validation paths. + /// + [SkippableFact] + public async Task ValidateProductInfo_V1_AcceptsConfiguredProductCode() + { + IntegrationSkip.IfNotConfigured(_fixture); + Skip.If(string.IsNullOrWhiteSpace(_fixture.ProductCode), + "CERTINEXT_PRODUCT_CODE not set — cannot assert against a real product code."); + + var plugin = new Keyfactor.Extensions.CAPlugin.CERTInext.CERTInextCAPlugin(); + var connectionInfo = new Dictionary + { + ["ApiUrl"] = _fixture.ApiUrl, + ["AuthMode"] = "AccessKey", + ["ApiKey"] = _fixture.AccessKey, + ["AccountNumber"] = _fixture.AccountNumber, + ["GroupNumber"] = _fixture.GroupNumber + }; + var productInfo = new EnrollmentProductInfo + { + ProductID = "ssl", + ProductParameters = new Dictionary { ["ProductCode"] = _fixture.ProductCode } + }; + + Func act = () => plugin.ValidateProductInfo(productInfo, connectionInfo); + + await act.Should().NotThrowAsync( + $"configured product code \"{_fixture.ProductCode}\" should validate in V1 mode"); + } } } diff --git a/CERTInext.IntegrationTests/RecordingDomainValidator.cs b/CERTInext.IntegrationTests/RecordingDomainValidator.cs new file mode 100644 index 0000000..4ecaeac --- /dev/null +++ b/CERTInext.IntegrationTests/RecordingDomainValidator.cs @@ -0,0 +1,94 @@ +// Copyright 2026 Keyfactor +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Linq; +using System.Threading; +using System.Threading.Tasks; +using Keyfactor.AnyGateway.Extensions; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.IntegrationTests +{ + /// + /// spy that wraps a real (Cloudflare or stub) validator + /// and records every StageValidation/CleanupValidation call, including the + /// FQDN and staged value, so DCV-on tests can assert whether the plugin actually staged + /// a TXT record rather than just asserting that Enroll did not throw. + /// + internal sealed class RecordingDomainValidator : IDomainValidator + { + private readonly IDomainValidator _inner; + private readonly ConcurrentQueue<(string Fqdn, string Value)> _staged = new(); + private readonly ConcurrentQueue _cleanedUp = new(); + + public RecordingDomainValidator(IDomainValidator inner) + { + _inner = inner; + } + + public IReadOnlyList<(string Fqdn, string Value)> StagedCalls => _staged.ToList(); + public IReadOnlyList CleanedUpFqdns => _cleanedUp.ToList(); + + public void Initialize(IDomainValidatorConfigProvider configProvider) => _inner.Initialize(configProvider); + + public async Task StageValidation(string key, string value, CancellationToken cancellationToken) + { + _staged.Enqueue((key, value)); + return await _inner.StageValidation(key, value, cancellationToken); + } + + public async Task CleanupValidation(string key, CancellationToken cancellationToken) + { + _cleanedUp.Enqueue(key); + return await _inner.CleanupValidation(key, cancellationToken); + } + + public Task ValidateConfiguration(Dictionary configuration) => _inner.ValidateConfiguration(configuration); + public Dictionary GetDomainValidatorAnnotations() => _inner.GetDomainValidatorAnnotations(); + public string GetValidationType() => _inner.GetValidationType(); + } + + /// + /// that wraps another factory and hands out + /// spies so tests can inspect what the plugin + /// actually did with the DNS provider, keyed by (domain, validationType). Does not own + /// disposal of the wrapped factory — callers that build a disposable inner factory + /// (e.g. CloudflareDomainValidatorFactory) remain responsible for disposing it. + /// + internal sealed class RecordingDomainValidatorFactory : IDomainValidatorFactory + { + private readonly IDomainValidatorFactory _inner; + private readonly ConcurrentDictionary _wrapped = new(); + + public RecordingDomainValidatorFactory(IDomainValidatorFactory inner) + { + _inner = inner; + } + + public IDomainValidator ResolveDomainValidator(string domain, string validationType) + { + string cacheKey = $"{domain}|{validationType}"; + return _wrapped.GetOrAdd(cacheKey, _ => new RecordingDomainValidator(_inner.ResolveDomainValidator(domain, validationType))); + } + + /// All StageValidation calls recorded across every domain resolved so far. + public IReadOnlyList<(string Fqdn, string Value)> StagedCalls => + _wrapped.Values.SelectMany(v => v.StagedCalls).ToList(); + + /// All CleanupValidation calls recorded across every domain resolved so far. + public IReadOnlyList CleanedUpFqdns => + _wrapped.Values.SelectMany(v => v.CleanedUpFqdns).ToList(); + } +} diff --git a/CERTInext.IntegrationTests/TESTING.md b/CERTInext.IntegrationTests/TESTING.md index b961130..e7a313b 100644 --- a/CERTInext.IntegrationTests/TESTING.md +++ b/CERTInext.IntegrationTests/TESTING.md @@ -1,194 +1,126 @@ -# CERTInext Integration Tests +# CERTInext Integration Tests — Test Catalog -This project contains xUnit integration tests that exercise the CERTInext plugin against -the live CERTInext REST API. All tests skip automatically when credentials are absent, -so the project is safe to include in CI pipelines that do not have API access. +This page lists the tests in `CERTInext.IntegrationTests`, what each one checks, and what to expect +for a given account state. For credentials, opt-in flags, and run commands, see +[INTEGRATION_TESTING.md](INTEGRATION_TESTING.md). + +Every live test skips (is reported as Skipped, not Failed) when its credentials or opt-in flag are +absent. Tests marked **opt-in** place real orders, publish DNS records, or cancel orders, and run +only when their flag is exported in the shell. --- ## Product Codes Are Per-Account -**CERTInext product codes are provisioned per account by eMudhra.** The codes available -to your account are established when the account is created and may differ from any -documentation examples or from codes used by other accounts. - -Key findings verified against sandbox account `9374221333` in April 2026: +CERTInext product codes are provisioned per account by eMudhra. The codes your account can order +are set when the account is created and can differ from documentation examples and from other +accounts. Notes that apply when choosing `CERTINEXT_PRODUCT_CODE`: -- `GetProductDetails` returns an empty list when called without `groupNumber` in the - `productDetails` block on some sandbox accounts. The plugin now passes `groupNumber` - automatically when `GroupNumber` is set in the connector config. -- The SSL/TLS product codes on this sandbox account are `842–851` (not `838–847` as on - the prior dev account). DV SSL is `842` on this account. -- Product code `100` (Private PKI / emSign Intranet SSL) is not provisioned on this - account — `GenerateOrderSSL` returns `EMS-1162: Invalid Product Code`. -- Product code `149` (Sandbox emSign Intranet SSL) appears in `GetProductDetails` for - this account but also returns `EMS-1162` when ordering — it is not usable for orders. -- EV SSL (codes `850`, `851`) requires an `organizationNumber` that is registered and - approved in CERTInext; using an unregistered org returns `EMS-1073: Invalid Organization Number`. -- The `GenerateOrderSSL` API requires `additionalInformation.remarks` in the request body. - Omitting it returns `EMS-918: Additional Information cannot be empty`. +- `GetProductDetails` returns an empty list on some sandbox accounts unless the request carries + `groupNumber`. The plugin sends it automatically when `GroupNumber` is configured. +- Private PKI codes (for example `100`, or `149` for the sandbox "emSign Intranet SSL") need a + separate entitlement. On an account without it, placing an order returns `EMS-1162: Invalid + Product Code` even when the code appears in the catalog. +- EV SSL needs a registered and approved `organizationNumber`; an unregistered one returns + `EMS-1073: Invalid Organization Number`. +- The V1 `GenerateOrderSSL` call requires `additionalInformation.remarks`; the plugin always sends it. -To discover the valid product codes for a new account, use: +To discover the codes your account accepts: ```sh make probe-products ``` -This places `saveAndHold=1` draft orders for all known SSL/TLS product codes and reports -which ones return a `requestNumber` (valid) vs. an error (invalid or not provisioned). - ---- - -## Prerequisites - -- .NET 8 or .NET 10 SDK -- Access to a CERTInext sandbox or production account -- An API Access Key generated in the CERTInext portal under **Integrations → APIs** - ---- - -## Credential Setup - -Create the file `~/.env_certinext` with the following content: - -```sh -# CERTInext API credentials -CERTINEXT_API_URL=https://sandbox-us-api.certinext.io/emSignHub-API -CERTINEXT_ACCESS_KEY=your-access-key-here -CERTINEXT_ACCOUNT_NUMBER=your-account-number -CERTINEXT_GROUP_NUMBER=your-group-number -CERTINEXT_ORG_NUMBER=your-org-number -CERTINEXT_PRODUCT_CODE=842 -CERTINEXT_REQUESTOR_EMAIL=you@example.com -CERTINEXT_REQUESTOR_NAME=Your Name -CERTINEXT_REQUESTOR_MOBILE=0000000000 -``` - -### Field reference - -| Variable | Required | Description | -|----------|----------|-------------| -| `CERTINEXT_API_URL` | Yes | Base URL of the CERTInext API (no trailing slash) | -| `CERTINEXT_ACCESS_KEY` | Yes | REST API Access Key from the CERTInext portal (Integrations → APIs) | -| `CERTINEXT_ACCOUNT_NUMBER` | Yes | Your CERTInext account number (numeric string) | -| `CERTINEXT_GROUP_NUMBER` | No | Group number for order placement, filtering, and `GetProductDetails`. Required on some sandbox accounts for `GetProductDetails` to return a non-empty list. | -| `CERTINEXT_ORG_NUMBER` | No | Organization number for OV/EV order placement | -| `CERTINEXT_PRODUCT_CODE` | Yes | Numeric product code for the target account. **This is per-account** — obtain the correct code for your account by calling `GetProductDetails` (or `make probe-products`). Default shown is for sandbox account `9374221333`. | -| `CERTINEXT_REQUESTOR_EMAIL` | Yes | Email submitted with test orders — must be registered in the account | -| `CERTINEXT_REQUESTOR_NAME` | Yes | Name submitted with test orders | -| `CERTINEXT_REQUESTOR_MOBILE` | No | Mobile number submitted with test orders | - -### API URL reference - -| Environment | URL | -|-------------|-----| -| Sandbox (US) | `https://sandbox-us-api.certinext.io/emSignHub-API` | -| Production (US) | `https://us-api.certinext.io/emSignHub-API` | -| Production (Global/India) | `https://api.certinext.io/emSignHub-API` | - -### Credential file format - -The file is parsed line by line: -- Lines starting with `#` are treated as comments and ignored. -- Blank lines are ignored. -- Each line must be in `KEY=VALUE` format. -- Values are not quoted — do not surround values with `"` or `'`. -- Real environment variables override file values (useful for CI injection). - ---- - -## Running the Tests - -### Build only - -```sh -dotnet build CERTInext.IntegrationTests/CERTInext.IntegrationTests.csproj --configuration Release -``` - -### Run all integration tests - -```sh -dotnet test CERTInext.IntegrationTests/CERTInext.IntegrationTests.csproj --configuration Release -v normal -``` - -### Run a single test class - -```sh -dotnet test CERTInext.IntegrationTests/ --filter "FullyQualifiedName~LifecycleTests" -v normal -``` - -### From the solution root (all tests including unit tests) - -```sh -dotnet test certinext-caplugin.sln --verbosity normal -``` - ---- - -## Skip Behaviour - -Each test calls `IntegrationSkip.IfNotConfigured(fixture)` at the top of the test method. -When `~/.env_certinext` is absent or either `CERTINEXT_API_URL` or `CERTINEXT_ACCESS_KEY` -is empty, every test is reported as **Skipped** rather than Failed. - -Some tests additionally skip when the account has no orders yet (e.g. on a fresh sandbox -account). These tests display a skip reason explaining that the account state does not -satisfy the test's pre-condition. +This places `saveAndHold=1` draft orders for the known SSL/TLS product codes and reports which return +a `requestNumber` (valid) and which return an error (invalid or not provisioned). --- ## Test Classes -### `ConnectivityTests` - -Verifies basic API reachability and credential validity. - -| Test | What it checks | -|------|---------------| -| `Ping_ReturnsSuccess` | Calls `ValidateCredentials`; asserts no exception is thrown | - -### `ProductTests` - -Verifies product discovery. - -| Test | What it checks | -|------|---------------| -| `GetProductDetails_ReturnsProducts` | Calls `GetProductDetails`; asserts the call succeeds without throwing; when products are returned, asserts the expected product code from `CERTINEXT_PRODUCT_CODE` is among them | - -Note: some CERTInext accounts return an empty list from `GetProductDetails` even though -orders using those product codes are visible in `GetOrderReport`. An empty list is -treated as acceptable — only the absence of an exception is mandatory. - -### `OrderReportTests` - -Exercises the `ListOrdersAsync` path used by `Synchronize`. Tests skip gracefully -when the account has no orders rather than failing. - -| Test | What it checks | -|------|---------------| -| `GetOrderReport_ReturnsOrders` | Fetches page 1; skips when account has no orders; otherwise asserts the list is non-empty | -| `GetOrderReport_AllOrders_HaveRequiredFields` | For each order on page 1: `requestNumber`, `productCode`, and `orderDate` are non-empty; skips when account has no orders | - -### `PluginSmokeTests` - -End-to-end tests exercising `CERTInextCAPlugin` via the `IAnyCAPlugin` interface with -a live `CERTInextClient` injected through the `(ICERTInextClient, CERTInextConfig)` -test constructor. - -| Test | What it checks | -|------|---------------| -| `Ping_ThroughPlugin_Succeeds` | Calls `IAnyCAPlugin.Ping()`; asserts no exception | -| `GetProductIds_ReturnsAtLeastOneProduct` | Calls `IAnyCAPlugin.GetProductIds()`; asserts a non-null list is returned without throwing | -| `Synchronize_ReturnsAtLeastOneRecord` | Runs a full sync; skips when account has no records; otherwise asserts at least one `AnyCAPluginCertificate` is produced | - -### `LifecycleTests` - -Full end-to-end lifecycle tests that create real orders against the configured CERTInext -account. These tests do not require any pre-existing account state. - -| Test | What it checks | -|------|---------------| -| `Enroll_Synchronize_Revoke_FullLifecycle` | (1) Generates a fresh RSA-2048 CSR; (2) calls `Enroll` and asserts a non-empty `CARequestID` is returned; (3) runs a full sync and asserts the new order appears by `CARequestID`; (4) attempts revocation — skips gracefully if the order is not yet in an issued/approved state | +### V1 — read-only and basic + +| Class | Test | What it checks | +|---|---|---| +| `ConnectivityTests` | `Ping_ReturnsSuccess` | `ValidateCredentials` succeeds | +| `ProductTests` | `GetProductDetails_ReturnsProducts` | `GetProductDetails` succeeds; when products come back, the configured product code is among them. An empty list is accepted, because some accounts return one | +| | `ValidateProductInfo_V1_AcceptsConfiguredProductCode` | `CERTInextCAPlugin.ValidateProductInfo` in V1 mode accepts `CERTINEXT_PRODUCT_CODE`; skips if it is unset | +| `OrderReportTests` | `GetOrderReport_ReturnsOrders` | Page 1 of `GetOrderReport` is non-empty; skips when the account has no orders | +| | `GetOrderReport_AllOrders_HaveRequiredFields` | Every order on page 1 has `requestNumber`, `productCode`, and `orderDate`; skips when the account has no orders | +| `PluginSmokeTests` | `Ping_ThroughPlugin_Succeeds` | `IAnyCAPlugin.Ping()` through a live client | +| | `GetProductIds_ReturnsAtLeastOneProduct` | `IAnyCAPlugin.GetProductIds()` returns a non-null list | +| | `Synchronize_ReturnsAtLeastOneRecord` | A full sync produces at least one record; skips when the account has none | +| `SmokeTests` | `Ping_Succeeds`, `GetProductDetails_ReturnsProducts`, `ListOrders_ReturnsFirstPage` | Client-level checks of the same endpoints | +| | `TrackOrder_ReturnsDetails`, `GetSingleRecord_ReturnsRecord` | Look up the order in `CERTINEXT_ORDER_ID`; skip when it is unset | +| | `GetSingleRecord_ForAllOrders_AllSucceed`, `Synchronize_DumpsAllRecords` | Read every order and write the results to the test output | + +### V1 — order lifecycle + +| Class | Test | What it checks | +|---|---|---| +| `LifecycleTests` | `Enroll_Synchronize_Revoke_FullLifecycle` | Generates an RSA-2048 CSR, enrolls it and asserts a `CARequestID`, runs a full sync and finds the new order, then attempts revocation. Skips gracefully if the order isn't issued yet | +| `AlgorithmMatrixTests` | `Csr_RoundTripsKeyAlgorithm` | Offline: each key algorithm in the matrix generates a CSR whose signature verifies and whose public key parses back to the same type and size | +| | `Enroll_AcceptsKeyAlgorithm` | **Opt-in** (`CERTINEXT_ALGO_MATRIX`). Submits one order per key algorithm and records whether CERTInext accepts it. CERTInext accepts RSA 2048/3072/4096 and ECC P-256/P-384, and rejects larger RSA, ECC P-521, and Ed25519/Ed448 | + +### V1 — DNS-01 DCV (need Cloudflare credentials unless noted) + +| Class | Test | What it checks | +|---|---|---| +| `DcvLifecycleTests` | `DcvEnroll_CompletesWithoutThrowing` | An enrollment with DCV enabled completes | +| | `EnrollWithoutDcv_DoesNotInvokeDnsProvider` | With DCV disabled, the DNS provider is never called | +| | `EnrollWithDcvOff_OrderAppearsInSync_PluginDidNotInvokeDcv` | An order placed with DCV off still appears in a full sync, and the plugin didn't run DCV | +| | `EnrollWithDcvOn_OrderIssuedEndToEnd_AndAppearsInSync` | Enroll with DCV on, issue the certificate, and find it in a sync | +| | `EnrollWithDcvOn_IssuesPerKeyAlgorithm` | **Opt-in** (`CERTINEXT_ALGO_MATRIX_DCV`). DCV issuance for each key algorithm | +| | `GetSingleRecord_DrivesDcvForPendingOrder` | Needs `CERTINEXT_PENDING_ORDER_ID`. A single-record refresh drives a pending order through DCV | +| | `BulkDvEnrollment_AllOrdersIssue_AndPaginationWorks` | **Opt-in** (`CERTINEXT_RUN_BULK_TEST`). Many concurrent DV enrollments all issue, and sync pagination returns them | +| | `CompleteAllPendingDvOrders` | **Opt-in** (`CERTINEXT_COMPLETE_PENDING`). Repeated full syncs until no DV order remains pending | +| | `FullSync_AllIssuedCerts_CarryParseableCertificateBody` | Every issued record from a full sync carries a parseable certificate | +| `PendingDvDiagnosticsTests` | `PendingDvDiagnostics_DumpDcvState` | Diagnostic. Needs `CERTINEXT_DIAG_ORDER_IDS`. Read-only dump of each listed order's DCV state | + +### V2 — API and lifecycle + +The V2 tests skip unless the V2 credentials are present (see [INTEGRATION_TESTING.md](INTEGRATION_TESTING.md#skip-behaviour)). + +Every V2 test that enrolls a product is a `[SkippableTheory]` that runs twice: `mode: Pinned` (the +template carries a `ProductCode`) and `mode: V2Template` (no `ProductCode`; CERTInext resolves the +product). See [INTEGRATION_TESTING.md](INTEGRATION_TESTING.md#v2-pinned-and-unpinned-v2-template-runs). +`BulkV2Enrollment_AllOrdersIssue_AndPaginationWorks` (a volume/pagination test, 101 orders) runs pinned +only. `PrivatePki_V2_*`, the validity/latency/inline-CSR experiments, and the read-only probes are not doubled. + +| Class | Test | What it checks | +|---|---|---| +| `V2ApiTests` | `Connectivity_V2_Ping` | `GET /auth/me` succeeds with an OAuth token | +| | `Lifecycle_V2_EnrollTrackRevoke` | Place an order with the CSR inline (a raw single create call), track it, then revoke or cancel it in the class cleanup. Every raw-client order in `V2ApiTests` is cleaned up the same way | +| | `Sync_UsesV2_WithZeroV1Credentials` | Synchronize works with no V1 credentials configured | +| | `GetProductDetails_V2_ReturnsProducts` | The V2 catalog returns products | +| | `ValidateProductInfo_V2_AcceptsConfiguredProductCode`, `ValidateProductInfo_V2_RejectsUnknownProductCode` | Template validation against the V2 catalog | +| | `GetSingleRecord_V2_ReturnsOrderDetails`, `Revoke_V2_IssuedOrder`, `ChainPem_V2_IsAssembled` | Single-record lookup, revocation, and chain assembly for an issued order (`CERTINEXT_V2_ISSUED_ORDER_ID`, or a fresh order) | +| | `DcvFlow_V2_PublishesAndVerifies` | Needs Cloudflare. The V2 DCV flow publishes the TXT record and CERTInext verifies it | +| `V2LifecycleTests` | `Enroll_V2_ReturnsCARequestID`, `Enroll_Synchronize_Revoke_V2_FullLifecycle` | V2 enrollment returns an ID; a full enroll, sync, revoke cycle | +| | `Revoke_V2_ExplicitOrder_Superseded`, `Revoke_V2_IssuedOrder_ReturnsRevoked` | Revocation with an explicit reason, and of an issued order (`CERTINEXT_REVOKE_ORDER_ID`) | +| | `GetSingleRecord_V2_Plugin_ReturnsDetails`, `GetSingleRecord_V2_IssuedOrder_HasParseableCertBody`, `GetSingleRecord_V2_AllSyncedOrders_DoNotThrow` | Single-record lookup through the plugin | +| | `Sync_V2_UsesV2ReportsOrders_ReturnsRecords`, `Sync_V2_WithZeroV1Credentials_Succeeds`, `Sync_V2_SmallPageSize_PaginatesAcrossMultiplePages` | V2 synchronization, with no V1 credentials and across several small pages | +| | `Sync_V2_FullSync_PaginatesEntireHistory` | Set `CERTINEXT_V2_FULL_SYNC_TEST` to run it; can be slow on a shared account | +| `V2DcvLifecycleTests` | `DcvEnroll_V2_CompletesWithoutThrowing`, `EnrollWithoutDcv_V2_DoesNotInvokeDnsProvider`, `GetSingleRecord_V2_DrivesDcvForPendingOrder`, `EnrollWithDcvOn_V2_OrderIssuedEndToEnd_AndAppearsInSync` | The V2 counterparts of the V1 DCV tests (`CERTINEXT_V2_PENDING_ORDER_ID` for the single-record one) | +| | `EnrollWithDcvOn_V2_IssuesPerKeyAlgorithm` | **Opt-in** (`CERTINEXT_V2_ALGO_MATRIX`) | +| | `BulkV2Enrollment_AllOrdersIssue_AndPaginationWorks` | **Opt-in** (`CERTINEXT_V2_RUN_BULK_TEST`) | +| `V2FreshDomainDcvLifecycleTests` | `EnrollWithDcvOn_V2_FreshUnverifiedSubdomain_StagesAndCleansUpTxt`, `EnrollWithDcvOn_V2_WildcardFreshSubdomain_RecordsTxtHostnameAndCleansUp` | **Opt-in** (`CERTINEXT_V2_LIFECYCLE_FRESH_DCV`). DCV against a never-validated subdomain, and against a wildcard on one: the TXT record is staged at the expected hostname and removed afterward | +| `V2FullLifecycleTests` | `Enroll_V2_DvUcc_WithMultipleSans_FullLifecycle`, `Enroll_V2_Ov_FullLifecycle`, `Enroll_V2_OvUcc_WithMultipleSans_FullLifecycle`, `Enroll_V2_Ev_FullLifecycle`, `Enroll_V2_WildcardDv_WildcardOnly_FullLifecycle`, `Enroll_V2_WildcardDv_WildcardPlusApexSan_RecordsActualBehavior`, `EnrollRenewReissue_V2_IssuedDvOrder_RecordsActualBehavior` | **Opt-in** (one `CERTINEXT_V2_LIFECYCLE_*` flag per product, see [INTEGRATION_TESTING.md](INTEGRATION_TESTING.md#opt-in-flags)). Each enrolls, waits, synchronizes, and cleans up its order | +| `PrivatePkiV2LiveTests` | `PrivatePki_V2_EnrollIntranetSsl_ThenRevoke_Live` | **Opt-in** (`CERTINEXT_PRIVATE_PKI_LIVE`). Enrolls a Private PKI Intranet SSL order with DNS and IP SANs, checks the issued SANs, and revokes it. Needs a Private PKI entitlement. Always two-call (create, then `PUT .../csr`): the sandbox rejects an inline CSR on Private PKI create with HTTP 422. The order parks at `pending-approval` and is cancelled, so the test reports it as inconclusive on this sandbox | +| | `PrivatePki_V2_RecordingProxy_BuildsOffline` | Offline sanity check of the test's recording proxy | +| `V2OrderWindowSweepTests` | `Sweep_ListRecentOrders_ByWindow_DryRun_ThenCancelExplicitIds` | **Opt-in** (`CERTINEXT_V2_OPS_TESTS`). Operations tool: lists V2 orders in a date window and optionally cancels listed IDs | + +### Offline tests and utilities + +| Class | What it covers | +|---|---| +| `IntegrationTestFixtureTests` | Parsing of `KEY=VALUE` env-file values: quote handling and null input | +| `V1FixtureApiUrlGuardTests` | The V1 fixture rejects a V2 `CERTINEXT_API_URL`; the V2 file loader never promotes V1 keys or opt-in flags into the process environment | +| `KfclabCsrEmitterTests` | Utility, not an API test. With `CERTINEXT_EMIT_CSR_DIR` and `CERTINEXT_EMIT_CSR_SPEC` set, writes CSR files for use by external tooling. Makes no CA calls | + +Shared helpers (not tests): `IntegrationTestFixture`, `IntegrationSkip`, `KeyAlgorithms`, +`V2EnvHelper`, `V2DomainStatusHelper`, `V2RawHttpHelpers`, and the DNS validators +`CloudflareDomainValidator`, `RecordingDomainValidator`, and `StubDomainValidator`. --- @@ -199,104 +131,29 @@ account. These tests do not require any pre-existing account state. | Test class | Expected result | |-----------|----------------| | `ConnectivityTests` | Pass — credentials only | -| `ProductTests` | Pass — product list may be empty if `CERTINEXT_GROUP_NUMBER` is not set and the account requires it; test tolerates an empty list | +| `ProductTests` | Pass — the product list may be empty if `CERTINEXT_GROUP_NUMBER` is unset and the account needs it; the test tolerates an empty list | | `OrderReportTests` | Skip — "account has no orders yet" | | `PluginSmokeTests.Synchronize_ReturnsAtLeastOneRecord` | Skip — "account has no certificate records yet" | -| `LifecycleTests.Enroll_Synchronize_Revoke_FullLifecycle` | Skip with "Invalid Product Code" if `CERTINEXT_PRODUCT_CODE` is not provisioned for this account; otherwise the enroll and sync steps pass, and the revoke step skips because the DV SSL sandbox order requires domain control verification and RA approval before it reaches an issued/revocable state | +| `LifecycleTests.Enroll_Synchronize_Revoke_FullLifecycle` | Skip with "Invalid Product Code" if `CERTINEXT_PRODUCT_CODE` isn't provisioned for the account; otherwise enroll and sync pass, and revoke skips because a sandbox DV order needs domain validation before it is issued | -### Account with history (orders previously placed) +### Account with history | Test class | Expected result | |-----------|----------------| -| `ConnectivityTests` | Pass | -| `ProductTests` | Pass | -| `OrderReportTests` | Pass | -| `PluginSmokeTests` | Pass | -| `LifecycleTests` | Pass (all three steps) | - ---- - -## Removed Tests - -The following test files were present in earlier versions but have been removed because -they relied on pre-existing account state that is not portable across accounts or -sandbox environments: - -- **`DraftOrderTests.cs`** — contained five tests that asserted specific `requestNumber` - values (e.g. `4572531551`, `9149755266`) hardcoded from a different developer account. - On any other account these request numbers do not exist so all five tests failed. - -- **`TrackOrderTests.cs`** — contained one test that located a known draft order by - `requestNumber` and asserted its `orderNumber` was null (draft/on-hold semantic). - Same problem: the hardcoded `requestNumber` does not exist on other accounts. - -The intent of those tests (verifying draft-order and track-order semantics) is now -covered indirectly by `LifecycleTests`, which creates its own order and verifies the -resulting state without relying on account-specific identifiers. - ---- - -## Authentication - -The CERTInext API uses HMAC-SHA256 authentication computed for every request: - -``` -authKey = SHA256(accessKey + ts + txn) (lowercase hex) -``` - -Where: -- `accessKey` is the raw API Access Key from `CERTINEXT_ACCESS_KEY` -- `ts` is the current timestamp in ISO 8601 format -- `txn` is a random numeric transaction ID - -The `CERTInextClient` handles this computation automatically. The raw access key is -never transmitted over the wire — only the derived `authKey` hash is sent. - ---- - -## Fresh Account Setup for Integration Tests - -When setting up a brand-new CERTInext sandbox account to run integration tests: - -1. **Discover valid product codes** — run `make probe-products` from the repo root. This places - `saveAndHold=1` draft orders for all known SSL/TLS product codes and reports which ones your - account accepts. Use the first DV SSL code that returns a `requestNumber` as your - `CERTINEXT_PRODUCT_CODE`. - -2. **Set `CERTINEXT_GROUP_NUMBER`** — if `make probe-products` or `GetProductDetails` returns no - products, find your group number in the CERTInext portal under **Delegation → Groups** and add - it to `~/.env_certinext`. The `GetProductDetails` API requires it on some accounts. - -3. **Run connectivity tests first** — `make integration-test` or - `dotnet test CERTInext.IntegrationTests/ -v normal`. The `ConnectivityTests` class verifies - credentials. The `LifecycleTests` class places real orders — it can be run even before any - orders exist. - -4. **Expect the revoke step to skip** — DV SSL orders on the sandbox require domain control - verification (DCV) and RA approval before they are issued. The `LifecycleTests` enroll step - will succeed and sync will find the order, but revoke will skip because the order is in a - pending state. This is the expected behavior for a public DV SSL order in sandbox. To test - revocation, either use a private PKI product that auto-approves, or log in to the CERTInext - portal and manually approve the pending order after `LifecycleTests` runs. - -5. **Account-specific product codes** — update `CERTINEXT_PRODUCT_CODE` in `~/.env_certinext` - with the code discovered in step 1. Do not use `100` (private PKI, not provisioned on - standard accounts) or codes from documentation examples — they may not be provisioned for your - account. - ---- - -## Troubleshooting - -| Symptom | Likely cause | Fix | -|---------|-------------|-----| -| All tests skipped | Missing or empty `~/.env_certinext` | Create the file with `CERTINEXT_API_URL` and `CERTINEXT_ACCESS_KEY` | -| `Ping` fails with 401/403 | Wrong `CERTINEXT_ACCESS_KEY` | Regenerate the key in the CERTInext portal under Integrations → APIs | -| `Ping` fails with timeout or 404 | Wrong `CERTINEXT_API_URL` | Verify the URL matches your account region (see API URL table above) | -| `Enroll` fails with "Invalid Product Code" (EMS-1162) | Wrong `CERTINEXT_PRODUCT_CODE` | Run `make probe-products` to discover the codes provisioned for your account | -| `GetProductDetails` returns empty list | `CERTINEXT_GROUP_NUMBER` not set | Add your group number to `~/.env_certinext`; some accounts require it for `GetProductDetails` to return results | -| `Enroll` fails with "Additional Information cannot be empty" (EMS-918) | Old plugin version missing `additionalInformation.remarks` | Rebuild and redeploy the plugin — the `remarks` field is now populated automatically | -| `Enroll` fails with "Invalid Organization Number" (EMS-1073) | OV/EV product code selected with an unregistered org | Use a DV SSL product code for automated tests, or register and approve your org in CERTInext first | -| Revoke step skips with "not GENERATED" | Sandbox DV SSL order requires domain validation and RA approval | Expected behavior for public DV SSL in sandbox — log in to the CERTInext portal and approve the pending order, then re-run; or use a private PKI product that auto-approves | -| `OrderReportTests` all skip | Fresh account with no orders | Run `LifecycleTests` first to place at least one order | -| `ProductTests` asserts configured product code is not found | `CERTINEXT_PRODUCT_CODE` set to a code not provisioned for the account | Run `make probe-products` and update `CERTINEXT_PRODUCT_CODE` with a valid code | +| `ConnectivityTests`, `ProductTests`, `OrderReportTests`, `PluginSmokeTests` | Pass | +| `LifecycleTests` | Pass for enroll and sync; revoke runs only if the new order is issued | + +The DCV tests complete a DV order end to end only when Cloudflare credentials are configured and the +domain in `CERTINEXT_DCV_DOMAIN` is in that zone. Without them, the revoke step of `LifecycleTests` +skips, because DV orders on the sandbox can't be issued without domain validation. + +### Fresh account setup + +1. **Discover valid product codes** with `make probe-products`. Use the first DV SSL code that + returns a `requestNumber` as `CERTINEXT_PRODUCT_CODE`. +2. **Set `CERTINEXT_GROUP_NUMBER`** if `make probe-products` or `GetProductDetails` returns no + products. Find it in the portal under **Delegation → Groups**. +3. **Run `ConnectivityTests` first**, then `LifecycleTests`, which places a real order and can run + before any orders exist. +4. **Expect the revoke step to skip** without DCV. To exercise revocation, configure Cloudflare so a + DV order can issue, or use a product that issues without domain validation. diff --git a/CERTInext.IntegrationTests/TestOutputLogging.cs b/CERTInext.IntegrationTests/TestOutputLogging.cs new file mode 100644 index 0000000..5512917 --- /dev/null +++ b/CERTInext.IntegrationTests/TestOutputLogging.cs @@ -0,0 +1,74 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using Microsoft.Extensions.Logging; +using Xunit.Abstractions; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.IntegrationTests +{ + /// + /// Routes plugin/client logs (LogHandler.Factory) to a test's xUnit output so a live run + /// shows why the plugin took a path, e.g. the V2 DCV early exits or a CA rejection at Submit CSR. + /// Minimum level is Debug, or CERTINEXT_TEST_LOG_LEVEL (e.g. Trace to include the + /// redacted request/response payloads). Plugin logs keep their default redaction + /// (LogSensitiveRequestData off). Must be called before the plugin is constructed — its + /// logger is created in a field initializer. + /// + internal static class TestOutputLogging + { + /// Points the plugin's log factory at ; returns the restore action. + public static Action RouteTo(ITestOutputHelper output) + { + var min = Enum.TryParse(Environment.GetEnvironmentVariable("CERTINEXT_TEST_LOG_LEVEL"), true, out LogLevel parsed) + ? parsed + : LogLevel.Debug; + Keyfactor.Logging.LogHandler.Factory = new Factory(output, min); + return () => Keyfactor.Logging.LogHandler.Factory = + Microsoft.Extensions.Logging.Abstractions.NullLoggerFactory.Instance; + } + + private sealed class Factory : ILoggerFactory + { + private readonly ITestOutputHelper _out; + private readonly LogLevel _min; + public Factory(ITestOutputHelper output, LogLevel min) { _out = output; _min = min; } + public ILogger CreateLogger(string categoryName) => new Logger(_out, categoryName, _min); + public void AddProvider(ILoggerProvider provider) { } + public void Dispose() { } + } + + private sealed class Logger : ILogger + { + private readonly ITestOutputHelper _out; + private readonly string _category; + private readonly LogLevel _min; + public Logger(ITestOutputHelper output, string category, LogLevel min) + { + _out = output; + _category = category.Substring(category.LastIndexOf('.') + 1); + _min = min; + } + public IDisposable BeginScope(TState state) => null; + public bool IsEnabled(LogLevel logLevel) => logLevel >= _min; + public void Log(LogLevel logLevel, EventId eventId, TState state, Exception exception, + Func formatter) + { + if (!IsEnabled(logLevel)) return; + try + { + _out.WriteLine($"[{logLevel}] {_category}: {formatter(state, exception)}" + + (exception == null ? string.Empty : $" | {exception.GetType().Name}: {exception.Message}")); + } + catch (InvalidOperationException) + { + // ITestOutputHelper throws once the test has finished (background continuations). + } + } + } + } +} diff --git a/CERTInext.IntegrationTests/V1FixtureApiUrlGuardTests.cs b/CERTInext.IntegrationTests/V1FixtureApiUrlGuardTests.cs new file mode 100644 index 0000000..541826d --- /dev/null +++ b/CERTInext.IntegrationTests/V1FixtureApiUrlGuardTests.cs @@ -0,0 +1,179 @@ +// Copyright 2026 Keyfactor +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; +using System.Collections; +using System.IO; +using FluentAssertions; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.IntegrationTests +{ + /// + /// Pure offline regression tests (no live-API dependency, no process-env mutation, so they + /// are safe to run in parallel with every other class): + /// + /// the V1 fixture's guard + /// rejects a V2 base URL with an actionable message that never echoes secrets; + /// never promotes a key the V1 side reads, + /// nor any of the fixture's opt-in-only flags. + /// + /// + public class V1FixtureApiUrlGuardTests + { + private const string V1Url = "https://sandbox-us-api.certinext.io/emSignHub-API"; + private const string V2Url = "https://sandbox-us-api.certinext.io"; + + // ------------------------------------------------------------------------- + // (D) fail-fast guard + // ------------------------------------------------------------------------- + + [Theory] + [InlineData(V1Url)] + [InlineData(V1Url + "/")] + [InlineData("https://api.certinext.io/emsignhub-api/")] // case-insensitive + [InlineData("")] // unconfigured: nothing to check + [InlineData(null)] + public void EnsureV1ApiUrl_V1OrEmptyUrl_DoesNotThrow(string apiUrl) + { + Action act = () => IntegrationTestFixture.EnsureV1ApiUrl(apiUrl, fromProcessEnvironment: false); + act.Should().NotThrow(); + } + + [Theory] + [InlineData(V2Url, true)] + [InlineData(V2Url + "/", false)] + [InlineData("https://sandbox-us-api.certinext.io/v2", true)] + public void EnsureV1ApiUrl_V2BaseUrl_ThrowsActionableMessage(string apiUrl, bool fromProcessEnv) + { + Action act = () => IntegrationTestFixture.EnsureV1ApiUrl(apiUrl, fromProcessEnv); + + var ex = act.Should().Throw().Which; + ex.Message.Should().Contain("CERTINEXT_API_URL") + .And.Contain("/emSignHub-API") + .And.Contain("V2 base URL") + .And.Contain("set -a; . ~/.env_certinext; set +a") + .And.Contain("~/.env_certinext_v2"); + ex.Message.Should().Contain(fromProcessEnv ? "process environment" : "(from ~/.env_certinext)"); + } + + [Fact] + public void EnsureV1ApiUrl_UrlWithUserInfoAndQuery_NeverEchoesThem() + { + Action act = () => IntegrationTestFixture.EnsureV1ApiUrl( + "https://someuser:not-a-real-secret@sandbox-us-api.certinext.io/?token=not-a-real-token", + fromProcessEnvironment: true); + + var ex = act.Should().Throw().Which; + ex.Message.Should().Contain("sandbox-us-api.certinext.io"); + ex.Message.Should().NotContain("someuser") + .And.NotContain("not-a-real-secret") + .And.NotContain("not-a-real-token"); + } + + /// + /// End-to-end offline composition of the shell-overlay path: a correct V1 file, a + /// V2 CERTINEXT_API_URL in the (simulated) process environment. Real env vars keep + /// precedence (documented behaviour), and the guard then rejects the leaked value — the + /// same two steps the fixture constructor runs before it builds any client. + /// + [Fact] + public void LoadEnvFile_ProcessEnvV2UrlOverridesV1File_GuardRejectsIt() + { + string path = Path.Combine(Path.GetTempPath(), $"certinext-v1url-{Guid.NewGuid():N}.env"); + try + { + File.WriteAllLines(path, new[] + { + $"CERTINEXT_API_URL={V1Url}", + "CERTINEXT_ACCESS_KEY=dummy-access-key", + }); + var processEnv = new Hashtable { ["CERTINEXT_API_URL"] = V2Url }; + + var env = IntegrationTestFixture.LoadEnvFile(path, processEnv); + + env["CERTINEXT_API_URL"].Should().Be(V2Url, "real env vars still override the file"); + Action act = () => IntegrationTestFixture.EnsureV1ApiUrl(env["CERTINEXT_API_URL"], true); + act.Should().Throw() + .Which.Message.Should().NotContain("dummy-access-key"); + } + finally + { + File.Delete(path); + } + } + + // ------------------------------------------------------------------------- + // (B) V2EnvHelper no longer promotes V1-shared keys + // ------------------------------------------------------------------------- + + [Fact] + public void PromotableKeys_ExcludesEveryV1Key_KeepsV2OnlyKeys() + { + // Mirrors the key set ~/.env_certinext_v2 defines today (names only). + string[] v2FileKeys = + { + "CERTINEXT_ACCOUNT_NUMBER", "CERTINEXT_API_URL", "CERTINEXT_CF_API_TOKEN", + "CERTINEXT_CF_ZONE_ID", "CERTINEXT_CLIENT_ID", "CERTINEXT_CLIENT_SECRET", + "CERTINEXT_DCV_DOMAIN", "CERTINEXT_GROUP_NUMBER", "CERTINEXT_ORG_NUMBER", + "CERTINEXT_PRODUCT_CODE", "CERTINEXT_REQUESTOR_EMAIL", "CERTINEXT_REQUESTOR_MOBILE", + "CERTINEXT_REQUESTOR_NAME", "CERTINEXT_SIGNER_IP", "CERTINEXT_USE_V2_API", + "certinext_api_url", // case-insensitive match + }; + + var promoted = V2EnvHelper.PromotableKeys(v2FileKeys); + + promoted.Should().BeEquivalentTo( + "CERTINEXT_CLIENT_ID", "CERTINEXT_CLIENT_SECRET", "CERTINEXT_REQUESTOR_MOBILE", + "CERTINEXT_SIGNER_IP", "CERTINEXT_USE_V2_API"); + } + + /// + /// If a developer ever left one of the fixture's opt-in-only flags (e.g. + /// CERTINEXT_V2_OPS_TESTS, CERTINEXT_PRIVATE_PKI_LIVE) in ~/.env_certinext_v2, it must + /// NOT come back out of — otherwise the first + /// test class constructed in a run reads the flag as unset, then promotes it into real + /// process env, silently arming every later-constructed test class in the same run even + /// though nothing was ever exported in the shell. Covers every flag in + /// , so a future addition to that set + /// is covered automatically. + /// + [Fact] + public void PromotableKeys_ExcludesEveryOptInOnlyFlag() + { + var promoted = V2EnvHelper.PromotableKeys(IntegrationTestFixture._optInOnlyFlags); + + promoted.Should().BeEmpty( + "every opt-in-only flag must be excluded from V2-file promotion, or a value left " + + "in ~/.env_certinext_v2 could silently arm a later test in the same run"); + } + + [Theory] + [InlineData("CERTINEXT_API_URL")] + [InlineData("CERTINEXT_ACCESS_KEY")] + [InlineData("CERTINEXT_ACCOUNT_NUMBER")] + [InlineData("CERTINEXT_GROUP_NUMBER")] + [InlineData("CERTINEXT_ORG_NUMBER")] + [InlineData("CERTINEXT_PRODUCT_CODE")] + [InlineData("CERTINEXT_REQUESTOR_EMAIL")] + [InlineData("CERTINEXT_REQUESTOR_NAME")] + [InlineData("CERTINEXT_CF_API_TOKEN")] + [InlineData("CERTINEXT_CF_ZONE_ID")] + [InlineData("CERTINEXT_DCV_DOMAIN")] // read from process env by V1 DcvLifecycleTests + public void V1EnvKeys_CoversEveryKeyTheV1SideReads(string key) + { + IntegrationTestFixture.V1EnvKeys.Should().Contain(key); + } + } +} diff --git a/CERTInext.IntegrationTests/V2ApiTests.cs b/CERTInext.IntegrationTests/V2ApiTests.cs new file mode 100644 index 0000000..3da4b09 --- /dev/null +++ b/CERTInext.IntegrationTests/V2ApiTests.cs @@ -0,0 +1,829 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Linq; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Org.BouncyCastle.Asn1.X509; +using Org.BouncyCastle.Crypto.Generators; +using Org.BouncyCastle.Crypto; +using Org.BouncyCastle.Pkcs; +using Org.BouncyCastle.Security; +using Xunit; +using Xunit.Abstractions; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.IntegrationTests +{ + /// + /// Integration test stubs for the V2 REST API code path. + /// + /// All tests are gated behind the CERTINEXT_USE_V2_API=1 environment variable + /// and skip gracefully when it is not set, so they are safe to run in CI environments + /// that do not have V2 credentials configured. + /// + /// To run against a live V2 environment: + /// + /// set -a; . ~/.env_certinext; set +a + /// export CERTINEXT_USE_V2_API=1 + /// dotnet test CERTInext.IntegrationTests/ --filter "FullyQualifiedName~V2ApiTests" + /// + /// Note: the shell must source ONLY ~/.env_certinext (never ~/.env_certinext_v2); + /// this class loads ~/.env_certinext_v2 itself from disk at test-construction time. + /// + /// Required variables in ~/.env_certinext_v2 (or real env vars): + /// + /// CERTINEXT_API_URL — V2 base URL (e.g. https://sandbox-us-api.certinext.io) + /// CERTINEXT_CLIENT_ID — OAuth2 client ID + /// CERTINEXT_CLIENT_SECRET — OAuth2 client secret + /// CERTINEXT_PRODUCT_CODE — product code for lifecycle test (e.g. 842) + /// CERTINEXT_DCV_DOMAIN — domain for lifecycle test (e.g. dcv-test.example.com) + /// + /// V1 variables (CERTINEXT_API_URL, CERTINEXT_ACCESS_KEY, etc.) are NOT required + /// for V2-mode tests — Synchronize uses V2 /reports/orders when UseV2Api is true, + /// and V1 credentials are optional in that mode. + /// + public class V2ApiTests : IClassFixture, IAsyncLifetime + { + private readonly IntegrationTestFixture _fixture; + private readonly ITestOutputHelper _output; + private readonly string _v2ApiUrl; + private readonly string _v2ClientId; + private readonly string _v2ClientSecret; + private readonly string _v2ProductCode; + private readonly string _v2Domain; + private readonly bool _v2Enabled; + private readonly string _cfApiToken; + private readonly string _cfZoneId; + private readonly bool _dcvEnabled; + private readonly string _issuedOrderId; + + public V2ApiTests(IntegrationTestFixture fixture, ITestOutputHelper output) + { + _fixture = fixture; + _output = output; + + // Load ~/.env_certinext_v2 via the shared helper (one env loader, not a private + // copy per test class). V2 file values take priority over + // process env because IntegrationTestFixture may have already promoted the V1 + // CERTINEXT_API_URL (with /emSignHub-API suffix) into process env, and the V2 base + // URL is different. + var env = V2EnvHelper.LoadAndPromote(); + + _v2ApiUrl = V2EnvHelper.GetEnv(env, "CERTINEXT_API_URL"); + _v2ClientId = V2EnvHelper.GetEnv(env, "CERTINEXT_CLIENT_ID"); + _v2ClientSecret = V2EnvHelper.GetEnv(env, "CERTINEXT_CLIENT_SECRET"); + _v2ProductCode = V2EnvHelper.GetEnv(env, "CERTINEXT_PRODUCT_CODE", "842"); + _v2Domain = V2EnvHelper.GetEnv(env, "CERTINEXT_DCV_DOMAIN", "test.example.com"); + _cfApiToken = V2EnvHelper.GetEnv(env, "CERTINEXT_CF_API_TOKEN"); + _cfZoneId = V2EnvHelper.GetEnv(env, "CERTINEXT_CF_ZONE_ID"); + _issuedOrderId = V2EnvHelper.GetEnv(env, "CERTINEXT_V2_ISSUED_ORDER_ID"); + + _v2Enabled = !string.IsNullOrWhiteSpace(V2EnvHelper.GetEnv(env, "CERTINEXT_USE_V2_API")) + && !string.IsNullOrWhiteSpace(_v2ApiUrl) + && !string.IsNullOrWhiteSpace(_v2ClientId) + && !string.IsNullOrWhiteSpace(_v2ClientSecret); + + _dcvEnabled = _v2Enabled + && !string.IsNullOrWhiteSpace(_cfApiToken) + && !string.IsNullOrWhiteSpace(_cfZoneId); + } + + // --------------------------------------------------------------------------- + // V2 Connectivity + // --------------------------------------------------------------------------- + + /// + /// Calls GET /api/certinext/v2/auth/me and verifies a non-empty accountNumber + /// is returned. Skips when CERTINEXT_USE_V2_API is not set. + /// + [SkippableFact] + public async Task Connectivity_V2_Ping() + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + + using var client = BuildV2Client(); + var me = await client.GetAuthMeV2Async(); + + me.Should().NotBeNull(); + me.AccountNumber.Should().NotBeNullOrEmpty("auth/me must return accountNumber for a valid OAuth2 client"); + me.AuthType.Should().Be("oauth2"); + } + + // --------------------------------------------------------------------------- + // V2 Lifecycle: place order → track → revoke + // --------------------------------------------------------------------------- + + /// + /// Places a V2 SSL order, asserts that the CARequestID starts with "ord_", + /// then revokes the order. + /// Skips when CERTINEXT_USE_V2_API is not set. + /// + [SkippableTheory] + [V2PinModes] + public async Task Lifecycle_V2_EnrollTrackRevoke(V2PinMode mode) + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + + using var client = BuildV2Client(); + + // Place order + var orderReq = BuildStandardOrderRequest(); + var createResp = await PlaceOrderTrackedAsync(client, orderReq, mode); + + createResp.Should().NotBeNull(); + createResp.OrderId.Should().NotBeNullOrEmpty( + "V2 place-order must return a non-empty orderId (sandbox may return numeric IDs rather than 'ord_' prefix)"); + + // Track the order + var (_, trackResp) = await ResolveOrderFamilyAsync(client, createResp.OrderId); + trackResp.OrderId.Should().Be(createResp.OrderId); + trackResp.Status.Should().NotBeNullOrEmpty( + "V2 TrackOrder must return a status for the placed order"); + // Best-effort structural check: this sandbox's TrackOrder response can omit + // "_links" entirely, so this logs rather than hard-fails — the shape actually + // guarded against here is OrderId/Status. + if (trackResp.Links?.Self?.Href is string href && !string.IsNullOrWhiteSpace(href)) + _output.WriteLine($"TrackOrder links.self.href: {href}"); + else + _output.WriteLine("TrackOrder response did not include a links.self.href (sandbox may omit _links)."); + + // Note: revoke requires the order to reach 'issued' state first. + // The sandbox processes orders asynchronously, so we only assert enroll + track here. + // A full revoke smoke test requires waiting for issuance (run separately with DCV configured). + } + + // --------------------------------------------------------------------------- + // Synchronize uses V2 /reports/orders when UseV2Api=true + // --------------------------------------------------------------------------- + + /// + /// Verifies that Synchronize calls V2 /reports/orders (not V1 GetOrderReport) + /// when UseV2Api=true, and succeeds with ZERO V1 credentials configured at all. + /// A single serves both modes, so the V1-only + /// fields (ApiKey/AccountNumber/AuthMode) below are simply never set. + /// + [SkippableFact] + public async Task Sync_UsesV2_WithZeroV1Credentials() + { + Skip.If(!_v2Enabled, "V2 opt-in (CERTINEXT_USE_V2_API) or V2 credentials not configured — skipping."); + + var config = new CERTInextConfig + { + ApiUrl = _v2ApiUrl, + UseV2Api = true, + OAuthClientId = _v2ClientId, + OAuthClientSecret = _v2ClientSecret, + RequestorName = "Keyfactor Test", + RequestorEmail = "test@example.com", + SignerPlace = "Gateway Lab", + SignerIp = "127.0.0.1", + PageSize = 10, + // A small lookback keeps this test's live API call volume bounded — every + // issued row in the window needs a live certificate download (the report + // carries no body), and ResolveAndDownloadCertificateV2Async re-resolves the + // product family via a sequential TrackOrder probe when it isn't already known. + // The DEFAULT 72h lookback margin (Constants.ApiV2.DefaultSyncLookbackHours) is + // always added on top of lastSync regardless of how recent lastSync is, so on a + // busy shared sandbox account even a "last hour" delta sync still touches + // several days of orders unless this is overridden. This is a real, currently + // unbounded cost on the live path, not just a test-tuning artifact. + V2SyncLookbackHours = 1 + // Deliberately NOT set: ApiKey, AccountNumber, AuthMode, OAuthTokenUrl — all + // V1-only fields. Proving Synchronize succeeds without them is the point of + // this test. + }; + + using var client = new CERTInextClient(config); + var plugin = new CERTInextCAPlugin(client, config); + + var buffer = new BlockingCollection(1000); + // 300s: this shared sandbox can return 100+ orders even within a narrow ~1-2h + // window (heavy ongoing test activity), and each issued row costs a live download + // plus (when family isn't already known) a family-probe TrackOrder call — a + // genuine current performance characteristic of the live path, not a test artifact. + using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(300)); + + await plugin.Synchronize(buffer, DateTime.UtcNow.AddHours(-1), false, cts.Token); + if (!buffer.IsAddingCompleted) + buffer.CompleteAdding(); + + var records = new List(); + foreach (var record in buffer.GetConsumingEnumerable()) + records.Add(record); + + // The delta sync window is narrow (see V2SyncLookbackHours above), so this only + // proves correctness (zero V1 creds, records returned, shape is sane) — not sync + // performance at scale, which is a separate, real concern. + records.Should().NotBeEmpty( + "Synchronize must return records via V2 /reports/orders when UseV2Api=true, with zero V1 " + + "credentials configured — an empty result here proves nothing about which code path ran"); + records.Should().OnlyContain(r => !string.IsNullOrWhiteSpace(r.CARequestID)); + + _output.WriteLine( + $"Sync_UsesV2_WithZeroV1Credentials: {records.Count} record(s) returned via V2 /reports/orders, " + + "with no ApiKey/AccountNumber/AuthMode configured."); + } + + // --------------------------------------------------------------------------- + // V2 Product catalogue + // --------------------------------------------------------------------------- + + /// + /// Calls GET /api/certinext/v2/catalog/products and asserts a non-empty list + /// is returned. Skips when CERTINEXT_USE_V2_API is not set. + /// + [SkippableFact] + public async Task GetProductDetails_V2_ReturnsProducts() + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + + using var client = BuildV2Client(); + List products = await client.GetProductDetailsV2Async(); + + products.Should().NotBeNull("V2 catalog/products must return a non-null list"); + products.Should().NotBeEmpty("V2 catalog/products must return at least one product"); + + // The live catalog/products response is a nested category envelope, the same + // shape V1's GetProductDetails returns. ParseProductDetailsV2Response flattens + // it, so every parsed product must carry a non-empty ProductCode. + products.Should().OnlyContain(p => !string.IsNullOrWhiteSpace(p.ProductCode), + "ParseProductDetailsV2Response must flatten the nested category envelope into ProductCode-bearing rows"); + _output.WriteLine($"{products.Count}/{products.Count} catalog products carry a non-empty ProductCode."); + } + + /// + /// Drives (not just the client + /// method) end-to-end in V2 mode against the configured product code. Read-only. + /// + [SkippableFact] + public async Task ValidateProductInfo_V2_AcceptsConfiguredProductCode() + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + + var plugin = new CERTInextCAPlugin(); + var connectionInfo = BuildV2ConnectionInfo(); + var productInfo = new EnrollmentProductInfo + { + ProductID = "ssl", + ProductParameters = new Dictionary { ["ProductCode"] = _v2ProductCode } + }; + + Func act = () => plugin.ValidateProductInfo(productInfo, connectionInfo); + + await act.Should().NotThrowAsync( + $"ProductCode '{_v2ProductCode}' should be present in the live V2 catalog"); + } + + /// + /// Same as but with a + /// product code that should never exist, asserting the same "not found" failure mode + /// V1 has always had. Read-only — no order is placed. + /// + [SkippableFact] + public async Task ValidateProductInfo_V2_RejectsUnknownProductCode() + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + + var plugin = new CERTInextCAPlugin(); + var connectionInfo = BuildV2ConnectionInfo(); + var productInfo = new EnrollmentProductInfo + { + ProductID = "ssl", + ProductParameters = new Dictionary { ["ProductCode"] = "999999" } + }; + + Func act = () => plugin.ValidateProductInfo(productInfo, connectionInfo); + + await act.Should().ThrowAsync() + .WithMessage("*not found*"); + } + + /// + /// ignores the constructor-injected + /// client/config and builds its own from connectionInfo, so integration tests + /// must pass a real dictionary — UseV2Api is a bool, not a string + /// (CERTInextCAPluginConfig.cs, CERTInextCAPlugin.cs's is bool check). + /// + private Dictionary BuildV2ConnectionInfo() + { + var info = new Dictionary + { + ["UseV2Api"] = true, + ["ApiUrl"] = _v2ApiUrl, + ["OAuthClientId"] = _v2ClientId, + ["OAuthClientSecret"] = _v2ClientSecret + }; + + string groupNumber = _fixture.IsConfigured ? _fixture.GroupNumber : null; + if (!string.IsNullOrWhiteSpace(groupNumber)) + info["GroupNumber"] = groupNumber; + + return info; + } + + // --------------------------------------------------------------------------- + // GetSingleRecord via V2 (ResolveAndTrackOrderV2Async) + // --------------------------------------------------------------------------- + + /// + /// Places a fresh DV SSL order then calls ResolveAndTrackOrderV2Async on the + /// returned orderId. Asserts that the order can be found and has a non-empty + /// status. The order will typically be issued, pending-approval or pending-dcv (the CSR is inline on create); that is fine. + /// Skips when CERTINEXT_USE_V2_API is not set. + /// + [SkippableTheory] + [V2PinModes] + public async Task GetSingleRecord_V2_ReturnsOrderDetails(V2PinMode mode) + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + + using var client = BuildV2Client(); + + var orderReq = BuildStandardOrderRequest(); + var createResp = await PlaceOrderTrackedAsync(client, orderReq, mode); + + createResp.Should().NotBeNull(); + string orderId = createResp.OrderId; + orderId.Should().NotBeNullOrEmpty("PlaceOrderV2Async must return a non-empty orderId"); + + var status = await client.ResolveAndTrackOrderV2Async(orderId); + + status.Should().NotBeNull("ResolveAndTrackOrderV2Async must return a non-null status"); + status.OrderId.Should().Be(orderId, "tracked order ID must match the placed order"); + status.Status.Should().NotBeNullOrEmpty("TrackOrder must return a non-empty status string"); + } + + // --------------------------------------------------------------------------- + // Revoke a known-issued V2 order + // --------------------------------------------------------------------------- + + /// + /// Revokes a previously issued V2 order. Prefers CERTINEXT_V2_ISSUED_ORDER_ID; + /// otherwise self-enrolls a fresh order via + /// and polls (bounded) for issuance, so the test does not depend on another test's + /// run order to have a usable order ID. + /// + [SkippableTheory] + [V2PinModes] + public async Task Revoke_V2_IssuedOrder(V2PinMode mode) + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + + using var client = BuildV2Client(); + var (orderId, family) = await EnsureIssuedOrderIdAsync(client, mode); + + // Revoke — sandbox may report 'issued' via track but reject revocation + // with 422 ("Certificate Request still being processed") while the order + // is still being processed internally. + var revokeReq = new V2RevokeRequest + { + Reason = "superseded", + Note = "V2 integration test cleanup" + }; + + try + { + await client.RevokeOrderV2Async(family, orderId, revokeReq); + } + catch (InvalidOperationException ex) when (ex.Message.Contains("still being processed")) + { + // Retry once after a short delay before giving up — any other exception + // (or a second failure) must fail the test rather than be swallowed here. + _output.WriteLine($"Revoke rejected as still-processing; retrying once after 15s: {ex.Message}"); + await Task.Delay(TimeSpan.FromSeconds(15)); + try + { + await client.RevokeOrderV2Async(family, orderId, revokeReq); + } + catch (InvalidOperationException ex2) when (ex2.Message.Contains("still being processed")) + { + Skip.If(true, + $"Order {orderId} tracked as 'issued' but CA rejected revocation twice (sandbox timing): {ex2.Message}"); + return; // unreachable; satisfies compiler + } + } + + // Re-track — must be revoked + var trackAfter = await client.ResolveAndTrackOrderV2Async(orderId); + trackAfter.Status.Should().Be( + Constants.ApiV2.StatusRevoked, + $"order {orderId} must be 'revoked' after revocation"); + } + + // --------------------------------------------------------------------------- + // DCV flow (publishes real Cloudflare TXT record) — requires SUPPORTS_DCV build + // --------------------------------------------------------------------------- + +#if SUPPORTS_DCV + /// + /// Places a DV SSL order, publishes the DCV TXT token via real Cloudflare DNS, + /// calls VerifyDcvV2Async, and polls until the order leaves pending-dcv. + /// Requires CERTINEXT_CF_API_TOKEN and CERTINEXT_CF_ZONE_ID in addition to + /// CERTINEXT_USE_V2_API. Skips if either is absent. + /// + /// CERTInext's domain DCV is account-scoped and reusable (BR 3.2.2.5): once + /// CERTINEXT_DCV_DOMAIN is verified once, it stays verified for the + /// validTill reuse window, and GetDcv/VerifyDcv return EMS-1080 + /// ("Domain is already verified") instead of issuing a fresh challenge. That is + /// treated here as the reuse-path outcome, not a failure: the publish/verify + /// steps are skipped and the order is polled directly for leaving pending-dcv. + /// + [SkippableTheory] + [V2PinModes] + public async Task DcvFlow_V2_PublishesAndVerifies(V2PinMode mode) + { + Skip.If(!_dcvEnabled, + "DCV test requires CERTINEXT_USE_V2_API + CERTINEXT_CF_API_TOKEN + CERTINEXT_CF_ZONE_ID — skipping."); + + using var client = BuildV2Client(); + var dns = new CloudflareDomainValidator(_cfApiToken, _cfZoneId); + string txtKey = null; + string orderId = null; + + var (domainVerifiedBeforeEnroll, rawStatus) = await V2DomainStatusHelper.GetDcvStatusAsync(client, _v2Domain); + _output.WriteLine($"Pre-enroll domain status for '{_v2Domain}': dcvStatus={rawStatus ?? ""}"); + + try + { + // 1. Place a DV SSL order — it lands in pending-dcv + var orderReq = BuildStandardOrderRequest(); + var createResp = await PlaceOrderTrackedAsync(client, orderReq, mode); + orderId = createResp.OrderId; + orderId.Should().NotBeNullOrEmpty(); + + // 2. Get DCV challenge + V2DcvChallengeResponse dcvResp; + try + { + dcvResp = await client.GetDcvV2Async(orderId, Constants.ApiV2.FamilySsl); + } + catch (Exception ex) when (ex.Message.Contains("EMS-1080")) + { + // Reuse path: the domain is already verified account-wide, so there is no + // fresh challenge to publish. Prove the order still reaches a non-pending-dcv + // state without ever staging a TXT record. + _output.WriteLine($"GetDcv returned EMS-1080 (domain already verified) — reuse path: {ex.Message}"); + _output.WriteLine($"(pre-enroll domain probe {(domainVerifiedBeforeEnroll ? "agreed: VERIFIED" : "did NOT show VERIFIED — status may have changed between the probe and this order")}.)"); + + V2OrderStatusResponse reuseStatus = null; + var reuseDeadline = DateTime.UtcNow.AddSeconds(30); + while (DateTime.UtcNow < reuseDeadline) + { + reuseStatus = await client.ResolveAndTrackOrderV2Async(orderId); + _output.WriteLine($"Poll (reuse path): orderId={orderId} status={reuseStatus.Status}"); + if (reuseStatus.Status != Constants.ApiV2.StatusPendingDcv) + break; + await Task.Delay(TimeSpan.FromSeconds(5)); + } + + reuseStatus.Should().NotBeNull(); + reuseStatus!.Status.Should().NotBe( + Constants.ApiV2.StatusPendingDcv, + $"order {orderId} must leave pending-dcv on a reused/already-verified domain (EMS-1080) " + + "without a fresh TXT challenge."); + return; + } + dcvResp.Should().NotBeNull(); + dcvResp.Token.Should().NotBeNullOrEmpty( + "GetDcvV2Async must return a TXT token in Token"); + + // The live response has no domainName field — the domain is already known + // locally from the order-placement request. + string domainName = _v2Domain; + + // 3. Publish TXT record + txtKey = $"_emudhra-challenge.{domainName}"; + _output.WriteLine($"Publishing TXT {txtKey} = {dcvResp.Token}"); + var staged = await dns.StageValidation(txtKey, dcvResp.Token, CancellationToken.None); + staged.Success.Should().BeTrue($"Cloudflare TXT record creation must succeed: {staged.ErrorMessage}"); + + // Brief propagation pause + await Task.Delay(TimeSpan.FromSeconds(5)); + + // 4. Ask CERTInext to verify + var verifyResp = await client.VerifyDcvV2Async(orderId, _v2Domain, Constants.ApiV2.FamilySsl); + verifyResp.Should().NotBeNull(); + verifyResp.OverallStatus.Should().Be("VERIFIED", + "VerifyDcvV2Async must return OverallStatus=VERIFIED after DNS record is published"); + + // 5. Poll until order leaves pending-dcv (up to 60s) + V2OrderStatusResponse finalStatus = null; + var deadline = DateTime.UtcNow.AddSeconds(60); + while (DateTime.UtcNow < deadline) + { + finalStatus = await client.ResolveAndTrackOrderV2Async(orderId); + _output.WriteLine($"Poll: orderId={orderId} status={finalStatus.Status}"); + if (finalStatus.Status != Constants.ApiV2.StatusPendingDcv) + break; + await Task.Delay(TimeSpan.FromSeconds(5)); + } + + finalStatus.Should().NotBeNull(); + finalStatus!.Status.Should().NotBe( + Constants.ApiV2.StatusPendingDcv, + "order must leave pending-dcv after successful DCV verification"); + } + finally + { + if (txtKey != null) + { + _output.WriteLine($"Cleaning up TXT record: {txtKey}"); + await dns.CleanupValidation(txtKey, CancellationToken.None); + } + } + } +#endif + + // --------------------------------------------------------------------------- + // Chain PEM assembly + // --------------------------------------------------------------------------- + + /// + /// Downloads the certificate for a known-issued V2 order and logs whether + /// ChainPem is populated. The test passes in either case — it is a + /// best-effort diagnostic to confirm chain assembly works in production. + /// Prefers CERTINEXT_V2_ISSUED_ORDER_ID; otherwise self-enrolls a fresh order + /// via . + /// + [SkippableTheory] + [V2PinModes] + public async Task ChainPem_V2_IsAssembled(V2PinMode mode) + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + + using var client = BuildV2Client(); + var (orderId, family) = await EnsureIssuedOrderIdAsync(client, mode); + + V2CertificateDownloadResponse downloadResp; + try + { + downloadResp = await client.DownloadCertificateV2Async(family, orderId); + } + catch (Exception ex) when (ex.Message.Contains("422") || ex.Message.Contains("Invalid request status")) + { + Skip.If(true, + $"Order {orderId} tracked as 'issued' but CA rejected download (sandbox timing): {ex.Message}"); + return; // unreachable; satisfies compiler + } + + downloadResp.Should().NotBeNull("DownloadCertificateV2Async must return a non-null response"); + downloadResp.CertificatePem.Should().NotBeNull( + "CertificatePem must be present for an issued order"); + downloadResp.CertificatePem.Should().StartWith( + "-----BEGIN CERTIFICATE-----", + "leaf certificate must be PEM-encoded"); + + bool chainPresent = downloadResp.ChainPem != null && downloadResp.ChainPem.Count > 0; + _output.WriteLine(chainPresent + ? $"ChainPem: {downloadResp.ChainPem!.Count} intermediate(s) returned." + : "ChainPem: null or empty — sandbox may not return chain."); + + if (chainPresent) + { + foreach (string chainCert in downloadResp.ChainPem!) + { + chainCert.Should().StartWith( + "-----BEGIN CERTIFICATE-----", + "each chain entry must be a PEM-encoded certificate"); + } + } + } + + // --------------------------------------------------------------------------- + // Private helpers + // --------------------------------------------------------------------------- + + private V2CreateSslOrderRequest BuildStandardOrderRequest() => + new V2CreateSslOrderRequest + { + ProductVariant = "dv", + EmailNotifications = "all", + Requestor = new V2Requestor + { + Name = _fixture.Config?.RequestorName ?? "Keyfactor Test", + Email = _fixture.Config?.RequestorEmail ?? "test@example.com", + Phone = "0000000000", + Designation = "IT Administrator" + }, + Certificate = new V2CertificateParams + { + Domain = _v2Domain, + AutoSecureWww = false + }, + Subscription = new V2SubscriptionParams + { + ValidityYears = 1, + AutoRenew = false, + RenewBeforeDays = 30 + }, + Agreement = new V2AgreementParams + { + SignerName = _fixture.Config?.RequestorName ?? "Keyfactor Test", + SignerPlace = "Gateway Lab", + Accepted = true + }, + Remarks = "Keyfactor V2 integration test — safe to revoke immediately.", + // Single-call create: the CSR goes inline on POST (a later PUT .../csr is rejected 422), + // so these raw-client orders issue exactly as a plugin Enroll would. + Csr = GenerateCsrPem(_v2Domain) + }; + + // --------------------------------------------------------------------------- + // Single-call create helpers + cleanup of every order this class places + // --------------------------------------------------------------------------- + + private readonly List _placedOrderIds = new List(); + + public Task InitializeAsync() => Task.CompletedTask; + + /// + /// Revokes (if issued) or cancels (if not yet terminal) every order placed through + /// . One attempt each (one retry for the sandbox's + /// "still being processed" revoke rejection); failures are logged, never thrown, so cleanup can + /// not mask the test's own result — revoke/cancel by hand in the portal if one is reported. + /// + public async Task DisposeAsync() + { + if (_placedOrderIds.Count == 0) return; + using var client = BuildV2Client(); + foreach (string orderId in _placedOrderIds) + { + try + { + var (family, status) = await ResolveOrderFamilyAsync(client, orderId); + string st = status.Status ?? string.Empty; + if (st == Constants.ApiV2.StatusRevoked || st == Constants.ApiV2.StatusCancelled + || st == Constants.ApiV2.StatusRejected) + { + _output.WriteLine($"Cleanup: order {orderId} already terminal ({st})."); + continue; + } + + if (st == Constants.ApiV2.StatusIssued) + { + var revokeReq = new V2RevokeRequest { Reason = "superseded", Note = "V2 integration test cleanup" }; + try { await client.RevokeOrderV2Async(family, orderId, revokeReq); } + catch (InvalidOperationException ex) when (ex.Message.Contains("still being processed")) + { + await Task.Delay(TimeSpan.FromSeconds(15)); + await client.RevokeOrderV2Async(family, orderId, revokeReq); + } + var after = await client.ResolveAndTrackOrderV2Async(orderId); + _output.WriteLine($"Cleanup: revoked issued order {orderId}; re-tracked status={after.Status}."); + } + else + { + var outcome = await client.CancelOrderV2Async(family, orderId, "V2 integration test cleanup"); + var after = await client.ResolveAndTrackOrderV2Async(orderId); + _output.WriteLine($"Cleanup: cancel of {orderId} (was {st}) -> {outcome}; re-tracked status={after.Status}."); + } + } + catch (Exception ex) + { + _output.WriteLine($"Cleanup FAILED for order {orderId}: {ex.GetType().Name}: {ex.Message}. " + + "Revoke/cancel it by hand in the CERTInext portal."); + } + } + } + + /// + /// Places the standard DV SSL order in : pinned sends the product code + /// (X-Product-Code), the V2 template sends none (productCode null omits the header) + /// and lets CERTInext resolve the product. Logs the mode and the response's + /// ResolvedProductCode (the product CERTInext actually picked). + /// + private async Task PlaceOrderTrackedAsync( + CERTInextClient client, V2CreateSslOrderRequest req, V2PinMode mode) + { + V2ProductPinning.Log(_output, Constants.Products.DvSsl, mode); + V2CreateOrderResponse resp; + try + { + resp = await client.PlaceOrderV2Async( + Constants.ApiV2.FamilySsl, V2ProductPinning.CodeSent(Constants.Products.DvSsl, mode), req); + } + catch (Exception ex) + { + _output.WriteLine($"{V2ProductPinning.Label(Constants.Products.DvSsl, mode)} order create FAILED: " + + $"{ex.GetType().Name}: {ex.Message}"); + throw; + } + + if (!string.IsNullOrWhiteSpace(resp?.OrderId)) + _placedOrderIds.Add(resp.OrderId); + V2ProductPinning.Log(_output, Constants.Products.DvSsl, mode, + resp?.ResolvedProductCode ?? "(not reported)"); + return resp; + } + + // BouncyCastle only (project crypto policy). + private static string GenerateCsrPem(string commonName) + { + var keyGen = new RsaKeyPairGenerator(); + keyGen.Init(new KeyGenerationParameters(new SecureRandom(), 2048)); + var keyPair = keyGen.GenerateKeyPair(); + var csr = new Pkcs10CertificationRequest( + "SHA256withRSA", new X509Name($"CN={commonName}"), keyPair.Public, null, keyPair.Private); + return "-----BEGIN CERTIFICATE REQUEST-----\n" + + Convert.ToBase64String(csr.GetEncoded(), Base64FormattingOptions.InsertLineBreaks) + + "\n-----END CERTIFICATE REQUEST-----"; + } + + private CERTInextClient BuildV2Client() + { + return new CERTInextClient(new CERTInextConfig + { + // A single ApiUrl serves V2 — no V1-only fields are set here. + ApiUrl = _v2ApiUrl, + UseV2Api = true, + OAuthClientId = _v2ClientId, + OAuthClientSecret = _v2ClientSecret, + RequestorName = _fixture.IsConfigured ? _fixture.Config.RequestorName : "Test", + RequestorEmail = _fixture.IsConfigured ? _fixture.Config.RequestorEmail : "test@example.com", + SignerIp = "127.0.0.1", + SignerPlace = "Gateway Lab", + PageSize = 100 + }); + } + + /// + /// Returns an issued V2 order (and the family it lives in) to exercise. Prefers + /// CERTINEXT_V2_ISSUED_ORDER_ID if set; otherwise places a fresh order on + /// and polls (bounded) until it reaches issued, so + /// tests using this helper are self-contained and don't depend on env state or + /// another test's run order. Skip.Ifs when + /// no env ID is set and the freshly-placed order never reaches issued within + /// the poll budget — sandboxes may require DCV to auto-issue. + /// + private async Task<(string orderId, string family)> EnsureIssuedOrderIdAsync(CERTInextClient client, V2PinMode mode) + { + // With an env order the test does not place one, so only the pinned row is meaningful. + V2ProductPinning.SkipUnpinnedWhenOrderSuppliedByEnv(mode, _issuedOrderId, "CERTINEXT_V2_ISSUED_ORDER_ID"); + if (!string.IsNullOrWhiteSpace(_issuedOrderId)) + { + var (family, status) = await ResolveOrderFamilyAsync(client, _issuedOrderId); + Skip.If(status.Status != Constants.ApiV2.StatusIssued, + $"Order '{_issuedOrderId}' is in '{status.Status}' state, not 'issued' — skipping."); + return (_issuedOrderId, family); + } + + var orderReq = BuildStandardOrderRequest(); + var createResp = await PlaceOrderTrackedAsync(client, orderReq, mode); + createResp.Should().NotBeNull(); + string orderId = createResp.OrderId; + orderId.Should().NotBeNullOrEmpty("PlaceOrderV2Async must return a non-empty orderId"); + _output.WriteLine( + $"EnsureIssuedOrderIdAsync: no CERTINEXT_V2_ISSUED_ORDER_ID set — placed fresh order {orderId}."); + + V2OrderStatusResponse trackResp = null; + var deadline = DateTime.UtcNow.AddSeconds(90); + while (DateTime.UtcNow < deadline) + { + trackResp = await client.TrackOrderV2Async(Constants.ApiV2.FamilySsl, orderId); + _output.WriteLine($"EnsureIssuedOrderIdAsync poll: orderId={orderId} status={trackResp.Status}"); + if (trackResp.Status == Constants.ApiV2.StatusIssued) + break; + await Task.Delay(TimeSpan.FromSeconds(15)); + } + + Skip.If(trackResp?.Status != Constants.ApiV2.StatusIssued, + $"Freshly-placed order '{orderId}' did not reach 'issued' within the poll budget " + + $"(status={trackResp?.Status}) — sandbox may require DCV to auto-issue. Set " + + "CERTINEXT_V2_ISSUED_ORDER_ID to a known-issued order to bypass placement."); + + return (orderId, Constants.ApiV2.FamilySsl); + } + + private static async Task<(string family, V2OrderStatusResponse status)> ResolveOrderFamilyAsync( + CERTInextClient client, string orderId) + { + foreach (var family in new[] { Constants.ApiV2.FamilySsl, Constants.ApiV2.FamilyPrivatePki, Constants.ApiV2.FamilySignature }) + { + try + { + var s = await client.TrackOrderV2Async(family, orderId); + return (family, s); + } + catch (KeyNotFoundException) + { + // try next + } + } + throw new KeyNotFoundException($"Order '{orderId}' not found in any V2 product family."); + } + + } +} diff --git a/CERTInext.IntegrationTests/V2DcvLifecycleTests.cs b/CERTInext.IntegrationTests/V2DcvLifecycleTests.cs new file mode 100644 index 0000000..43aa9f3 --- /dev/null +++ b/CERTInext.IntegrationTests/V2DcvLifecycleTests.cs @@ -0,0 +1,646 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +#if SUPPORTS_DCV +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Linq; +using System.Threading; +using System.Threading.Tasks; +using Org.BouncyCastle.Asn1.X509; +using Org.BouncyCastle.Crypto; +using Org.BouncyCastle.Crypto.Generators; +using Org.BouncyCastle.Crypto.Parameters; +using Org.BouncyCastle.Pkcs; +using Org.BouncyCastle.Security; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Xunit; +using Xunit.Abstractions; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.IntegrationTests +{ + /// + /// Plugin-level DCV integration tests for the V2 (OAuth2) API path (gaps 5-8, 14-15). + /// Mirrors 's structure for V1: uses a real + /// when Cloudflare credentials are + /// configured, otherwise a . + /// + /// Requires the SUPPORTS_DCV build (-p:DcvSupport=true) because it uses + /// the v3.3-only constructor. Excluded from the + /// no-DCV build via the test project's <Compile Remove> item group. + /// + public class V2DcvLifecycleTests : IClassFixture, IDisposable + { + private readonly IntegrationTestFixture _fixture; + private readonly ITestOutputHelper _output; + private readonly List _toDispose = new List(); + + private readonly string _v2ApiUrl; + private readonly string _v2ClientId; + private readonly string _v2ClientSecret; + private readonly string _v2Domain; + private readonly bool _v2Enabled; + private readonly string _cfApiToken; + private readonly string _cfZoneId; + private readonly bool _dcvEnabled; + + public V2DcvLifecycleTests(IntegrationTestFixture fixture, ITestOutputHelper output) + { + _fixture = fixture; + _output = output; + + var env = V2EnvHelper.LoadAndPromote(); + + _v2ApiUrl = V2EnvHelper.GetEnv(env, "CERTINEXT_API_URL"); + _v2ClientId = V2EnvHelper.GetEnv(env, "CERTINEXT_CLIENT_ID"); + _v2ClientSecret = V2EnvHelper.GetEnv(env, "CERTINEXT_CLIENT_SECRET"); + _v2Domain = V2EnvHelper.GetEnv(env, "CERTINEXT_DCV_DOMAIN", "test.example.com"); + _cfApiToken = V2EnvHelper.GetEnv(env, "CERTINEXT_CF_API_TOKEN"); + _cfZoneId = V2EnvHelper.GetEnv(env, "CERTINEXT_CF_ZONE_ID"); + + _v2Enabled = !string.IsNullOrWhiteSpace(V2EnvHelper.GetEnv(env, "CERTINEXT_USE_V2_API")) + && !string.IsNullOrWhiteSpace(_v2ApiUrl) + && !string.IsNullOrWhiteSpace(_v2ClientId) + && !string.IsNullOrWhiteSpace(_v2ClientSecret); + + _dcvEnabled = _v2Enabled + && !string.IsNullOrWhiteSpace(_cfApiToken) + && !string.IsNullOrWhiteSpace(_cfZoneId); + } + + public void Dispose() + { + foreach (var d in _toDispose) + d.Dispose(); + _toDispose.Clear(); + } + + // --------------------------------------------------------------------------- + // Helpers + // --------------------------------------------------------------------------- + + private static string GenerateCsrPem(string commonName) + { + var keyGen = new RsaKeyPairGenerator(); + keyGen.Init(new KeyGenerationParameters(new SecureRandom(), 2048)); + var keyPair = keyGen.GenerateKeyPair(); + + var subject = new X509Name($"CN={commonName}"); + var csr = new Pkcs10CertificationRequest("SHA256withRSA", subject, keyPair.Public, null, keyPair.Private); + + return "-----BEGIN CERTIFICATE REQUEST-----\n" + + Convert.ToBase64String(csr.GetEncoded(), Base64FormattingOptions.InsertLineBreaks) + + "\n-----END CERTIFICATE REQUEST-----"; + } + + private static async Task> RunSyncAsync( + CERTInextCAPlugin plugin, DateTime? lastSync = null, bool fullSync = true) + { + var buffer = new BlockingCollection(boundedCapacity: 10_000); + var collected = new List(); + + var syncTask = Task.Run(async () => + { + await plugin.Synchronize(buffer, lastSync: lastSync, fullSync: fullSync, cancelToken: CancellationToken.None); + if (!buffer.IsAddingCompleted) + buffer.CompleteAdding(); + }); + + foreach (var record in buffer.GetConsumingEnumerable()) + collected.Add(record); + + await syncTask; + return collected; + } + + private IDomainValidatorFactory BuildV2DnsFactory() + { + if (_dcvEnabled) + { + var factory = new CloudflareDomainValidatorFactory(_cfApiToken, _cfZoneId); + _toDispose.Add(factory); + return factory; + } + return new StubDomainValidatorFactory(); + } + + /// + /// Builds a wired for the V2 API. A single + /// serves both modes, and V2 auth reuses + /// /. + /// Deliberately omits every V1-only field (ApiKey/AccountNumber/AuthMode) — V1 + /// credentials are optional when UseV2Api is true, including for Synchronize + /// (which uses V2 /reports/orders). + /// + private CERTInextConfig BuildV2Config( + bool dcvEnabled = true, int propagationDelaySeconds = 5, int? pageSize = null, int? syncLookbackHours = null) + { + return new CERTInextConfig + { + ApiUrl = _v2ApiUrl, + UseV2Api = true, + V2InlineCsr = V2EnvHelper.InlineCsrFromEnv, // default single-call; CERTINEXT_V2_INLINE_CSR=0 selects two-call + OAuthClientId = _v2ClientId, + OAuthClientSecret = _v2ClientSecret, + + // Default 72h (Constants.ApiV2.DefaultSyncLookbackHours) is always added on top + // of lastSync — on a busy shared sandbox that makes an un-narrowed delta sync + // slow, since every issued row costs a live certificate download. Narrow via + // syncLookbackHours in tests that don't need the full margin. + V2SyncLookbackHours = syncLookbackHours ?? Constants.ApiV2.DefaultSyncLookbackHours, + + RequestorName = _fixture.IsConfigured ? _fixture.Config.RequestorName : "Keyfactor Test", + RequestorEmail = _fixture.IsConfigured ? _fixture.Config.RequestorEmail : "test@example.com", + RequestorIsdCode = "1", + RequestorMobileNumber = "0000000000", + SignerPlace = "Gateway Lab", + SignerIp = "127.0.0.1", + + PageSize = pageSize ?? 100, + + DcvEnabled = dcvEnabled, + DcvPropagationDelaySeconds = propagationDelaySeconds, + DcvTimeoutMinutes = 3 + }; + } + + /// + /// Builds a plugin wired for the V2 API with a real DNS factory injected via the + /// v3.3-only three-arg test constructor, so EnrollV2Async / + /// GetSingleRecordV2Async can drive DCV inline. + /// + private CERTInextCAPlugin BuildV2DcvPlugin( + bool dcvEnabled = true, int propagationDelaySeconds = 5, int? pageSize = null, int? syncLookbackHours = null) + { + var config = BuildV2Config(dcvEnabled, propagationDelaySeconds, pageSize, syncLookbackHours); + var client = new CERTInextClient(config); + return new CERTInextCAPlugin(client, BuildV2DnsFactory(), config); + } + + /// + /// Product info for the "DV SSL" gateway template in : pinned + /// (ProductCode set, e.g. 842) or the unpinned "V2 template" (no ProductCode, so + /// CERTInext resolves the product). See . + /// + private static EnrollmentProductInfo BuildV2ProductInfo(V2PinMode mode) => + V2ProductPinning.Info(Constants.Products.DvSsl, mode); + + /// + /// Parses an issued certificate PEM and asserts its public key matches the requested + /// algorithm/size. Copy of the equivalent helper in . + /// + private static void AssertIssuedCertMatchesAlgorithm(string certPem, KeyAlgorithmSpec spec, string tag) + { + var b64 = certPem + .Replace("-----BEGIN CERTIFICATE-----", string.Empty) + .Replace("-----END CERTIFICATE-----", string.Empty) + .Replace("\r", string.Empty).Replace("\n", string.Empty).Trim(); + + var cert = new Org.BouncyCastle.X509.X509CertificateParser().ReadCertificate(Convert.FromBase64String(b64)); + cert.Should().NotBeNull($"{tag}: issued cert PEM must parse"); + + var pub = cert.GetPublicKey(); + switch (spec.Kind) + { + case KeyKind.Rsa: + pub.Should().BeOfType(); + ((RsaKeyParameters)pub).Modulus.BitLength.Should().Be(spec.Strength, + $"{tag}: issued RSA cert must have a {spec.Strength}-bit modulus"); + break; + case KeyKind.Ecdsa: + pub.Should().BeOfType(); + ((ECPublicKeyParameters)pub).Parameters.Curve.FieldSize.Should().Be(spec.Strength, + $"{tag}: issued EC cert must use a {spec.Strength}-bit curve"); + break; + case KeyKind.Ed25519: + pub.Should().BeOfType(); + break; + case KeyKind.Ed448: + pub.Should().BeOfType(); + break; + } + } + + // --------------------------------------------------------------------------- + // Enroll with DCV on, V2 path, does not throw + // --------------------------------------------------------------------------- + + [SkippableTheory] + [V2PinModes] + public async Task DcvEnroll_V2_CompletesWithoutThrowing(V2PinMode mode) + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + V2ProductPinning.Log(_output, Constants.Products.DvSsl, mode); + + var config = BuildV2Config(dcvEnabled: true); + using var probeClient = new CERTInextClient(config); + var (domainVerified, rawStatus) = await V2DomainStatusHelper.GetDcvStatusAsync(probeClient, _v2Domain); + _output.WriteLine($"Pre-enroll domain status for '{_v2Domain}': dcvStatus={rawStatus ?? ""}"); + + var recordingFactory = new RecordingDomainValidatorFactory(BuildV2DnsFactory()); + var plugin = new CERTInextCAPlugin(new CERTInextClient(config), recordingFactory, config); + + var result = await plugin.Enroll( + csr: GenerateCsrPem(_v2Domain), + subject: $"CN={_v2Domain}", + san: new Dictionary { ["dns"] = new[] { _v2Domain } }, + productInfo: BuildV2ProductInfo(mode), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.Should().NotBeNull("Enroll must return a result even when DCV verification does not complete inline"); + _output.WriteLine($"CARequestID: {result.CARequestID}"); + _output.WriteLine($"Status: {result.Status}"); + _output.WriteLine($"Message: {result.StatusMessage}"); + + var staged = recordingFactory.StagedCalls; + var cleaned = recordingFactory.CleanedUpFqdns; + _output.WriteLine($"DNS provider calls: staged={staged.Count}, cleaned={cleaned.Count}"); + + if (domainVerified) + { + // Reuse path: the domain is already verified account-wide, so no fresh TXT + // record should ever be staged for it. + staged.Should().BeEmpty( + $"domain '{_v2Domain}' was already VERIFIED before enrollment (reuse path) — no TXT record " + + "should be staged. The plugin must treat the CA's EMS-1080 'already verified' response as " + + "satisfied rather than as a failure requiring a deferred retry."); + new[] { (int)EndEntityStatus.EXTERNALVALIDATION, (int)EndEntityStatus.GENERATED } + .Should().Contain(result.Status, + $"a reused, already-verified domain must let the order proceed to pending or issued; " + + $"got {result.Status}. Message: {result.StatusMessage}"); + } + else + { + // Publish path: a fresh challenge must actually get staged and cleaned up. + staged.Should().NotBeEmpty( + $"domain '{_v2Domain}' was not yet VERIFIED (dcvStatus={rawStatus ?? ""}) — Enroll " + + "must stage a TXT record to exercise the publish path."); + cleaned.Should().NotBeEmpty( + "a staged DCV TXT record must be cleaned up after the publish-path attempt."); + } + } + + // --------------------------------------------------------------------------- + // Enroll with DCV off, V2 path, does not invoke the DNS provider + // --------------------------------------------------------------------------- + + [SkippableTheory] + [V2PinModes] + public async Task EnrollWithoutDcv_V2_DoesNotInvokeDnsProvider(V2PinMode mode) + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + V2ProductPinning.Log(_output, Constants.Products.DvSsl, mode); + + var config = BuildV2Config(dcvEnabled: false); + var recordingFactory = new RecordingDomainValidatorFactory(BuildV2DnsFactory()); + var plugin = new CERTInextCAPlugin(new CERTInextClient(config), recordingFactory, config); + + var result = await plugin.Enroll( + csr: GenerateCsrPem(_v2Domain), + subject: $"CN={_v2Domain}", + san: new Dictionary { ["dns"] = new[] { _v2Domain } }, + productInfo: BuildV2ProductInfo(mode), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.Should().NotBeNull(); + result.CARequestID.Should().NotBeNullOrWhiteSpace( + "the CA must accept the order even with DCV off — DCV-off must not block enrollment"); + + recordingFactory.StagedCalls.Should().BeEmpty( + "with DcvEnabled=false the plugin must never stage a DCV TXT record — this test's name promised " + + "that, but nothing previously checked it"); + recordingFactory.CleanedUpFqdns.Should().BeEmpty( + "with DcvEnabled=false the plugin must never attempt DCV cleanup either"); + } + + // --------------------------------------------------------------------------- + // GetSingleRecord drives DCV for an existing pending V2 order + // --------------------------------------------------------------------------- + + [SkippableFact] + public async Task GetSingleRecord_V2_DrivesDcvForPendingOrder() + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + + string orderId = Environment.GetEnvironmentVariable("CERTINEXT_V2_PENDING_ORDER_ID"); + Skip.If(string.IsNullOrWhiteSpace(orderId), + "Set CERTINEXT_V2_PENDING_ORDER_ID to a real pending-dcv V2 order to run this test."); + Skip.If(!_dcvEnabled, + "CERTINEXT_CF_API_TOKEN and CERTINEXT_CF_ZONE_ID must be set so the plugin can publish a real TXT record."); + + // Route plugin/client logs to the test output: the V2 DCV path has many quiet early exits + // (no challenge, no validator, stage failure...) that are otherwise invisible from a test. + // Must be set before the plugin is constructed — its logger is created in the field initializer. + var restoreLogging = TestOutputLogging.RouteTo(_output); + AnyCAPluginCertificate record; + try + { + var plugin = BuildV2DcvPlugin(dcvEnabled: true); + record = await plugin.GetSingleRecord(orderId); + } + finally + { + restoreLogging(); + } + + record.Should().NotBeNull(); + _output.WriteLine($"CARequestID: {record.CARequestID}"); + _output.WriteLine($"Status: {record.Status}"); + + new[] { (int)EndEntityStatus.GENERATED, (int)EndEntityStatus.EXTERNALVALIDATION } + .Should().Contain(record.Status, + "deferred-DCV retry should leave the V2 order in a valid pending or issued state"); + } + + // --------------------------------------------------------------------------- + // End-to-end DCV-on enrollment, issued cert appears in sync + // --------------------------------------------------------------------------- + + [SkippableTheory] + [V2PinModes] + public async Task EnrollWithDcvOn_V2_OrderIssuedEndToEnd_AndAppearsInSync(V2PinMode mode) + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + V2ProductPinning.Log(_output, Constants.Products.DvSsl, mode); + Skip.If(!_dcvEnabled, + "CERTINEXT_CF_API_TOKEN + CERTINEXT_CF_ZONE_ID required — DCV-on test must publish real TXT records."); + + var config = BuildV2Config(dcvEnabled: true); + using var probeClient = new CERTInextClient(config); + var (domainVerified, rawStatus) = await V2DomainStatusHelper.GetDcvStatusAsync(probeClient, _v2Domain); + _output.WriteLine($"Pre-enroll domain status for '{_v2Domain}': dcvStatus={rawStatus ?? ""}"); + + var recordingFactory = new RecordingDomainValidatorFactory(BuildV2DnsFactory()); + var plugin = new CERTInextCAPlugin(new CERTInextClient(config), recordingFactory, config); + + var enrollResult = await plugin.Enroll( + csr: GenerateCsrPem(_v2Domain), + subject: $"CN={_v2Domain}", + san: new Dictionary { ["dns"] = new[] { _v2Domain } }, + productInfo: BuildV2ProductInfo(mode), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + enrollResult.Should().NotBeNull(); + enrollResult.CARequestID.Should().NotBeNullOrWhiteSpace(); + _output.WriteLine($"Enroll CARequestID={enrollResult.CARequestID}, Status={enrollResult.Status}"); + + new[] { (int)EndEntityStatus.EXTERNALVALIDATION, (int)EndEntityStatus.GENERATED } + .Should().Contain(enrollResult.Status, + $"DCV-on V2 Enroll must return pending or issued; got {enrollResult.Status}"); + + var staged = recordingFactory.StagedCalls; + var cleaned = recordingFactory.CleanedUpFqdns; + _output.WriteLine($"DNS provider calls: staged={staged.Count}, cleaned={cleaned.Count}"); + + if (domainVerified) + { + // Reuse path: no fresh TXT record should be staged for an already-verified + // domain. + staged.Should().BeEmpty( + $"domain '{_v2Domain}' was already VERIFIED before enrollment (reuse path) — no TXT record " + + "should be staged."); + } + else + { + staged.Should().NotBeEmpty( + $"domain '{_v2Domain}' was not yet VERIFIED (dcvStatus={rawStatus ?? ""}) — Enroll " + + "must stage a TXT record to exercise the publish path."); + cleaned.Should().NotBeEmpty( + "a staged DCV TXT record must be cleaned up after the publish-path attempt."); + } + + // Delta sync — this sandbox account has 1000+ historical orders. + var synced = await RunSyncAsync(plugin, lastSync: DateTime.UtcNow.AddDays(-1), fullSync: false); + var record = synced.FirstOrDefault(r => r.CARequestID == enrollResult.CARequestID); + record.Should().NotBeNull( + $"the enrolled V2 order ({enrollResult.CARequestID}) must appear in plugin.Synchronize results"); + + _output.WriteLine($"Synced record status: {record!.Status}"); + + if (record.Status == (int)EndEntityStatus.GENERATED) + { + record.Certificate.Should().NotBeNullOrWhiteSpace( + "Synchronize must populate the cert body for an issued V2 order (mirroring V1 behavior)"); + } + } + + // --------------------------------------------------------------------------- + // Key-algorithm issuance matrix, V2 path (opt-in) + // --------------------------------------------------------------------------- + + [SkippableTheory] + [V2PinModesWithKeyAlgorithms] + public async Task EnrollWithDcvOn_V2_IssuesPerKeyAlgorithm(string tag, V2PinMode mode) + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + V2ProductPinning.Log(_output, Constants.Products.DvSsl, mode); + Skip.If(Environment.GetEnvironmentVariable("CERTINEXT_V2_ALGO_MATRIX") != "1", + "Opt-in: set CERTINEXT_V2_ALGO_MATRIX=1 to issue one real V2 cert per key algorithm."); + Skip.If(!_dcvEnabled, + "CERTINEXT_CF_API_TOKEN + CERTINEXT_CF_ZONE_ID required — DCV issuance must publish real TXT records."); + + var spec = KeyAlgorithms.For(tag); + string suffix = Guid.NewGuid().ToString("N").Substring(0, 8); + string cn = $"algo-{KeyAlgorithms.Slug(tag)}-{suffix}.{_v2Domain}"; + string csr = KeyAlgorithms.GenerateCsrPem(cn, spec); + + var plugin = BuildV2DcvPlugin(dcvEnabled: true); + + EnrollmentResult enrollResult; + try + { + enrollResult = await plugin.Enroll( + csr: csr, + subject: $"CN={cn}", + san: new Dictionary { ["dns"] = new[] { cn } }, + productInfo: BuildV2ProductInfo(mode), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + } + catch (Exception ex) + { + string reason = KeyAlgorithms.ClassifyRejection(ex.Message); + _output.WriteLine($"[SKIP] {tag}: {reason} — {ex.Message}"); + Skip.If(true, $"CERTInext did not issue a {tag} V2 cert: {reason}. CA message: {ex.Message}"); + return; // unreachable + } + + enrollResult.Should().NotBeNull(); + enrollResult.CARequestID.Should().NotBeNullOrWhiteSpace($"{tag}: CA must return a CARequestID when it accepts the order"); + _output.WriteLine($"[{tag}] enrolled cn={cn} id={enrollResult.CARequestID} status={enrollResult.Status}"); + + const int maxPolls = 6; + const int delaySeconds = 15; + AnyCAPluginCertificate record = null; + for (int poll = 1; poll <= maxPolls; poll++) + { + record = await plugin.GetSingleRecord(enrollResult.CARequestID); + int status = record?.Status ?? -1; + _output.WriteLine($"[{tag}] poll #{poll}: status={status} certLen={record?.Certificate?.Length ?? 0}"); + + if (status == (int)EndEntityStatus.GENERATED && !string.IsNullOrWhiteSpace(record?.Certificate)) + break; + if (status == (int)EndEntityStatus.FAILED) + { + Skip.If(true, $"CERTInext FAILED the {tag} V2 order — algorithm not issuable on this account/profile."); + return; // unreachable + } + if (poll < maxPolls) + await Task.Delay(TimeSpan.FromSeconds(delaySeconds)); + } + + record.Should().NotBeNull($"{tag}: enrolled order {enrollResult.CARequestID} must be retrievable"); + if (record!.Status != (int)EndEntityStatus.GENERATED) + { + Skip.If(true, $"CERTInext accepted the {tag} V2 order but it did not reach GENERATED within the polling window " + + $"(Status={record.Status})."); + return; // unreachable + } + + record.Certificate.Should().NotBeNullOrWhiteSpace($"{tag}: issued V2 cert must carry a PEM body"); + AssertIssuedCertMatchesAlgorithm(record.Certificate, spec, tag); + _output.WriteLine($"--- {tag}: V2 DCV-on issuance OK — order {enrollResult.CARequestID} GENERATED. ---"); + } + + // --------------------------------------------------------------------------- + // Bulk V2 enrollment + pagination smoke test (opt-in) + // --------------------------------------------------------------------------- + + [SkippableFact] + public async Task BulkV2Enrollment_AllOrdersIssue_AndPaginationWorks() + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + Skip.If(Environment.GetEnvironmentVariable("CERTINEXT_V2_RUN_BULK_TEST") != "1", + "Opt-in: set CERTINEXT_V2_RUN_BULK_TEST=1 to run the V2 volume/pagination test."); + Skip.If(!_dcvEnabled, + "CERTINEXT_CF_API_TOKEN + CERTINEXT_CF_ZONE_ID required — bulk test must publish real TXT records."); + + int count = int.TryParse(Environment.GetEnvironmentVariable("CERTINEXT_V2_BULK_TEST_COUNT"), out int c) ? c : 101; + int parallel = int.TryParse(Environment.GetEnvironmentVariable("CERTINEXT_V2_BULK_TEST_PARALLEL"), out int p) ? p : 5; + + // PageSize=100 ensures the 101st order forces a second page during Synchronize. + // Since this plugin is UseV2Api=true, Synchronize pages through V2 + // /reports/orders (ListOrdersV2Async) rather than V1 GetOrderReport — + // this is the live pagination proof for that path, not just the WireMock-based + // client unit tests. + // syncLookbackHours narrowed to 2h: the default 72h margin would otherwise re-download + // every issued cert in a multi-day window on EACH of the (up to 8) sync passes below, + // compounded by the retry loop. + // Volume/pagination test (101 orders): deliberately NOT doubled by pin mode. Product resolution is + // not what it exercises, and a second pass would place another 101 sandbox orders. Runs pinned. + var plugin = BuildV2DcvPlugin(dcvEnabled: true, propagationDelaySeconds: 5, pageSize: 100, syncLookbackHours: 2); + + var enrolled = new ConcurrentBag<(int idx, string cn, EnrollmentResult result)>(); + var failures = new ConcurrentBag<(int idx, string error)>(); + var sw = System.Diagnostics.Stopwatch.StartNew(); + + using (var sem = new SemaphoreSlim(parallel, parallel)) + { + var tasks = Enumerable.Range(0, count).Select(async i => + { + await sem.WaitAsync(); + try + { + string suffix = Guid.NewGuid().ToString("N").Substring(0, 8); + string cn = $"v2bulk-{suffix}.{_v2Domain}"; + string csr = GenerateCsrPem(cn); + + var result = await plugin.Enroll( + csr: csr, + subject: $"CN={cn}", + san: new Dictionary { ["dns"] = new[] { cn } }, + productInfo: BuildV2ProductInfo(V2PinMode.Pinned), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + enrolled.Add((i, cn, result)); + _output.WriteLine($"[{i:000}] OK cn={cn} id={result.CARequestID} status={result.Status}"); + } + catch (Exception ex) + { + failures.Add((i, ex.Message)); + _output.WriteLine($"[{i:000}] FAIL {ex.GetType().Name}: {ex.Message}"); + } + finally + { + sem.Release(); + } + }); + await Task.WhenAll(tasks); + } + + sw.Stop(); + _output.WriteLine($"--- Enroll phase: enrolled={enrolled.Count}, failed={failures.Count}, elapsed={sw.Elapsed:mm\\:ss} ---"); + + failures.Should().BeEmpty($"every V2 Enroll() call must succeed; got {failures.Count} hard failures."); + enrolled.Count.Should().Be(count, $"expected {count} successful V2 Enroll() calls"); + + var enrolledIds = enrolled + .Where(e => !string.IsNullOrEmpty(e.result.CARequestID)) + .Select(e => e.result.CARequestID) + .ToHashSet(); + enrolledIds.Count.Should().Be(count, "every V2 enrollment must return a CARequestID"); + + const int maxSyncPasses = 8; + const int delayBetweenPassesSeconds = 30; + + List synced = null; + int passesUsed = 0; + + for (int pass = 1; pass <= maxSyncPasses; pass++) + { + passesUsed = pass; + synced = await RunSyncAsync(plugin, lastSync: DateTime.UtcNow.AddDays(-1), fullSync: false); + + int generated = synced.Count(r => enrolledIds.Contains(r.CARequestID) && r.Status == (int)EndEntityStatus.GENERATED); + int failed = synced.Count(r => enrolledIds.Contains(r.CARequestID) && r.Status == (int)EndEntityStatus.FAILED); + int pending = enrolledIds.Count - generated - failed; + + _output.WriteLine($"--- Sync pass #{pass}: {generated}/{enrolledIds.Count} GENERATED, {failed} FAILED, {pending} pending ---"); + + if (failed > 0) + { + var failedIds = synced + .Where(r => enrolledIds.Contains(r.CARequestID) && r.Status == (int)EndEntityStatus.FAILED) + .Select(r => r.CARequestID) + .Take(5); + Assert.Fail($"Pass #{pass}: {failed} V2 order(s) reached FAILED status: {string.Join(", ", failedIds)}"); + } + + if (pending == 0) + break; + + if (pass < maxSyncPasses) + await Task.Delay(TimeSpan.FromSeconds(delayBetweenPassesSeconds)); + } + + var syncedIds = synced!.Select(r => r.CARequestID).ToHashSet(); + var missing = enrolledIds.Where(id => !syncedIds.Contains(id)).ToList(); + missing.Should().BeEmpty( + $"{missing.Count} enrolled V2 orders did not appear in sync results: {string.Join(", ", missing.Take(5))}"); + + var lookup = synced!.Where(r => r.CARequestID != null).ToDictionary(r => r.CARequestID, r => r); + var notIssued = enrolledIds + .Where(id => lookup.TryGetValue(id, out var rec) && rec.Status != (int)EndEntityStatus.GENERATED) + .Select(id => lookup[id]) + .ToList(); + + notIssued.Should().BeEmpty( + $"every enrolled V2 order should auto-issue after {maxSyncPasses} sync passes; {notIssued.Count} did not."); + + _output.WriteLine($"--- SUCCESS: {count}/{count} V2 orders enrolled and issued in {passesUsed} sync pass(es). ---"); + } + } +} +#endif diff --git a/CERTInext.IntegrationTests/V2DomainStatusHelper.cs b/CERTInext.IntegrationTests/V2DomainStatusHelper.cs new file mode 100644 index 0000000..9340e6b --- /dev/null +++ b/CERTInext.IntegrationTests/V2DomainStatusHelper.cs @@ -0,0 +1,58 @@ +// Copyright 2026 Keyfactor +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; +using System.Text.Json; +using System.Threading.Tasks; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.IntegrationTests +{ + /// + /// Read-only helper for querying GET /api/certinext/v2/domains?search=&exactMatch=true + /// via the existing escape hatch, so DCV-on V2 + /// tests can tell the reuse path (domain already VERIFIED) apart from the publish path + /// before asserting what the DNS provider spy should have recorded. + /// + internal static class V2DomainStatusHelper + { + /// + /// Returns whether currently has dcvStatus=VERIFIED, plus + /// the raw dcvStatus string (null if the domain has no row at all, e.g. never + /// submitted on any order yet). + /// + public static async Task<(bool IsVerified, string RawStatus)> GetDcvStatusAsync( + CERTInextClient client, string domain) + { + string query = $"/api/certinext/v2/domains?search={Uri.EscapeDataString(domain)}&exactMatch=true"; + var (statusCode, _, content) = await client.ProbeV2GetAsync(query); + + // A failed lookup must not masquerade as "not verified" — that would steer the caller + // into asserting the publish path for the wrong reason. + if (statusCode != 200 || string.IsNullOrWhiteSpace(content)) + throw new InvalidOperationException( + $"GET /domains lookup for '{domain}' failed: HTTP {statusCode}; cannot tell reuse path from publish path."); + + using var doc = JsonDocument.Parse(content); + if (!doc.RootElement.TryGetProperty("content", out var arr) + || arr.ValueKind != JsonValueKind.Array + || arr.GetArrayLength() == 0) + return (false, null); + + var row = arr[0]; + string dcvStatus = row.TryGetProperty("dcvStatus", out var v) ? v.GetString() : null; + return (string.Equals(dcvStatus, "VERIFIED", StringComparison.OrdinalIgnoreCase), dcvStatus); + } + } +} diff --git a/CERTInext.IntegrationTests/V2FreshDomainDcvLifecycleTests.cs b/CERTInext.IntegrationTests/V2FreshDomainDcvLifecycleTests.cs new file mode 100644 index 0000000..369c03f --- /dev/null +++ b/CERTInext.IntegrationTests/V2FreshDomainDcvLifecycleTests.cs @@ -0,0 +1,388 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. +// +// V2 release-candidate readiness: DCV against a FRESH, never-before-seen domain. Every DCV +// test in V2DcvLifecycleTests.cs targets CERTINEXT_DCV_DOMAIN, which this sandbox account has +// reused across dozens of prior test runs and is therefore typically already VERIFIED +// account-wide — so those tests take the reuse path (staged=0) and never actually exercise +// the TXT publish/verify/cleanup path. This file's test targets a freshly-generated subdomain +// instead, so a real TXT challenge must be staged and cleaned up (staged>0). + +#if SUPPORTS_DCV +using System; +using System.Collections.Generic; +using System.Linq; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Org.BouncyCastle.Asn1.X509; +using Org.BouncyCastle.Crypto; +using Org.BouncyCastle.Crypto.Generators; +using Org.BouncyCastle.Pkcs; +using Org.BouncyCastle.Security; +using Xunit; +using Xunit.Abstractions; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.IntegrationTests +{ + public class V2FreshDomainDcvLifecycleTests : IClassFixture, IDisposable + { + private readonly IntegrationTestFixture _fixture; + private readonly ITestOutputHelper _output; + private readonly List _toDispose = new List(); + + private readonly string _v2ApiUrl; + private readonly string _v2ClientId; + private readonly string _v2ClientSecret; + private readonly string _v2Domain; + private readonly string _freshDcvParent; + private readonly bool _v2Enabled; + private readonly string _cfApiToken; + private readonly string _cfZoneId; + private readonly bool _dcvEnabled; + + public V2FreshDomainDcvLifecycleTests(IntegrationTestFixture fixture, ITestOutputHelper output) + { + _fixture = fixture; + _output = output; + + var env = V2EnvHelper.LoadAndPromote(); + + _v2ApiUrl = V2EnvHelper.GetEnv(env, "CERTINEXT_API_URL"); + _v2ClientId = V2EnvHelper.GetEnv(env, "CERTINEXT_CLIENT_ID"); + _v2ClientSecret = V2EnvHelper.GetEnv(env, "CERTINEXT_CLIENT_SECRET"); + _v2Domain = V2EnvHelper.GetEnv(env, "CERTINEXT_DCV_DOMAIN", "test.example.com"); + _cfApiToken = V2EnvHelper.GetEnv(env, "CERTINEXT_CF_API_TOKEN"); + _cfZoneId = V2EnvHelper.GetEnv(env, "CERTINEXT_CF_ZONE_ID"); + + // A fresh subdomain of CERTINEXT_DCV_DOMAIN is NOT genuinely unverified — this + // sandbox account has already completed DCV for CERTINEXT_DCV_DOMAIN itself, and + // CERTInext (like most DCV implementations) treats that as covering every + // subdomain beneath it. A dcv-fresh- name built under CERTINEXT_DCV_DOMAIN + // therefore never actually exercises the publish path (staged stays 0) — it is + // simply inheriting the parent's prior verification. A sibling domain under a + // DIFFERENT, still-unverified parent is required instead. Defaults to + // CERTINEXT_DCV_DOMAIN with its first label stripped (e.g. + // "dcv-test.scrup.org" -> "scrup.org"), which this sandbox account has never + // itself completed DCV against. + _freshDcvParent = V2EnvHelper.GetEnv(env, "CERTINEXT_V2_FRESH_DCV_PARENT", DeriveDefaultFreshDcvParent(_v2Domain)); + + _v2Enabled = !string.IsNullOrWhiteSpace(V2EnvHelper.GetEnv(env, "CERTINEXT_USE_V2_API")) + && !string.IsNullOrWhiteSpace(_v2ApiUrl) + && !string.IsNullOrWhiteSpace(_v2ClientId) + && !string.IsNullOrWhiteSpace(_v2ClientSecret); + + _dcvEnabled = _v2Enabled + && !string.IsNullOrWhiteSpace(_cfApiToken) + && !string.IsNullOrWhiteSpace(_cfZoneId); + } + + /// + /// Strips the first DNS label from (e.g. + /// "dcv-test.scrup.org" -> "scrup.org") to derive a default value for + /// CERTINEXT_V2_FRESH_DCV_PARENT when it is unset — a sibling built under this + /// parent is not covered by the DCV domain's own prior verification. Falls back to the + /// input unchanged if it has no "." to strip. + /// + private static string DeriveDefaultFreshDcvParent(string domain) + { + if (string.IsNullOrWhiteSpace(domain)) return domain; + int dot = domain.IndexOf('.'); + return dot >= 0 && dot < domain.Length - 1 ? domain.Substring(dot + 1) : domain; + } + + public void Dispose() + { + foreach (var d in _toDispose) + d.Dispose(); + _toDispose.Clear(); + } + + // --------------------------------------------------------------------------- + // Helpers + // --------------------------------------------------------------------------- + + private static string GenerateCsrPem(string commonName) + { + var keyGen = new RsaKeyPairGenerator(); + keyGen.Init(new KeyGenerationParameters(new SecureRandom(), 2048)); + var keyPair = keyGen.GenerateKeyPair(); + + var subject = new X509Name($"CN={commonName}"); + var csr = new Pkcs10CertificationRequest("SHA256withRSA", subject, keyPair.Public, null, keyPair.Private); + + return "-----BEGIN CERTIFICATE REQUEST-----\n" + + Convert.ToBase64String(csr.GetEncoded(), Base64FormattingOptions.InsertLineBreaks) + + "\n-----END CERTIFICATE REQUEST-----"; + } + + private IDomainValidatorFactory BuildV2DnsFactory() + { + if (_dcvEnabled) + { + var factory = new CloudflareDomainValidatorFactory(_cfApiToken, _cfZoneId); + _toDispose.Add(factory); + return factory; + } + return new StubDomainValidatorFactory(); + } + + private CERTInextConfig BuildV2Config() + { + return new CERTInextConfig + { + ApiUrl = _v2ApiUrl, + UseV2Api = true, + V2InlineCsr = V2EnvHelper.InlineCsrFromEnv, // default single-call; CERTINEXT_V2_INLINE_CSR=0 selects two-call + DefaultProductCode = Environment.GetEnvironmentVariable("CERTINEXT_PRODUCT_CODE") ?? "842", + OAuthClientId = _v2ClientId, + OAuthClientSecret = _v2ClientSecret, + + V2SyncLookbackHours = 1, + + RequestorName = _fixture.IsConfigured ? _fixture.Config.RequestorName : "Keyfactor Test", + RequestorEmail = _fixture.IsConfigured ? _fixture.Config.RequestorEmail : "test@example.com", + RequestorIsdCode = "1", + RequestorMobileNumber = "0000000000", + SignerPlace = "Gateway Lab", + SignerIp = "127.0.0.1", + + PageSize = 100, + + DcvEnabled = true, + DcvPropagationDelaySeconds = 5, + DcvTimeoutMinutes = 3 + }; + } + + /// + /// Revoke-if-issued / cancel-otherwise cleanup keyed on the order's V2 status (V2OrderCleanup) — + /// single attempt only, never retries a cancel, logs rather than + /// throws so a cleanup problem never masks the test's own assertion result. Returns + /// whether cleanup completed without throwing (true = revoked or cancelled successfully, + /// or nothing to do), so a caller that wants to assert "nothing leaks" — e.g. the + /// wildcard fresh-subdomain test below — has something other than log text to check. + /// + private async System.Threading.Tasks.Task CleanupOrderAsync(CERTInextCAPlugin plugin, string orderId) + { + // Keyed on the order's V2 status (see V2OrderCleanup): GetSingleRecord can still report an + // already-issued order as pending, and cancelling it leaks an issued certificate. + using var client = new CERTInextClient(BuildV2Config()); + return await V2OrderCleanup.RevokeOrCancelAsync( + client, orderId, "V2 fresh-domain DCV test cleanup.", _output.WriteLine); + } + + // --------------------------------------------------------------------------- + // 7. DCV against a fresh, never-before-verified subdomain + // --------------------------------------------------------------------------- + + /// + /// Enrolls a DV order for a freshly-generated subdomain of a genuinely unverified parent + /// (CERTINEXT_V2_FRESH_DCV_PARENT, NOT a subdomain of CERTINEXT_DCV_DOMAIN itself + /// — that domain's own prior DCV covers every subdomain beneath it, so a + /// dcv-fresh-<ts>.CERTINEXT_DCV_DOMAIN name never actually exercises the publish + /// path), with DcvEnabled=true and a real Cloudflare-backed + /// wrapped in . + /// Because the domain is guaranteed unseen, this is the one DCV test in the V2 suite that + /// actually exercises the publish path: every existing V2DcvLifecycleTests case targets + /// the long-reused CERTINEXT_DCV_DOMAIN, which this account has verified account-wide, so + /// those always take the reuse path and observe staged=0. Asserts staged>0 + /// and cleaned==staged. + /// Expected sandbox order count: 1. + /// + [SkippableTheory] + [V2PinModes] + public async System.Threading.Tasks.Task EnrollWithDcvOn_V2_FreshUnverifiedSubdomain_StagesAndCleansUpTxt(V2PinMode mode) + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + V2ProductPinning.Log(_output, Constants.Products.DvSsl, mode); + Skip.If(!_dcvEnabled, + "CERTINEXT_CF_API_TOKEN and CERTINEXT_CF_ZONE_ID must be set so the plugin can publish a real TXT record."); + Skip.If(Environment.GetEnvironmentVariable("CERTINEXT_V2_LIFECYCLE_FRESH_DCV") != "1", + "CERTINEXT_V2_LIFECYCLE_FRESH_DCV=1 not set — this places a real sandbox order and publishes a live DNS TXT record. Skipping."); + + string freshDomain = $"dcv-fresh-{DateTime.UtcNow:yyyyMMddHHmmssfff}.{_freshDcvParent}"; + + var config = BuildV2Config(); + var recordingFactory = new RecordingDomainValidatorFactory(BuildV2DnsFactory()); + var plugin = new CERTInextCAPlugin(new CERTInextClient(config), recordingFactory, config); + + string orderId = null; + try + { + var result = await plugin.Enroll( + csr: GenerateCsrPem(freshDomain), + subject: $"CN={freshDomain}", + san: new Dictionary { ["dns"] = new[] { freshDomain } }, + productInfo: V2ProductPinning.Info(Constants.Products.DvSsl, mode), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.Should().NotBeNull(); + result.CARequestID.Should().NotBeNullOrWhiteSpace("Enroll must return a CARequestID even if DCV verification does not complete inline"); + orderId = result.CARequestID; + _output.WriteLine($"Fresh-domain order {orderId} for '{freshDomain}' (parent={_freshDcvParent}): Status={result.Status}, Message={result.StatusMessage}"); + + var staged = recordingFactory.StagedCalls; + var cleaned = recordingFactory.CleanedUpFqdns; + _output.WriteLine($"DNS provider calls: staged={staged.Count}, cleaned={cleaned.Count}"); + + // Expected behavior is staged>0 (see class-level remarks). The CA may instead + // treat the fresh subdomain's parent as already covering it and issue + // immediately with zero TXT records staged — in which case the TXT + // publish/verify path was never exercised and the assertions below cannot be + // meaningfully evaluated. Skip rather than fail; the finally below still runs + // cleanup regardless of this skip. + Skip.If(staged.Count == 0, + $"blocked by sandbox: CA treated {freshDomain} as pre-validated; TXT publish/verify path not exercised"); + + staged.Should().NotBeEmpty( + $"domain '{freshDomain}' is freshly generated under a genuinely unverified parent " + + "and cannot already be VERIFIED on this account — unlike every pre-existing " + + "V2DcvLifecycleTests case (which targets the long-reused CERTINEXT_DCV_DOMAIN and " + + "always takes the reuse path with staged=0), Enroll must actually stage " + + "a TXT record here."); + cleaned.Count.Should().Be(staged.Count, + "every staged DCV TXT record for a fresh domain must be cleaned up after the attempt."); + + new[] { (int)EndEntityStatus.EXTERNALVALIDATION, (int)EndEntityStatus.GENERATED } + .Should().Contain(result.Status, + $"DCV-on Enroll for a fresh domain must return pending or issued; got {result.Status}. Message: {result.StatusMessage}"); + } + finally + { + await CleanupOrderAsync(plugin, orderId); + } + } + + // --------------------------------------------------------------------------- + // 8. Wildcard DV DCV against a fresh, never-before-verified subdomain + // --------------------------------------------------------------------------- + + /// + /// Wildcard-only CSR shape (CN = SAN = the wildcard) on a freshly-generated, + /// never-before-seen subdomain of a genuinely unverified parent + /// (CERTINEXT_V2_FRESH_DCV_PARENT, same freshness rationale as + /// above), + /// for . Asserts the staged TXT hostname + /// does NOT contain a literal '*' (a wildcard's "*." label is not a queryable DNS name — + /// see the base-domain hostname fix). DOES fail if the order ends FAILED. If the order + /// is still at EXTERNALVALIDATION (pending DCV) when this test's wait elapses, wildcard + /// DCV completion was never actually exercised, so the test Skips with a "blocked by + /// sandbox" message rather than claiming wildcard DCV works — cleanup (cancel) still + /// runs regardless. Also records what Track Order's + /// verifications.domain.domains[].domain echoes back for the same order, and + /// whether any domain entry reached VERIFIED within the wait. Cleanup (revoke-if-issued + /// or cancel) must succeed regardless of outcome, so this probe never leaks a live order. + /// Expected sandbox order count: 1. + /// + [SkippableTheory] + [V2PinModes] + public async System.Threading.Tasks.Task EnrollWithDcvOn_V2_WildcardFreshSubdomain_RecordsTxtHostnameAndCleansUp(V2PinMode mode) + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + V2ProductPinning.Log(_output, Constants.Products.DvSslWildcard, mode); + Skip.If(!_dcvEnabled, + "CERTINEXT_CF_API_TOKEN and CERTINEXT_CF_ZONE_ID must be set so the plugin can publish a real TXT record."); + Skip.If(Environment.GetEnvironmentVariable("CERTINEXT_V2_LIFECYCLE_FRESH_DCV") != "1", + "CERTINEXT_V2_LIFECYCLE_FRESH_DCV=1 not set — this places a real sandbox order and publishes a live DNS TXT record. Skipping."); + + string freshSubdomain = $"dcv-fresh-{DateTime.UtcNow:yyyyMMddHHmmssfff}.{_freshDcvParent}"; + string wildcard = $"*.{freshSubdomain}"; + + var config = BuildV2Config(); + var recordingFactory = new RecordingDomainValidatorFactory(BuildV2DnsFactory()); + var client = new CERTInextClient(config); + var plugin = new CERTInextCAPlugin(client, recordingFactory, config); + + string orderId = null; + try + { + var result = await plugin.Enroll( + csr: GenerateCsrPem(wildcard), + subject: $"CN={wildcard}", + san: new Dictionary { ["dns"] = new[] { wildcard } }, + productInfo: V2ProductPinning.Info(Constants.Products.DvSslWildcard, mode), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.Should().NotBeNull(); + _output.WriteLine($"Wildcard fresh-subdomain order ({wildcard}, parent={_freshDcvParent}): Status={result.Status}, Message={result.StatusMessage}"); + + if (!string.IsNullOrWhiteSpace(result.CARequestID)) + orderId = result.CARequestID; + + // Don't fail solely on CA verification timing (EXTERNALVALIDATION is fine) — + // but a FAILED order (CERTInext rejected/cancelled it) is a real problem, not a + // timing artifact. + result.Status.Should().NotBe((int)EndEntityStatus.FAILED, + $"the order must not end FAILED; Message: {result.StatusMessage}"); + + // Ending at EXTERNALVALIDATION means DCV never actually completed within this + // test's wait — the wildcard DCV path was not exercised to issuance, so this test + // cannot claim wildcard DCV works. Skip rather than pass silently; cleanup + // (cancel) still runs in the finally below regardless of this skip. + Skip.If(result.Status == (int)EndEntityStatus.EXTERNALVALIDATION, + $"blocked by sandbox: wildcard order for '{wildcard}' ended at pending-approval (EXTERNALVALIDATION); wildcard DCV completion not exercised"); + + var staged = recordingFactory.StagedCalls; + var cleaned = recordingFactory.CleanedUpFqdns; + _output.WriteLine($"DNS provider calls: staged={staged.Count}, cleaned={cleaned.Count}"); + foreach (var call in staged) + _output.WriteLine($"Staged TXT hostname: Fqdn='{call.Fqdn}'."); + foreach (var fqdn in cleaned) + _output.WriteLine($"Cleaned-up TXT hostname: Fqdn='{fqdn}'."); + + staged.Should().OnlyContain(call => call.Fqdn == null || !call.Fqdn.Contains('*'), + "a literal '*' DNS label is not queryable by the CA and must never be staged — " + + "see the wildcard base-domain hostname fix."); + + if (!string.IsNullOrWhiteSpace(orderId)) + { + try + { + var tracked = await client.ResolveAndTrackOrderV2Async(orderId); + var domainEntries = tracked?.Verifications?.Domain?.Domains; + if (domainEntries != null && domainEntries.Count > 0) + { + foreach (var entry in domainEntries) + _output.WriteLine( + $"Track Order verifications.domain.domains[]: domain='{entry.Domain}', dcvStatus={entry.DcvStatus ?? ""}."); + + bool anyVerified = domainEntries.Any(e => + string.Equals(e.DcvStatus, "VERIFIED", StringComparison.OrdinalIgnoreCase)); + _output.WriteLine(anyVerified + ? "At least one domain entry reached VERIFIED within this test's wait — the CA " + + "accepted a base-domain TXT record for a wildcard domain entry." + : "No domain entry reached VERIFIED within this test's wait (CA-side timing, or " + + "the base-domain TXT record is not accepted for a wildcard domain entry — still " + + "UNVERIFIED; this is not asserted as a test failure)."); + } + else + { + _output.WriteLine("Track Order returned no verifications.domain.domains[] entries for this order."); + } + } + catch (Exception ex) + { + _output.WriteLine($"Track Order (for verifications detail) FAILED: {ex.GetType().Name}: {ex.Message}."); + } + } + } + finally + { + bool cleanedUp = await CleanupOrderAsync(plugin, orderId); + cleanedUp.Should().BeTrue( + "cleanup (revoke-if-issued or cancel) must succeed so this wildcard fresh-subdomain probe " + + "never leaves a live order on the sandbox, regardless of what the TXT-hostname/Track-Order " + + "observations above turn out to show — see the 'Cleanup FAILED' output above if this fails."); + } + } + } +} +#endif diff --git a/CERTInext.IntegrationTests/V2FullLifecycleTests.cs b/CERTInext.IntegrationTests/V2FullLifecycleTests.cs new file mode 100644 index 0000000..a841ec5 --- /dev/null +++ b/CERTInext.IntegrationTests/V2FullLifecycleTests.cs @@ -0,0 +1,947 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. +// +// V2 release-candidate readiness: assertion-bearing live lifecycle coverage for the product +// families/shapes the existing V2 suite (V2LifecycleTests/V2ApiTests/V2DcvLifecycleTests) +// never exercised end to end — DV UCC, OV, OV UCC, EV, wildcard DV, and renew/reissue. Each +// test is gated by its own CERTINEXT_V2_LIFECYCLE_=1 flag (never +// promoted from ~/.env_certinext_v2 — see IntegrationTestFixture._optInOnlyFlags), places real +// sandbox orders, and always cleans up (revoke if issued, cancel otherwise) via +// CleanupOrderAsync in a try/finally. Fresh-domain DCV coverage lives in +// V2FreshDomainDcvLifecycleTests.cs (requires the SUPPORTS_DCV build). + +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Linq; +using System.Threading; +using System.Threading.Tasks; +using Org.BouncyCastle.Asn1.X509; +using Org.BouncyCastle.Crypto; +using Org.BouncyCastle.Crypto.Generators; +using Org.BouncyCastle.Pkcs; +using Org.BouncyCastle.Security; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Xunit; +using Xunit.Abstractions; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.IntegrationTests +{ + /// + /// Plugin-level V2 lifecycle tests for product shapes/flows the pre-existing V2 suite did + /// not cover with an assertion-bearing live test (readiness audit, 2026-10-01): DV UCC, OV, + /// OV UCC, EV, wildcard DV (both CSR shapes), and renew/reissue of an issued DV order. + /// + public class V2FullLifecycleTests : IClassFixture + { + private readonly IntegrationTestFixture _fixture; + private readonly ITestOutputHelper _output; + + private readonly string _v2ApiUrl; + private readonly string _v2ClientId; + private readonly string _v2ClientSecret; + private readonly string _v2Domain; + private readonly bool _v2Enabled; + + /// + /// 300s target for OV/EV order-creation calls (CA latency for these product types can + /// be significant). NOT actually enforceable at this (plugin-level) layer: + /// CERTInextClient's V2 RestClient hard-codes Timeout = TimeSpan.FromSeconds(120) + /// (CERTInextClient.cs, both the V1 and V2 RestClientOptions blocks) with no + /// CERTInextConfig override to raise it. OV/EV tests below catch a client-side timeout + /// distinctly from a CA-side rejection and record it rather than assert past it — see + /// IsClientTimeout below. This is a known production gap: the client-side timeout can + /// trip before the CA itself would reject or accept the order. + /// + private static readonly TimeSpan OvEvCreateTimeoutTarget = TimeSpan.FromSeconds(300); + + public V2FullLifecycleTests(IntegrationTestFixture fixture, ITestOutputHelper output) + { + _fixture = fixture; + _output = output; + + var env = V2EnvHelper.LoadAndPromote(); + + _v2ApiUrl = V2EnvHelper.GetEnv(env, "CERTINEXT_API_URL"); + _v2ClientId = V2EnvHelper.GetEnv(env, "CERTINEXT_CLIENT_ID"); + _v2ClientSecret = V2EnvHelper.GetEnv(env, "CERTINEXT_CLIENT_SECRET"); + _v2Domain = V2EnvHelper.GetEnv(env, "CERTINEXT_DCV_DOMAIN", "test.example.com"); + + _v2Enabled = !string.IsNullOrWhiteSpace(V2EnvHelper.GetEnv(env, "CERTINEXT_USE_V2_API")) + && !string.IsNullOrWhiteSpace(_v2ApiUrl) + && !string.IsNullOrWhiteSpace(_v2ClientId) + && !string.IsNullOrWhiteSpace(_v2ClientSecret); + } + + // --------------------------------------------------------------------------- + // Helpers + // --------------------------------------------------------------------------- + + private static string Timestamp() => DateTime.UtcNow.ToString("yyyyMMddHHmmssfff"); + + private static string GenerateCsrPem(string commonName) => GenerateCsrPem(commonName, ouTag: null); + + /// + /// , when supplied, is folded into the CSR subject as an OU — + /// e.g. ov- for the OV/OV-UCC orphan-sweep probes below. The orders report + /// () does not surface OU anywhere, so this + /// tag is NOT how an orphan is actually located (that's domain + creation-time window — + /// see ); it exists only so a human reviewing + /// the order in the CERTInext portal or a raw CSR dump can see which test run placed it. + /// + private static string GenerateCsrPem(string commonName, string ouTag) + { + var keyGen = new RsaKeyPairGenerator(); + keyGen.Init(new KeyGenerationParameters(new SecureRandom(), 2048)); + var keyPair = keyGen.GenerateKeyPair(); + + string subjectDn = string.IsNullOrWhiteSpace(ouTag) ? $"CN={commonName}" : $"CN={commonName},OU={ouTag}"; + var subject = new X509Name(subjectDn); + var csr = new Pkcs10CertificationRequest("SHA256withRSA", subject, keyPair.Public, null, keyPair.Private); + + return "-----BEGIN CERTIFICATE REQUEST-----\n" + + Convert.ToBase64String(csr.GetEncoded(), Base64FormattingOptions.InsertLineBreaks) + + "\n-----END CERTIFICATE REQUEST-----"; + } + + private static async Task> RunSyncAsync( + CERTInextCAPlugin plugin, DateTime? lastSync = null, bool fullSync = true) + { + var buffer = new BlockingCollection(boundedCapacity: 10_000); + var collected = new List(); + + var syncTask = Task.Run(async () => + { + await plugin.Synchronize(buffer, lastSync: lastSync, fullSync: fullSync, cancelToken: CancellationToken.None); + if (!buffer.IsAddingCompleted) + buffer.CompleteAdding(); + }); + + foreach (var record in buffer.GetConsumingEnumerable()) + collected.Add(record); + + await syncTask; + return collected; + } + + private CERTInextConfig BuildV2Config( + int? syncLookbackHours = null, string organizationNumber = null) + { + return new CERTInextConfig + { + ApiUrl = _v2ApiUrl, + UseV2Api = true, + V2InlineCsr = V2EnvHelper.InlineCsrFromEnv, // default single-call; CERTINEXT_V2_INLINE_CSR=0 selects two-call + DefaultProductCode = Environment.GetEnvironmentVariable("CERTINEXT_PRODUCT_CODE") ?? "842", + OAuthClientId = _v2ClientId, + OAuthClientSecret = _v2ClientSecret, + + RequestorName = _fixture.IsConfigured ? _fixture.Config.RequestorName : "Keyfactor Test", + RequestorEmail = _fixture.IsConfigured ? _fixture.Config.RequestorEmail : "test@example.com", + RequestorIsdCode = "1", + RequestorMobileNumber = "0000000000", + SignerPlace = "Gateway Lab", + SignerIp = "127.0.0.1", + + PageSize = 100, + + V2SyncLookbackHours = syncLookbackHours ?? 1, + + OrganizationNumber = organizationNumber ?? string.Empty, + + DcvEnabled = false + }; + } + + private static CERTInextCAPlugin BuildV2Plugin(CERTInextConfig config) + { + var client = new CERTInextClient(config); + return new CERTInextCAPlugin(client, config); + } + + /// + /// Distinguishes a client-side HTTP timeout (RestSharp/TaskCanceledException — the + /// plugin's hard-coded 120s V2 RestClient timeout expiring before the CA responds) from a + /// genuine CA-side rejection. See 's doc comment. + /// + /// Also matches the shape the CA can return for the same condition: CERTInextClient's + /// ThrowOnV2Failure does not always surface a + /// for a RestSharp-level transport timeout — it can instead produce a plain + /// reading "CERTInext V2 API error during '...'. HTTP 0. + /// CERTInext V2 returned no body for '...'." (StatusCode 0 = no HTTP response was ever + /// received). Both substrings ("HTTP 0" and "returned no body") must be present so this + /// never also matches a genuine HTTP-0-with-a-body CA-side condition. + /// + private static bool IsClientTimeout(Exception ex) => + ex is TaskCanceledException + || ex is OperationCanceledException + || (ex.Message?.IndexOf("timed out", StringComparison.OrdinalIgnoreCase) >= 0) + // PlaceOrderV2CoreAsync maps a create that got no usable response (no HTTP status / 5xx) to this + // "created but we never heard back" message (single-call create: the order may exist AND issue). + || (ex.Message?.IndexOf("did not return a usable response to the V2 order create", StringComparison.OrdinalIgnoreCase) >= 0) + || (ex.Message != null + && ex.Message.IndexOf("HTTP 0", StringComparison.OrdinalIgnoreCase) >= 0 + && ex.Message.IndexOf("returned no body", StringComparison.OrdinalIgnoreCase) >= 0); + + /// + /// Best-effort search for an order the CA may have created despite the plugin's own + /// client-side timeout () — a timeout proves nothing about + /// what happened server-side. Scans the V2 orders report + /// ( via ListOrdersV2Async) for the + /// "UTC today" window, matches on domainName == domain (the only field this report + /// row model exposes — no OU/SAN/tag field is echoed there) plus + /// orderDate >= windowStartUtc - 5min to avoid grabbing an older, unrelated + /// order on the same long-reused , picks the single most-recent + /// match if more than one row qualifies, and cancels it (one attempt, never retried) if + /// it is not already terminal. Never throws — every failure path is folded into the + /// returned description string so the caller's Skip.If message always has something + /// actionable. is logged only (see ). + /// + private async Task TryCancelOrphanByWindowAsync(string domain, DateTime windowStartUtc, string probeTag) + { + try + { + using var client = new CERTInextClient(BuildV2Config()); + + string from = windowStartUtc.Date.ToString("yyyy-MM-dd"); + string to = windowStartUtc.Date.AddDays(1).ToString("yyyy-MM-dd"); + + OrderReportEntryV2 best = null; + DateTime bestDate = DateTime.MinValue; + int scanned = 0; + + await foreach (var row in client.ListOrdersV2Async(from, to, pageSize: 100)) + { + scanned++; + if (!string.Equals(row.DomainName, domain, StringComparison.OrdinalIgnoreCase)) + continue; + + DateTime rowDate = DateTime.TryParse( + row.OrderDate, null, + System.Globalization.DateTimeStyles.AdjustToUniversal | System.Globalization.DateTimeStyles.AssumeUniversal, + out var parsed) + ? parsed + : windowStartUtc; // unparseable date: don't exclude it from consideration on that basis alone + + if (rowDate < windowStartUtc.AddMinutes(-5)) + continue; + + if (best == null || rowDate >= bestDate) + { + best = row; + bestDate = rowDate; + } + } + + _output.WriteLine( + $"Orphan sweep (tag={probeTag}): scanned {scanned} report row(s) for domain '{domain}', " + + $"window >= {windowStartUtc:O} (-5min grace)."); + + if (best == null) + return "orphan sweep found no matching report row for this domain/window (nothing to cancel, " + + "or the order has not appeared in the report yet — try again later by hand if needed)"; + + string orderId = best.OrderNumber; + if (string.IsNullOrWhiteSpace(orderId)) + return $"orphan sweep found a matching report row for domain '{domain}' with no orderNumber — cannot cancel it programmatically"; + + var (family, status) = await client.ResolveAndTrackOrderV2WithFamilyAsync(orderId); + bool terminal = + string.Equals(status.Status, Constants.ApiV2.StatusCancelled, StringComparison.OrdinalIgnoreCase) || + string.Equals(status.Status, Constants.ApiV2.StatusRevoked, StringComparison.OrdinalIgnoreCase) || + string.Equals(status.Status, Constants.ApiV2.StatusRejected, StringComparison.OrdinalIgnoreCase); + + if (terminal) + return $"orphan sweep found order {orderId} already terminal (status={status.Status}) — nothing to cancel"; + + try + { + var outcome = await client.CancelOrderV2Async( + family, orderId, + $"V2 full-lifecycle test orphan sweep — client-side timeout at submission, tag={probeTag}."); + return $"orphan sweep found order {orderId} (status was {status.Status}) and cancelled it (outcome={outcome})"; + } + catch (Exception cancelEx) + { + return $"orphan sweep found order {orderId} but the cancel call itself FAILED " + + $"({cancelEx.GetType().Name}: {cancelEx.Message}) — not retried; cancel it by hand in the CERTInext portal"; + } + } + catch (Exception ex) + { + return $"orphan sweep itself FAILED ({ex.GetType().Name}: {ex.Message}) — could not search for an orphaned order; check the CERTInext portal by hand"; + } + } + + /// + /// Cleans up a sandbox order this test created, keyed on the order's own V2 status + /// (): revoke if issued, cancel otherwise, then re-track. + /// Single attempt only — never retries a cancel. Logs rather than throws on failure so a + /// cleanup problem never masks the test's own assertion result; failures are surfaced in test + /// output for manual follow-up in the CERTInext portal. + /// + private async Task CleanupOrderAsync(CERTInextCAPlugin plugin, string orderId) + { + // Keyed on the order's V2 status (see V2OrderCleanup): GetSingleRecord can still report an + // already-issued order as pending, and cancelling it leaks an issued certificate. + using var client = new CERTInextClient(BuildV2Config()); + await V2OrderCleanup.RevokeOrCancelAsync( + client, orderId, "V2 full-lifecycle test cleanup.", _output.WriteLine); + } + + // --------------------------------------------------------------------------- + // 1. DV UCC — enroll (2+ SANs) -> track -> sync/GetSingleRecord -> revoke + // --------------------------------------------------------------------------- + + /// + /// Places one V2 DV SSL UCC order () with the + /// primary domain on the account's long-reused, likely-already-verified + /// CERTINEXT_DCV_DOMAIN, plus two fresh never-seen subdomains as additional SANs + /// (so the order itself places cleanly regardless of whether the extra SANs clear DCV). + /// Exercises Enroll -> GetSingleRecord -> Synchronize, then cleans up (revoke if + /// GENERATED, else cancel). + /// Expected sandbox order count: 1. + /// + [SkippableTheory] + [V2PinModes] + public async Task Enroll_V2_DvUcc_WithMultipleSans_FullLifecycle(V2PinMode mode) + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + V2ProductPinning.Log(_output, Constants.Products.DvSslUcc, mode); + Skip.If(Environment.GetEnvironmentVariable("CERTINEXT_V2_LIFECYCLE_DV_UCC") != "1", + "CERTINEXT_V2_LIFECYCLE_DV_UCC=1 not set — this places a real DV UCC sandbox order. Skipping."); + + string ts = Timestamp(); + string primary = _v2Domain; + string sanA = $"ucc-a-{ts}.{_v2Domain}"; + string sanB = $"ucc-b-{ts}.{_v2Domain}"; + + var config = BuildV2Config(); + var plugin = BuildV2Plugin(config); + + string orderId = null; + try + { + var productInfo = V2ProductPinning.Info(Constants.Products.DvSslUcc, mode); + + var enrollResult = await plugin.Enroll( + csr: GenerateCsrPem(primary), + subject: $"CN={primary}", + san: new Dictionary { ["dns"] = new[] { sanA, sanB } }, + productInfo: productInfo, + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + enrollResult.Should().NotBeNull(); + enrollResult.CARequestID.Should().NotBeNullOrWhiteSpace( + "V2 DV UCC Enroll must return a non-empty CARequestID"); + orderId = enrollResult.CARequestID; + enrollResult.Status.Should().NotBe((int)EndEntityStatus.FAILED, + $"DV UCC Enroll must not FAILED at submission; message: {enrollResult.StatusMessage}"); + _output.WriteLine($"DV UCC order {orderId}: Status={enrollResult.Status}, Primary={primary}, SANs=[{sanA}, {sanB}]"); + + var tracked = await plugin.GetSingleRecord(orderId); + tracked.Should().NotBeNull("GetSingleRecord must return a record for a just-placed DV UCC order"); + tracked.CARequestID.Should().Be(orderId); + _output.WriteLine($"Tracked: Status={tracked.Status}"); + + var synced = await RunSyncAsync(plugin, lastSync: DateTime.UtcNow.AddHours(-1), fullSync: false); + synced.Should().Contain(r => r.CARequestID == orderId, + $"the newly placed DV UCC order '{orderId}' must appear in a delta sync via V2 /reports/orders"); + + var syncedRecord = synced.First(r => r.CARequestID == orderId); + _output.WriteLine($"Synced status: {syncedRecord.Status}"); + if (syncedRecord.Status == (int)EndEntityStatus.GENERATED) + syncedRecord.Certificate.Should().NotBeNullOrWhiteSpace("an issued DV UCC order must carry a cert body via Synchronize"); + } + finally + { + await CleanupOrderAsync(plugin, orderId); + } + } + + // --------------------------------------------------------------------------- + // 2. OV — enroll -> track -> sync -> revoke/cancel + // --------------------------------------------------------------------------- + + /// + /// Places one V2 OV SSL order (); productVariant + /// "ov" and the organization block are both derived/required automatically by + /// EnrollV2Async from the connector's OrganizationNumber. Sandbox OV orders commonly + /// park in a pending-vetting state rather than auto-issuing — this test asserts on + /// whatever state machine actually results (only FAILED at submission is treated as a + /// hard failure) rather than forcing GENERATED. See + /// for the 120s-vs-300s client timeout caveat. + /// Expected sandbox order count: 1. + /// + [SkippableTheory] + [V2PinModes] + public async Task Enroll_V2_Ov_FullLifecycle(V2PinMode mode) + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + V2ProductPinning.Log(_output, Constants.Products.OvSsl, mode); + Skip.If(Environment.GetEnvironmentVariable("CERTINEXT_V2_LIFECYCLE_OV") != "1", + "CERTINEXT_V2_LIFECYCLE_OV=1 not set — this places a real OV sandbox order. Skipping."); + + string organizationNumber = _fixture.IsConfigured ? _fixture.OrgNumber : null; + Skip.If(string.IsNullOrWhiteSpace(organizationNumber), + "CERTINEXT_ORG_NUMBER not set in ~/.env_certinext — OV requires a pre-vetted organization number. Skipping."); + + var config = BuildV2Config(organizationNumber: organizationNumber); + var plugin = BuildV2Plugin(config); + + string domain = _v2Domain; + string probeTag = $"ov-{Timestamp()}"; + DateTime windowStart = DateTime.UtcNow; + string orderId = null; + try + { + EnrollmentResult enrollResult; + try + { + enrollResult = await plugin.Enroll( + csr: GenerateCsrPem(domain, probeTag), + subject: $"CN={domain},OU={probeTag}", + san: new Dictionary { ["dns"] = new[] { domain } }, + productInfo: V2ProductPinning.Info(Constants.Products.OvSsl, mode), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + } + catch (Exception ex) when (IsClientTimeout(ex)) + { + string sweepResult = await TryCancelOrphanByWindowAsync(domain, windowStart, probeTag); + Skip.If(true, + "OV order creation did not return within the plugin's hard-coded 120s V2 HTTP client " + + "timeout. That timeout is a known client-side limitation rather than a CA-side " + + "rejection, so this is an expected skip — but a client timeout does not prove the CA " + + $"never created the order; it likely did. {sweepResult}. " + + $"Observed: {ex.GetType().Name}: {ex.Message}"); + return; + } + + enrollResult.Should().NotBeNull(); + enrollResult.CARequestID.Should().NotBeNullOrWhiteSpace("V2 OV Enroll must return a non-empty CARequestID"); + orderId = enrollResult.CARequestID; + enrollResult.Status.Should().NotBe((int)EndEntityStatus.FAILED, + $"OV Enroll must not FAILED at submission; message: {enrollResult.StatusMessage}"); + _output.WriteLine($"OV order {orderId}: Status={enrollResult.Status}, Message={enrollResult.StatusMessage}"); + + var tracked = await plugin.GetSingleRecord(orderId); + tracked.Should().NotBeNull(); + _output.WriteLine($"Tracked OV order {orderId}: Status={tracked.Status} (OV sandbox orders commonly sit in a pending-vetting state rather than a forced GENERATED state)."); + + var synced = await RunSyncAsync(plugin, lastSync: DateTime.UtcNow.AddHours(-1), fullSync: false); + synced.Should().Contain(r => r.CARequestID == orderId, + $"the newly placed OV order '{orderId}' must appear in a delta sync"); + } + finally + { + await CleanupOrderAsync(plugin, orderId); + } + } + + // --------------------------------------------------------------------------- + // 3. OV UCC — enroll (2+ SANs) -> track -> sync -> revoke/cancel + // --------------------------------------------------------------------------- + + /// + /// Places one V2 OV SSL UCC order () — the + /// organization-block requirement (OV/EV) and the UCC multi-SAN path (additionalDomains) + /// are exercised together in one order. Same pending-vetting behavior and timeout + /// caveat as the plain OV test above. + /// Expected sandbox order count: 1. + /// + [SkippableTheory] + [V2PinModes] + public async Task Enroll_V2_OvUcc_WithMultipleSans_FullLifecycle(V2PinMode mode) + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + V2ProductPinning.Log(_output, Constants.Products.OvSslUcc, mode); + Skip.If(Environment.GetEnvironmentVariable("CERTINEXT_V2_LIFECYCLE_OV_UCC") != "1", + "CERTINEXT_V2_LIFECYCLE_OV_UCC=1 not set — this places a real OV UCC sandbox order. Skipping."); + + string organizationNumber = _fixture.IsConfigured ? _fixture.OrgNumber : null; + Skip.If(string.IsNullOrWhiteSpace(organizationNumber), + "CERTINEXT_ORG_NUMBER not set in ~/.env_certinext — OV UCC requires a pre-vetted organization number. Skipping."); + + string ts = Timestamp(); + string primary = _v2Domain; + string sanA = $"ovucc-a-{ts}.{_v2Domain}"; + string sanB = $"ovucc-b-{ts}.{_v2Domain}"; + + var config = BuildV2Config(organizationNumber: organizationNumber); + var plugin = BuildV2Plugin(config); + + string probeTag = $"ovucc-{ts}"; + DateTime windowStart = DateTime.UtcNow; + string orderId = null; + try + { + EnrollmentResult enrollResult; + try + { + enrollResult = await plugin.Enroll( + csr: GenerateCsrPem(primary, probeTag), + subject: $"CN={primary},OU={probeTag}", + san: new Dictionary { ["dns"] = new[] { sanA, sanB } }, + productInfo: V2ProductPinning.Info(Constants.Products.OvSslUcc, mode), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + } + catch (Exception ex) when (IsClientTimeout(ex)) + { + string sweepResult = await TryCancelOrphanByWindowAsync(primary, windowStart, probeTag); + Skip.If(true, + "OV UCC order creation did not return within the plugin's hard-coded 120s V2 HTTP client " + + "timeout — same known client-side limitation as the plain OV test. A client timeout " + + $"does not prove the CA never created the order; it likely did. {sweepResult}. " + + $"Observed: {ex.GetType().Name}: {ex.Message}"); + return; + } + + enrollResult.Should().NotBeNull(); + enrollResult.CARequestID.Should().NotBeNullOrWhiteSpace("V2 OV UCC Enroll must return a non-empty CARequestID"); + orderId = enrollResult.CARequestID; + enrollResult.Status.Should().NotBe((int)EndEntityStatus.FAILED, + $"OV UCC Enroll must not FAILED at submission; message: {enrollResult.StatusMessage}"); + _output.WriteLine($"OV UCC order {orderId}: Status={enrollResult.Status}, Primary={primary}, SANs=[{sanA}, {sanB}]"); + + var tracked = await plugin.GetSingleRecord(orderId); + tracked.Should().NotBeNull(); + _output.WriteLine($"Tracked OV UCC order {orderId}: Status={tracked.Status}"); + + var synced = await RunSyncAsync(plugin, lastSync: DateTime.UtcNow.AddHours(-1), fullSync: false); + synced.Should().Contain(r => r.CARequestID == orderId, + $"the newly placed OV UCC order '{orderId}' must appear in a delta sync"); + } + finally + { + await CleanupOrderAsync(plugin, orderId); + } + } + + // --------------------------------------------------------------------------- + // 4. EV — enroll -> track -> sync -> revoke/cancel + // --------------------------------------------------------------------------- + + /// + /// Places one V2 EV SSL order () — same + /// organization-block requirement as OV (ProductVariantsV2 mapping resolves "ev" + /// automatically), same pending-vetting behavior, same client-timeout caveat. Uses + /// CERTINEXT_EV_ORG_NUMBER — NOT CERTINEXT_ORG_NUMBER/ + /// , which is only pre-vetted for OV. EV + /// requires its own, separately-vetted organization number that this account does not + /// currently have; the test skips cleanly rather than guessing. + /// Expected sandbox order count: 1. + /// + [SkippableTheory] + [V2PinModes] + public async Task Enroll_V2_Ev_FullLifecycle(V2PinMode mode) + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + V2ProductPinning.Log(_output, Constants.Products.EvSsl, mode); + Skip.If(Environment.GetEnvironmentVariable("CERTINEXT_V2_LIFECYCLE_EV") != "1", + "CERTINEXT_V2_LIFECYCLE_EV=1 not set — this places a real EV sandbox order. Skipping."); + + string organizationNumber = Environment.GetEnvironmentVariable("CERTINEXT_EV_ORG_NUMBER"); + Skip.If(string.IsNullOrWhiteSpace(organizationNumber), + "CERTINEXT_EV_ORG_NUMBER not set — EV requires its own pre-vetted organization number " + + "(distinct from CERTINEXT_ORG_NUMBER, which is only vetted for OV). Skipping."); + + var config = BuildV2Config(organizationNumber: organizationNumber); + var plugin = BuildV2Plugin(config); + + string domain = _v2Domain; + string orderId = null; + try + { + EnrollmentResult enrollResult; + try + { + enrollResult = await plugin.Enroll( + csr: GenerateCsrPem(domain), + subject: $"CN={domain}", + san: new Dictionary { ["dns"] = new[] { domain } }, + productInfo: V2ProductPinning.Info(Constants.Products.EvSsl, mode), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + } + catch (Exception ex) when (IsClientTimeout(ex)) + { + Skip.If(true, + $"EV order creation did not return within the plugin's hard-coded 120s V2 HTTP " + + $"client timeout — same known client-side limitation flagged for OV. " + + $"Observed: {ex.GetType().Name}: {ex.Message}"); + return; + } + + enrollResult.Should().NotBeNull(); + enrollResult.CARequestID.Should().NotBeNullOrWhiteSpace("V2 EV Enroll must return a non-empty CARequestID"); + orderId = enrollResult.CARequestID; + enrollResult.Status.Should().NotBe((int)EndEntityStatus.FAILED, + $"EV Enroll must not FAILED at submission; message: {enrollResult.StatusMessage}"); + _output.WriteLine($"EV order {orderId}: Status={enrollResult.Status}, Message={enrollResult.StatusMessage}"); + + var tracked = await plugin.GetSingleRecord(orderId); + tracked.Should().NotBeNull(); + _output.WriteLine($"Tracked EV order {orderId}: Status={tracked.Status} (EV sandbox orders commonly sit in a pending-vetting state)."); + + var synced = await RunSyncAsync(plugin, lastSync: DateTime.UtcNow.AddHours(-1), fullSync: false); + synced.Should().Contain(r => r.CARequestID == orderId, + $"the newly placed EV order '{orderId}' must appear in a delta sync"); + } + finally + { + await CleanupOrderAsync(plugin, orderId); + } + } + + // --------------------------------------------------------------------------- + // 5. Wildcard DV — both CSR shapes (wildcard-only, wildcard+apex SAN) + // --------------------------------------------------------------------------- + + /// + /// Resolves the wildcard domain to use: CERTINEXT_V2_WILDCARD_DOMAIN if set, + /// else the literal *.dcv-test.scrup.org — this repo's own always-reused sandbox + /// base domain, not customer data. + /// + private static string ResolveWildcardDomain() => + Environment.GetEnvironmentVariable("CERTINEXT_V2_WILDCARD_DOMAIN") ?? "*.dcv-test.scrup.org"; + + /// + /// Wildcard-only CSR shape: CN and sole SAN are both the wildcard + /// (). Expected to be accepted — wildcard is a + /// first-class DV SSL Wildcard product shape. + /// Expected sandbox order count: 1. + /// + [SkippableTheory] + [V2PinModes] + public async Task Enroll_V2_WildcardDv_WildcardOnly_FullLifecycle(V2PinMode mode) + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + V2ProductPinning.Log(_output, Constants.Products.DvSslWildcard, mode); + Skip.If(Environment.GetEnvironmentVariable("CERTINEXT_V2_LIFECYCLE_WILDCARD_DV") != "1", + "CERTINEXT_V2_LIFECYCLE_WILDCARD_DV=1 not set — this places real wildcard DV sandbox orders. Skipping."); + + string wildcard = ResolveWildcardDomain(); + var config = BuildV2Config(); + var plugin = BuildV2Plugin(config); + + string orderId = null; + try + { + var enrollResult = await plugin.Enroll( + csr: GenerateCsrPem(wildcard), + subject: $"CN={wildcard}", + san: new Dictionary { ["dns"] = new[] { wildcard } }, + productInfo: V2ProductPinning.Info(Constants.Products.DvSslWildcard, mode), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + enrollResult.Should().NotBeNull(); + _output.WriteLine($"Wildcard-only ({wildcard}): Status={enrollResult.Status}, Message={enrollResult.StatusMessage}"); + enrollResult.Status.Should().NotBe((int)EndEntityStatus.FAILED, + $"a wildcard-only CSR/SAN shape must not be rejected; message: {enrollResult.StatusMessage}"); + enrollResult.CARequestID.Should().NotBeNullOrWhiteSpace(); + orderId = enrollResult.CARequestID; + + var tracked = await plugin.GetSingleRecord(orderId); + tracked.Should().NotBeNull(); + _output.WriteLine($"Tracked: Status={tracked.Status}"); + } + finally + { + await CleanupOrderAsync(plugin, orderId); + } + } + + /// + /// Wildcard+apex CSR shape: CN is the wildcard, SAN dictionary carries BOTH the wildcard + /// and its bare apex domain. The non-UCC V2 SAN guard (CERTInextCAPlugin.cs, EnrollV2Async) + /// explicitly exempts exactly this shape for a wildcard product — the guard computes + /// domain as the literal CN ("*.dcv-test.scrup.org" here), and without the + /// exemption the apex ("dcv-test.scrup.org") would match neither that nor its "www." + /// variant and be treated as a disallowed "extra SAN", even though a wildcard+apex + /// pairing is an extremely common, legitimate certificate shape. The order is therefore + /// expected to be accepted and issued. This test records the actual resulting behavior + /// rather than hard-asserting on it everywhere: if the order is rejected anyway, + /// it asserts the rejection is specifically this guard's (by message content) rather than + /// some unrelated failure; if accepted and issued, it parses the issued leaf (BouncyCastle) + /// and logs — as an observation only, not an assertion — whether the apex is covered by + /// the certificate's own SAN list (CERTInext may or may not add the apex to + /// additionalDomains automatically for a non-UCC wildcard product). + /// Expected sandbox order count: 0 or 1 (0 if CERTInext itself rejects a FAILED result + /// before any order is ever placed — see the FAILED branch below). + /// + [SkippableTheory] + [V2PinModes] + public async Task Enroll_V2_WildcardDv_WildcardPlusApexSan_RecordsActualBehavior(V2PinMode mode) + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + V2ProductPinning.Log(_output, Constants.Products.DvSslWildcard, mode); + Skip.If(Environment.GetEnvironmentVariable("CERTINEXT_V2_LIFECYCLE_WILDCARD_DV") != "1", + "CERTINEXT_V2_LIFECYCLE_WILDCARD_DV=1 not set — this places real wildcard DV sandbox orders. Skipping."); + + string wildcard = ResolveWildcardDomain(); + string apex = wildcard.StartsWith("*.", StringComparison.Ordinal) ? wildcard.Substring(2) : wildcard; + + var config = BuildV2Config(); + var plugin = BuildV2Plugin(config); + + string orderId = null; + try + { + var enrollResult = await plugin.Enroll( + csr: GenerateCsrPem(wildcard), + subject: $"CN={wildcard}", + san: new Dictionary { ["dns"] = new[] { wildcard, apex } }, + productInfo: V2ProductPinning.Info(Constants.Products.DvSslWildcard, mode), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + enrollResult.Should().NotBeNull(); + _output.WriteLine($"Wildcard+apex ({wildcard} + {apex}): Status={enrollResult.Status}, Message={enrollResult.StatusMessage}"); + + if (enrollResult.Status == (int)EndEntityStatus.FAILED) + { + _output.WriteLine( + "RESULT: wildcard+apex was REJECTED before any CA call — the non-UCC SAN guard's " + + $"wildcard-apex exemption did not cover this case: domain==CN=='{wildcard}', and the " + + $"apex '{apex}' matched neither that nor its 'www.' variant."); + enrollResult.StatusMessage.Should().Contain("SAN", + "a FAILED result here must specifically be the non-UCC multi-SAN guard's rejection " + + "(StatusMessage mentions SAN/domain count), not some unrelated failure masquerading as it"); + enrollResult.CARequestID.Should().BeNullOrWhiteSpace( + "the guard rejects before PlaceOrderV2Async — no CARequestID should be minted"); + } + else + { + _output.WriteLine( + "RESULT: wildcard+apex was ACCEPTED — the non-UCC single-domain SAN guard's " + + "wildcard-apex exemption allows the bare apex alongside the wildcard CN."); + enrollResult.CARequestID.Should().NotBeNullOrWhiteSpace(); + orderId = enrollResult.CARequestID; + + var tracked = await plugin.GetSingleRecord(orderId); + tracked.Should().NotBeNull(); + _output.WriteLine($"Tracked: Status={tracked.Status}"); + + if (tracked.Status == (int)EndEntityStatus.GENERATED && !string.IsNullOrWhiteSpace(tracked.Certificate)) + { + var sans = ExtractDnsSansOrEmpty(tracked.Certificate); + _output.WriteLine($"Issued certificate SAN list: [{string.Join(", ", sans)}]"); + + bool apexCovered = sans.Any(s => string.Equals(s, apex, StringComparison.OrdinalIgnoreCase)); + _output.WriteLine(apexCovered + ? $"The apex '{apex}' IS covered by the issued certificate's SAN list." + : $"The apex '{apex}' is NOT covered by the issued certificate's SAN list " + + "(not asserted — CERTInext may or may not add the apex to additionalDomains " + + "automatically for a non-UCC wildcard product)."); + } + else + { + _output.WriteLine( + $"Order not yet issued (Status={tracked.Status}) — skipping the SAN-coverage observation."); + } + } + } + finally + { + await CleanupOrderAsync(plugin, orderId); + } + } + + // --------------------------------------------------------------------------- + // 6. Renew and Reissue of an issued DV order + // --------------------------------------------------------------------------- + + /// + /// Enrolls a DV order (New), then calls Enroll again with EnrollmentType.Renew and then + /// EnrollmentType.Reissue for the same domain, passing the prior order's serial via + /// ProductParameters["PriorCertSN"] (the V1 RenewOrReissueAsync convention). V2's + /// EnrollV2Async never branches on enrollmentType beyond logging it — every enrollment + /// type is dispatched identically (CERTInextCAPlugin.cs: "V2 path: all enrollment types + /// go through EnrollV2Async", and EnrollV2Async itself never reads PriorCertSN or + /// enrollmentType except in log statements). This test records the actual resulting + /// behavior (distinct CARequestIDs, original never implicitly revoked) but does NOT pass + /// merely because the CA accepted each submission; a FAILED order at the CA must still + /// fail this test, since "records actual behavior" was never meant to license "observe + /// FAILED three times and call it a pass." + /// Expected sandbox order count: up to 3 (original + renew + reissue). + /// + [SkippableTheory] + [V2PinModes] + public async Task EnrollRenewReissue_V2_IssuedDvOrder_RecordsActualBehavior(V2PinMode mode) + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + V2ProductPinning.Log(_output, Constants.Products.DvSsl, mode); + Skip.If(Environment.GetEnvironmentVariable("CERTINEXT_V2_LIFECYCLE_RENEW_REISSUE") != "1", + "CERTINEXT_V2_LIFECYCLE_RENEW_REISSUE=1 not set — this places up to 3 real DV sandbox orders. Skipping."); + + var config = BuildV2Config(); + var plugin = BuildV2Plugin(config); + + string domain = _v2Domain; + string originalOrderId = null, renewOrderId = null, reissueOrderId = null; + try + { + var original = await plugin.Enroll( + csr: GenerateCsrPem(domain), + subject: $"CN={domain}", + san: new Dictionary { ["dns"] = new[] { domain } }, + productInfo: V2ProductPinning.Info(Constants.Products.DvSsl, mode), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + original.Should().NotBeNull(); + original.CARequestID.Should().NotBeNullOrWhiteSpace(); + originalOrderId = original.CARequestID; + _output.WriteLine($"Original order {originalOrderId}: Status={original.Status}, Message={original.StatusMessage}"); + original.Status.Should().BeOneOf( + new[] { (int)EndEntityStatus.GENERATED, (int)EndEntityStatus.EXTERNALVALIDATION }, + $"the original New enrollment must actually reach an in-flight or issued state for this to be a " + + $"meaningful renew/reissue lifecycle test, not FAILED; message: {original.StatusMessage}"); + + string priorSn = ExtractHexSerialOrEmpty(original.Certificate); + var priorParams = new Dictionary { ["PriorCertSN"] = priorSn }; + + var renewResult = await plugin.Enroll( + csr: GenerateCsrPem(domain), + subject: $"CN={domain}", + san: new Dictionary { ["dns"] = new[] { domain } }, + productInfo: V2ProductPinning.Info(Constants.Products.DvSsl, mode, priorParams), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.Renew); + + renewResult.Should().NotBeNull(); + renewResult.CARequestID.Should().NotBeNullOrWhiteSpace(); + renewOrderId = renewResult.CARequestID; + renewOrderId.Should().NotBe(originalOrderId, + "V2 has no dedicated renew endpoint — EnrollV2Async dispatches every EnrollmentType " + + "identically, so Renew places a brand-new order with a new CARequestID rather than " + + "reusing or superseding the original's ID"); + _output.WriteLine($"Renew order {renewOrderId}: Status={renewResult.Status}, Message={renewResult.StatusMessage} (new order, distinct CARequestID)."); + renewResult.Status.Should().BeOneOf( + new[] { (int)EndEntityStatus.GENERATED, (int)EndEntityStatus.EXTERNALVALIDATION }, + $"Renew must actually reach an in-flight or issued state, not FAILED; message: {renewResult.StatusMessage}"); + + var reissueResult = await plugin.Enroll( + csr: GenerateCsrPem(domain), + subject: $"CN={domain}", + san: new Dictionary { ["dns"] = new[] { domain } }, + productInfo: V2ProductPinning.Info(Constants.Products.DvSsl, mode, priorParams), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.Reissue); + + reissueResult.Should().NotBeNull(); + reissueResult.CARequestID.Should().NotBeNullOrWhiteSpace(); + reissueOrderId = reissueResult.CARequestID; + reissueOrderId.Should().NotBe(originalOrderId); + reissueOrderId.Should().NotBe(renewOrderId); + _output.WriteLine($"Reissue order {reissueOrderId}: Status={reissueResult.Status}, Message={reissueResult.StatusMessage} (new order, distinct CARequestID)."); + reissueResult.Status.Should().BeOneOf( + new[] { (int)EndEntityStatus.GENERATED, (int)EndEntityStatus.EXTERNALVALIDATION }, + $"Reissue must actually reach an in-flight or issued state, not FAILED; message: {reissueResult.StatusMessage}"); + + var originalAfter = await plugin.GetSingleRecord(originalOrderId); + originalAfter.Should().NotBeNull(); + originalAfter.Status.Should().NotBe((int)EndEntityStatus.REVOKED, + "neither Renew nor Reissue should implicitly revoke the original order under the V2 " + + "path — EnrollV2Async never calls Revoke on a prior order"); + _output.WriteLine($"Original order {originalOrderId} after renew+reissue: Status={originalAfter.Status} (unaffected, as expected)."); + } + finally + { + await CleanupOrderAsync(plugin, originalOrderId); + await CleanupOrderAsync(plugin, renewOrderId); + await CleanupOrderAsync(plugin, reissueOrderId); + } + } + + /// + /// Extracts the issued certificate's serial number as an uppercase hex string using + /// BouncyCastle (never BCL System.Security.Cryptography). Returns empty when + /// is null/blank/unparseable — e.g. a DV order still pending + /// DCV at enrollment time has no cert body yet, and PriorCertSN is not read at all by + /// EnrollV2Async under V2 (see this method's caller), so an empty value is harmless here. + /// + private static string ExtractHexSerialOrEmpty(string certPem) + { + if (string.IsNullOrWhiteSpace(certPem)) + return string.Empty; + + try + { + var match = System.Text.RegularExpressions.Regex.Match( + certPem, + @"-----BEGIN CERTIFICATE-----(.*?)-----END CERTIFICATE-----", + System.Text.RegularExpressions.RegexOptions.Singleline); + if (!match.Success) + return string.Empty; + + string b64 = match.Groups[1].Value.Replace("\r", string.Empty).Replace("\n", string.Empty).Trim(); + var cert = new Org.BouncyCastle.X509.X509CertificateParser().ReadCertificate(Convert.FromBase64String(b64)); + return cert.SerialNumber.ToString(16).ToUpperInvariant(); + } + catch + { + return string.Empty; + } + } + + /// + /// Extracts the issued certificate's dNSName SAN entries using BouncyCastle (never BCL + /// System.Security.Cryptography) — mirrors the main plugin's own GeneralNameToSanEntry + /// dNSName handling, but reading the ISSUED certificate's own SAN extension rather than a + /// CSR's. Returns an empty list when is null/blank/unparseable, + /// or the certificate carries no SAN extension. + /// + private static List ExtractDnsSansOrEmpty(string certPem) + { + var result = new List(); + if (string.IsNullOrWhiteSpace(certPem)) + return result; + + try + { + var match = System.Text.RegularExpressions.Regex.Match( + certPem, + @"-----BEGIN CERTIFICATE-----(.*?)-----END CERTIFICATE-----", + System.Text.RegularExpressions.RegexOptions.Singleline); + if (!match.Success) + return result; + + string b64 = match.Groups[1].Value.Replace("\r", string.Empty).Replace("\n", string.Empty).Trim(); + var cert = new Org.BouncyCastle.X509.X509CertificateParser().ReadCertificate(Convert.FromBase64String(b64)); + + var sanExtensionOctets = cert.GetExtensionValue(X509Extensions.SubjectAlternativeName)?.GetOctets(); + if (sanExtensionOctets == null) + return result; + + var generalNames = GeneralNames.GetInstance( + Org.BouncyCastle.Asn1.Asn1Object.FromByteArray(sanExtensionOctets)); + + foreach (var generalName in generalNames.GetNames()) + { + if (generalName.TagNo == GeneralName.DnsName) + result.Add(Org.BouncyCastle.Asn1.DerIA5String.GetInstance(generalName.Name).GetString()); + } + } + catch + { + // Observation-only helper — an unparseable cert/extension just yields no SAN + // observations rather than failing the test. + } + + return result; + } + } +} diff --git a/CERTInext.IntegrationTests/V2InlineCsrIssuanceExperimentTests.cs b/CERTInext.IntegrationTests/V2InlineCsrIssuanceExperimentTests.cs new file mode 100644 index 0000000..95e0f8e --- /dev/null +++ b/CERTInext.IntegrationTests/V2InlineCsrIssuanceExperimentTests.cs @@ -0,0 +1,979 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Diagnostics; +using System.Globalization; +using System.IO; +using System.Linq; +using System.Text; +using System.Text.Json; +using System.Text.Json.Nodes; +using System.Text.RegularExpressions; +using System.Threading; +using System.Threading.Tasks; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Org.BouncyCastle.Asn1.X509; +using Org.BouncyCastle.Crypto; +using Org.BouncyCastle.Crypto.Generators; +using Org.BouncyCastle.Crypto.Parameters; +using Org.BouncyCastle.OpenSsl; +using Org.BouncyCastle.Pkcs; +using Org.BouncyCastle.Security; +using Org.BouncyCastle.X509; +using RestSharp; +using Xunit; +using Xunit.Abstractions; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.IntegrationTests +{ + /// + /// Measurement experiment (issues 0062 + 0090, V2): does a SINGLE V2 call + /// (POST /ssl-certificates with the CSR inline in the create body, no follow-up + /// PUT .../csr) actually issue a certificate, and does the ~20 s "certificate is + /// generated inside the call that delivers the CSR" hold move from PUT /csr onto the + /// create call? + /// + /// Two arms, interleaved (A, B, A, B, ...), sequential, on the verified base domain + /// (CERTINEXT_DCV_DOMAIN itself, DV product 842 pinned via X-Product-Code by default): + /// + /// A - inline CSR single call: create body carries "csr"; nothing else is sent. + /// B - two-call control exactly as the plugin does it: create (no csr), then + /// PUT .../csr with the PEM CSR. + /// + /// The plugin's V2CreateSslOrderRequest has no csr property, so every call here is + /// raw HTTP (RestSharp, same headers the plugin sends); the body is the plugin's own DTO + /// serialized with its own serializer options, with csr injected for arm A. No plugin + /// production code is exercised or changed. + /// + /// Per order the test records: create latency + status/orderState/certificateState; PUT latency + /// (arm B); Track Order polled every ~1.5 s from the create response (status/orderState/ + /// certificateState transitions, incl. whether "System Error" appears and clears); the orders + /// report (the call Synchronize makes) polled concurrently every ~1.5 s with a narrow + /// today..tomorrow window (first appearance and every status transition = the enroll/sync race + /// window); whether GET .../certificate succeeds and when, and that the issued certificate + /// matches the CSR's public key and CN. Every order is then revoked/cancelled and re-tracked. + /// + /// Opt-in: CERTINEXT_V2_INLINE_CSR_EXPERIMENT=1 as a REAL environment variable. + /// Optional env: + /// CERTINEXT_V2_INLINE_CSR_COUNT orders per arm (default 5, max 8); + /// CERTINEXT_V2_INLINE_CSR_ARMS (AB default, BA runs the control first in each pair, A, or B); + /// CERTINEXT_V2_INLINE_CSR_ENCODING arm-A CSR encoding (pem default, der = + /// headerless Base64 DER, alt = alternate per arm-A order); arm B is always PEM (the plugin's shape); + /// CERTINEXT_V2_INLINE_CSR_PRODUCT_HEADER (on default = X-Product-Code: CERTINEXT_PRODUCT_CODE + /// [842]; off = omit the header; anything else = that literal code); + /// CERTINEXT_V2_INLINE_CSR_SPACING_SECONDS pause between orders (default 20); + /// CERTINEXT_V2_INLINE_CSR_TIMEOUT_SECONDS per-order observation cap (default 180). + /// No retries of order creation. Emails are scrubbed from every output line; credentials come + /// from ~/.env_certinext_v2. Raw CSV goes to experiment-results/. + /// + public class V2InlineCsrIssuanceExperimentTests : IClassFixture + { + private const string OptInFlag = "CERTINEXT_V2_INLINE_CSR_EXPERIMENT"; + private const int MaxPerArm = 8; + private const int MaxListPollsInFlight = 2; + private const string CleanupReason = "V2 inline-CSR experiment cleanup (issues 0062/0090) - sandbox test order."; + private static readonly TimeSpan ListPollInterval = TimeSpan.FromSeconds(1.5); + private static readonly TimeSpan TrackPollInterval = TimeSpan.FromSeconds(1.5); + + private readonly ITestOutputHelper _output; + private readonly Stopwatch _clock = Stopwatch.StartNew(); + + private readonly string _apiUrl; + private readonly string _clientId; + private readonly string _clientSecret; + private readonly string _productCode; + private readonly string _baseDomain; + private readonly string _requestorName; + private readonly string _requestorEmail; + private readonly string _groupNumber; + private readonly bool _v2Enabled; + + public V2InlineCsrIssuanceExperimentTests(IntegrationTestFixture fixture, ITestOutputHelper output) + { + _output = output; + + var env = V2EnvHelper.LoadAndPromote(); + _apiUrl = V2EnvHelper.GetEnv(env, "CERTINEXT_API_URL"); + _clientId = V2EnvHelper.GetEnv(env, "CERTINEXT_CLIENT_ID"); + _clientSecret = V2EnvHelper.GetEnv(env, "CERTINEXT_CLIENT_SECRET"); + _productCode = V2EnvHelper.GetEnv(env, "CERTINEXT_PRODUCT_CODE", "842"); + _baseDomain = V2EnvHelper.GetEnv(env, "CERTINEXT_DCV_DOMAIN", string.Empty); + _requestorName = V2EnvHelper.GetEnv(env, "CERTINEXT_REQUESTOR_NAME", "Keyfactor Integration Test"); + _requestorEmail = V2EnvHelper.GetEnv(env, "CERTINEXT_REQUESTOR_EMAIL", "test@example.com"); + _groupNumber = V2EnvHelper.GetEnv(env, "CERTINEXT_GROUP_NUMBER", string.Empty); + _v2Enabled = !string.IsNullOrWhiteSpace(V2EnvHelper.GetEnv(env, "CERTINEXT_USE_V2_API")) + && !string.IsNullOrWhiteSpace(_apiUrl) + && !string.IsNullOrWhiteSpace(_clientId) + && !string.IsNullOrWhiteSpace(_clientSecret); + } + + private double Now => _clock.Elapsed.TotalSeconds; + + private static readonly Regex EmailRx = new(@"[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}", RegexOptions.Compiled); + + /// Strips anything email-shaped and caps length; used for every line that leaves the test. + private static string Scrub(string s, int max = 400) + { + if (string.IsNullOrEmpty(s)) return s ?? string.Empty; + s = EmailRx.Replace(s, ""); + s = s.Replace("\r", " ").Replace("\n", " "); + return s.Length > max ? s.Substring(0, max) + "..." : s; + } + + private static readonly Regex PersonBlockRx = new( + "\"(orderedBy|requestor|technicalPointOfContact|requestedBy)\"\\s*:\\s*\\{[^}]*\\}", RegexOptions.Compiled | RegexOptions.IgnoreCase); + + /// + /// Scrub for raw API bodies: drops the person blocks (the response echoes the requestor and the + /// account user's name/email) and then applies the normal email scrub and length cap. + /// + private static string ScrubBody(string s, int max = 400) => + Scrub(PersonBlockRx.Replace(s ?? string.Empty, m => $"\"{m.Groups[1].Value}\":{{}}"), max); + + private static string Describe(Exception ex) => Scrub($"{ex.GetType().Name}: {ex.Message}"); + + private void W(string s) => _output.WriteLine(Scrub(s, 1200)); + + // --------------------------------------------------------------------------- + // Observation records + // --------------------------------------------------------------------------- + + private sealed class HttpResult + { + public double Start; + public double End = double.NaN; + public int Status; + public string Body = string.Empty; + public string Error = string.Empty; + public double Ms => (End - Start) * 1000.0; + public bool Ok => Status >= 200 && Status < 300; + } + + private sealed class TrackObs + { + public double Sent; + public double Recv; + public int Http; + public string Status = string.Empty; + public string OrderState = string.Empty; + public string CertState = string.Empty; + public string Error = string.Empty; + public string Body = string.Empty; + public string Sig => $"{Status}|{OrderState}|{CertState}"; + } + + private sealed class ListObs + { + public double Start; + public double End; + public int Rows; + public string Error = string.Empty; + /// Orders on the experiment domain that did not exist before t0: orderNumber -> "orderStatus|certStatus". + public Dictionary New = new(StringComparer.Ordinal); + } + + private sealed class Trial + { + public int Index; + public string Arm; + public string Encoding = "pem"; + public string Domain; + public string OrderId = string.Empty; + public DateTime T0Utc; + public double T0; + + public int CreateHttp; + public double CreateMs = double.NaN, TCreateResp = double.NaN; + public string CreateStatus = string.Empty, CreateOrderState = string.Empty, CreateCertState = string.Empty; + public string CreateBody = string.Empty; + public int PutHttp; + public double PutMs = double.NaN, TPutResp = double.NaN; + public string PutBody = string.Empty; + + public double TFirstTrackObs = double.NaN; + public double TIssuedTrack = double.NaN, TIssuedTrackLower = double.NaN; + public string TrackSeq = string.Empty; + public bool SystemErrorSeen; + public double SysErrFirst = double.NaN, SysErrCleared = double.NaN; + public int TrackPolls, TrackErrors; + + public double FirstSeenList = double.NaN, FirstSeenListLower = double.NaN; + public string FirstSeenListStatus = string.Empty; + public double TIssuedList = double.NaN; + public string ListSeq = string.Empty; + public int ListPolls, ListErrors; + public double ListPollMedianS = double.NaN; + + public double DlFirstAt = double.NaN, DlSuccessAt = double.NaN, DlMs = double.NaN; + public int DlAttempts; + public volatile bool TrackSaidIssued; + public string DlLastFailure = string.Empty; + public string DlFirstResult = string.Empty; + public string CertPubKeyMatch = string.Empty, CertCnMatch = string.Empty; + + public List Strays = new(); + public string CleanupNote = string.Empty; + public string FinalState = string.Empty; + public string Error = string.Empty; + + public bool Issued => !double.IsNaN(TIssuedTrack) || !double.IsNaN(TIssuedList); + } + + // --------------------------------------------------------------------------- + // Small helpers + // --------------------------------------------------------------------------- + + private static string F(double x) => double.IsNaN(x) ? "" : x.ToString("0.00", CultureInfo.InvariantCulture); + + private static double Median(IEnumerable xs) + { + var a = xs.Where(x => !double.IsNaN(x)).OrderBy(x => x).ToArray(); + if (a.Length == 0) return double.NaN; + return a.Length % 2 == 1 ? a[a.Length / 2] : (a[a.Length / 2 - 1] + a[a.Length / 2]) / 2.0; + } + + private static string RepoRoot() + { + var dir = new DirectoryInfo(AppContext.BaseDirectory); + while (dir != null && !File.Exists(Path.Combine(dir.FullName, "certinext-caplugin.sln"))) + dir = dir.Parent; + return dir?.FullName ?? Directory.GetCurrentDirectory(); + } + + private static string EnvOr(string name, string fallback) + { + string v = Environment.GetEnvironmentVariable(name); + return string.IsNullOrWhiteSpace(v) ? fallback : v.Trim(); + } + + /// First string value of at the top level of the JSON body, else anywhere (depth-first); "" if none. + private static string JsonString(string body, string name, bool topLevelOnly) + { + if (string.IsNullOrWhiteSpace(body)) return string.Empty; + try + { + using var doc = JsonDocument.Parse(body); + if (doc.RootElement.ValueKind == JsonValueKind.Object) + { + foreach (var p in doc.RootElement.EnumerateObject()) + if (string.Equals(p.Name, name, StringComparison.OrdinalIgnoreCase) && p.Value.ValueKind == JsonValueKind.String) + return p.Value.GetString() ?? string.Empty; + } + if (topLevelOnly) return string.Empty; + return FindDeep(doc.RootElement, name) ?? string.Empty; + } + catch (JsonException) { return string.Empty; } + } + + private static string FindDeep(JsonElement e, string name) + { + if (e.ValueKind == JsonValueKind.Object) + { + foreach (var p in e.EnumerateObject()) + { + if (string.Equals(p.Name, name, StringComparison.OrdinalIgnoreCase) && p.Value.ValueKind == JsonValueKind.String) + return p.Value.GetString(); + string d = FindDeep(p.Value, name); + if (d != null) return d; + } + } + else if (e.ValueKind == JsonValueKind.Array) + { + foreach (var item in e.EnumerateArray()) + { + string d = FindDeep(item, name); + if (d != null) return d; + } + } + return null; + } + + private static bool IsIssuedStatus(string s) => + string.Equals(s, Constants.ApiV2.StatusIssued, StringComparison.OrdinalIgnoreCase); + + private static bool IsTerminalNonIssued(string s) => + string.Equals(s, Constants.ApiV2.StatusRevoked, StringComparison.OrdinalIgnoreCase) + || string.Equals(s, Constants.ApiV2.StatusCancelled, StringComparison.OrdinalIgnoreCase) + || string.Equals(s, Constants.ApiV2.StatusRejected, StringComparison.OrdinalIgnoreCase) + || string.Equals(s, Constants.ApiV2.StatusExpired, StringComparison.OrdinalIgnoreCase); + + private static bool IsPendingStatus(string s) => + !string.IsNullOrEmpty(s) && s.StartsWith("pending-", StringComparison.OrdinalIgnoreCase); + + private static bool IsIssuedListing(string combined) => + combined != null && + (combined.IndexOf("Generated", StringComparison.OrdinalIgnoreCase) >= 0 + || combined.IndexOf("Downloaded", StringComparison.OrdinalIgnoreCase) >= 0); + + private static bool IsSystemError(string certState) => + !string.IsNullOrEmpty(certState) && certState.IndexOf("error", StringComparison.OrdinalIgnoreCase) >= 0; + + private static readonly JsonSerializerOptions PluginJsonOptions = new JsonSerializerOptions + { + PropertyNameCaseInsensitive = true, + DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull + }; + + private CERTInextConfig BuildConfig() => new CERTInextConfig + { + ApiUrl = _apiUrl, + UseV2Api = true, + OAuthClientId = _clientId, + OAuthClientSecret = _clientSecret, + RequestorName = _requestorName, + RequestorEmail = _requestorEmail, + RequestorIsdCode = "1", + RequestorMobileNumber = "0000000000", + SignerPlace = "Gateway Lab", + SignerIp = "127.0.0.1", + GroupNumber = _groupNumber, + PageSize = 100, + DcvEnabled = false + }; + + // --------------------------------------------------------------------------- + // CSR (BouncyCastle only) + // --------------------------------------------------------------------------- + + private sealed class CsrBundle + { + public AsymmetricCipherKeyPair KeyPair; + public string Pem; + public string Base64Der; + } + + private static CsrBundle GenerateCsr(string commonName) + { + var keyGen = new RsaKeyPairGenerator(); + keyGen.Init(new KeyGenerationParameters(new SecureRandom(), 2048)); + var keyPair = keyGen.GenerateKeyPair(); + var csr = new Pkcs10CertificationRequest("SHA256withRSA", new X509Name($"CN={commonName}"), + keyPair.Public, null, keyPair.Private); + byte[] der = csr.GetEncoded(); + return new CsrBundle + { + KeyPair = keyPair, + Base64Der = Convert.ToBase64String(der), + Pem = "-----BEGIN CERTIFICATE REQUEST-----\n" + + Convert.ToBase64String(der, Base64FormattingOptions.InsertLineBreaks) + + "\n-----END CERTIFICATE REQUEST-----" + }; + } + + /// Parses the downloaded PEM with BouncyCastle and compares public key + CN to the CSR. + private static void CheckCertificate(Trial t, string certPem, CsrBundle csr) + { + try + { + using var sr = new StringReader(certPem); + var cert = new PemReader(sr).ReadObject() as Org.BouncyCastle.X509.X509Certificate; + if (cert == null) { t.CertPubKeyMatch = "unparseable"; t.CertCnMatch = "unparseable"; return; } + var certKey = cert.GetPublicKey() as RsaKeyParameters; + var csrKey = csr.KeyPair.Public as RsaKeyParameters; + t.CertPubKeyMatch = certKey != null && csrKey != null && certKey.Modulus.Equals(csrKey.Modulus) + && certKey.Exponent.Equals(csrKey.Exponent) ? "match" : "MISMATCH"; + string subject = cert.SubjectDN.ToString(); + t.CertCnMatch = subject.IndexOf("CN=" + t.Domain, StringComparison.OrdinalIgnoreCase) >= 0 ? "match" : "MISMATCH(" + Scrub(subject, 120) + ")"; + } + catch (Exception ex) + { + t.CertPubKeyMatch = "error: " + Describe(ex); + t.CertCnMatch = t.CertPubKeyMatch; + } + } + + // --------------------------------------------------------------------------- + // Raw HTTP + // --------------------------------------------------------------------------- + + /// + /// One raw V2 call with the same headers the plugin client sends (Bearer, Accept, optional + /// Idempotency-Key and X-Product-Code). Never throws: transport errors land in . + /// + private async Task SendAsync(RestClient api, string token, Method method, string path, + string jsonBody, string productHeader, bool idempotency, TimeSpan timeout) + { + var r = new HttpResult { Start = Now }; + try + { + var req = new RestRequest(path, method); + req.AddHeader("Authorization", $"Bearer {token}"); + req.AddHeader("Accept", "application/json"); + if (idempotency) req.AddHeader("Idempotency-Key", Guid.NewGuid().ToString()); + if (!string.IsNullOrWhiteSpace(productHeader)) req.AddHeader("X-Product-Code", productHeader); + if (jsonBody != null) req.AddJsonBody(jsonBody); + using var cts = new CancellationTokenSource(timeout); + var resp = await api.ExecuteAsync(req, cts.Token); + r.Status = (int)resp.StatusCode; + r.Body = resp.Content ?? string.Empty; + if (resp.StatusCode == 0) + r.Error = Scrub($"{resp.ResponseStatus}: {resp.ErrorMessage}"); + } + catch (Exception ex) + { + r.Error = Describe(ex); + } + r.End = Now; + return r; + } + + // --------------------------------------------------------------------------- + // The experiment + // --------------------------------------------------------------------------- + + [SkippableFact] + public async Task V2InlineCsr_SingleCall_Vs_TwoCall_Issuance_Experiment() + { + Skip.If(!_v2Enabled, "V2 credentials not configured in ~/.env_certinext_v2 (CERTINEXT_USE_V2_API, API_URL, CLIENT_ID, CLIENT_SECRET)."); + Skip.If(Environment.GetEnvironmentVariable(OptInFlag) != "1", + $"Opt-in: set {OptInFlag}=1 as a real environment variable (places live sandbox orders)."); + Skip.If(string.IsNullOrWhiteSpace(_baseDomain), "CERTINEXT_DCV_DOMAIN is required (verified base domain used as the order CN)."); + + int perArm = int.TryParse(Environment.GetEnvironmentVariable("CERTINEXT_V2_INLINE_CSR_COUNT"), out int c) ? c : 5; + perArm = Math.Max(1, Math.Min(MaxPerArm, perArm)); + string arms = EnvOr("CERTINEXT_V2_INLINE_CSR_ARMS", "AB").ToUpperInvariant(); + bool doA = arms.Contains('A'), doB = arms.Contains('B'); + Assert.True(doA || doB, "CERTINEXT_V2_INLINE_CSR_ARMS must contain A and/or B."); + string encMode = EnvOr("CERTINEXT_V2_INLINE_CSR_ENCODING", "pem").ToLowerInvariant(); + Assert.Contains(encMode, new[] { "pem", "der", "alt" }); + string headerMode = EnvOr("CERTINEXT_V2_INLINE_CSR_PRODUCT_HEADER", "on"); + string productHeader = headerMode.Equals("on", StringComparison.OrdinalIgnoreCase) ? _productCode + : (headerMode.Equals("off", StringComparison.OrdinalIgnoreCase) || headerMode.Equals("none", StringComparison.OrdinalIgnoreCase)) ? null + : headerMode; + double spacing = double.TryParse(Environment.GetEnvironmentVariable("CERTINEXT_V2_INLINE_CSR_SPACING_SECONDS"), + NumberStyles.Float, CultureInfo.InvariantCulture, out double sp) ? sp : 20; + double timeoutS = double.TryParse(Environment.GetEnvironmentVariable("CERTINEXT_V2_INLINE_CSR_TIMEOUT_SECONDS"), + NumberStyles.Float, CultureInfo.InvariantCulture, out double to) ? to : 180; + + string runId = DateTime.UtcNow.ToString("MMddHHmm", CultureInfo.InvariantCulture); + var cfg = BuildConfig(); + using var listClient = new CERTInextClient(cfg); + using var cleanupClient = new CERTInextClient(cfg); + var api = V2RawHttpHelpers.NewApiClient(_apiUrl.TrimEnd('/'), TimeSpan.FromSeconds(300)); + + W($"V2 inline-CSR experiment run {runId}: domain={_baseDomain}, X-Product-Code={(productHeader ?? "")}, " + + $"arms={arms}, perArm={perArm}, armAEncoding={encMode}, spacingS={F(spacing)}, observeCapS={F(timeoutS)}"); + + // Interleaved schedule A,B,A,B,... + var schedule = new List(); + for (int i = 0; i < perArm; i++) + { + // Arm order within each pair follows the ARMS string (e.g. "BA" puts the two-call control first). + foreach (char ch in arms) + if (ch == 'A' || ch == 'B') schedule.Add(ch.ToString()); + } + + var trials = new List(); + var consecutiveNoIssue = new Dictionary { ["A"] = 0, ["B"] = 0 }; + var aCount = 0; + double lastEnd = double.NegativeInfinity; + try + { + foreach (string arm in schedule) + { + if (consecutiveNoIssue[arm] >= 2) + { + W($"arm {arm}: skipped - the previous 2 orders in this arm did not issue; stopping the arm (report as a finding)."); + continue; + } + var t = new Trial { Index = trials.Count + 1, Arm = arm, Domain = _baseDomain.ToLowerInvariant() }; + if (arm == "A") + { + t.Encoding = encMode == "alt" ? (aCount % 2 == 0 ? "pem" : "der") : encMode; + aCount++; + } + trials.Add(t); + + double wait = lastEnd + spacing - Now; + if (wait > 0) await Task.Delay(TimeSpan.FromSeconds(wait)); + + try + { + await RunTrialAsync(t, api, listClient, productHeader, timeoutS); + } + catch (Exception ex) + { + t.Error += "trial: " + Describe(ex) + "; "; + } + finally + { + await CleanupTrialAsync(cleanupClient, t); + lastEnd = Now; + } + consecutiveNoIssue[arm] = t.Issued ? 0 : consecutiveNoIssue[arm] + 1; + LogTrial(t); + } + } + finally + { + WriteCsv(runId, trials, productHeader, encMode); + WriteSummary(trials); + W("ORDER IDS: " + string.Join(",", trials.SelectMany(t => new[] { t.OrderId }.Concat(t.Strays)).Where(s => !string.IsNullOrEmpty(s)).Distinct())); + } + + var notTerminal = trials.Where(t => !string.IsNullOrEmpty(t.OrderId) && !IsTerminalNonIssued(t.FinalState)) + .Select(t => $"{t.OrderId}({t.FinalState})").ToList(); + Assert.True(notTerminal.Count == 0, "Orders not in a terminal state after cleanup: " + string.Join(", ", notTerminal)); + } + + private async Task RunTrialAsync(Trial t, RestClient api, CERTInextClient listClient, string productHeader, double timeoutS) + { + string basePath = Constants.ApiV2.SslCertificatesPath; + bool inline = t.Arm == "A"; + + // Everything not under test happens before t0. + var csr = GenerateCsr(t.Domain); + string token = await V2RawHttpHelpers.GetV2AccessTokenAsync(_apiUrl, _clientId, _clientSecret); + string today = DateTime.UtcNow.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture); + string tomorrow = DateTime.UtcNow.AddDays(1).ToString("yyyy-MM-dd", CultureInfo.InvariantCulture); + + var snapshot = new HashSet(StringComparer.Ordinal); + await foreach (var e in listClient.ListOrdersV2Async(today, tomorrow, 100)) + if (e?.OrderNumber != null && string.Equals(e.DomainName, t.Domain, StringComparison.OrdinalIgnoreCase)) + snapshot.Add(e.OrderNumber); + + // Body = the plugin's own DTO + serializer options (identical to what Enroll sends for DV 842), + // plus "csr" injected for arm A. + string requestorPhone = CERTInextCAPlugin.ComposeV2Phone("1", "0000000000"); + var orderReq = new V2CreateSslOrderRequest + { + ProductVariant = "dv", + Requestor = new V2Requestor { Name = _requestorName, Email = _requestorEmail, Phone = requestorPhone }, + Certificate = new V2CertificateParams { Domain = t.Domain, AutoSecureWww = false }, + Subscription = new V2SubscriptionParams { ValidityYears = 1, AutoRenew = false }, + Agreement = new V2AgreementParams { SignerName = _requestorName, SignerPlace = "Gateway Lab", Accepted = true }, + TechnicalPointOfContact = new V2TechnicalPointOfContact + { + Name = _requestorName, Email = _requestorEmail, Phone = requestorPhone, + Designation = Constants.ApiV2.DefaultTechnicalContactDesignation + }, + Remarks = "Issued via Keyfactor Command AnyCA REST Gateway.", + GroupNumber = string.IsNullOrWhiteSpace(_groupNumber) ? null : _groupNumber + }; + string createJson = JsonSerializer.Serialize(orderReq, PluginJsonOptions); + if (inline) + { + var node = JsonNode.Parse(createJson) as JsonObject ?? throw new InvalidOperationException("create body is not a JSON object"); + node["csr"] = t.Encoding == "der" ? csr.Base64Der : csr.Pem; + createJson = node.ToJsonString(); + } + string putJson = JsonSerializer.Serialize(new V2SubmitCsrRequest { Csr = csr.Pem }, PluginJsonOptions); + + var trackObs = new ConcurrentQueue(); + var listObs = new ConcurrentQueue(); + using var stopAll = new CancellationTokenSource(); + + var inflight = new List(); + var listerTask = Task.Run(async () => + { + async Task PollOnce() + { + var o = new ListObs { Start = Now }; + try + { + await foreach (var e in listClient.ListOrdersV2Async(today, tomorrow, 100)) + { + o.Rows++; + if (e?.OrderNumber != null + && string.Equals(e.DomainName, t.Domain, StringComparison.OrdinalIgnoreCase) + && !snapshot.Contains(e.OrderNumber)) + o.New[e.OrderNumber] = $"{e.OrderStatus}|{e.CertificateStatus}"; + } + } + catch (Exception ex) { o.Error = Describe(ex); } + o.End = Now; + listObs.Enqueue(o); + } + while (!stopAll.IsCancellationRequested) + { + inflight.RemoveAll(x => x.IsCompleted); + if (inflight.Count < MaxListPollsInFlight) inflight.Add(Task.Run(PollOnce)); + try { await Task.Delay(ListPollInterval, stopAll.Token); } catch (OperationCanceledException) { } + } + await Task.WhenAll(inflight); + }); + await Task.Delay(ListPollInterval); // listing poller is already running before t0 + + Task trackerTask = Task.CompletedTask; + string orderId = string.Empty; + try + { + // ---- t0: create ---- + t.T0Utc = DateTime.UtcNow; + t.T0 = Now; + var create = await SendAsync(api, token, Method.Post, basePath, createJson, productHeader, idempotency: true, TimeSpan.FromSeconds(280)); + t.CreateHttp = create.Status; + t.CreateMs = create.Ms; + t.TCreateResp = create.End; + t.CreateBody = ScrubBody(create.Body, 900); + t.CreateStatus = JsonString(create.Body, "status", topLevelOnly: true); + t.CreateOrderState = JsonString(create.Body, "orderState", topLevelOnly: false); + t.CreateCertState = JsonString(create.Body, "certificateState", topLevelOnly: false); + if (!string.IsNullOrEmpty(create.Error)) t.Error += "create: " + create.Error + "; "; + if (!create.Ok) t.Error += $"create HTTP {create.Status}: {ScrubBody(create.Body, 300)}; "; + orderId = create.Ok ? JsonString(create.Body, "orderId", topLevelOnly: true) : string.Empty; + t.OrderId = orderId ?? string.Empty; + + if (!string.IsNullOrEmpty(orderId)) + { + // Tracker starts the instant the create response lands. + trackerTask = Task.WhenAll( + Task.Run(() => TrackLoopAsync(t, api, token, basePath, orderId, trackObs, stopAll.Token)), + Task.Run(() => DownloadLoopAsync(t, api, token, basePath, orderId, csr, stopAll.Token))); + + if (!inline) + { + var put = await SendAsync(api, token, Method.Put, $"{basePath}/{orderId}/csr", putJson, null, idempotency: false, TimeSpan.FromSeconds(280)); + t.PutHttp = put.Status; + t.PutMs = put.Ms; + t.TPutResp = put.End; + t.PutBody = ScrubBody(put.Body, 400); + if (!string.IsNullOrEmpty(put.Error)) t.Error += "put: " + put.Error + "; "; + if (!put.Ok) t.Error += $"put HTTP {put.Status}: {ScrubBody(put.Body, 300)}; "; + } + + // Observe until issued + downloaded + listing agrees, a terminal failure, or the cap. + double deadline = t.T0 + timeoutS; + double terminalAt = double.NaN; + double settledAt = double.NaN; + while (Now < deadline) + { + await Task.Delay(500); + var snapT = trackObs.ToArray(); + var latest = snapT.OrderBy(o => o.Recv).LastOrDefault(o => string.IsNullOrEmpty(o.Error)); + if (latest != null && IsTerminalNonIssued(latest.Status)) + { + if (double.IsNaN(terminalAt)) terminalAt = Now; + if (Now >= terminalAt + 3) break; + } + bool issuedSeen = snapT.Any(o => IsIssuedStatus(o.Status)); + bool listingIssued = listObs.ToArray().Any(l => l.New.TryGetValue(orderId, out var s) && IsIssuedListing(s)); + if (issuedSeen && !double.IsNaN(t.DlSuccessAt) && (listingIssued || Now > t.TIssuedTrack + 30)) + { + // Tail: keep polling a few more seconds so the final Track Order / listing states are captured. + if (double.IsNaN(settledAt)) settledAt = Now; + if (Now >= settledAt + 5) break; + } + if (t.DlAttempts >= 60 && issuedSeen) break; + } + } + else + { + // Create failed or returned no order id: keep listing for a moment so any stray order is seen. + await Task.Delay(TimeSpan.FromSeconds(10)); + } + } + finally + { + stopAll.Cancel(); + try { await Task.WhenAll(trackerTask, listerTask); } catch { /* observation only */ } + } + + Analyze(t, trackObs.OrderBy(o => o.Recv).ToList(), listObs.OrderBy(o => o.Start).ToList()); + } + + private async Task TrackLoopAsync(Trial t, RestClient api, string token, string basePath, string orderId, + ConcurrentQueue trackObs, CancellationToken stop) + { + while (!stop.IsCancellationRequested) + { + var o = new TrackObs { Sent = Now }; + var r = await SendAsync(api, token, Method.Get, $"{basePath}/{orderId}", null, null, idempotency: false, TimeSpan.FromSeconds(30)); + o.Recv = Now; + o.Http = r.Status; + o.Error = r.Ok ? string.Empty : (string.IsNullOrEmpty(r.Error) ? $"HTTP {r.Status} {Scrub(r.Body, 150)}" : r.Error); + if (r.Ok) + { + o.Status = JsonString(r.Body, "status", topLevelOnly: true); + o.OrderState = JsonString(r.Body, "orderState", topLevelOnly: false); + o.CertState = JsonString(r.Body, "certificateState", topLevelOnly: false); + o.Body = ScrubBody(r.Body, 700); + } + trackObs.Enqueue(o); + + if (r.Ok && IsIssuedStatus(o.Status)) t.TrackSaidIssued = true; + try { await Task.Delay(TrackPollInterval, stop); } catch (OperationCanceledException) { } + } + } + + /// + /// Separate from the tracker so slow/failing downloads never delay Track Order polling. + /// Starts probing GET .../certificate once Track Order first says "issued" and retries every + /// ~2 s until one call returns a certificate (or the observation ends). The first failure body is kept. + /// + private async Task DownloadLoopAsync(Trial t, RestClient api, string token, string basePath, string orderId, + CsrBundle csr, CancellationToken stop) + { + while (!stop.IsCancellationRequested && double.IsNaN(t.DlSuccessAt) && t.DlAttempts < 60) + { + if (t.TrackSaidIssued) + { + t.DlAttempts++; + var dl = await SendAsync(api, token, Method.Get, $"{basePath}/{orderId}/certificate", null, null, idempotency: false, TimeSpan.FromSeconds(60)); + string pem = dl.Ok ? JsonString(dl.Body, "certificatePem", topLevelOnly: true) : string.Empty; + string result = dl.Ok ? (string.IsNullOrWhiteSpace(pem) ? "ok-empty" : "ok-with-certificate") + : $"HTTP {dl.Status} {ScrubBody(string.IsNullOrEmpty(dl.Error) ? dl.Body : dl.Error, 220)}"; + if (double.IsNaN(t.DlFirstAt)) + { + t.DlFirstAt = dl.Start; + t.DlFirstResult = result; + } + t.DlLastFailure = dl.Ok && !string.IsNullOrWhiteSpace(pem) ? t.DlLastFailure : $"{result} @{F(dl.End - t.T0)}s ({F(dl.Ms / 1000)}s call)"; + if (dl.Ok && !string.IsNullOrWhiteSpace(pem)) + { + t.DlSuccessAt = dl.End; + t.DlMs = dl.Ms; + CheckCertificate(t, pem, csr); + return; + } + } + try { await Task.Delay(TimeSpan.FromSeconds(2), stop); } catch (OperationCanceledException) { } + } + } + + private void Analyze(Trial t, List track, List lists) + { + string id = t.OrderId; + + // ---- tracker ---- + t.TrackPolls = track.Count; + t.TrackErrors = track.Count(o => !string.IsNullOrEmpty(o.Error)); + var ok = track.Where(o => string.IsNullOrEmpty(o.Error)).ToList(); + if (ok.Count > 0) t.TFirstTrackObs = ok[0].Recv; + var issuedTrack = ok.FirstOrDefault(o => IsIssuedStatus(o.Status)); + if (issuedTrack != null) { t.TIssuedTrack = issuedTrack.Recv; t.TIssuedTrackLower = issuedTrack.Sent; } + + // Sequence starts with the create response's own state so "System Error" at create time is visible. + var seq = new List(); + string createSig = $"{t.CreateStatus}|{t.CreateOrderState}|{t.CreateCertState}"; + if (!string.IsNullOrEmpty(t.OrderId)) seq.Add($"create:{createSig}@{F(t.TCreateResp - t.T0)}"); + string prev = createSig; + foreach (var o in ok) + if (o.Sig != prev) + { + seq.Add($"{o.Sig}@{F(o.Recv - t.T0)}"); + prev = o.Sig; + } + t.TrackSeq = string.Join("; ", seq); + + // System Error: first seen (create response counts) and when it clears. + var states = new List<(double at, string cs)>(); + if (!string.IsNullOrEmpty(t.OrderId)) states.Add((t.TCreateResp, t.CreateCertState)); + states.AddRange(ok.Select(o => (o.Recv, o.CertState))); + var firstErr = states.FirstOrDefault(s => IsSystemError(s.cs)); + if (firstErr.cs != null) + { + t.SystemErrorSeen = true; + t.SysErrFirst = firstErr.at; + var cleared = states.FirstOrDefault(s => s.at > firstErr.at && !IsSystemError(s.cs)); + if (cleared.cs != null) t.SysErrCleared = cleared.at; + } + foreach (var o in track.Where(o => !string.IsNullOrEmpty(o.Error)).Take(2)) + t.Error += "track: " + o.Error + "; "; + + // ---- listing ---- + t.ListPolls = lists.Count; + t.ListErrors = lists.Count(l => !string.IsNullOrEmpty(l.Error)); + t.ListPollMedianS = Median(lists.Select(l => l.End - l.Start)); + var allNew = lists.SelectMany(l => l.New.Keys).Distinct().ToList(); + if (string.IsNullOrEmpty(id)) + { + // No order id from create: any new order on the domain is a stray from this trial. + t.Strays.AddRange(allNew); + return; + } + if (allNew.Any(n => n != id)) t.Error += $"other new orders on domain during trial: {string.Join("/", allNew.Where(n => n != id))}; "; + + var matched = lists.Where(l => l.New.ContainsKey(id)).OrderBy(l => l.End).ToList(); + if (matched.Count > 0) + { + t.FirstSeenList = matched[0].End; + t.FirstSeenListLower = matched[0].Start; + t.FirstSeenListStatus = Scrub(matched[0].New[id]); + var issuedL = matched.FirstOrDefault(l => IsIssuedListing(l.New[id])); + if (issuedL != null) t.TIssuedList = issuedL.End; + } + var lseq = new List(); + foreach (var l in matched) + { + string s = Scrub(l.New[id]); + if (lseq.Count == 0 || !lseq[^1].StartsWith(s + "@", StringComparison.Ordinal)) + lseq.Add($"{s}@{F(l.End - t.T0)}"); + } + t.ListSeq = string.Join("; ", lseq); + } + + // --------------------------------------------------------------------------- + // Cleanup: revoke issued / cancel pending, then re-track and record the final state + // --------------------------------------------------------------------------- + + private async Task CleanupTrialAsync(CERTInextClient client, Trial t) + { + var ids = new List(); + if (!string.IsNullOrEmpty(t.OrderId)) ids.Add(t.OrderId); + // Strays are only populated when create returned no order id, so there is exactly one order we created. + if (string.IsNullOrEmpty(t.OrderId) && t.Strays.Count == 1) ids.AddRange(t.Strays); + if (ids.Count == 0) { t.CleanupNote = "no order"; return; } + + var notes = new List(); + foreach (string id in ids) + { + string note = await CleanupOneAsync(client, id, t); + notes.Add($"{id}: {note}"); + } + t.CleanupNote = string.Join(" | ", notes); + if (string.IsNullOrEmpty(t.OrderId) && t.Strays.Count == 1) t.OrderId = t.Strays[0]; // reported as this trial's order + } + + private async Task CleanupOneAsync(CERTInextClient client, string id, Trial t) + { + string family = Constants.ApiV2.FamilySsl; + string before = "?"; + string action = "none"; + try + { + before = (await client.TrackOrderV2Async(family, id)).Status ?? "(null)"; + if (IsTerminalNonIssued(before)) action = "skip (already " + before + ")"; + else if (IsIssuedStatus(before)) + { + try + { + await client.RevokeOrderV2Async(family, id, new V2RevokeRequest { Reason = "superseded", Note = CleanupReason }); + action = "revoke(superseded)"; + } + catch (Exception rex) + { + action = "revoke(superseded) rejected: " + Describe(rex); + await client.RevokeOrderV2Async(family, id, new V2RevokeRequest { Reason = "unspecified", Note = CleanupReason }); + action += " -> revoke(unspecified)"; + } + } + else if (IsPendingStatus(before)) + { + var outcome = await client.CancelOrderV2Async(family, id, CleanupReason); + action = "cancel -> " + outcome; + } + else action = "skip (unrecognised status)"; + } + catch (Exception ex) + { + action += "; ACTION FAILED: " + Describe(ex); + } + + string after = "?"; + for (int attempt = 0; attempt < 4; attempt++) + { + try + { + after = (await client.TrackOrderV2Async(family, id)).Status ?? "(null)"; + if (IsTerminalNonIssued(after)) break; + } + catch (Exception ex) { after = "TRACK ERROR: " + Describe(ex); } + await Task.Delay(TimeSpan.FromSeconds(2)); + } + if (id == t.OrderId || string.IsNullOrEmpty(t.OrderId)) t.FinalState = after; + return $"before={before}; {action}; after={after}"; + } + + // --------------------------------------------------------------------------- + // Output + // --------------------------------------------------------------------------- + + private void LogTrial(Trial t) + { + W($"trial {t.Index:D2} arm={t.Arm} enc={(t.Arm == "A" ? t.Encoding : "pem(put)")} order={(string.IsNullOrEmpty(t.OrderId) ? "-" : t.OrderId)} " + + $"createHttp={t.CreateHttp} createS={F(t.CreateMs / 1000)} createStatus={t.CreateStatus} createOrderState={t.CreateOrderState} createCertState={t.CreateCertState} " + + $"putHttp={t.PutHttp} putS={F(t.PutMs / 1000)} " + + $"issuedTrack={F(t.TIssuedTrack - t.T0)}s issuedListing={F(t.TIssuedList - t.T0)}s firstSeenListing={F(t.FirstSeenList - t.T0)}s({t.FirstSeenListStatus}) " + + $"dlFirst@{F(t.DlFirstAt - t.T0)}s={t.DlFirstResult} dlAttempts={t.DlAttempts} dlLastFail=[{t.DlLastFailure}] dlOkAt={F(t.DlSuccessAt - t.T0)}s pubkey={t.CertPubKeyMatch} cn={t.CertCnMatch} " + + $"sysErr={t.SystemErrorSeen}(first={F(t.SysErrFirst - t.T0)}s cleared={F(t.SysErrCleared - t.T0)}s) " + + $"trackSeq=[{t.TrackSeq}] listSeq=[{t.ListSeq}] cleanup=[{t.CleanupNote}] final={t.FinalState} {t.Error}"); + if (t.Arm == "B" || !string.IsNullOrEmpty(t.PutBody)) + W($"trial {t.Index:D2} put body: {t.PutBody}"); + W($"trial {t.Index:D2} create body: {t.CreateBody}"); + } + + private void WriteCsv(string runId, List trials, string productHeader, string encMode) + { + try + { + string dir = Path.Combine(RepoRoot(), "experiment-results"); + Directory.CreateDirectory(dir); + string path = Path.Combine(dir, $"v2-inline-csr-{runId}.csv"); + var sb = new StringBuilder(); + sb.AppendLine("trial,arm,arm_a_encoding,product_header,domain,order_id,t0_utc," + + "create_http,create_ms,create_status,create_order_state,create_cert_state,create_body," + + "put_http,put_ms,put_body," + + "t_create_resp_s,t_put_resp_s,t_first_track_obs_s,t_issued_track_s,t_issued_track_lower_s,track_seq," + + "system_error_seen,system_error_first_s,system_error_cleared_s," + + "first_seen_listing_s,first_seen_listing_lower_s,first_seen_listing_status,t_issued_listing_s,listing_seq," + + "seen_in_listing_before_create_resp,listing_first_seen_to_create_resp_s,issued_in_listing_before_create_resp,create_resp_minus_issued_listing_s," + + "dl_first_at_s,dl_first_result,dl_last_failure,dl_success_at_s,dl_ms,dl_attempts,cert_pubkey,cert_cn," + + "track_polls,track_errors,list_polls,list_poll_median_s,list_errors,cleanup,final_state,error"); + foreach (var t in trials) + { + string Rel(double x) => double.IsNaN(x) ? "" : F(x - t.T0); + string Q(string s) => "\"" + Scrub(s ?? "", 800).Replace("\"", "'") + "\""; + bool seenBefore = !double.IsNaN(t.FirstSeenList) && !double.IsNaN(t.TCreateResp) && t.FirstSeenList < t.TCreateResp; + bool issuedBefore = !double.IsNaN(t.TIssuedList) && !double.IsNaN(t.TCreateResp) && t.TIssuedList < t.TCreateResp; + sb.AppendLine(string.Join(",", new[] + { + t.Index.ToString(CultureInfo.InvariantCulture), t.Arm, t.Arm == "A" ? t.Encoding : "n/a", Q(productHeader ?? ""), t.Domain, t.OrderId, + t.T0Utc.ToString("o", CultureInfo.InvariantCulture), + t.CreateHttp.ToString(CultureInfo.InvariantCulture), F(t.CreateMs), t.CreateStatus, Q(t.CreateOrderState), Q(t.CreateCertState), Q(t.CreateBody), + t.PutHttp.ToString(CultureInfo.InvariantCulture), F(t.PutMs), Q(t.PutBody), + Rel(t.TCreateResp), Rel(t.TPutResp), Rel(t.TFirstTrackObs), Rel(t.TIssuedTrack), Rel(t.TIssuedTrackLower), Q(t.TrackSeq), + t.SystemErrorSeen ? "1" : "0", Rel(t.SysErrFirst), Rel(t.SysErrCleared), + Rel(t.FirstSeenList), Rel(t.FirstSeenListLower), Q(t.FirstSeenListStatus), Rel(t.TIssuedList), Q(t.ListSeq), + seenBefore ? "1" : "0", (!double.IsNaN(t.FirstSeenList) && !double.IsNaN(t.TCreateResp)) ? F(t.TCreateResp - t.FirstSeenList) : "", + issuedBefore ? "1" : "0", (!double.IsNaN(t.TIssuedList) && !double.IsNaN(t.TCreateResp)) ? F(t.TCreateResp - t.TIssuedList) : "", + Rel(t.DlFirstAt), Q(t.DlFirstResult), Q(t.DlLastFailure), Rel(t.DlSuccessAt), F(t.DlMs), t.DlAttempts.ToString(CultureInfo.InvariantCulture), Q(t.CertPubKeyMatch), Q(t.CertCnMatch), + t.TrackPolls.ToString(CultureInfo.InvariantCulture), t.TrackErrors.ToString(CultureInfo.InvariantCulture), + t.ListPolls.ToString(CultureInfo.InvariantCulture), F(t.ListPollMedianS), t.ListErrors.ToString(CultureInfo.InvariantCulture), + Q(t.CleanupNote), Q(t.FinalState), Q(t.Error) + })); + } + File.WriteAllText(path, sb.ToString()); + W($"CSV written: experiment-results/{Path.GetFileName(path)}"); + } + catch (Exception ex) + { + W($"CSV write failed: {Describe(ex)}"); + } + } + + private void WriteSummary(List trials) + { + foreach (string arm in new[] { "A", "B" }) + { + var ts = trials.Where(t => t.Arm == arm && !string.IsNullOrEmpty(t.OrderId)).ToList(); + if (ts.Count == 0) continue; + W($"=== arm {arm} summary (seconds after t0; min / median / max; n) over {ts.Count} orders, {ts.Count(t => t.Issued)} issued ==="); + void Row(string name, Func get) + { + var xs = ts.Select(get).Where(x => !double.IsNaN(x)).ToArray(); + W(xs.Length == 0 ? $"{name,-34} n=0" + : $"{name,-34} {F(xs.Min())} / {F(Median(xs))} / {F(xs.Max())} (n={xs.Length})"); + } + Row("create HTTP", t => t.CreateMs / 1000); + if (arm == "B") Row("PUT /csr HTTP", t => t.PutMs / 1000); + Row("first seen in listing", t => t.FirstSeenList - t.T0); + Row("issued (track)", t => t.TIssuedTrack - t.T0); + Row("issued (listing)", t => t.TIssuedList - t.T0); + Row("create resp (t_create_resp)", t => t.TCreateResp - t.T0); + Row("listing first seen -> create resp", t => t.TCreateResp - t.FirstSeenList); + Row("download ok at", t => t.DlSuccessAt - t.T0); + W($" system error seen in {ts.Count(t => t.SystemErrorSeen)}/{ts.Count}; cleared in {ts.Count(t => !double.IsNaN(t.SysErrCleared))}; " + + $"download ok {ts.Count(t => !double.IsNaN(t.DlSuccessAt))}/{ts.Count}; pubkey match {ts.Count(t => t.CertPubKeyMatch == "match")}; cn match {ts.Count(t => t.CertCnMatch == "match")}"); + } + } + } +} diff --git a/CERTInext.IntegrationTests/V2LifecycleTests.cs b/CERTInext.IntegrationTests/V2LifecycleTests.cs new file mode 100644 index 0000000..68a4859 --- /dev/null +++ b/CERTInext.IntegrationTests/V2LifecycleTests.cs @@ -0,0 +1,796 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.IO; +using System.Linq; +using System.Threading; +using System.Threading.Tasks; +using Org.BouncyCastle.Asn1.X509; +using Org.BouncyCastle.Crypto; +using Org.BouncyCastle.Crypto.Generators; +using Org.BouncyCastle.Pkcs; +using Org.BouncyCastle.Security; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Xunit; +using Xunit.Abstractions; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.IntegrationTests +{ + /// + /// Plugin-level integration tests for the V2 (OAuth2) API path — Tiers 1–3 (no DCV + /// build required). Unlike , which exercises + /// methods directly, these tests drive the full + /// IAnyCAPlugin surface (Enroll, Revoke, GetSingleRecord, + /// Synchronize) the way Keyfactor Command actually calls the plugin. + /// + /// All tests are gated behind CERTINEXT_USE_V2_API=1 plus valid V2 OAuth2 + /// credentials and skip gracefully otherwise. See for the + /// full list of required environment variables. + /// + public class V2LifecycleTests : IClassFixture + { + private readonly IntegrationTestFixture _fixture; + private readonly ITestOutputHelper _output; + + private readonly string _v2ApiUrl; + private readonly string _v2ClientId; + private readonly string _v2ClientSecret; + private readonly string _v2Domain; + private readonly bool _v2Enabled; + + public V2LifecycleTests(IntegrationTestFixture fixture, ITestOutputHelper output) + { + _fixture = fixture; + _output = output; + + var env = V2EnvHelper.LoadAndPromote(); + + _v2ApiUrl = V2EnvHelper.GetEnv(env, "CERTINEXT_API_URL"); + _v2ClientId = V2EnvHelper.GetEnv(env, "CERTINEXT_CLIENT_ID"); + _v2ClientSecret = V2EnvHelper.GetEnv(env, "CERTINEXT_CLIENT_SECRET"); + _v2Domain = V2EnvHelper.GetEnv(env, "CERTINEXT_DCV_DOMAIN", "test.example.com"); + + _v2Enabled = !string.IsNullOrWhiteSpace(V2EnvHelper.GetEnv(env, "CERTINEXT_USE_V2_API")) + && !string.IsNullOrWhiteSpace(_v2ApiUrl) + && !string.IsNullOrWhiteSpace(_v2ClientId) + && !string.IsNullOrWhiteSpace(_v2ClientSecret); + } + + // --------------------------------------------------------------------------- + // Helpers + // --------------------------------------------------------------------------- + + /// + /// Builds a wired for the V2 API. A single + /// serves both modes — in V2 mode it is the V2 + /// base URL, and V2 auth reuses + /// /. + /// Deliberately does NOT set any V1-only field (ApiKey/AccountNumber/AuthMode) — proving + /// those are optional when UseV2Api is true is itself part of what these tests exercise + /// (Synchronize now uses V2 /reports/orders, not V1 GetOrderReport). + /// + private CERTInextConfig BuildV2Config(bool dcvEnabled = false, int? pageSize = null, int? syncLookbackHours = null) + { + return new CERTInextConfig + { + ApiUrl = _v2ApiUrl, + UseV2Api = true, + V2InlineCsr = V2EnvHelper.InlineCsrFromEnv, // default single-call; CERTINEXT_V2_INLINE_CSR=0 selects two-call + OAuthClientId = _v2ClientId, + OAuthClientSecret = _v2ClientSecret, + + RequestorName = _fixture.IsConfigured ? _fixture.Config.RequestorName : "Keyfactor Test", + RequestorEmail = _fixture.IsConfigured ? _fixture.Config.RequestorEmail : "test@example.com", + RequestorIsdCode = "1", + RequestorMobileNumber = "0000000000", + SignerPlace = "Gateway Lab", + SignerIp = "127.0.0.1", + + PageSize = pageSize ?? 100, + + // Default 72h (Constants.ApiV2.DefaultSyncLookbackHours) is always added on top + // of lastSync regardless of how recent it is — on a busy shared sandbox that + // means every delta-sync test touches several days of orders (each issued row + // costs a live certificate download) unless narrowed here. + V2SyncLookbackHours = syncLookbackHours ?? Constants.ApiV2.DefaultSyncLookbackHours, + + DcvEnabled = dcvEnabled, + DcvPropagationDelaySeconds = 5, + DcvTimeoutMinutes = 3 + }; + } + + /// + /// Constructs a plugin instance wired to a real + /// built from (or a fresh + /// if none is supplied). Uses the two-arg test constructor so no + /// Initialize call is required. + /// + private CERTInextCAPlugin BuildV2Plugin(CERTInextConfig config = null) + { + config ??= BuildV2Config(); + var client = new CERTInextClient(config); + return new CERTInextCAPlugin(client, config); + } + + /// + /// Generates a fresh RSA-2048 PKCS#10 CSR for the given common name using + /// BouncyCastle only. + /// + private static string GenerateCsrPem(string commonName) + { + var keyGen = new RsaKeyPairGenerator(); + keyGen.Init(new KeyGenerationParameters(new SecureRandom(), 2048)); + var keyPair = keyGen.GenerateKeyPair(); + + var subject = new X509Name($"CN={commonName}"); + var csr = new Pkcs10CertificationRequest("SHA256withRSA", subject, keyPair.Public, null, keyPair.Private); + + return "-----BEGIN CERTIFICATE REQUEST-----\n" + + Convert.ToBase64String(csr.GetEncoded(), Base64FormattingOptions.InsertLineBreaks) + + "\n-----END CERTIFICATE REQUEST-----"; + } + + /// + /// Runs a full synchronization via the plugin and returns all collected records. + /// + private static async Task> RunSyncAsync( + CERTInextCAPlugin plugin, DateTime? lastSync = null, bool fullSync = true) + { + var buffer = new BlockingCollection(boundedCapacity: 10_000); + var collected = new List(); + + var syncTask = Task.Run(async () => + { + await plugin.Synchronize( + buffer, + lastSync: lastSync, + fullSync: fullSync, + cancelToken: CancellationToken.None); + + if (!buffer.IsAddingCompleted) + buffer.CompleteAdding(); + }); + + foreach (var record in buffer.GetConsumingEnumerable()) + collected.Add(record); + + await syncTask; + return collected; + } + + /// + /// Polls until the order reaches + /// GENERATED or FAILED, or the poll budget is exhausted. + /// + private static async Task WaitForIssuanceAsync( + CERTInextCAPlugin plugin, string caRequestId, int maxPolls = 6, int delaySeconds = 15) + { + AnyCAPluginCertificate record = null; + for (int poll = 1; poll <= maxPolls; poll++) + { + record = await plugin.GetSingleRecord(caRequestId); + if (record?.Status == (int)EndEntityStatus.GENERATED + || record?.Status == (int)EndEntityStatus.FAILED) + break; + if (poll < maxPolls) + await Task.Delay(TimeSpan.FromSeconds(delaySeconds)); + } + return record; + } + + /// + /// Product info for the "DV SSL" gateway template in : pinned + /// (ProductCode set, e.g. 842) or the unpinned "V2 template" (no ProductCode, so + /// CERTInext resolves the product). See . + /// + private static EnrollmentProductInfo BuildV2ProductInfo(V2PinMode mode) => + V2ProductPinning.Info(Constants.Products.DvSsl, mode); + + /// + /// Resolves the order ID to exercise for tests that need a pre-existing V2 order. + /// Reads only CERTINEXT_V2_ORDER_ID — deliberately does not fall back to an + /// order ID produced by another test in this class, so results do not depend on + /// test run order. + /// + private static string ResolveOrderId() + => Environment.GetEnvironmentVariable("CERTINEXT_V2_ORDER_ID"); + + /// + /// Returns an issued (GENERATED) V2 order to exercise, plus the plugin instance + /// that owns it. Prefers CERTINEXT_V2_ORDER_ID if set; otherwise enrolls a + /// fresh order in this test and polls (bounded) for issuance, so tests using this + /// helper are self-contained and don't depend on env state or another test's run + /// order. Skip.Ifs (via ) when no env ID + /// is set and the freshly-enrolled order never reaches GENERATED within the poll + /// budget — sandboxes may require DCV to auto-issue. + /// + private async Task<(string orderId, CERTInextCAPlugin plugin)> EnsureIssuedOrderIdAsync(V2PinMode mode) + { + var plugin = BuildV2Plugin(); + string envOrderId = ResolveOrderId(); + // With an env order the test does not enroll, so only the pinned row is meaningful. + V2ProductPinning.SkipUnpinnedWhenOrderSuppliedByEnv(mode, envOrderId, "CERTINEXT_V2_ORDER_ID"); + if (!string.IsNullOrWhiteSpace(envOrderId)) + return (envOrderId, plugin); + + var enrollResult = await plugin.Enroll( + csr: GenerateCsrPem(_v2Domain), + subject: $"CN={_v2Domain}", + san: new Dictionary { ["dns"] = new[] { _v2Domain } }, + productInfo: BuildV2ProductInfo(mode), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + enrollResult.Should().NotBeNull(); + enrollResult.CARequestID.Should().NotBeNullOrWhiteSpace(); + _output.WriteLine( + $"{V2ProductPinning.Label(Constants.Products.DvSsl, mode)} EnsureIssuedOrderIdAsync: no CERTINEXT_V2_ORDER_ID set — enrolled fresh order {enrollResult.CARequestID}."); + + var record = await WaitForIssuanceAsync(plugin, enrollResult.CARequestID); + Skip.If(record?.Status != (int)EndEntityStatus.GENERATED, + $"Freshly-enrolled order '{enrollResult.CARequestID}' did not reach GENERATED within the poll " + + $"budget (status={record?.Status}) — sandbox may require DCV to auto-issue. Set " + + "CERTINEXT_V2_ORDER_ID to a known-issued order to bypass enrollment."); + + return (enrollResult.CARequestID, plugin); + } + + // --------------------------------------------------------------------------- + // Enroll() via the plugin, V2 path + // --------------------------------------------------------------------------- + + /// + /// Runs twice: (template carries a ProductCode) and + /// (no ProductCode; CERTInext resolves the product). + /// + [SkippableTheory] + [V2PinModes] + public async Task Enroll_V2_ReturnsCARequestID(V2PinMode mode) + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + V2ProductPinning.Log(_output, Constants.Products.DvSsl, mode); + + // Plugin logs to the test output, so a CA rejection (e.g. at Submit CSR) shows the call + // sequence; CERTINEXT_TEST_LOG_LEVEL=Trace adds the redacted request payloads. + var restoreLogging = TestOutputLogging.RouteTo(_output); + EnrollmentResult result; + try + { + var plugin = BuildV2Plugin(); + + result = await plugin.Enroll( + csr: GenerateCsrPem(_v2Domain), + subject: $"CN={_v2Domain}", + san: new Dictionary { ["dns"] = new[] { _v2Domain } }, + productInfo: BuildV2ProductInfo(mode), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + } + finally + { + restoreLogging(); + } + + result.Should().NotBeNull(); + result.CARequestID.Should().NotBeNullOrWhiteSpace( + "V2 Enroll must return a non-empty CARequestID — it is the stable foreign key for all future operations"); + result.Status.Should().NotBe((int)EndEntityStatus.FAILED, + $"V2 Enroll must not FAILED at submission time; message: {result.StatusMessage}"); + + _output.WriteLine($"CARequestID: {result.CARequestID}"); + _output.WriteLine($"Status: {result.Status}"); + _output.WriteLine($"Message: {result.StatusMessage}"); + } + + // --------------------------------------------------------------------------- + // Revoke() via the plugin, V2 path + // --------------------------------------------------------------------------- + + /// + /// Opt-in cleanup: revokes one explicit, already-issued order through the plugin's + /// V2 Revoke with reason superseded (4), outside Command. Used to clean up lab + /// orders Command never imported and to reproduce an out-of-band CA-side revoke. + /// Gated behind CERTINEXT_REVOKE_ORDER_ID; never retries. + /// + [SkippableFact] + public async Task Revoke_V2_ExplicitOrder_Superseded() + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + string orderId = Environment.GetEnvironmentVariable("CERTINEXT_REVOKE_ORDER_ID"); + Skip.If(string.IsNullOrWhiteSpace(orderId), "CERTINEXT_REVOKE_ORDER_ID not set — skipping."); + + var plugin = BuildV2Plugin(); + var before = await plugin.GetSingleRecord(orderId); + _output.WriteLine($"Before: CARequestID={orderId}, Status={before?.Status}"); + Skip.If(before?.Status != (int)EndEntityStatus.GENERATED, + $"Order '{orderId}' is in status {before?.Status} (not GENERATED) — not revoking."); + + int revokeResult = await plugin.Revoke(orderId, hexSerialNumber: string.Empty, revocationReason: 4 /* superseded */); + _output.WriteLine($"Revoke result: {revokeResult}"); + + var after = await plugin.GetSingleRecord(orderId); + _output.WriteLine($"After: Status={after?.Status}, RevocationDate={after?.RevocationDate:o}, RevocationReason={after?.RevocationReason}"); + revokeResult.Should().Be((int)EndEntityStatus.REVOKED); + } + + [SkippableTheory] + [V2PinModes] + public async Task Revoke_V2_IssuedOrder_ReturnsRevoked(V2PinMode mode) + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + V2ProductPinning.Log(_output, Constants.Products.DvSsl, mode); + + var (orderId, plugin) = await EnsureIssuedOrderIdAsync(mode); + + var current = await plugin.GetSingleRecord(orderId); + Skip.If(current?.Status != (int)EndEntityStatus.GENERATED, + $"Order '{orderId}' is in status {current?.Status} (not GENERATED) — revocation requires an issued certificate; skipping."); + + int revokeResult; + try + { + revokeResult = await plugin.Revoke(orderId, hexSerialNumber: string.Empty, revocationReason: 1 /* keyCompromise */); + } + catch (InvalidOperationException ex) when (ex.Message.Contains("still being processed")) + { + // Documented sandbox-timing quirk: the CA reports 'issued' via GetSingleRecord + // while still internally finalizing the order, and rejects revoke with 422 + // ("Certificate Request still being processed") in that window. Retry once + // after a short delay before giving up — any other exception (or a second + // failure) must fail the test rather than be swallowed here. + _output.WriteLine($"Revoke rejected as still-processing; retrying once after 15s: {ex.Message}"); + await Task.Delay(TimeSpan.FromSeconds(15)); + try + { + revokeResult = await plugin.Revoke(orderId, hexSerialNumber: string.Empty, revocationReason: 1); + } + catch (InvalidOperationException ex2) when (ex2.Message.Contains("still being processed")) + { + Skip.If(true, + $"Order '{orderId}' tracked as GENERATED but CA rejected revocation twice (sandbox timing): {ex2.Message}"); + return; // unreachable + } + } + + revokeResult.Should().Be((int)EndEntityStatus.REVOKED, + "V2 Revoke must return the REVOKED status code on success"); + } + + // --------------------------------------------------------------------------- + // GetSingleRecord() via the plugin, V2 path + // --------------------------------------------------------------------------- + + [SkippableFact] + public async Task GetSingleRecord_V2_Plugin_ReturnsDetails() + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + + string orderId = ResolveOrderId(); + Skip.If(string.IsNullOrWhiteSpace(orderId), + "No V2 order ID available — set CERTINEXT_V2_ORDER_ID to a real V2 order to run this test."); + + var plugin = BuildV2Plugin(); + var record = await plugin.GetSingleRecord(orderId); + + record.Should().NotBeNull("plugin.GetSingleRecord must return a record for a known V2 order"); + record.CARequestID.Should().Be(orderId); + _output.WriteLine($"CARequestID: {record.CARequestID}"); + _output.WriteLine($"Status: {record.Status}"); + _output.WriteLine($"ProductID: {record.ProductID}"); + } + + // --------------------------------------------------------------------------- + // Enroll -> Synchronize -> Revoke, full V2 lifecycle via the plugin + // --------------------------------------------------------------------------- + + [SkippableTheory] + [V2PinModes] + public async Task Enroll_Synchronize_Revoke_V2_FullLifecycle(V2PinMode mode) + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + V2ProductPinning.Log(_output, Constants.Products.DvSsl, mode); + + // Narrow lookback (1h): the plugin's default 72h margin makes an un-narrowed delta + // sync slow against this busy shared sandbox, and the order enrolled below is + // only seconds old. + var config = BuildV2Config(syncLookbackHours: 1); + var plugin = BuildV2Plugin(config); + + // --- Enroll --- + var enrollResult = await plugin.Enroll( + csr: GenerateCsrPem(_v2Domain), + subject: $"CN={_v2Domain}", + san: new Dictionary { ["dns"] = new[] { _v2Domain } }, + productInfo: BuildV2ProductInfo(mode), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + enrollResult.Should().NotBeNull(); + enrollResult.CARequestID.Should().NotBeNullOrWhiteSpace(); + enrollResult.Status.Should().NotBe((int)EndEntityStatus.FAILED, + $"V2 Enroll must not FAILED at submission time; message: {enrollResult.StatusMessage}"); + + _output.WriteLine($"Enrolled V2 order {enrollResult.CARequestID}, status={enrollResult.Status}"); + + // --- Synchronize (V2 /reports/orders) --- + // Delta sync (fullSync=false, lastSync=recent) rather than a full historical + // pull — this sandbox account has accumulated 1000+ orders from prior test + // runs, and a full sync of the entire history is unnecessarily slow here; the + // order we just enrolled is recent, so a delta sync (with the configured + // lookback window) is sufficient to prove it surfaces via Synchronize. + var synced = await RunSyncAsync(BuildV2Plugin(config), lastSync: DateTime.UtcNow.AddHours(-1), fullSync: false); + synced.Should().Contain( + r => r.CARequestID == enrollResult.CARequestID, + $"the newly enrolled V2 order '{enrollResult.CARequestID}' must appear in a delta sync " + + "via V2 /reports/orders"); + + var syncedRecord = synced.First(r => r.CARequestID == enrollResult.CARequestID); + _output.WriteLine($"Synced record status: {syncedRecord.Status}"); + + // --- Revoke — only if the sandbox has already auto-issued --- + if (syncedRecord.Status != (int)EndEntityStatus.GENERATED) + { + Skip.If(true, + $"Order '{enrollResult.CARequestID}' is in status {syncedRecord.Status} (not GENERATED) — " + + "sandbox may not auto-issue a V2 order without DCV; skipping revoke step."); + } + + int revokeResult; + try + { + revokeResult = await plugin.Revoke(enrollResult.CARequestID, hexSerialNumber: string.Empty, revocationReason: 1); + } + catch (InvalidOperationException ex) when (ex.Message.Contains("still being processed")) + { + // Documented sandbox-timing quirk: the sandbox can report an order as 'issued' + // via TrackOrder/GetSingleRecord while still internally finalizing it, and + // reject a revoke attempted in that window with 422 "Certificate Request + // still being processed". Retry once after a short delay before giving up — + // any other exception must fail the test rather than be swallowed here. + _output.WriteLine($"Revoke rejected as still-processing; retrying once after 15s: {ex.Message}"); + await Task.Delay(TimeSpan.FromSeconds(15)); + try + { + revokeResult = await plugin.Revoke(enrollResult.CARequestID, hexSerialNumber: string.Empty, revocationReason: 1); + } + catch (InvalidOperationException ex2) when (ex2.Message.Contains("still being processed")) + { + Skip.If(true, + $"Order '{enrollResult.CARequestID}' tracked as GENERATED but CA rejected revocation " + + $"twice (sandbox timing): {ex2.Message}"); + return; // unreachable + } + } + + revokeResult.Should().Be((int)EndEntityStatus.REVOKED, + "Revoke must return the REVOKED status code on success"); + } + + // --------------------------------------------------------------------------- + // GetSingleRecord() cert-body check, V2 path + // --------------------------------------------------------------------------- + + [SkippableTheory] + [V2PinModes] + public async Task GetSingleRecord_V2_IssuedOrder_HasParseableCertBody(V2PinMode mode) + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + V2ProductPinning.Log(_output, Constants.Products.DvSsl, mode); + + var (orderId, plugin) = await EnsureIssuedOrderIdAsync(mode); + var record = await WaitForIssuanceAsync(plugin, orderId, maxPolls: 1); + + Skip.If(record?.Status != (int)EndEntityStatus.GENERATED, + $"Order '{orderId}' is not GENERATED (status={record?.Status}) — skipping cert-body check."); + + record!.Certificate.Should().NotBeNullOrWhiteSpace( + "GetSingleRecord must populate the PEM body for a GENERATED V2 order"); + record.Certificate.Should().StartWith("-----BEGIN CERTIFICATE-----"); + + // record.Certificate may be the leaf cert alone, or the leaf followed by one or + // more chain PEM blocks (AssembleV2CertChain concatenates them) — extract only the + // FIRST block. Naively stripping every BEGIN/END marker and decoding the + // concatenation as one base64 blob breaks as soon as a chain is present, because + // each block's own '=' padding then lands mid-string, which is illegal base64. + var firstBlock = System.Text.RegularExpressions.Regex.Match( + record.Certificate, + @"-----BEGIN CERTIFICATE-----(.*?)-----END CERTIFICATE-----", + System.Text.RegularExpressions.RegexOptions.Singleline); + firstBlock.Success.Should().BeTrue("the certificate body must contain at least one PEM block"); + + var b64 = firstBlock.Groups[1].Value + .Replace("\r", string.Empty).Replace("\n", string.Empty).Trim(); + + Action parse = () => new Org.BouncyCastle.X509.X509CertificateParser().ReadCertificate(Convert.FromBase64String(b64)); + parse.Should().NotThrow("the issued V2 certificate's leaf PEM block must be parseable"); + } + + // --------------------------------------------------------------------------- + // GetSingleRecord() across all synced orders, V2-configured plugin + // --------------------------------------------------------------------------- + + /// + /// Runs a delta sync via V2 /reports/orders with a V2-configured (UseV2Api=true) + /// plugin, then calls GetSingleRecord for a sample of the resulting CARequestIDs. + /// All sampled IDs are now V2-native (from the V2 report itself, not a V1 listing), so + /// they are expected to resolve via the V2 family probe; + /// is tolerated only as a defensive allowance (e.g. an order deleted between sync and + /// this call) — this test's real job is to guard against any *other* unhandled exception + /// type escaping GetSingleRecord. + /// + [SkippableFact] + public async Task GetSingleRecord_V2_AllSyncedOrders_DoNotThrow() + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + + // Narrow lookback (1h) — this sandbox account has 1000+ historical orders, and the + // plugin's default 72h lookback margin is always added on top of lastSync + // regardless of how recent it is, so an un-narrowed delta sync here would touch + // several days of orders. Every issued row costs a live certificate download, and + // family resolution costs a sequential TrackOrder probe when not already known — + // an un-narrowed window can take several minutes against this shared sandbox. + var plugin = BuildV2Plugin(BuildV2Config(syncLookbackHours: 1)); + var synced = await RunSyncAsync(plugin, lastSync: DateTime.UtcNow.AddHours(-1), fullSync: false); + synced.Should().NotBeNull(); + synced.Should().NotBeEmpty( + "the delta sync window must return at least one record from this sandbox account to sample " + + "GetSingleRecord against — an empty sync makes the rest of this test vacuous"); + + var sample = synced.Take(10).ToList(); + _output.WriteLine($"Sampling {sample.Count} of {synced.Count} synced records for GetSingleRecord (V2-configured plugin)."); + + int ok = 0, keyNotFound = 0; + foreach (var rec in sample) + { + try + { + await plugin.GetSingleRecord(rec.CARequestID); + ok++; + } + catch (KeyNotFoundException) + { + // Tolerated defensively (e.g. sandbox timing/deletion) — every sampled ID + // came from the V2 report itself, so this should be rare, not expected. + keyNotFound++; + } + } + + _output.WriteLine($"GetSingleRecord results: {ok} succeeded, {keyNotFound} KeyNotFoundException."); + (ok + keyNotFound).Should().Be(sample.Count, + "every sampled GetSingleRecord call must either succeed or throw the tolerated " + + "KeyNotFoundException — any other exception type must escape this loop and fail the test"); + } + + // --------------------------------------------------------------------------- + // Synchronize() uses V2 /reports/orders when UseV2Api=true + // --------------------------------------------------------------------------- + + [SkippableFact] + public async Task Sync_V2_UsesV2ReportsOrders_ReturnsRecords() + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + + // Narrow lookback (1h) — see the comment in GetSingleRecord_V2_AllSyncedOrders_DoNotThrow + // above for why the plugin's default 72h margin makes an un-narrowed delta sync slow + // against this shared, busy sandbox. + var plugin = BuildV2Plugin(BuildV2Config(syncLookbackHours: 1)); + var synced = await RunSyncAsync(plugin, lastSync: DateTime.UtcNow.AddHours(-1), fullSync: false); + + synced.Should().NotBeNull(); + synced.Should().NotBeEmpty( + "Synchronize must return the account's recent order inventory via V2 /reports/orders " + + "(Synchronize no longer falls back to V1 GetOrderReport when UseV2Api=true)"); + synced.Should().OnlyContain(r => !string.IsNullOrWhiteSpace(r.CARequestID)); + + _output.WriteLine($"Synchronize (V2 /reports/orders) returned {synced.Count} record(s)."); + foreach (var r in synced.Take(5)) + _output.WriteLine($" CARequestID={r.CARequestID}, Status={r.Status}, ProductID={r.ProductID}"); + } + + /// + /// Hard acceptance criterion: Synchronize with + /// UseV2Api=true must succeed and return records with ZERO V1 credentials + /// configured at all — no ApiKey, no AccountNumber, no AuthMode, no V1-shaped ApiUrl. + /// Builds its own config (rather than reusing 's default) so + /// the absence of every V1-only field is explicit and self-evident at the call site. + /// + [SkippableFact] + public async Task Sync_V2_WithZeroV1Credentials_Succeeds() + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + + var config = new CERTInextConfig + { + ApiUrl = _v2ApiUrl, + UseV2Api = true, + OAuthClientId = _v2ClientId, + OAuthClientSecret = _v2ClientSecret, + RequestorName = "Keyfactor Test", + RequestorEmail = "test@example.com", + SignerPlace = "Gateway Lab", + SignerIp = "127.0.0.1", + PageSize = 100, + // Narrowed to keep this test's live API call volume bounded against a busy + // shared sandbox. + V2SyncLookbackHours = 1 + // Deliberately NOT set: ApiKey, AccountNumber, AuthMode, OAuthTokenUrl — all + // V1-only fields. Their CERTInextConfig defaults (empty string / "AccessKey") + // are never read on this path once UseV2Api is true. + }; + + var client = new CERTInextClient(config); + var plugin = new CERTInextCAPlugin(client, config); + + var synced = await RunSyncAsync(plugin, lastSync: DateTime.UtcNow.AddHours(-1), fullSync: false); + + synced.Should().NotBeNull(); + _output.WriteLine( + $"Synchronize succeeded with UseV2Api=true and ZERO V1 credentials configured " + + $"(ApiKey/AccountNumber/AuthMode all unset). Returned {synced.Count} record(s)."); + } + + /// + /// Opt-in (walks the sandbox's entire order history — 1000+ orders per the other + /// tests' comments in this class): proves a full sync (fullSync=true, + /// lastSync=null) paginates to completion via V2 /reports/orders without + /// throwing or truncating silently. + /// + [SkippableFact] + public async Task Sync_V2_FullSync_PaginatesEntireHistory() + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + Skip.If(string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable("CERTINEXT_V2_FULL_SYNC_TEST")), + "CERTINEXT_V2_FULL_SYNC_TEST not set — a full sync walks this sandbox's entire order " + + "history and is opt-in to keep the default .V2 filter fast."); + + var plugin = BuildV2Plugin(); + var synced = await RunSyncAsync(plugin, lastSync: null, fullSync: true); + + synced.Should().NotBeNull(); + synced.Should().NotBeEmpty("a full sync of a non-empty sandbox account must return records"); + _output.WriteLine($"Full sync (V2, entire history) returned {synced.Count} record(s)."); + } + + /// + /// Forces multi-page traversal with a small page size (5) on a delta sync, proving + /// ListOrdersV2Async's pagination is exercised end-to-end through Synchronize + /// against the live sandbox (not just the WireMock-based client unit tests). + /// + [SkippableFact] + public async Task Sync_V2_SmallPageSize_PaginatesAcrossMultiplePages() + { + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + + // A narrow (2h) window with pageSize=5 still forces multi-page traversal whenever + // this busy shared sandbox has more than 5 matching orders — no need for a wide + // window (e.g. 30 days), which would also multiply live per-row download calls + // for no added pagination proof. + var config = BuildV2Config(pageSize: 5, syncLookbackHours: 1); + var plugin = BuildV2Plugin(config); + + var synced = await RunSyncAsync(plugin, lastSync: DateTime.UtcNow.AddHours(-2), fullSync: false); + + synced.Should().NotBeNull(); + _output.WriteLine( + $"Delta sync (2h window, pageSize=5) returned {synced.Count} record(s) — pageSize=5 " + + "forces multi-page traversal whenever the account has more than 5 matching orders."); + } + } + + /// + /// Shared helper for loading ~/.env_certinext_v2. V2 test classes must read their + /// values from the dictionary returns, never from process env: + /// keys the V1 also reads are deliberately NOT + /// promoted. Used by , V2DcvLifecycleTests, and the + /// other V2 test classes so they don't duplicate env-loading logic. + /// + internal static class V2EnvHelper + { + /// + /// The V2 enrollment tests run with the connector's default V2InlineCsr=true (SSL/TLS + /// single-call create). CERTINEXT_V2_INLINE_CSR=0 in the real process environment selects + /// the two-call flow instead; unset or any other value keeps the default. Read from the process environment only (it is an + /// opt-in-only flag, never promoted from an env file). + /// + public static bool InlineCsrFromEnv => + Environment.GetEnvironmentVariable("CERTINEXT_V2_INLINE_CSR")?.Trim() != "0"; + + /// + /// Loads ~/.env_certinext_v2 and returns the merged environment dictionary (V2 file + /// values win over process env). V2-only file keys (e.g. CERTINEXT_CLIENT_ID, + /// CERTINEXT_USE_V2_API) are still promoted into process env; keys in + /// (CERTINEXT_API_URL and the rest) + /// are never written to process env. The V1 fixture lets real env vars override + /// ~/.env_certinext, so promoting the V2 values of those shared names would + /// corrupt the V1 fixture of any class constructed later in the same test process. + /// + public static Dictionary LoadAndPromote() + { + string v2Path = Path.Combine( + Environment.GetFolderPath(Environment.SpecialFolder.UserProfile), + ".env_certinext_v2"); + + var (env, fileKeys) = LoadEnvFile(v2Path); + + foreach (string key in PromotableKeys(fileKeys)) + if (env.TryGetValue(key, out string fv)) + Environment.SetEnvironmentVariable(key, fv); + + return env; + } + + /// + /// The V2-file keys may write into process env: every file + /// key except those the V1 side reads () + /// and the fixture's opt-in-only flags (). + /// Without the latter exclusion, a value left in ~/.env_certinext_v2 for + /// one of those flags (e.g. CERTINEXT_V2_OPS_TESTS, CERTINEXT_PRIVATE_PKI_LIVE) would be + /// read as unset by the first test class constructed in a run (before this method's + /// promotion step runs), then promoted into real process env, silently arming every + /// later-constructed test class in the same run even though no flag was ever exported in + /// the shell. Exposed internal for direct unit-testing. + /// + internal static List PromotableKeys(IEnumerable fileKeys) + { + var keys = new List(); + foreach (string key in fileKeys) + if (!IntegrationTestFixture.V1EnvKeys.Contains(key) + && !IntegrationTestFixture._optInOnlyFlags.Contains(key)) + keys.Add(key); + return keys; + } + + /// + /// Loads a KEY=VALUE env file and merges with process env vars. File values take + /// priority over process env because the fixture may have already promoted V1 + /// values (e.g. CERTINEXT_API_URL with /emSignHub-API suffix) into process env, + /// and the V2 base URL differs. Returns the merged dict and the set of keys + /// defined in the file. + /// + public static (Dictionary env, HashSet fileKeys) LoadEnvFile(string path) + { + var fileKeys = new HashSet(StringComparer.OrdinalIgnoreCase); + var result = new Dictionary(StringComparer.OrdinalIgnoreCase); + + foreach (System.Collections.DictionaryEntry de in Environment.GetEnvironmentVariables()) + { + string k = de.Key?.ToString(); + string v = de.Value?.ToString(); + if (!string.IsNullOrEmpty(k)) result[k] = v ?? string.Empty; + } + + if (File.Exists(path)) + { + foreach (string rawLine in File.ReadAllLines(path)) + { + string line = rawLine.Trim(); + if (string.IsNullOrEmpty(line) || line.StartsWith("#")) continue; + + int idx = line.IndexOf('='); + if (idx <= 0) continue; + + string key = line.Substring(0, idx).Trim(); + string val = line.Substring(idx + 1).Trim().Trim('"').Trim('\''); + result[key] = val; + fileKeys.Add(key); + } + } + + return (result, fileKeys); + } + + public static string GetEnv(Dictionary env, string key, string defaultValue = "") + => env.TryGetValue(key, out string v) && !string.IsNullOrWhiteSpace(v) ? v : defaultValue; + } +} diff --git a/CERTInext.IntegrationTests/V2OrderCleanup.cs b/CERTInext.IntegrationTests/V2OrderCleanup.cs new file mode 100644 index 0000000..c6e1d02 --- /dev/null +++ b/CERTInext.IntegrationTests/V2OrderCleanup.cs @@ -0,0 +1,85 @@ +// Copyright 2026 Keyfactor +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; +using System.Threading.Tasks; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.IntegrationTests +{ + /// + /// Sandbox order cleanup keyed on the order's own V2 status, not on what GetSingleRecord + /// returns. GetSingleRecord reports an order as pending until its certificate is + /// downloadable, and right after issued the download can still return 422 (EMS-1165); a + /// cleanup that cancels whenever the record is not yet GENERATED therefore cancels an order that + /// is already issuing, and the sandbox still produces the certificate (leaked order 9185757376, + /// and the F001 child of a cancelled OV order). So: issued is revoked (one retry on + /// "still being processed"), anything not yet terminal is cancelled, and the order is re-tracked + /// afterwards to confirm the outcome. + /// + internal static class V2OrderCleanup + { + public static async Task RevokeOrCancelAsync( + CERTInextClient client, string orderId, string cancelReason, Action log) + { + if (string.IsNullOrWhiteSpace(orderId)) + return true; + + try + { + var (family, status) = await client.ResolveAndTrackOrderV2WithFamilyAsync(orderId); + string st = status.Status ?? string.Empty; + if (IsTerminal(st)) + { + log($"Cleanup: order {orderId} already terminal ({st})."); + return true; + } + + if (string.Equals(st, Constants.ApiV2.StatusIssued, StringComparison.OrdinalIgnoreCase)) + { + var revoke = new V2RevokeRequest { Reason = "superseded", Note = "V2 integration test cleanup" }; + try + { + await client.RevokeOrderV2Async(family, orderId, revoke); + } + catch (InvalidOperationException ex) when (ex.Message.Contains("still being processed")) + { + await Task.Delay(TimeSpan.FromSeconds(15)); + await client.RevokeOrderV2Async(family, orderId, revoke); + } + var after = await client.ResolveAndTrackOrderV2Async(orderId); + log($"Cleanup: revoked issued order {orderId}; re-tracked status={after.Status}."); + return IsTerminal(after.Status); + } + + var outcome = await client.CancelOrderV2Async(family, orderId, cancelReason); + var tracked = await client.ResolveAndTrackOrderV2Async(orderId); + log($"Cleanup: cancelled non-issued order {orderId} (was {st}) -> {outcome}; re-tracked status={tracked.Status}."); + return IsTerminal(tracked.Status); + } + catch (Exception ex) + { + log($"Cleanup FAILED for order {orderId}: {ex.GetType().Name}: {ex.Message}. " + + "Revoke/cancel it by hand in the CERTInext portal if it should not remain pending."); + return false; + } + } + + private static bool IsTerminal(string status) => + string.Equals(status, Constants.ApiV2.StatusRevoked, StringComparison.OrdinalIgnoreCase) + || string.Equals(status, Constants.ApiV2.StatusCancelled, StringComparison.OrdinalIgnoreCase) + || string.Equals(status, Constants.ApiV2.StatusRejected, StringComparison.OrdinalIgnoreCase); + } +} diff --git a/CERTInext.IntegrationTests/V2OrderCleanupTests.cs b/CERTInext.IntegrationTests/V2OrderCleanupTests.cs new file mode 100644 index 0000000..3ae301f --- /dev/null +++ b/CERTInext.IntegrationTests/V2OrderCleanupTests.cs @@ -0,0 +1,312 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Generic; +using System.Globalization; +using System.Linq; +using System.Text.RegularExpressions; +using System.Threading.Tasks; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Xunit; +using Xunit.Abstractions; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.IntegrationTests +{ + /// + /// Explicit-ID cleanup of V2 SANDBOX orders (fake credits) left behind by experiments. + /// Opt-in: CERTINEXT_V2_CLEANUP_ORDERS=<comma-separated order ids> as a REAL + /// environment variable (it is never read from an env file). Credentials come from + /// ~/.env_certinext_v2. + /// + /// Only the listed ids are ever acted on. For each: TrackOrder (record status) -> revoke if + /// issued, cancel if pending, skip if already revoked / cancelled / rejected / expired -> + /// TrackOrder again (verify). A narrow read-only order-report window (yesterday..tomorrow) is + /// read once to report each listed order's creation date and domain; no full sync is run and + /// nothing is acted on by pattern. Set CERTINEXT_V2_CLEANUP_DRYRUN=1 to track and report + /// details only (no revoke/cancel). Set + /// CERTINEXT_V2_CLEANUP_FORCE_CANCEL=1 (single id only) to make one raw cancel attempt instead of a revoke. Emails are scrubbed from all output. + /// + public class V2OrderCleanupTests : IClassFixture + { + private const string OptInFlag = "CERTINEXT_V2_CLEANUP_ORDERS"; + private const int MaxOrders = 25; + private const string CleanupReason = "Sandbox test order cleanup (issue 0090 lab race repro)."; + + private readonly ITestOutputHelper _output; + private readonly string _apiUrl; + private readonly string _clientId; + private readonly string _clientSecret; + private readonly string _groupNumber; + private readonly bool _v2Enabled; + + private static readonly Regex EmailRx = + new(@"[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}", RegexOptions.Compiled); + + public V2OrderCleanupTests(IntegrationTestFixture fixture, ITestOutputHelper output) + { + _output = output; + var env = V2EnvHelper.LoadAndPromote(); + _apiUrl = V2EnvHelper.GetEnv(env, "CERTINEXT_API_URL"); + _clientId = V2EnvHelper.GetEnv(env, "CERTINEXT_CLIENT_ID"); + _clientSecret = V2EnvHelper.GetEnv(env, "CERTINEXT_CLIENT_SECRET"); + _groupNumber = V2EnvHelper.GetEnv(env, "CERTINEXT_GROUP_NUMBER", string.Empty); + _v2Enabled = !string.IsNullOrWhiteSpace(V2EnvHelper.GetEnv(env, "CERTINEXT_USE_V2_API")) + && !string.IsNullOrWhiteSpace(_apiUrl) + && !string.IsNullOrWhiteSpace(_clientId) + && !string.IsNullOrWhiteSpace(_clientSecret); + } + + private static string Scrub(string s) + { + if (string.IsNullOrEmpty(s)) return s ?? string.Empty; + s = EmailRx.Replace(s, ""); + return s.Length > 500 ? s.Substring(0, 500) + "..." : s; + } + + private void W(string s) => _output.WriteLine(Scrub(s)); + + private static string Describe(Exception ex) => $"{ex.GetType().Name}: {ex.Message}"; + + private CERTInextConfig BuildConfig() => new CERTInextConfig + { + ApiUrl = _apiUrl, + UseV2Api = true, + OAuthClientId = _clientId, + OAuthClientSecret = _clientSecret, + RequestorName = "Keyfactor Integration Test", + RequestorIsdCode = "1", + RequestorMobileNumber = "0000000000", + SignerPlace = "Gateway Lab", + SignerIp = "127.0.0.1", + GroupNumber = _groupNumber, + PageSize = 100, + DcvEnabled = false + }; + + private static bool IsTerminalNoAction(string status) => + string.Equals(status, Constants.ApiV2.StatusRevoked, StringComparison.OrdinalIgnoreCase) + || string.Equals(status, Constants.ApiV2.StatusCancelled, StringComparison.OrdinalIgnoreCase) + || string.Equals(status, Constants.ApiV2.StatusRejected, StringComparison.OrdinalIgnoreCase) + || string.Equals(status, Constants.ApiV2.StatusExpired, StringComparison.OrdinalIgnoreCase); + + private static bool IsPending(string status) => + !string.IsNullOrEmpty(status) && status.StartsWith("pending-", StringComparison.OrdinalIgnoreCase); + + private sealed class Row + { + public string OrderId; + public string Before = "-"; + public string Action = "none"; + public string After = "-"; + public string Notes = string.Empty; + } + + [SkippableFact] + public async Task V2_CleanupExplicitOrders_RevokeOrCancelListedIdsOnly() + { + Skip.If(!_v2Enabled, + "V2 credentials not configured in ~/.env_certinext_v2 (CERTINEXT_USE_V2_API, API_URL, CLIENT_ID, CLIENT_SECRET)."); + string flag = Environment.GetEnvironmentVariable(OptInFlag); + Skip.If(string.IsNullOrWhiteSpace(flag), + $"Opt-in: set {OptInFlag}= as a real environment variable."); + + var ids = flag.Split(new[] { ',', ' ', ';' }, StringSplitOptions.RemoveEmptyEntries) + .Select(s => s.Trim()).Distinct(StringComparer.Ordinal).ToList(); + Assert.NotEmpty(ids); + Assert.True(ids.Count <= MaxOrders, $"At most {MaxOrders} order ids per run."); + Assert.All(ids, id => Assert.Matches("^[0-9]{1,20}$", id)); // digits only: refuse anything pattern-like + + var cfg = BuildConfig(); + using var client = new CERTInextClient(cfg); + string family = Constants.ApiV2.FamilySsl; + bool dryRun = Environment.GetEnvironmentVariable("CERTINEXT_V2_CLEANUP_DRYRUN") == "1"; + if (dryRun) W("DRY RUN: track + details only; no revoke/cancel will be sent."); + bool forceCancel = Environment.GetEnvironmentVariable("CERTINEXT_V2_CLEANUP_FORCE_CANCEL") == "1"; + Assert.True(!forceCancel || ids.Count == 1, "CERTINEXT_V2_CLEANUP_FORCE_CANCEL requires exactly one order id."); + if (forceCancel) W("FORCE CANCEL: one raw cancel attempt (no revoke, no retry) for the single listed order."); + + W($"V2 order cleanup: {ids.Count} listed order(s), family={family}"); + + // 1) Read-only detail lookup (creation date, domain) from a narrow order-report window. + // Only the listed ids are retained; nothing here drives an action. + var listed = new Dictionary(StringComparer.Ordinal); + try + { + string from = DateTime.UtcNow.AddDays(-1).ToString("yyyy-MM-dd", CultureInfo.InvariantCulture); + string to = DateTime.UtcNow.AddDays(1).ToString("yyyy-MM-dd", CultureInfo.InvariantCulture); + int scanned = 0; + await foreach (var e in client.ListOrdersV2Async(from, to, 100)) + { + scanned++; + if (e?.OrderNumber != null && ids.Contains(e.OrderNumber)) + listed[e.OrderNumber] = e; + } + W($"order-report window {from}..{to}: scanned={scanned}, matched listed ids={listed.Count}"); + } + catch (Exception ex) + { + W("order-report lookup failed (details only; cleanup continues): " + Describe(ex)); + } + + foreach (var id in ids) + { + if (listed.TryGetValue(id, out var e)) + W($"detail order={id} domain={e.DomainName} orderStatus={e.OrderStatus} certStatus={e.CertificateStatus} " + + $"orderDate={e.OrderDate} productCode={e.ProductCode} requestNumber={e.RequestNumber}"); + else + W($"detail order={id} NOT present in order-report window"); + } + + // 2) Per-order: track -> act -> track. + var rows = new List(); + foreach (var id in ids) + { + var row = new Row { OrderId = id }; + rows.Add(row); + + V2OrderStatusResponse before = null; + try + { + before = await client.TrackOrderV2Async(family, id); + row.Before = before.Status ?? "(null)"; + W($"track-before order={id} status={before.Status} domain={before.Domain} variant={before.ProductVariant} " + + $"issuedAt={before.IssuedAt} expiresAt={before.ExpiresAt}"); + } + catch (KeyNotFoundException) + { + row.Before = "NOT FOUND"; + row.Action = "skipped (not found in " + family + ")"; + W($"order={id} not found in family {family}; no action taken"); + continue; + } + catch (Exception ex) + { + row.Before = "TRACK ERROR"; + row.Action = "skipped"; + row.Notes = Scrub(Describe(ex)); + continue; + } + + string status = before.Status; + if (dryRun) + { + row.Action = "dry-run (none)"; + row.After = row.Before; + continue; + } + try + { + if (IsTerminalNoAction(status)) + { + row.Action = "skip (already " + status + ")"; + } + else if (forceCancel) + { + // Single attempt via the raw helper (same POST .../cancel endpoint as CancelOrderV2Async) + // so the exact HTTP status and body detail are captured; no retry, no other mutation. + row.Action = "force-cancel (single attempt)"; + try + { + await V2RawHttpHelpers.CancelSslOrderRawAsync(_apiUrl, _clientId, _clientSecret, id, CleanupReason); + row.Action += " -> accepted (2xx)"; + } + catch (Exception cex) + { + row.Action += " -> REJECTED"; + row.Notes += "cancel response: " + Scrub(Describe(cex)); + } + } + else if (string.Equals(status, Constants.ApiV2.StatusIssued, StringComparison.OrdinalIgnoreCase)) + { + row.Action = await RevokeAsync(client, family, id, row); + } + else if (IsPending(status)) + { + var outcome = await client.CancelOrderV2Async(family, id, CleanupReason); + row.Action = "cancel -> " + outcome; + } + else + { + row.Action = "skip (unrecognised status; not acting)"; + } + } + catch (Exception ex) + { + row.Action += (row.Action == "none" ? "" : "; ") + "ACTION FAILED"; + row.Notes += (row.Notes.Length > 0 ? " | " : "") + Scrub(Describe(ex)); + } + + try + { + var after = await client.TrackOrderV2Async(family, id); + row.After = after.Status ?? "(null)"; + if (after.Revocation != null) + row.Notes += (row.Notes.Length > 0 ? " | " : "") + + $"revocation.reason={after.Revocation.Reason} processedAt={after.Revocation.ProcessedAt}"; + } + catch (Exception ex) + { + row.After = "TRACK ERROR"; + row.Notes += (row.Notes.Length > 0 ? " | " : "") + Scrub(Describe(ex)); + } + } + + if (forceCancel) + { + try + { + string from2 = DateTime.UtcNow.AddDays(-1).ToString("yyyy-MM-dd", CultureInfo.InvariantCulture); + string to2 = DateTime.UtcNow.AddDays(1).ToString("yyyy-MM-dd", CultureInfo.InvariantCulture); + bool found = false; + await foreach (var e2 in client.ListOrdersV2Async(from2, to2, 100)) + if (e2?.OrderNumber != null && ids.Contains(e2.OrderNumber)) + { + found = true; + W($"listing-after order={e2.OrderNumber} orderStatus={e2.OrderStatus} certStatus={e2.CertificateStatus} orderDate={e2.OrderDate}"); + } + if (!found) W("listing-after: listed order not present in window"); + } + catch (Exception lex) { W("listing-after failed: " + Describe(lex)); } + } + + W("=== result: order | before | action | after | notes ==="); + foreach (var r in rows) + W($"RESULT {r.OrderId} | {r.Before} | {r.Action} | {r.After} | {r.Notes}"); + + if (dryRun || forceCancel) return; // force-cancel is a probe: outcome is reported, not asserted + + // Pass only when every listed order ended in a terminal non-issued state. + var bad = rows.Where(r => !IsTerminalNoAction(r.After)).Select(r => $"{r.OrderId}({r.After})").ToList(); + Assert.True(bad.Count == 0, "Orders not in a terminal state after cleanup: " + string.Join(", ", bad)); + } + + /// + /// Revoke an issued order. Tries "superseded" (what plugin reason 4 maps to); if CERTInext + /// rejects it, records the exact rejection in and retries once with + /// "unspecified" so a spec-vs-live reason discrepancy is surfaced instead of hidden. + /// + private static async Task RevokeAsync(CERTInextClient client, string family, string id, Row row) + { + try + { + await client.RevokeOrderV2Async(family, id, + new V2RevokeRequest { Reason = "superseded", Note = CleanupReason }); + return "revoke(reason=superseded)"; + } + catch (Exception ex) + { + row.Notes += "revoke(superseded) rejected: " + Scrub(Describe(ex)); + } + + await client.RevokeOrderV2Async(family, id, + new V2RevokeRequest { Reason = "unspecified", Note = CleanupReason }); + return "revoke(reason=unspecified, after superseded rejected)"; + } + } +} diff --git a/CERTInext.IntegrationTests/V2OrderWindowSweepTests.cs b/CERTInext.IntegrationTests/V2OrderWindowSweepTests.cs new file mode 100644 index 0000000..65ab0c8 --- /dev/null +++ b/CERTInext.IntegrationTests/V2OrderWindowSweepTests.cs @@ -0,0 +1,268 @@ +// Copyright 2026 Keyfactor +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// +// Opt-in, read-only-by-default sweep over an arbitrary UTC date/time window of the V2 orders +// report (GET /api/certinext/v2/reports/orders). Takes an explicit, caller-supplied window and +// lists every order it finds in it — a general-purpose tool for manually auditing/cleaning up a +// date range after a batch of live-API work (e.g. a day's worth of V2 lifecycle tests). +// +// Env: +// CERTINEXT_V2_SWEEP_FROM / CERTINEXT_V2_SWEEP_TO — UTC ISO-8601 timestamps, e.g. +// 2026-09-30T00:00:00Z. Both required; the test skips (does not default to any window) if +// either is unset. +// CERTINEXT_V2_SWEEP_CANCEL_IDS — optional, comma-separated V2 order IDs. When unset, this +// test only LISTS orders in the window (orderId, domain, status, productCode, orderDate) — +// fully read-only. When set, it additionally cancels exactly those IDs, but only if each one +// is actually found in the listed window and is not already in a terminal state +// (cancelled/revoked/rejected). No bulk "cancel everything" mode exists here deliberately. +// +// Terminal state is decided by Track Order's own `status` field (via +// CERTInextClient.ResolveAndTrackOrderV2WithFamilyAsync), not the orders report's human-readable +// orderStatus/certificateStatus display strings. Exactly one cancel attempt per id; never +// retried, matching every other cleanup/sweep helper in this project +// (V2FullLifecycleTests.CleanupOrderAsync, etc.). +// +// The V2 orders report only filters by calendar date (YYYY-MM-DD) server-side — this test +// requests the covering date range, then re-applies the caller's precise sub-day window +// client-side against each row's own orderDate. +// +// Gating: requires the CERTINEXT_V2_OPS_TESTS=1 opt-in (listed in +// IntegrationTestFixture._optInOnlyFlags, read from the real process environment before +// V2EnvHelper.LoadAndPromote() runs) — this sweep can cancel real sandbox orders, so it needs an +// explicit go/no-go, shared with the other opt-in V2 ops/diagnostic tests. +// +// Logging: every domain value is passed through CERTInextClient.ApplyLoggingRedaction (same +// default-off PII posture as every other V2 live test in this repo) before being written via +// ITestOutputHelper. +// +// Run (list-only): +// set -a; . ~/.env_certinext; set +a +// export CERTINEXT_V2_OPS_TESTS=1 +// export CERTINEXT_V2_SWEEP_FROM=2026-09-25T00:00:00Z +// export CERTINEXT_V2_SWEEP_TO=2026-10-01T00:00:00Z +// dotnet test CERTInext.IntegrationTests/CERTInext.IntegrationTests.csproj -c Release -p:DcvSupport=false \ +// --filter "FullyQualifiedName~Sweep_ListRecentOrders_ByWindow" --logger "console;verbosity=detailed" +// +// Add CERTINEXT_V2_SWEEP_CANCEL_IDS=12345,67890 to also cancel those two specific orders (only +// if each is found in the window and is not already terminal). +namespace Keyfactor.Extensions.CAPlugin.CERTInext.IntegrationTests +{ + using System; + using System.Collections.Generic; + using System.Globalization; + using System.Linq; + using System.Threading.Tasks; + using FluentAssertions; + using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; + using Keyfactor.Extensions.CAPlugin.CERTInext.Client; + using Xunit; + using Xunit.Abstractions; + + public class V2OrderWindowSweepTests : IClassFixture + { + private const string OptInFlag = "CERTINEXT_V2_OPS_TESTS"; + + private readonly IntegrationTestFixture _fixture; + private readonly ITestOutputHelper _output; + + private readonly bool _armed; + private readonly string _v2ApiUrl; + private readonly string _v2ClientId; + private readonly string _v2ClientSecret; + private readonly bool _v2Enabled; + + public V2OrderWindowSweepTests(IntegrationTestFixture fixture, ITestOutputHelper output) + { + _fixture = fixture; + _output = output; + + // Read the opt-in flag from the real process environment BEFORE promoting the V2 env + // file (mirrors PrivatePkiV2LiveTests) — a value left in ~/.env_certinext_v2 must + // never arm this file. IntegrationTestFixture's own _optInOnlyFlags list already + // keeps ~/.env_certinext from arming it either. + _armed = Environment.GetEnvironmentVariable(OptInFlag)?.Trim() == "1"; + + var env = V2EnvHelper.LoadAndPromote(); + _v2ApiUrl = V2EnvHelper.GetEnv(env, "CERTINEXT_API_URL"); + _v2ClientId = V2EnvHelper.GetEnv(env, "CERTINEXT_CLIENT_ID"); + _v2ClientSecret = V2EnvHelper.GetEnv(env, "CERTINEXT_CLIENT_SECRET"); + + _v2Enabled = !string.IsNullOrWhiteSpace(V2EnvHelper.GetEnv(env, "CERTINEXT_USE_V2_API")) + && !string.IsNullOrWhiteSpace(_v2ApiUrl) + && !string.IsNullOrWhiteSpace(_v2ClientId) + && !string.IsNullOrWhiteSpace(_v2ClientSecret); + } + + private CERTInextClient BuildV2Client() => new CERTInextClient(new CERTInextConfig + { + ApiUrl = _v2ApiUrl, + UseV2Api = true, + OAuthClientId = _v2ClientId, + OAuthClientSecret = _v2ClientSecret, + RequestorName = _fixture.IsConfigured ? _fixture.Config.RequestorName : "Keyfactor Test", + RequestorEmail = _fixture.IsConfigured ? _fixture.Config.RequestorEmail : "test@example.com", + SignerIp = "127.0.0.1", + SignerPlace = "Gateway Lab", + PageSize = 100 + }); + + /// + /// Redacts emails/other personal data before any row reaches ITestOutputHelper — same + /// default-off PII posture as every other V2 live test in this repo (see + /// CERTInextClient.ApplyLoggingRedaction; reachable here via + /// InternalsVisibleTo("CERTInext.IntegrationTests")). Domain names themselves are not + /// touched by this redaction. + /// + private static string RedactForLog(string value) => + CERTInextClient.ApplyLoggingRedaction(value, logSensitiveRequestData: false); + + [SkippableFact] + public async Task Sweep_ListRecentOrders_ByWindow_DryRun_ThenCancelExplicitIds() + { + Skip.If(!_armed, + $"{OptInFlag}=1 not set in the real process environment — this sweep can cancel real sandbox " + + "orders when CERTINEXT_V2_SWEEP_CANCEL_IDS is set, and requires an explicit go/no-go. Skipping."); + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + + string fromRaw = Environment.GetEnvironmentVariable("CERTINEXT_V2_SWEEP_FROM"); + string toRaw = Environment.GetEnvironmentVariable("CERTINEXT_V2_SWEEP_TO"); + Skip.If(string.IsNullOrWhiteSpace(fromRaw) || string.IsNullOrWhiteSpace(toRaw), + "CERTINEXT_V2_SWEEP_FROM and CERTINEXT_V2_SWEEP_TO (UTC ISO-8601) must both be set — this sweep " + + "does not default to any particular window. Skipping."); + + const DateTimeStyles utcStyles = DateTimeStyles.AdjustToUniversal | DateTimeStyles.AssumeUniversal; + + if (!DateTime.TryParse(fromRaw, CultureInfo.InvariantCulture, utcStyles, out DateTime fromUtc)) + throw new ArgumentException($"CERTINEXT_V2_SWEEP_FROM='{fromRaw}' is not a parseable UTC ISO-8601 timestamp."); + if (!DateTime.TryParse(toRaw, CultureInfo.InvariantCulture, utcStyles, out DateTime toUtc)) + throw new ArgumentException($"CERTINEXT_V2_SWEEP_TO='{toRaw}' is not a parseable UTC ISO-8601 timestamp."); + if (toUtc <= fromUtc) + throw new ArgumentException($"CERTINEXT_V2_SWEEP_TO ({toUtc:O}) must be after CERTINEXT_V2_SWEEP_FROM ({fromUtc:O})."); + + var cancelIds = (Environment.GetEnvironmentVariable("CERTINEXT_V2_SWEEP_CANCEL_IDS") ?? string.Empty) + .Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries) + .ToHashSet(StringComparer.OrdinalIgnoreCase); + + // The V2 orders report only filters by calendar date (YYYY-MM-DD) server-side — + // request the covering date range, then apply the caller's precise sub-day window + // client-side against each row's own orderDate. + string apiFrom = fromUtc.Date.ToString("yyyy-MM-dd"); + string apiTo = toUtc.Date.AddDays(1).ToString("yyyy-MM-dd"); + + _output.WriteLine("=== V2 order window sweep ==="); + _output.WriteLine($"Window: {fromUtc:O} .. {toUtc:O} (UTC). Report query date range: {apiFrom}..{apiTo}."); + _output.WriteLine(cancelIds.Count > 0 + ? $"Cancel targets (CERTINEXT_V2_SWEEP_CANCEL_IDS): {string.Join(", ", cancelIds)}" + : "No CERTINEXT_V2_SWEEP_CANCEL_IDS set — list-only dry run; nothing will be cancelled."); + + using CERTInextClient client = BuildV2Client(); + + var rowsInWindow = new List(); + int rowsScanned = 0; + + await foreach (var row in client.ListOrdersV2Async(apiFrom, apiTo, pageSize: 100)) + { + rowsScanned++; + + bool parsed = DateTime.TryParse(row.OrderDate, CultureInfo.InvariantCulture, utcStyles, out DateTime rowDate); + + // A row with an unparseable/missing orderDate is kept rather than silently + // dropped — this is a read-only listing, so erring toward showing more (and + // flagging the parse miss) beats erring toward hiding a row the operator + // actually wanted to see. + if (parsed && (rowDate < fromUtc || rowDate > toUtc)) + continue; + + rowsInWindow.Add(row); + + _output.WriteLine( + $"LISTED | OrderId={row.OrderNumber ?? ""} Domain={RedactForLog(row.DomainName)} " + + $"Status={row.OrderStatus ?? ""}/{row.CertificateStatus ?? ""} " + + $"ProductCode={row.ProductCode ?? ""} OrderDate={row.OrderDate ?? ""}" + + (parsed ? string.Empty : " (orderDate unparseable — kept anyway)")); + } + + _output.WriteLine($"Report rows scanned (date-range query): {rowsScanned}. Rows within the precise window: {rowsInWindow.Count}."); + + bool anyCancelFailed = false; + var matchedCancelIds = new HashSet(StringComparer.OrdinalIgnoreCase); + + foreach (string targetId in cancelIds) + { + var row = rowsInWindow.FirstOrDefault(r => string.Equals(r.OrderNumber, targetId, StringComparison.OrdinalIgnoreCase)); + if (row == null) + { + _output.WriteLine( + $"SUMMARY | OrderId={targetId} Cancel=SKIPPED (not found in the listed window — " + + "not touching an order outside it)"); + continue; + } + + matchedCancelIds.Add(targetId); + + try + { + var (family, status) = await client.ResolveAndTrackOrderV2WithFamilyAsync(targetId); + + bool terminal = + string.Equals(status.Status, Constants.ApiV2.StatusCancelled, StringComparison.OrdinalIgnoreCase) || + string.Equals(status.Status, Constants.ApiV2.StatusRevoked, StringComparison.OrdinalIgnoreCase) || + string.Equals(status.Status, Constants.ApiV2.StatusRejected, StringComparison.OrdinalIgnoreCase); + + string cancelOutcome; + if (terminal) + { + cancelOutcome = $"SKIPPED (already {status.Status})"; + } + else + { + try + { + var outcome = await client.CancelOrderV2Async( + family, targetId, + "V2 order-window sweep — explicitly listed in CERTINEXT_V2_SWEEP_CANCEL_IDS."); + cancelOutcome = outcome.ToString(); + } + catch (Exception cancelEx) + { + anyCancelFailed = true; + cancelOutcome = $"FAILED ({cancelEx.GetType().Name}: {cancelEx.Message})"; + } + } + + _output.WriteLine( + $"SUMMARY | OrderId={targetId} Domain={RedactForLog(row.DomainName)} " + + $"StatusBefore={status.Status ?? ""} Cancel={cancelOutcome}"); + } + catch (Exception ex) + { + anyCancelFailed = true; + _output.WriteLine( + $"SUMMARY | OrderId={targetId} Domain={RedactForLog(row.DomainName)} " + + $"Cancel=FAILED (could not resolve product family/status: {ex.GetType().Name}: {ex.Message})"); + } + } + + _output.WriteLine(""); + _output.WriteLine( + $"SUMMARY | Sweep complete. RowsScanned={rowsScanned} RowsInWindow={rowsInWindow.Count} " + + $"CancelTargets={cancelIds.Count} CancelsMatched={matchedCancelIds.Count}"); + + anyCancelFailed.Should().BeFalse( + "one or more explicitly-listed orders could not be cancelled (or could not have their " + + "status/family resolved) during the sweep — see the FAILED outcome(s) logged above; this " + + "sweep does not retry a failed cancel automatically."); + } + } +} diff --git a/CERTInext.IntegrationTests/V2PlaceOrderLatencyExperimentTests.cs b/CERTInext.IntegrationTests/V2PlaceOrderLatencyExperimentTests.cs new file mode 100644 index 0000000..1c0ee8c --- /dev/null +++ b/CERTInext.IntegrationTests/V2PlaceOrderLatencyExperimentTests.cs @@ -0,0 +1,700 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Diagnostics; +using System.Globalization; +using System.IO; +using System.Linq; +using System.Reflection; +using System.Text; +using System.Text.RegularExpressions; +using System.Threading; +using System.Threading.Tasks; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Org.BouncyCastle.Asn1.X509; +using Org.BouncyCastle.Crypto.Generators; +using Org.BouncyCastle.Crypto; +using Org.BouncyCastle.Pkcs; +using Org.BouncyCastle.Security; +using Xunit; +using Xunit.Abstractions; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.IntegrationTests +{ + /// + /// Measurement experiment (issue 0090, V2 side): does the V2 API hold order placement open + /// the way V1 GenerateOrderSSL does in production (response returned 19 s / 100 s after + /// the order already exists and is issued), and how long is the window between "order visible + /// to a CA Sync" and "plugin Enroll returns the CARequestID to the gateway"? + /// + /// V2 order placement is three calls: POST create (returns orderId, order sits in + /// pending-csr), PUT /csr, then GET track (+ download / pickup poll). The plugin's real + /// Enroll is driven end to end; a wraps the real client + /// and timestamps every plugin-to-CA call, so the numbers are the plugin's own call pattern. + /// Two independent clients run beside it: + /// + /// a listing poller (the call Synchronize makes: /reports/orders) every ~1.5 s, + /// which finds the order by its unique domain BEFORE the place response returns; + /// an order tracker (GET track) every ~1 s, started the instant the place response lands. + /// + /// Opt-in: CERTINEXT_V2_LATENCY_EXPERIMENT=1 as a REAL environment variable. + /// Optional: CERTINEXT_V2_LATENCY_COUNT (default 7, max 12), + /// CERTINEXT_V2_LATENCY_SPACING_SECONDS (default 30), + /// CERTINEXT_V2_LATENCY_DOMAIN_MODE (unique = fresh subdomain of + /// CERTINEXT_DCV_DOMAIN per order [default]; reuse = CERTINEXT_DCV_DOMAIN itself). + /// Credentials come from ~/.env_certinext_v2. Raw CSV goes to experiment-results/. + /// No order numbers or timings are tied to personal data; emails are never printed. + /// + public class V2PlaceOrderLatencyExperimentTests : IClassFixture + { + private const string OptInFlag = "CERTINEXT_V2_LATENCY_EXPERIMENT"; + private const int MaxOrders = 12; + private static readonly TimeSpan ListPollInterval = TimeSpan.FromSeconds(1.5); + private static readonly TimeSpan TrackPollInterval = TimeSpan.FromSeconds(1.0); + private const int MaxListPollsInFlight = 2; + + private readonly IntegrationTestFixture _fixture; + private readonly ITestOutputHelper _output; + private readonly Stopwatch _clock = Stopwatch.StartNew(); + + private readonly string _apiUrl; + private readonly string _clientId; + private readonly string _clientSecret; + private readonly string _productCode; + private readonly string _baseDomain; + private readonly string _requestorName; + private readonly string _requestorEmail; + private readonly string _groupNumber; + private readonly bool _v2Enabled; + + public V2PlaceOrderLatencyExperimentTests(IntegrationTestFixture fixture, ITestOutputHelper output) + { + _fixture = fixture; + _output = output; + + var env = V2EnvHelper.LoadAndPromote(); + _apiUrl = V2EnvHelper.GetEnv(env, "CERTINEXT_API_URL"); + _clientId = V2EnvHelper.GetEnv(env, "CERTINEXT_CLIENT_ID"); + _clientSecret = V2EnvHelper.GetEnv(env, "CERTINEXT_CLIENT_SECRET"); + _productCode = V2EnvHelper.GetEnv(env, "CERTINEXT_PRODUCT_CODE", "842"); + _baseDomain = V2EnvHelper.GetEnv(env, "CERTINEXT_DCV_DOMAIN", string.Empty); + _requestorName = V2EnvHelper.GetEnv(env, "CERTINEXT_REQUESTOR_NAME", "Keyfactor Integration Test"); + _requestorEmail = V2EnvHelper.GetEnv(env, "CERTINEXT_REQUESTOR_EMAIL", "test@example.com"); + _groupNumber = V2EnvHelper.GetEnv(env, "CERTINEXT_GROUP_NUMBER", string.Empty); + _v2Enabled = !string.IsNullOrWhiteSpace(V2EnvHelper.GetEnv(env, "CERTINEXT_USE_V2_API")) + && !string.IsNullOrWhiteSpace(_apiUrl) + && !string.IsNullOrWhiteSpace(_clientId) + && !string.IsNullOrWhiteSpace(_clientSecret); + } + + private double Now => _clock.Elapsed.TotalSeconds; + + private static readonly Regex EmailRx = new(@"[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}", RegexOptions.Compiled); + + /// Strips anything email-shaped and caps length; used for every line that leaves the test. + private static string Scrub(string s) + { + if (string.IsNullOrEmpty(s)) return s ?? string.Empty; + s = EmailRx.Replace(s, ""); + return s.Length > 400 ? s.Substring(0, 400) + "..." : s; + } + + private static string Describe(Exception ex) => Scrub($"{ex.GetType().Name}: {ex.Message}"); + + private void W(string s) => _output.WriteLine(Scrub(s)); + + // --------------------------------------------------------------------------- + // Timing proxy: wraps the real client, timestamps every plugin-to-CA call + // --------------------------------------------------------------------------- + + public sealed class CallRecord + { + public string Name; + public double Start; + public double End; + public string Error; + public double DurationMs => (End - Start) * 1000.0; + } + + /// DispatchProxy over recording start/end of every async call. + public class TimingClientProxy : DispatchProxy + { + internal ICERTInextClient Inner; + internal Func Clock; + internal ConcurrentQueue Calls = new(); + internal Action OnResult; + + protected override object Invoke(MethodInfo targetMethod, object[] args) + { + double start = Clock(); + object ret; + try + { + ret = targetMethod.Invoke(Inner, args); + } + catch (TargetInvocationException tie) + { + Calls.Enqueue(new CallRecord { Name = targetMethod.Name, Start = start, End = Clock(), Error = Describe(tie.InnerException ?? tie) }); + throw tie.InnerException ?? tie; + } + + if (ret is Task t) + { + Type rt = targetMethod.ReturnType; + if (rt.IsGenericType && rt.GetGenericTypeDefinition() == typeof(Task<>)) + { + var m = typeof(TimingClientProxy).GetMethod(nameof(WrapTaskT), BindingFlags.NonPublic | BindingFlags.Instance) + ?.MakeGenericMethod(rt.GetGenericArguments()[0]); + return m?.Invoke(this, new object[] { t, targetMethod.Name, start }); + } + return WrapTask(t, targetMethod.Name, start); + } + return ret; // sync members and IAsyncEnumerable pass straight through, untimed + } + + private async Task WrapTask(Task t, string name, double start) + { + try { await t.ConfigureAwait(false); Calls.Enqueue(new CallRecord { Name = name, Start = start, End = Clock() }); } + catch (Exception ex) { Calls.Enqueue(new CallRecord { Name = name, Start = start, End = Clock(), Error = Describe(ex) }); throw; } + } + + private async Task WrapTaskT(Task t, string name, double start) + { + try + { + T r = await t.ConfigureAwait(false); + Calls.Enqueue(new CallRecord { Name = name, Start = start, End = Clock() }); + OnResult?.Invoke(name, r); + return r; + } + catch (Exception ex) + { + Calls.Enqueue(new CallRecord { Name = name, Start = start, End = Clock(), Error = Describe(ex) }); + throw; + } + } + } + + // --------------------------------------------------------------------------- + // Observations + // --------------------------------------------------------------------------- + + private sealed class TrackObs + { + public double Sent; + public double Recv; + public string Status; + public string Error; + } + + private sealed class ListObs + { + public double Start; + public double End; + public int Rows; + public string OrderNumber; + public string OrderStatus; + public string CertStatus; + public string Error; + public bool Matched => OrderNumber != null; + public string Combined => $"{OrderStatus}|{CertStatus}"; + } + + private sealed class Trial + { + public int Index; + public string Domain; + public string OrderId; + public DateTime T0Utc; + public double T0; + public double TPlaceResp = double.NaN; + public double TCsrResp = double.NaN; + public double TEnrollEnd = double.NaN; + public double PlaceMs = double.NaN, CsrMs = double.NaN, DownloadMs = double.NaN; + public List TrackCallMs = new(); + public string EnrollStatus = string.Empty; + public bool EnrollHasCert; + public string EnrollMessage = string.Empty; + public string CreateRespStatus = string.Empty; + public double FirstSeenList = double.NaN, FirstSeenListLower = double.NaN; + public string FirstSeenListStatus = string.Empty; + public double TrackFirstObsRecv = double.NaN; + public string TrackFirstObsStatus = string.Empty; + public string StatusAfterCsr = string.Empty; + public double TIssuedTrack = double.NaN, TIssuedTrackLower = double.NaN; + public double TIssuedList = double.NaN; + public string TrackSeq = string.Empty; + public string ListSeq = string.Empty; + public int ListPolls, ListErrors, TrackPolls, TrackErrors; + public double ListPollMedianS = double.NaN; + public string CleanupNote = string.Empty; + public string Error = string.Empty; + // One extra GET /certificate fired by the tracker the first time track reports 'issued' + // (while the CSR PUT may still be in flight): does 'issued' mean the cert is downloadable? + public double DlProbeAt = double.NaN, DlProbeMs = double.NaN; + public string DlProbeResult = string.Empty; + } + + // --------------------------------------------------------------------------- + // Helpers + // --------------------------------------------------------------------------- + + private static string F(double x) => double.IsNaN(x) ? "" : x.ToString("0.00", CultureInfo.InvariantCulture); + + private static double Median(IEnumerable xs) + { + var a = xs.Where(x => !double.IsNaN(x)).OrderBy(x => x).ToArray(); + if (a.Length == 0) return double.NaN; + return a.Length % 2 == 1 ? a[a.Length / 2] : (a[a.Length / 2 - 1] + a[a.Length / 2]) / 2.0; + } + + private static string RepoRoot() + { + var dir = new DirectoryInfo(AppContext.BaseDirectory); + while (dir != null && !File.Exists(Path.Combine(dir.FullName, "certinext-caplugin.sln"))) + dir = dir.Parent; + return dir?.FullName ?? Directory.GetCurrentDirectory(); + } + + /// RSA-2048 PKCS#10 CSR, BouncyCastle only. + private static string GenerateCsrPem(string commonName) + { + var keyGen = new RsaKeyPairGenerator(); + keyGen.Init(new KeyGenerationParameters(new SecureRandom(), 2048)); + var keyPair = keyGen.GenerateKeyPair(); + var csr = new Pkcs10CertificationRequest("SHA256withRSA", new X509Name($"CN={commonName}"), + keyPair.Public, null, keyPair.Private); + return "-----BEGIN CERTIFICATE REQUEST-----\n" + + Convert.ToBase64String(csr.GetEncoded(), Base64FormattingOptions.InsertLineBreaks) + + "\n-----END CERTIFICATE REQUEST-----"; + } + + private CERTInextConfig BuildConfig() => new CERTInextConfig + { + ApiUrl = _apiUrl, + UseV2Api = true, + OAuthClientId = _clientId, + OAuthClientSecret = _clientSecret, + RequestorName = _requestorName, + RequestorEmail = _requestorEmail, + RequestorIsdCode = "1", + RequestorMobileNumber = "0000000000", + SignerPlace = "Gateway Lab", + SignerIp = "127.0.0.1", + GroupNumber = _groupNumber, + PageSize = 100, + DcvEnabled = false + }; + + private static bool IsIssuedListing(ListObs o) => + o.CertStatus != null && + (o.CertStatus.IndexOf("Generated", StringComparison.OrdinalIgnoreCase) >= 0 + || o.CertStatus.IndexOf("Downloaded", StringComparison.OrdinalIgnoreCase) >= 0); + + private static bool IsIssuedTrack(string status) => + string.Equals(status, Constants.ApiV2.StatusIssued, StringComparison.OrdinalIgnoreCase); + + // --------------------------------------------------------------------------- + // The experiment + // --------------------------------------------------------------------------- + + [SkippableFact] + public async Task V2PlaceOrder_Latency_And_ExposureWindow_Experiment() + { + Skip.If(!_v2Enabled, "V2 credentials not configured in ~/.env_certinext_v2 (CERTINEXT_USE_V2_API, API_URL, CLIENT_ID, CLIENT_SECRET)."); + Skip.If(Environment.GetEnvironmentVariable(OptInFlag) != "1", + $"Opt-in: set {OptInFlag}=1 as a real environment variable (places live sandbox orders)."); + Skip.If(string.IsNullOrWhiteSpace(_baseDomain), "CERTINEXT_DCV_DOMAIN is required (base domain for test CNs)."); + + int count = int.TryParse(Environment.GetEnvironmentVariable("CERTINEXT_V2_LATENCY_COUNT"), out int c) ? c : 7; + count = Math.Max(1, Math.Min(MaxOrders, count)); + double spacing = double.TryParse(Environment.GetEnvironmentVariable("CERTINEXT_V2_LATENCY_SPACING_SECONDS"), + NumberStyles.Float, CultureInfo.InvariantCulture, out double sp) ? sp : 30; + bool reuse = string.Equals(Environment.GetEnvironmentVariable("CERTINEXT_V2_LATENCY_DOMAIN_MODE"), + "reuse", StringComparison.OrdinalIgnoreCase); + + string runId = DateTime.UtcNow.ToString("MMddHHmm", CultureInfo.InvariantCulture); + var cfg = BuildConfig(); + + // Independent clients: listing poller (stands in for the sync pod) and order tracker. + using var listClient = new CERTInextClient(cfg); + using var trackClient = new CERTInextClient(cfg); + using var realClient = new CERTInextClient(cfg); + using var cleanupClient = new CERTInextClient(cfg); + var cleanupPlugin = new CERTInextCAPlugin(cleanupClient, cfg); + + W($"V2 latency experiment run {runId}: product={_productCode}, mode={(reuse ? "reuse" : "unique")}, " + + $"count={count}, spacingS={F(spacing)}, pickupRetries={cfg.GetEffectivePickupRetries()}"); + + var trials = new List(); + double lastT0 = double.NegativeInfinity; + try + { + for (int i = 0; i < count; i++) + { + var t = new Trial + { + Index = i + 1, + Domain = reuse ? _baseDomain : $"v2lat-{runId}-{i + 1:D2}.{_baseDomain}".ToLowerInvariant() + }; + trials.Add(t); + + double wait = lastT0 + spacing - Now; + if (wait > 0) await Task.Delay(TimeSpan.FromSeconds(wait)); + + try + { + await RunTrialAsync(t, cfg, realClient, listClient, trackClient, reuse); + lastT0 = t.T0; + } + catch (Exception ex) + { + t.Error = (t.Error.Length > 0 ? t.Error + "; " : "") + "trial: " + Describe(ex); + lastT0 = t.T0 > 0 ? t.T0 : Now; + } + finally + { + t.CleanupNote = await CleanupAsync(cleanupPlugin, t.OrderId); + } + LogTrial(t); + } + } + finally + { + WriteCsv(runId, trials); + WriteSummary(trials); + } + } + + private async Task RunTrialAsync(Trial t, CERTInextConfig cfg, CERTInextClient realClient, + CERTInextClient listClient, CERTInextClient trackClient, bool reuse) + { + // Everything not under test happens before t0. + string csr = GenerateCsrPem(t.Domain); + string today = DateTime.UtcNow.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture); + string tomorrow = DateTime.UtcNow.AddDays(1).ToString("yyyy-MM-dd", CultureInfo.InvariantCulture); + + // reuse mode: orders already on the base domain today are excluded from "mine". + var snapshot = new HashSet(StringComparer.Ordinal); + if (reuse) + { + await foreach (var e in listClient.ListOrdersV2Async(today, tomorrow, 100)) + if (string.Equals(e.DomainName, t.Domain, StringComparison.OrdinalIgnoreCase) && e.OrderNumber != null) + snapshot.Add(e.OrderNumber); + } + bool Mine(OrderReportEntryV2 e) => + string.Equals(e.DomainName, t.Domain, StringComparison.OrdinalIgnoreCase) + && e.OrderNumber != null && !snapshot.Contains(e.OrderNumber); + + var proxy = DispatchProxy.Create(); + var tp = (TimingClientProxy)(object)proxy; + tp.Inner = realClient; + tp.Clock = () => Now; + + var trackObs = new ConcurrentQueue(); + var listObs = new ConcurrentQueue(); + using var stopAll = new CancellationTokenSource(); + Task trackerTask = Task.CompletedTask; + string orderIdFromCreate = null; + + // The instant the place response lands, start tracking the order with the independent client. + tp.OnResult = (name, result) => + { + if (name == "PlaceOrderV2Async" && result is V2CreateOrderResponse cr && orderIdFromCreate == null) + { + orderIdFromCreate = cr.OrderId; + t.CreateRespStatus = cr.Status ?? string.Empty; + trackerTask = Task.Run(async () => + { + while (!stopAll.IsCancellationRequested) + { + var o = new TrackObs { Sent = Now }; + try + { + var s = await trackClient.TrackOrderV2Async(Constants.ApiV2.FamilySsl, cr.OrderId); + o.Status = s.Status; + } + catch (Exception ex) { o.Error = Describe(ex); } + o.Recv = Now; + trackObs.Enqueue(o); + if (o.Error == null && IsIssuedTrack(o.Status) && double.IsNaN(t.DlProbeAt)) + { + t.DlProbeAt = Now; + double p0 = Now; + try + { + var dl = await trackClient.DownloadCertificateV2Async(Constants.ApiV2.FamilySsl, cr.OrderId); + t.DlProbeResult = string.IsNullOrWhiteSpace(dl?.CertificatePem) ? "ok-empty" : "ok-with-certificate"; + } + catch (Exception ex) { t.DlProbeResult = "error: " + Describe(ex); } + t.DlProbeMs = (Now - p0) * 1000.0; + } + try { await Task.Delay(TrackPollInterval, stopAll.Token); } catch (OperationCanceledException) { } + } + }); + } + }; + + var inflight = new List(); + var listerTask = Task.Run(async () => + { + async Task PollOnce() + { + var o = new ListObs { Start = Now }; + try + { + await foreach (var e in listClient.ListOrdersV2Async(today, tomorrow, 100)) + { + o.Rows++; + if (Mine(e) && o.OrderNumber == null) + { + o.OrderNumber = e.OrderNumber; + o.OrderStatus = e.OrderStatus; + o.CertStatus = e.CertificateStatus; + } + } + } + catch (Exception ex) { o.Error = Describe(ex); } + o.End = Now; + listObs.Enqueue(o); + } + while (!stopAll.IsCancellationRequested) + { + inflight.RemoveAll(x => x.IsCompleted); + if (inflight.Count < MaxListPollsInFlight) inflight.Add(Task.Run(PollOnce)); + try { await Task.Delay(ListPollInterval, stopAll.Token); } catch (OperationCanceledException) { } + } + await Task.WhenAll(inflight); + }); + await Task.Delay(ListPollInterval); // listing poller is already running before t0 + + var plugin = new CERTInextCAPlugin(proxy, cfg); + var productInfo = new EnrollmentProductInfo + { + ProductID = _productCode, + ProductParameters = new Dictionary + { + [Constants.EnrollmentParam.ProductCode] = _productCode, + [Constants.EnrollmentParam.ProfileId] = _productCode, + } + }; + + t.T0Utc = DateTime.UtcNow; + t.T0 = Now; + EnrollmentResult result = null; + try + { + result = await plugin.Enroll( + csr: csr, + subject: $"CN={t.Domain}", + san: new Dictionary { ["dns"] = new[] { t.Domain } }, + productInfo: productInfo, + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + } + catch (Exception ex) + { + t.Error = "Enroll: " + Describe(ex); + } + t.TEnrollEnd = Now; + t.OrderId = result?.CARequestID ?? orderIdFromCreate; + if (result != null) + { + t.EnrollStatus = ((EndEntityStatus)result.Status).ToString(); + t.EnrollHasCert = !string.IsNullOrWhiteSpace(result.Certificate); + t.EnrollMessage = Scrub(result.StatusMessage ?? string.Empty); + } + + // Keep observing: until issued is seen by tracker, or 90 s after the enroll returned. + double deadline = t.TEnrollEnd + 90; + while (Now < deadline) + { + await Task.Delay(500); + bool issuedSeen = trackObs.Any(o => IsIssuedTrack(o.Status)); + if (issuedSeen && Now >= t.TEnrollEnd + 4) break; + if (orderIdFromCreate == null && Now >= t.TEnrollEnd + 6) break; // nothing was placed + } + stopAll.Cancel(); + try { await Task.WhenAll(trackerTask, listerTask); } catch { /* observation only */ } + + Analyze(t, tp, trackObs.OrderBy(o => o.Recv).ToList(), listObs.OrderBy(o => o.Start).ToList()); + } + + private void Analyze(Trial t, TimingClientProxy tp, List track, List lists) + { + var calls = tp.Calls.OrderBy(c => c.Start).ToList(); + var place = calls.FirstOrDefault(c => c.Name == "PlaceOrderV2Async"); + var csr = calls.FirstOrDefault(c => c.Name == "SubmitCsrV2Async"); + var dl = calls.FirstOrDefault(c => c.Name == "DownloadCertificateV2Async"); + if (place != null) { t.PlaceMs = place.DurationMs; t.TPlaceResp = place.End; if (place.Error != null) t.Error += "place: " + place.Error + "; "; } + if (csr != null) { t.CsrMs = csr.DurationMs; t.TCsrResp = csr.End; if (csr.Error != null) t.Error += "csr: " + csr.Error + "; "; } + if (dl != null) t.DownloadMs = dl.DurationMs; + t.TrackCallMs = calls.Where(c => c.Name == "TrackOrderV2Async").Select(c => c.DurationMs).ToList(); + + // Listing: first poll whose rows contained the order. + t.ListPolls = lists.Count; + t.ListErrors = lists.Count(l => l.Error != null); + t.ListPollMedianS = Median(lists.Select(l => l.End - l.Start)); + var firstSeen = lists.Where(l => l.Matched).OrderBy(l => l.End).FirstOrDefault(); + if (firstSeen != null) + { + t.FirstSeenList = firstSeen.End; + t.FirstSeenListLower = firstSeen.Start; + t.FirstSeenListStatus = Scrub(firstSeen.Combined); + } + var issuedList = lists.Where(l => l.Matched && IsIssuedListing(l)).OrderBy(l => l.End).FirstOrDefault(); + if (issuedList != null) t.TIssuedList = issuedList.End; + + var lseq = new List(); + foreach (var l in lists.Where(l => l.Matched).OrderBy(l => l.End)) + { + string s = Scrub(l.Combined); + if (lseq.Count == 0 || !lseq[^1].StartsWith(s + "@", StringComparison.Ordinal)) + lseq.Add($"{s}@{F(l.End - t.T0)}"); + } + t.ListSeq = string.Join("; ", lseq); + + // Tracker. + t.TrackPolls = track.Count; + t.TrackErrors = track.Count(o => o.Error != null); + var okObs = track.Where(o => o.Error == null).ToList(); + if (okObs.Count > 0) + { + t.TrackFirstObsRecv = okObs[0].Recv; + t.TrackFirstObsStatus = okObs[0].Status; + } + if (!double.IsNaN(t.TCsrResp)) + { + var afterCsr = okObs.FirstOrDefault(o => o.Recv >= t.TCsrResp); + if (afterCsr != null) t.StatusAfterCsr = afterCsr.Status + "@" + F(afterCsr.Recv - t.T0); + } + var issuedTrack = okObs.FirstOrDefault(o => IsIssuedTrack(o.Status)); + if (issuedTrack != null) { t.TIssuedTrack = issuedTrack.Recv; t.TIssuedTrackLower = issuedTrack.Sent; } + + var tseq = new List(); + foreach (var o in okObs) + if (tseq.Count == 0 || !tseq[^1].StartsWith(o.Status + "@", StringComparison.Ordinal)) + tseq.Add($"{o.Status}@{F(o.Recv - t.T0)}"); + t.TrackSeq = string.Join("; ", tseq); + foreach (var o in track.Where(o => o.Error != null).Take(2)) + t.Error += "track: " + o.Error + "; "; + } + + private void LogTrial(Trial t) + { + W($"trial {t.Index:D2} order={(string.IsNullOrEmpty(t.OrderId) ? "-" : t.OrderId)} " + + $"place={F(t.PlaceMs / 1000)}s csr={F(t.CsrMs / 1000)}s tracks=[{string.Join(",", t.TrackCallMs.Select(x => F(x / 1000)))}]s " + + $"download={F(t.DownloadMs / 1000)}s enrollWall={F(t.TEnrollEnd - t.T0)}s enroll={t.EnrollStatus} cert={t.EnrollHasCert} " + + $"createStatus={t.CreateRespStatus} firstSeenInListing={F(t.FirstSeenList - t.T0)}s({t.FirstSeenListStatus}) " + + $"placeResp={F(t.TPlaceResp - t.T0)}s csrResp={F(t.TCsrResp - t.T0)}s " + + $"dlProbe@{F(t.DlProbeAt - t.T0)}s={t.DlProbeResult} issuedTrack={F(t.TIssuedTrack - t.T0)}s issuedList={F(t.TIssuedList - t.T0)}s " + + $"trackSeq=[{t.TrackSeq}] listSeq=[{t.ListSeq}] cleanup={t.CleanupNote} {t.Error}"); + } + + private void WriteCsv(string runId, List trials) + { + try + { + string dir = Path.Combine(RepoRoot(), "experiment-results"); + Directory.CreateDirectory(dir); + string path = Path.Combine(dir, $"v2-placeorder-latency-{runId}.csv"); + var sb = new StringBuilder(); + sb.AppendLine("trial,domain,order_id,t0_utc,create_resp_status,place_ms,csr_ms,track_calls_ms,download_ms," + + "enroll_wall_s,enroll_status,enroll_has_cert,t_place_resp_s,t_csr_resp_s,t_enroll_end_s," + + "first_seen_listing_s,first_seen_listing_lower_s,first_seen_listing_status," + + "seen_in_listing_before_place_resp,seen_in_listing_before_csr_resp,exposure_seen_to_enroll_end_s," + + "track_first_obs_s,track_first_obs_status,status_after_csr," + + "t_issued_track_s,t_issued_track_lower_s,t_issued_listing_s," + + "issued_before_place_resp,issued_before_csr_resp,issued_before_enroll_end," + + "dl_probe_at_s,dl_probe_ms,dl_probe_result,track_seq,listing_seq,list_polls,list_poll_median_s,track_polls,list_errors,track_errors,cleanup,error"); + foreach (var t in trials) + { + string Rel(double x) => double.IsNaN(x) ? "" : F(x - t.T0); + string Q(string s) => "\"" + Scrub(s ?? "").Replace("\"", "'") + "\""; + bool seenBeforePlace = !double.IsNaN(t.FirstSeenList) && !double.IsNaN(t.TPlaceResp) && t.FirstSeenList < t.TPlaceResp; + bool seenBeforeCsr = !double.IsNaN(t.FirstSeenList) && !double.IsNaN(t.TCsrResp) && t.FirstSeenList < t.TCsrResp; + // Issued strictly before a response returned: use the observation's RECEIVE time vs that response's time. + bool issuedBeforePlace = !double.IsNaN(t.TIssuedList) && !double.IsNaN(t.TPlaceResp) && t.TIssuedList < t.TPlaceResp; + double issuedAny = double.IsNaN(t.TIssuedTrack) ? t.TIssuedList + : double.IsNaN(t.TIssuedList) ? t.TIssuedTrack : Math.Min(t.TIssuedTrack, t.TIssuedList); + bool issuedBeforeCsr = !double.IsNaN(issuedAny) && !double.IsNaN(t.TCsrResp) && issuedAny < t.TCsrResp; + bool issuedBeforeEnd = !double.IsNaN(issuedAny) && !double.IsNaN(t.TEnrollEnd) && issuedAny < t.TEnrollEnd; + double exposure = (!double.IsNaN(t.FirstSeenList) && !double.IsNaN(t.TEnrollEnd)) ? t.TEnrollEnd - t.FirstSeenList : double.NaN; + sb.AppendLine(string.Join(",", new[] + { + t.Index.ToString(CultureInfo.InvariantCulture), t.Domain, t.OrderId ?? "", t.T0Utc.ToString("o", CultureInfo.InvariantCulture), + t.CreateRespStatus, F(t.PlaceMs), F(t.CsrMs), Q(string.Join(";", t.TrackCallMs.Select(F))), F(t.DownloadMs), + F(t.TEnrollEnd - t.T0), t.EnrollStatus, t.EnrollHasCert ? "1" : "0", Rel(t.TPlaceResp), Rel(t.TCsrResp), Rel(t.TEnrollEnd), + Rel(t.FirstSeenList), Rel(t.FirstSeenListLower), Q(t.FirstSeenListStatus), + seenBeforePlace ? "1" : "0", seenBeforeCsr ? "1" : "0", F(exposure), + Rel(t.TrackFirstObsRecv), Q(t.TrackFirstObsStatus), Q(t.StatusAfterCsr), + Rel(t.TIssuedTrack), Rel(t.TIssuedTrackLower), Rel(t.TIssuedList), + issuedBeforePlace ? "1" : "0", issuedBeforeCsr ? "1" : "0", issuedBeforeEnd ? "1" : "0", + Rel(t.DlProbeAt), F(t.DlProbeMs), Q(t.DlProbeResult), + Q(t.TrackSeq), Q(t.ListSeq), t.ListPolls.ToString(CultureInfo.InvariantCulture), F(t.ListPollMedianS), + t.TrackPolls.ToString(CultureInfo.InvariantCulture), t.ListErrors.ToString(CultureInfo.InvariantCulture), + t.TrackErrors.ToString(CultureInfo.InvariantCulture), Q(t.CleanupNote), Q(t.Error) + })); + } + File.WriteAllText(path, sb.ToString()); + W($"CSV written: experiment-results/{Path.GetFileName(path)}"); + } + catch (Exception ex) + { + W($"CSV write failed: {Describe(ex)}"); + } + } + + private void WriteSummary(List trials) + { + var ok = trials.Where(t => !string.IsNullOrEmpty(t.OrderId)).ToList(); + W($"=== summary (seconds; min / median / max; n) over {ok.Count} placed orders ==="); + void Row(string name, Func get) + { + var xs = ok.Select(get).Where(x => !double.IsNaN(x)).ToArray(); + W(xs.Length == 0 ? $"{name,-22} n=0" + : $"{name,-22} {F(xs.Min())} / {F(Median(xs))} / {F(xs.Max())} (n={xs.Length})"); + } + Row("place (HTTP)", t => t.PlaceMs / 1000); + Row("csr submit (HTTP)", t => t.CsrMs / 1000); + Row("download (HTTP)", t => t.DownloadMs / 1000); + Row("enroll wall", t => t.TEnrollEnd - t.T0); + Row("first seen in listing", t => t.FirstSeenList - t.T0); + Row("issued (track)", t => t.TIssuedTrack - t.T0); + Row("issued (listing)", t => t.TIssuedList - t.T0); + Row("seen->enroll end", t => t.TEnrollEnd - t.FirstSeenList); + } + + /// Revoke if issued, otherwise cancel via the raw endpoint (single attempt). Never throws. + private async Task CleanupAsync(CERTInextCAPlugin plugin, string orderId) + { + if (string.IsNullOrWhiteSpace(orderId)) return "no order"; + try + { + var current = await plugin.GetSingleRecord(orderId); + if (current?.Status == (int)EndEntityStatus.GENERATED) + { + int r = await plugin.Revoke(orderId, hexSerialNumber: string.Empty, revocationReason: 4); + return $"revoked ({r})"; + } + await V2RawHttpHelpers.CancelSslOrderRawAsync(_apiUrl, _clientId, _clientSecret, orderId, + "V2 latency experiment cleanup — order not issued, cancelling."); + return $"cancelled (status was {current?.Status})"; + } + catch (Exception ex) + { + return "cleanup FAILED: " + Describe(ex); + } + } + } +} diff --git a/CERTInext.IntegrationTests/V2ProductPinning.cs b/CERTInext.IntegrationTests/V2ProductPinning.cs new file mode 100644 index 0000000..c1683c7 --- /dev/null +++ b/CERTInext.IntegrationTests/V2ProductPinning.cs @@ -0,0 +1,181 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Generic; +using System.Linq; +using System.Reflection; +using System.Text.Json; +using Keyfactor.AnyGateway.Extensions; +using Xunit.Sdk; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.IntegrationTests +{ + /// + /// How a V2 enrollment test selects the CERTInext product, mirroring the two gateway template + /// sets registered by scripts/register/02-gateway-ca-config.sh. + /// + public enum V2PinMode + { + /// + /// "Pinned" template: ProductID is the product name (e.g. "DV SSL") and the template + /// carries an explicit ProductCode, so the plugin sends X-Product-Code. + /// + Pinned, + + /// + /// "V2 template" (unpinned): same ProductID but NO ProductCode parameter, so + /// the plugin sends no X-Product-Code and CERTInext resolves the product itself. + /// + V2Template, + } + + /// + /// Builds the a gateway template would hand the plugin, in + /// either , and supplies the pin-mode rows for parameterised V2 tests. + /// + internal static class V2ProductPinning + { + /// + /// Sandbox V2 catalog product codes per product name (the same codes stage 02's + /// PRODUCT_CODE_MAP_JSON pins on the lab gateway: DV 842-845, OV 846-849, EV 850-851). + /// Product codes are per-environment; override with CERTINEXT_PRODUCT_CODE_MAP_JSON + /// (e.g. {"OV SSL":"900"}) or, for DV SSL only, CERTINEXT_PRODUCT_CODE. + /// + private static readonly Dictionary SandboxCodes = + new Dictionary(StringComparer.OrdinalIgnoreCase) + { + [Constants.Products.DvSsl] = "842", + [Constants.Products.DvSslWildcard] = "843", + [Constants.Products.DvSslUcc] = "844", + [Constants.Products.DvSslWildcardUcc] = "845", + [Constants.Products.OvSsl] = "846", + [Constants.Products.OvSslWildcard] = "847", + [Constants.Products.OvSslUcc] = "848", + [Constants.Products.OvSslWildcardUcc] = "849", + [Constants.Products.EvSsl] = "850", + [Constants.Products.EvSslUcc] = "851", + }; + + /// Both modes, in run order (pinned first). + public static readonly V2PinMode[] AllModes = { V2PinMode.Pinned, V2PinMode.V2Template }; + + /// + /// The product code a pinned template would carry for : + /// CERTINEXT_PRODUCT_CODE_MAP_JSON entry, else (DV SSL only) CERTINEXT_PRODUCT_CODE, + /// else the sandbox default. Reads the V2 env file via so a V2-file value + /// wins over the V1 fixture's. + /// + public static string CodeFor(string productId) + { + var env = V2EnvHelper.LoadAndPromote(); + + string mapJson = V2EnvHelper.GetEnv(env, "CERTINEXT_PRODUCT_CODE_MAP_JSON"); + if (!string.IsNullOrWhiteSpace(mapJson)) + { + var map = JsonSerializer.Deserialize>(mapJson) + ?? new Dictionary(); + var hit = map.FirstOrDefault(kv => string.Equals(kv.Key, productId, StringComparison.OrdinalIgnoreCase)); + if (!string.IsNullOrWhiteSpace(hit.Value)) + return hit.Value; + } + + if (string.Equals(productId, Constants.Products.DvSsl, StringComparison.OrdinalIgnoreCase)) + return V2EnvHelper.GetEnv(env, "CERTINEXT_PRODUCT_CODE", SandboxCodes[Constants.Products.DvSsl]); + + if (SandboxCodes.TryGetValue(productId, out string code)) + return code; + + throw new ArgumentException( + $"No sandbox product code known for ProductID '{productId}'; add it to CERTINEXT_PRODUCT_CODE_MAP_JSON.", + nameof(productId)); + } + + /// + /// The ProductCode a template in carries: the pinned code, or + /// null for a V2 template (the parameter is absent entirely). + /// + public static string CodeSent(string productId, V2PinMode mode) => + mode == V2PinMode.Pinned ? CodeFor(productId) : null; + + /// + /// Product info as the gateway would deliver it for the template in : + /// ProductID = product name, ValidityYears = 1 (as on the lab templates), plus + /// ProductCode only when pinned. (e.g. PriorCertSN) are added last. + /// + public static EnrollmentProductInfo Info( + string productId, V2PinMode mode, IDictionary extraParameters = null) + { + var parameters = new Dictionary + { + [Constants.EnrollmentParam.ValidityYears] = "1", + }; + + string code = CodeSent(productId, mode); + if (code != null) + parameters[Constants.EnrollmentParam.ProductCode] = code; + + if (extraParameters != null) + foreach (var kv in extraParameters) + parameters[kv.Key] = kv.Value; + + return new EnrollmentProductInfo { ProductID = productId, ProductParameters = parameters }; + } + + /// Short label for test output, e.g. [pinned DV SSL ProductCode=842]. + public static string Label(string productId, V2PinMode mode) => + mode == V2PinMode.Pinned + ? $"[pinned {productId} ProductCode={CodeFor(productId)}]" + : $"[V2 template (unpinned) {productId} no ProductCode]"; + + /// + /// Logs which mode a test row runs in plus, when the response exposes it (raw-client order + /// create), the product CERTInext actually resolved. + /// + public static void Log( + Xunit.Abstractions.ITestOutputHelper output, string productId, V2PinMode mode, string resolvedProductCode = null) + { + output.WriteLine(Label(productId, mode) + + (resolvedProductCode == null ? string.Empty : $" ResolvedProductCode={resolvedProductCode}")); + } + + /// + /// A V2-template (unpinned) row does not exercise pinning when the test is handed a pre-existing + /// order via an env var instead of enrolling: skip it so the same order is not reused twice. + /// + public static void SkipUnpinnedWhenOrderSuppliedByEnv(V2PinMode mode, string envOrderId, string envVarName) + { + Xunit.Skip.If(mode == V2PinMode.V2Template && !string.IsNullOrWhiteSpace(envOrderId), + $"{envVarName} is set: the test uses that existing order and does not enroll, so the pin mode is " + + "irrelevant. Only the pinned row runs."); + } + } + + /// + /// xUnit data source: one row per (mode as the sole argument). + /// Rows display as Test(mode: Pinned) / Test(mode: V2Template), so + /// --filter "DisplayName~V2Template" or "DisplayName~Pinned" selects one set. + /// + [AttributeUsage(AttributeTargets.Method, AllowMultiple = false)] + internal sealed class V2PinModesAttribute : DataAttribute + { + public override IEnumerable GetData(MethodInfo testMethod) => + V2ProductPinning.AllModes.Select(m => new object[] { m }); + } + + /// + /// xUnit data source: the cross product of tags and + /// , as (string tag, V2PinMode mode). + /// + [AttributeUsage(AttributeTargets.Method, AllowMultiple = false)] + internal sealed class V2PinModesWithKeyAlgorithmsAttribute : DataAttribute + { + public override IEnumerable GetData(MethodInfo testMethod) => + KeyAlgorithms.AsMemberData.SelectMany( + row => V2ProductPinning.AllModes.Select(m => new object[] { row[0], m })); + } +} diff --git a/CERTInext.IntegrationTests/V2RawHttpHelpers.cs b/CERTInext.IntegrationTests/V2RawHttpHelpers.cs new file mode 100644 index 0000000..a2ce034 --- /dev/null +++ b/CERTInext.IntegrationTests/V2RawHttpHelpers.cs @@ -0,0 +1,78 @@ +// Copyright 2026 Keyfactor +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. +// +// Raw-HTTP helpers for V2 order cleanup in test fixtures. The plugin has no V2 cancel +// method, so cleanup that needs to cancel a non-issued sandbox order goes directly +// against the V2 REST API rather than through the plugin surface. +namespace Keyfactor.Extensions.CAPlugin.CERTInext.IntegrationTests +{ + using System; + using System.Text.Json; + using System.Threading.Tasks; + using RestSharp; + + internal static class V2RawHttpHelpers + { + /// + /// Builds a against , applying + /// when provided. + /// + public static RestClient NewApiClient(string baseUrl, TimeSpan? timeout = null) => + timeout.HasValue + ? new RestClient(new RestClientOptions(baseUrl) { Timeout = timeout.Value }) + : new RestClient(baseUrl); + + /// + /// Standalone OAuth2 client_credentials token fetch against {apiUrl}/oauth/token. + /// Throws if the token call itself is not successful. + /// + public static async Task GetV2AccessTokenAsync( + string apiUrl, string clientId, string clientSecret, TimeSpan? timeout = null) + { + string tokenUrl = apiUrl.TrimEnd('/') + "/oauth/token"; + using var tokenClient = NewApiClient(tokenUrl, timeout); + var tokenReq = new RestRequest(string.Empty, Method.Post); + tokenReq.AddHeader("Content-Type", "application/x-www-form-urlencoded"); + tokenReq.AddParameter("grant_type", "client_credentials"); + tokenReq.AddParameter("client_id", clientId); + tokenReq.AddParameter("client_secret", clientSecret); + var tokenResp = await tokenClient.ExecuteAsync(tokenReq); + if (!tokenResp.IsSuccessful || string.IsNullOrWhiteSpace(tokenResp.Content)) + throw new Exception($"Token request failed: {(int)tokenResp.StatusCode}"); + + using var tokenDoc = JsonDocument.Parse(tokenResp.Content); + return tokenDoc.RootElement.GetProperty("access_token").GetString(); + } + + /// + /// Cancels a V2 SSL order via POST {SslCertificatesPath}/{orderId}/cancel. Throws + /// on a non-success response. + /// + public static async Task CancelSslOrderRawAsync( + string apiUrl, string clientId, string clientSecret, string orderId, string reason, + TimeSpan? timeout = null) + { + string accessToken = await GetV2AccessTokenAsync(apiUrl, clientId, clientSecret, timeout); + + using var apiClient = NewApiClient(apiUrl.TrimEnd('/'), timeout); + var cancelReq = new RestRequest($"{Constants.ApiV2.SslCertificatesPath}/{orderId}/cancel", Method.Post); + cancelReq.AddHeader("Authorization", $"Bearer {accessToken}"); + cancelReq.AddJsonBody(new { reason }); + var cancelResp = await apiClient.ExecuteAsync(cancelReq); + if (!cancelResp.IsSuccessful) + throw new Exception( + $"Cancel request failed: {(int)cancelResp.StatusCode} {cancelResp.Content}"); + } + } +} diff --git a/CERTInext.IntegrationTests/V2ValidityProbeTests.cs b/CERTInext.IntegrationTests/V2ValidityProbeTests.cs new file mode 100644 index 0000000..1fb00c2 --- /dev/null +++ b/CERTInext.IntegrationTests/V2ValidityProbeTests.cs @@ -0,0 +1,581 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +#if SUPPORTS_DCV +using System; +using System.Collections.Generic; +using System.IO; +using System.Linq; +using System.Net; +using System.Net.Http; +using System.Net.Sockets; +using System.Text; +using System.Text.Json; +using System.Text.Json.Nodes; +using System.Text.RegularExpressions; +using System.Threading; +using System.Threading.Tasks; +using Org.BouncyCastle.Asn1.X509; +using Org.BouncyCastle.Crypto.Generators; +using Org.BouncyCastle.Pkcs; +using Org.BouncyCastle.Security; +using Org.BouncyCastle.X509; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Xunit; +using Xunit.Abstractions; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.IntegrationTests +{ + /// + /// Opt-in live probe: can the CERTInext V2 API express a certificate lifetime shorter than one + /// year (CA/B Forum is shrinking maximum TLS lifetimes: 200 days now, 100 from Mar 2027, 47 from + /// Mar 2029)? V2 orders only document subscription.validityYears (an integer billing + /// entitlement window, "distinct from the certificate's own notBefore/notAfter"). + /// + /// Each variant drives a real DV order through the V2 plugin (Enroll, then + /// GetSingleRecord until issued) with the plugin's HTTP traffic routed through a loopback + /// pass-through proxy. The proxy optionally mutates the JSON body of the order-create POST (to + /// inject undocumented lifetime-style fields) and records the create request shape and response, so + /// the evidence is the wire body and the issued certificate's notBefore/notAfter, never just + /// "the CA accepted it". Every order created is revoked/cancelled in a finally block. + /// + /// Gated behind CERTINEXT_PROBE_VALIDITY=1 (opt-in-only flag, never promoted from an env + /// file) plus V2 credentials and Cloudflare DCV credentials. Places roughly 5-7 sandbox orders per + /// full run. Reads ~/.env_certinext_v2 itself (do NOT source it into the shell). + /// + public class V2ValidityProbeTests : IClassFixture + { + private const string FlagName = "CERTINEXT_PROBE_VALIDITY"; + + private readonly IntegrationTestFixture _fixture; + private readonly ITestOutputHelper _output; + + private readonly string _v2ApiUrl; + private readonly string _v2ClientId; + private readonly string _v2ClientSecret; + private readonly string _v2ProductCode; + private readonly string _v2Domain; + private readonly string _cfApiToken; + private readonly string _cfZoneId; + private readonly bool _v2Enabled; + private readonly bool _dcvEnabled; + + public V2ValidityProbeTests(IntegrationTestFixture fixture, ITestOutputHelper output) + { + _fixture = fixture; + _output = output; + + var env = V2EnvHelper.LoadAndPromote(); + + _v2ApiUrl = V2EnvHelper.GetEnv(env, "CERTINEXT_API_URL"); + _v2ClientId = V2EnvHelper.GetEnv(env, "CERTINEXT_CLIENT_ID"); + _v2ClientSecret = V2EnvHelper.GetEnv(env, "CERTINEXT_CLIENT_SECRET"); + _v2ProductCode = V2EnvHelper.GetEnv(env, "CERTINEXT_PRODUCT_CODE", "842"); + _v2Domain = V2EnvHelper.GetEnv(env, "CERTINEXT_DCV_DOMAIN", "test.example.com"); + _cfApiToken = V2EnvHelper.GetEnv(env, "CERTINEXT_CF_API_TOKEN"); + _cfZoneId = V2EnvHelper.GetEnv(env, "CERTINEXT_CF_ZONE_ID"); + + _v2Enabled = !string.IsNullOrWhiteSpace(V2EnvHelper.GetEnv(env, "CERTINEXT_USE_V2_API")) + && !string.IsNullOrWhiteSpace(_v2ApiUrl) + && !string.IsNullOrWhiteSpace(_v2ClientId) + && !string.IsNullOrWhiteSpace(_v2ClientSecret); + _dcvEnabled = _v2Enabled + && !string.IsNullOrWhiteSpace(_cfApiToken) + && !string.IsNullOrWhiteSpace(_cfZoneId); + } + + // --------------------------------------------------------------------------- + // Variants. Each is its own fact so a single variant can be re-run with --filter. + // --------------------------------------------------------------------------- + + /// Plugin path, template ValidityDays=45 (the V2 plugin path reads only ValidityYears). + [SkippableFact] + public Task Probe_A_Plugin_TemplateValidityDays45() => + RunVariantAsync("A-plugin-days45", + new Dictionary { [Constants.EnrollmentParam.ValidityDays] = "45" }, + mutator: null); + + /// Control: plugin path, template ValidityYears=1. + [SkippableFact] + public Task Probe_B_Plugin_TemplateValidityYears1_Control() => + RunVariantAsync("B-plugin-years1", + new Dictionary { [Constants.EnrollmentParam.ValidityYears] = "1" }, + mutator: null); + + /// Undocumented subscription.validityDays=45 injected next to validityYears=1. + [SkippableFact] + public Task Probe_C_Raw_SubscriptionValidityDays45() => + RunVariantAsync("C-sub-validityDays45", null, o => + { + o["subscription"]!.AsObject()["validityDays"] = 45; + }); + + /// Kitchen sink of undocumented lifetime-ish fields at plausible levels (disjoint from C). + [SkippableFact] + public Task Probe_D_Raw_KitchenSinkLifetimeFields() => + RunVariantAsync("D-kitchen-sink", null, o => + { + o["validityDays"] = 45; + o["certificateValidityDays"] = 45; + o["lifetimeDays"] = 45; + o["certificate"]!.AsObject()["validityDays"] = 45; + o["certificate"]!.AsObject()["lifetimeDays"] = 45; + o["subscription"]!.AsObject()["lifetimeDays"] = 45; + o["subscription"]!.AsObject()["certificateValidityDays"] = 45; + }); + + /// subscription.validityYears=0 (documented field, out-of-range value). + [SkippableFact] + public Task Probe_E_Raw_ValidityYears0() => + RunVariantAsync("E-years0", null, o => + { + o["subscription"]!.AsObject()["validityYears"] = 0; + }); + + /// Negative control: a field that cannot possibly be meaningful, to learn whether unknown fields are rejected or ignored. + [SkippableFact] + public Task Probe_F_Raw_BogusUnknownField_Control() => + RunVariantAsync("F-bogus-field", null, o => + { + o["bogusProbeField"] = 45; + }); + + /// subscription.validityYears=0.1233 (45/365): a fractional year in the documented integer field. + [SkippableFact] + public Task Probe_G_Raw_ValidityYearsFractional() => + RunVariantAsync("G-years-frac", null, o => + { + o["subscription"]!.AsObject()["validityYears"] = 0.1233; + }); + + /// subscription.validityYears=2: does the documented field change the issued certificate's own lifetime? + [SkippableFact] + public Task Probe_H_Raw_ValidityYears2() => + RunVariantAsync("H-years2", null, o => + { + o["subscription"]!.AsObject()["validityYears"] = 2; + }); + + /// Read-only: dumps the V2 catalog entry shape (keys, validity-like fields, price tiers) for the configured product. + [SkippableFact] + public async Task Probe_I_CatalogEntryShape_ReadOnly() + { + Skip.If(Environment.GetEnvironmentVariable(FlagName) != "1", + $"Opt-in: set {FlagName}=1 to run the certificate-lifetime probe."); + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + + using var client = new CERTInextClient(BuildV2Config(_v2ApiUrl)); + var (code, _, content) = await client.ProbeV2GetAsync(Constants.ApiV2.CatalogProductsPath); + _output.WriteLine($"Catalog HTTP {code}, {content?.Length ?? 0} chars"); + code.Should().Be(200); + + using var doc = JsonDocument.Parse(content ?? string.Empty); + JsonElement? match = null; + void Walk(JsonElement e) + { + if (match != null) return; + if (e.ValueKind == JsonValueKind.Object) + { + if (e.TryGetProperty("productCode", out var pc) && pc.ToString() == _v2ProductCode) + { + match = e; + return; + } + foreach (var p in e.EnumerateObject()) Walk(p.Value); + } + else if (e.ValueKind == JsonValueKind.Array) + { + foreach (var i in e.EnumerateArray()) Walk(i); + } + } + Walk(doc.RootElement); + + match.Should().NotBeNull($"catalog must list product {_v2ProductCode}"); + _output.WriteLine($"Catalog entry for {_v2ProductCode}: keys=[{string.Join(",", match!.Value.EnumerateObject().Select(p => p.Name))}]"); + foreach (var p in match.Value.EnumerateObject()) + { + if (Regex.IsMatch(p.Name, "valid|day|term|year|life|price|period", RegexOptions.IgnoreCase)) + _output.WriteLine($" {p.Name} = {Scrub(p.Value.GetRawText())}"); + } + } + + // --------------------------------------------------------------------------- + // Engine + // --------------------------------------------------------------------------- + + private async Task RunVariantAsync( + string tag, Dictionary extraTemplateParams, Action mutator) + { + Skip.If(Environment.GetEnvironmentVariable(FlagName) != "1", + $"Opt-in: set {FlagName}=1 to place real sandbox orders probing certificate lifetime handling."); + Skip.If(!_v2Enabled, "CERTINEXT_USE_V2_API not set or V2 credentials not configured — skipping."); + Skip.If(!_dcvEnabled, + "CERTINEXT_CF_API_TOKEN + CERTINEXT_CF_ZONE_ID required — probe orders are driven to issuance via real DCV."); + + string suffix = Guid.NewGuid().ToString("N").Substring(0, 8); + string cn = $"probe45-{suffix}.{_v2Domain}"; + string orderId = null; + + using var proxy = new MutatingProxy(_v2ApiUrl.TrimEnd('/'), mutator); + var proxiedConfig = BuildV2Config(proxy.BaseUrl); + using var directClient = new CERTInextClient(BuildV2Config(_v2ApiUrl)); + using var dnsFactory = new CloudflareDomainValidatorFactory(_cfApiToken, _cfZoneId); + var plugin = new CERTInextCAPlugin(new CERTInextClient(proxiedConfig), dnsFactory, proxiedConfig); + + var productParams = new Dictionary + { + [Constants.EnrollmentParam.ProductCode] = _v2ProductCode, + [Constants.EnrollmentParam.ProfileId] = _v2ProductCode, + }; + if (extraTemplateParams != null) + foreach (var kv in extraTemplateParams) + productParams[kv.Key] = kv.Value; + + string enrollOutcome; + EnrollmentResult enrollResult = null; + try + { + try + { + enrollResult = await plugin.Enroll( + csr: GenerateCsrPem(cn), + subject: $"CN={cn}", + san: new Dictionary { ["dns"] = new[] { cn } }, + productInfo: new EnrollmentProductInfo { ProductID = _v2ProductCode, ProductParameters = productParams }, + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + orderId = string.IsNullOrWhiteSpace(enrollResult?.CARequestID) ? null : enrollResult.CARequestID; + enrollOutcome = $"returned status={enrollResult?.Status} msg={Scrub(enrollResult?.StatusMessage)}"; + } + catch (Exception ex) + { + enrollOutcome = $"threw {ex.GetType().Name}: {Scrub(ex.Message)}"; + } + + // Wire evidence for the create call (the proxy only records POST /ssl-certificates). + var creates = proxy.CreateCaptures; + _output.WriteLine($"=== {tag} ==="); + _output.WriteLine($"Plugin template params: {string.Join(", ", productParams.Where(k => k.Key.StartsWith("Validity")).Select(k => k.Key + "=" + k.Value))}"); + _output.WriteLine($"Create POSTs observed on the wire: {creates.Count}"); + foreach (var c in creates) + { + _output.WriteLine($" create request shape : {c.RequestShape}"); + _output.WriteLine($" create response : HTTP {c.Status} {Scrub(c.ResponseBody)}"); + } + _output.WriteLine($"Enroll outcome: {enrollOutcome}"); + + // Order id from the create response is authoritative even if Enroll threw afterwards. + orderId ??= creates.Select(c => c.OrderId).FirstOrDefault(i => !string.IsNullOrWhiteSpace(i)); + + if (orderId == null) + { + _output.WriteLine($"PROBE|{tag}|accepted=NO|orderId=-|createHttp={creates.FirstOrDefault()?.Status}"); + return; + } + + // Drive to issuance (DCV retry path runs inside GetSingleRecord for pending orders). + AnyCAPluginCertificate record = null; + for (int poll = 1; poll <= 12; poll++) + { + record = await plugin.GetSingleRecord(orderId); + _output.WriteLine($" poll #{poll}: status={record?.Status} certLen={record?.Certificate?.Length ?? 0}"); + if (record?.Status == (int)EndEntityStatus.GENERATED && !string.IsNullOrWhiteSpace(record.Certificate)) + break; + if (record?.Status == (int)EndEntityStatus.FAILED) + break; + await Task.Delay(TimeSpan.FromSeconds(15)); + } + + // Raw Track Order (direct, not proxied) so unmodelled fields such as `subscription` are visible. + var (code, _, content) = await directClient.ProbeV2GetAsync( + $"{Constants.ApiV2.SslCertificatesPath}/{orderId}"); + string trackSummary = SummariseTrack(code, content); + _output.WriteLine($" Track Order: {trackSummary}"); + + string certSummary = "no-cert"; + if (record?.Status == (int)EndEntityStatus.GENERATED && !string.IsNullOrWhiteSpace(record.Certificate)) + { + var cert = ParseLeaf(record.Certificate); + double days = (cert.NotAfter - cert.NotBefore).TotalDays; + certSummary = $"notBefore={cert.NotBefore:O} notAfter={cert.NotAfter:O} lifetimeDays={days:F2}"; + } + _output.WriteLine($" Issued cert: {certSummary}"); + _output.WriteLine($"PROBE|{tag}|accepted=YES|orderId={orderId}|{certSummary}|track={trackSummary}"); + } + finally + { + if (orderId != null) + { + var log = new List(); + bool ok = await V2OrderCleanup.RevokeOrCancelAsync( + directClient, orderId, "V2 validity probe cleanup", log.Add); + foreach (var l in log) _output.WriteLine(" " + Scrub(l)); + var (_, finalStatus) = await directClient.ResolveAndTrackOrderV2WithFamilyAsync(orderId); + _output.WriteLine($"CLEANUP|{tag}|orderId={orderId}|terminal={ok}|finalStatus={finalStatus?.Status}"); + ok.Should().BeTrue($"probe order {orderId} must be revoked/cancelled"); + } + else + { + _output.WriteLine($"CLEANUP|{tag}|no order created, nothing to clean up"); + } + } + } + + // --------------------------------------------------------------------------- + // Helpers + // --------------------------------------------------------------------------- + + private CERTInextConfig BuildV2Config(string apiUrl) => + new CERTInextConfig + { + ApiUrl = apiUrl, + UseV2Api = true, + V2InlineCsr = V2EnvHelper.InlineCsrFromEnv, + OAuthClientId = _v2ClientId, + OAuthClientSecret = _v2ClientSecret, + + RequestorName = _fixture.IsConfigured ? _fixture.Config.RequestorName : "Keyfactor Test", + RequestorEmail = _fixture.IsConfigured ? _fixture.Config.RequestorEmail : "test@example.com", + RequestorIsdCode = "1", + RequestorMobileNumber = "0000000000", + SignerPlace = "Gateway Lab", + SignerIp = "127.0.0.1", + + PageSize = 100, + V2SyncLookbackHours = 2, + DcvEnabled = true, + DcvPropagationDelaySeconds = 5, + DcvTimeoutMinutes = 3 + }; + + private static string GenerateCsrPem(string commonName) + { + var keyGen = new RsaKeyPairGenerator(); + keyGen.Init(new Org.BouncyCastle.Crypto.KeyGenerationParameters(new SecureRandom(), 2048)); + var keyPair = keyGen.GenerateKeyPair(); + var csr = new Pkcs10CertificationRequest( + "SHA256withRSA", new X509Name($"CN={commonName}"), keyPair.Public, null, keyPair.Private); + return "-----BEGIN CERTIFICATE REQUEST-----\n" + + Convert.ToBase64String(csr.GetEncoded(), Base64FormattingOptions.InsertLineBreaks) + + "\n-----END CERTIFICATE REQUEST-----"; + } + + private static Org.BouncyCastle.X509.X509Certificate ParseLeaf(string pem) + { + var m = Regex.Match(pem, "-----BEGIN CERTIFICATE-----(.*?)-----END CERTIFICATE-----", RegexOptions.Singleline); + string b64 = (m.Success ? m.Groups[1].Value : pem) + .Replace("\r", string.Empty).Replace("\n", string.Empty).Trim(); + return new X509CertificateParser().ReadCertificate(Convert.FromBase64String(b64)); + } + + /// Redacts e-mail addresses and truncates to 500 chars before anything is printed. + private static string Scrub(string s) + { + if (string.IsNullOrEmpty(s)) return s; + s = Regex.Replace(s, @"[A-Za-z0-9._%+\-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}", ""); + return s.Length > 500 ? s.Substring(0, 500) + "...(truncated)" : s; + } + + /// Only non-PII Track Order fields: status, issuedAt, expiresAt, subscription, and the top-level key names. + private static string SummariseTrack(int httpStatus, string content) + { + if (string.IsNullOrWhiteSpace(content)) return $"HTTP {httpStatus} "; + try + { + using var doc = JsonDocument.Parse(content); + var root = doc.RootElement; + string Get(string n) => root.TryGetProperty(n, out var v) ? v.ToString() : "-"; + string sub = root.TryGetProperty("subscription", out var s) ? s.GetRawText() : ""; + string keys = string.Join(",", root.EnumerateObject().Select(p => p.Name)); + return $"HTTP {httpStatus} status={Get("status")} issuedAt={Get("issuedAt")} expiresAt={Get("expiresAt")} " + + $"subscription={Scrub(sub)} keys=[{keys}]"; + } + catch (Exception ex) + { + return $"HTTP {httpStatus} "; + } + } + + /// + /// Allow-listed rendering of an order-create body. Requestor / TPOC / agreement / organization / + /// certificate / delegation blocks and csr / remarks / recipient e-mails are reduced to their + /// key names so no personal data reaches the test output. subscription and every other + /// scalar are printed in full. + /// + private static string Shape(JsonObject body) + { + var keysOnly = new HashSet(StringComparer.OrdinalIgnoreCase) + { "requestor", "technicalPointOfContact", "agreement", "organization", "certificate", "delegation" }; + var hidden = new HashSet(StringComparer.OrdinalIgnoreCase) + { "csr", "remarks", "recipientEmails", "tags", "groupNumber" }; + var sb = new StringBuilder("{"); + foreach (var kv in body) + { + if (sb.Length > 1) sb.Append(", "); + if (hidden.Contains(kv.Key)) + sb.Append($"\"{kv.Key}\":"); + else if (keysOnly.Contains(kv.Key) && kv.Value is JsonObject jo) + sb.Append($"\"{kv.Key}\":{{keys:[{string.Join(",", jo.Select(p => p.Key))}]}}"); + else + sb.Append($"\"{kv.Key}\":{kv.Value?.ToJsonString()}"); + } + return sb.Append('}').ToString(); + } + + // --------------------------------------------------------------------------- + // Loopback pass-through proxy (records / mutates only the order-create POST) + // --------------------------------------------------------------------------- + + private sealed class CreateCapture + { + public string RequestShape; + public int Status; + public string ResponseBody; + public string OrderId; + } + + private sealed class MutatingProxy : IDisposable + { + private readonly string _upstreamBase; + private readonly Action _mutator; + private readonly HttpListener _listener = new HttpListener(); + private readonly HttpClient _upstream; + private readonly List _creates = new List(); + private readonly CancellationTokenSource _cts = new CancellationTokenSource(); + + public string BaseUrl { get; } + + public List CreateCaptures + { + get { lock (_creates) return _creates.ToList(); } + } + + public MutatingProxy(string upstreamBase, Action mutator) + { + _upstreamBase = upstreamBase; + _mutator = mutator; + _upstream = new HttpClient(new HttpClientHandler + { + AutomaticDecompression = DecompressionMethods.All + }) { Timeout = TimeSpan.FromSeconds(120) }; + + var probe = new TcpListener(IPAddress.Loopback, 0); + probe.Start(); + int port = ((IPEndPoint)probe.LocalEndpoint).Port; + probe.Stop(); + + BaseUrl = $"http://127.0.0.1:{port}"; + _listener.Prefixes.Add(BaseUrl + "/"); + _listener.Start(); + _ = Task.Run(AcceptLoopAsync); + } + + private async Task AcceptLoopAsync() + { + while (!_cts.IsCancellationRequested && _listener.IsListening) + { + HttpListenerContext ctx; + try { ctx = await _listener.GetContextAsync(); } + catch { return; } + _ = Task.Run(() => HandleAsync(ctx)); + } + } + + private async Task HandleAsync(HttpListenerContext ctx) + { + try + { + byte[] reqBody; + using (var ms = new MemoryStream()) + { + await ctx.Request.InputStream.CopyToAsync(ms); + reqBody = ms.ToArray(); + } + + string path = ctx.Request.Url!.AbsolutePath; + bool isCreate = string.Equals(ctx.Request.HttpMethod, "POST", StringComparison.OrdinalIgnoreCase) + && string.Equals(path.TrimEnd('/'), Constants.ApiV2.SslCertificatesPath, StringComparison.Ordinal); + + string capturedShape = null; + if (isCreate && reqBody.Length > 0) + { + var obj = JsonNode.Parse(reqBody)!.AsObject(); + _mutator?.Invoke(obj); + capturedShape = Shape(obj); + reqBody = Encoding.UTF8.GetBytes(obj.ToJsonString()); + } + + using var up = new HttpRequestMessage(new HttpMethod(ctx.Request.HttpMethod), _upstreamBase + ctx.Request.RawUrl); + foreach (string name in ctx.Request.Headers.AllKeys) + { + if (name == null) continue; + string lower = name.ToLowerInvariant(); + if (lower is "host" or "content-length" or "connection" or "transfer-encoding" + or "accept-encoding" or "expect" or "content-type" or "keep-alive") + continue; + up.Headers.TryAddWithoutValidation(name, ctx.Request.Headers[name]); + } + if (reqBody.Length > 0 || ctx.Request.ContentType != null) + { + var content = new ByteArrayContent(reqBody); + if (ctx.Request.ContentType != null) + content.Headers.TryAddWithoutValidation("Content-Type", ctx.Request.ContentType); + up.Content = content; + } + + using var resp = await _upstream.SendAsync(up); + byte[] respBody = await resp.Content.ReadAsByteArrayAsync(); + + if (isCreate) + { + string text = Encoding.UTF8.GetString(respBody); + string orderId = null; + try + { + using var d = JsonDocument.Parse(text); + if (d.RootElement.TryGetProperty("orderId", out var o)) orderId = o.GetString(); + } + catch { /* error body or non-JSON */ } + lock (_creates) + _creates.Add(new CreateCapture + { + RequestShape = capturedShape, + Status = (int)resp.StatusCode, + ResponseBody = text, + OrderId = orderId + }); + } + + ctx.Response.StatusCode = (int)resp.StatusCode; + if (resp.Content.Headers.ContentType != null) + ctx.Response.ContentType = resp.Content.Headers.ContentType.ToString(); + if (resp.Headers.Location != null) + ctx.Response.RedirectLocation = resp.Headers.Location.ToString(); + ctx.Response.ContentLength64 = respBody.Length; + await ctx.Response.OutputStream.WriteAsync(respBody, 0, respBody.Length); + ctx.Response.Close(); + } + catch + { + try { ctx.Response.StatusCode = 502; ctx.Response.Close(); } catch { /* already closed */ } + } + } + + public void Dispose() + { + _cts.Cancel(); + try { _listener.Stop(); _listener.Close(); } catch { /* best effort */ } + _upstream.Dispose(); + _cts.Dispose(); + } + } + } +} +#endif diff --git a/CERTInext.Tests/BlankRequestorWireTests.cs b/CERTInext.Tests/BlankRequestorWireTests.cs new file mode 100644 index 0000000..db30338 --- /dev/null +++ b/CERTInext.Tests/BlankRequestorWireTests.cs @@ -0,0 +1,203 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Linq; +using System.Text.Json; +using System.Text.Json.Nodes; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Microsoft.Extensions.Logging; +using Moq; +using WireMock.RequestBuilders; +using WireMock.ResponseBuilders; +using WireMock.Server; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Pins the bytes actually POSTed to GenerateOrderSSL when the connector has + /// RequestorName="" and TechnicalContactName="" (the configuration the opt-in live + /// probe BlankRequestorLiveTests uses). Drives the real + /// enroll and renewal paths over a real against WireMock, so the + /// assertions are on the captured wire body, not on an intermediate object. + /// + /// Expected wire shape: requestorInformation.requestorName == "" (present, empty string — + /// the plugin does not substitute a default for a blank-but-non-null connector value), + /// no technicalPointOfContact key, and agreementDetails.signerName falls back to + /// "Keyfactor Gateway". + /// + [Collection(LoggingStateCollection.Name)] + public class BlankRequestorWireTests : IDisposable + { + private readonly WireMockServer _server; + + public BlankRequestorWireTests() + { + _server = WireMockServer.Start(); + + _server.Given(Request.Create().WithPath("/GenerateOrderSSL").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.GenerateOrderSuccessJson(MockCertificateData.OrderNumber1))); + _server.Given(Request.Create().WithPath("/TrackOrder").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.TrackOrderIssuedJson(MockCertificateData.OrderNumber1))); + _server.Given(Request.Create().WithPath("/GetCertificate").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.GetCertificateSuccessJson())); + } + + public void Dispose() => _server.Stop(); + + private sealed class CapturingLogger : ILogger + { + public ConcurrentQueue Messages { get; } = new(); + public IDisposable BeginScope(TState state) => null; + public bool IsEnabled(LogLevel logLevel) => true; + public void Log(LogLevel logLevel, EventId eventId, TState state, Exception exception, + Func formatter) => Messages.Enqueue(formatter(state, exception)); + } + + private CERTInextClient BuildBlankRequestorClient(bool logSensitiveRequestData = false) => new CERTInextClient(new CERTInextConfig + { + LogSensitiveRequestData = logSensitiveRequestData, + ApiUrl = _server.Urls[0], + AuthMode = "AccessKey", + ApiKey = "test-key", + AccountNumber = "12345", + RequestorName = string.Empty, + TechnicalContactName = string.Empty, + RequestorEmail = "requestor@example.com", + RequestorIsdCode = "1", + RequestorMobileNumber = "5550000000", + SignerPlace = "Austin", + SignerIp = "203.0.113.10", + PageSize = 100 + }); + + private static EnrollmentProductInfo MakeProductInfo(Dictionary extras = null) + { + var parameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProfileId"] = "842" + }; + if (extras != null) + foreach (var kv in extras) + parameters[kv.Key] = kv.Value; + return new EnrollmentProductInfo { ProductID = "842", ProductParameters = parameters }; + } + + private JsonElement CapturedRoot() + { + var posts = _server.LogEntries + .Where(e => e.RequestMessage.Path == "/GenerateOrderSSL") + .ToList(); + posts.Should().HaveCount(1, "exactly one GenerateOrderSSL POST should have been emitted"); + string body = posts[0].RequestMessage.Body; + body.Should().NotBeNullOrEmpty(); + return JsonDocument.Parse(body!).RootElement; + } + + private static void AssertBlankRequestorShape(JsonElement root) + { + var od = root.GetProperty("orderDetails"); + + od.TryGetProperty("requestorInformation", out var ri).Should().BeTrue(); + ri.TryGetProperty("requestorName", out var name).Should().BeTrue( + "requestorName is serialized even when blank"); + name.ValueKind.Should().Be(JsonValueKind.String); + name.GetString().Should().Be(string.Empty, + "a blank connector RequestorName reaches the wire as an empty string, not a substituted default"); + + od.TryGetProperty("technicalPointOfContact", out _).Should().BeFalse( + "no name resolves, so the technicalPointOfContact block is omitted entirely"); + + od.GetProperty("agreementDetails").GetProperty("signerName").GetString() + .Should().Be("Keyfactor Gateway", "blank requestor/signer name falls back to the built-in default"); + } + + [Fact] + public async Task Enroll_New_BlankRequestorAndTechContact_WireBodyMatchesExpectedShape() + { + var plugin = new CERTInextCAPlugin(BuildBlankRequestorClient(), new CERTInextConfig { PickupRetries = 0 }); + + await plugin.Enroll( + MockCertificateData.FakeCsrPem, "CN=test.example.com", + new Dictionary { ["dns"] = new[] { "test.example.com" } }, + MakeProductInfo(), RequestFormat.PKCS10, EnrollmentType.New); + + AssertBlankRequestorShape(CapturedRoot()); + } + + [Fact] + public async Task Enroll_RenewOrReissue_RenewalApi_BlankRequestorAndTechContact_WireBodyMatchesExpectedShape() + { + var reader = new Mock(); + reader.Setup(r => r.GetRequestIDBySerialNumber(It.IsAny())) + .ReturnsAsync(MockCertificateData.CertId1); + reader.Setup(r => r.GetExpirationDateByRequestId(MockCertificateData.CertId1)) + .Returns(DateTime.UtcNow.AddDays(30)); + + var plugin = new CERTInextCAPlugin(BuildBlankRequestorClient(), reader.Object); + + await plugin.Enroll( + MockCertificateData.FakeCsrPem, "CN=test.example.com", + new Dictionary { ["dns"] = new[] { "test.example.com" } }, + MakeProductInfo(new Dictionary + { + ["PriorCertSN"] = "AABB", + ["RenewalWindowDays"] = "90" + }), + RequestFormat.PKCS10, EnrollmentType.RenewOrReissue); + + // Guard: the renewal API path (not the new-enroll fallback) must have produced the body. + reader.Verify(r => r.GetExpirationDateByRequestId(MockCertificateData.CertId1), Times.Once); + AssertBlankRequestorShape(CapturedRoot()); + } + + /// + /// Justifies the live test capturing the Trace PlaceOrderAsync request payload dump + /// (LogSensitiveRequestData=true) instead of the socket: apart from the redacted + /// meta.authKey, the dump's orderDetails is identical to the body WireMock + /// received. + /// + [Fact] + public async Task TraceDump_OrderDetails_EqualsWireBody_WhenSensitiveLoggingOn() + { + string marker = $"wire-{Guid.NewGuid():N}.example.com"; + var plugin = new CERTInextCAPlugin(BuildBlankRequestorClient(logSensitiveRequestData: true), + new CERTInextConfig { PickupRetries = 0 }); + + var logger = new CapturingLogger(); + using (CERTInextClient.OverrideLoggerForTests(logger)) + { + await plugin.Enroll( + MockCertificateData.FakeCsrPem, $"CN={marker}", + new Dictionary { ["dns"] = new[] { marker } }, + MakeProductInfo(), RequestFormat.PKCS10, EnrollmentType.New); + } + + const string prefix = "PlaceOrderAsync request payload: "; + string dump = logger.Messages.Single(m => m.StartsWith(prefix, StringComparison.Ordinal) && m.Contains(marker)); + string dumpJson = dump.Substring(prefix.Length); + + dumpJson.Should().NotContain("test-key").And.Contain("***REDACTED***"); + var logged = JsonNode.Parse(dumpJson)!["orderDetails"]; + var wire = JsonNode.Parse(CapturedRoot().GetRawText())!["orderDetails"]; + JsonNode.DeepEquals(logged, wire).Should().BeTrue("the Trace dump must mirror the POSTed orderDetails"); + AssertBlankRequestorShape(JsonDocument.Parse(dumpJson).RootElement); + } + } +} diff --git a/CERTInext.Tests/BodylessRevokedGuardTests.cs b/CERTInext.Tests/BodylessRevokedGuardTests.cs new file mode 100644 index 0000000..4b250b5 --- /dev/null +++ b/CERTInext.Tests/BodylessRevokedGuardTests.cs @@ -0,0 +1,237 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Linq; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Moq; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Issue 0049 (V1 port): the V1 client never downloads a revoked certificate's body, so a + /// revoked order always reaches Synchronize/GetSingleRecord with Certificate = null. + /// Emitted as-is for an order the gateway never stored with a body, that record poisons the + /// gateway's revoked-certificate search (FromDER on an empty body → 500 on every Command scan). + /// The guard consults : + /// a date → REVOKED unchanged; null → FAILED without revocation data; no row / error / + /// no reader → Sync skips, GetSingleRecord returns FAILED. + /// + public class BodylessRevokedGuardTests + { + private const string Id = MockCertificateData.CertId3; + + /// A revoked record as the V1 client returns it after the sync refetch: no body. + private static LegacyGetCertificateResponse BodylessRevoked() => + new LegacyGetCertificateResponse + { + Id = Id, + Status = "revoked", + Certificate = null, + ProfileId = MockCertificateData.ProfileIdTls, + RevokedAt = new DateTime(2026, 10, 20, 0, 0, 0, DateTimeKind.Utc), + RevocationReason = "keyCompromise" + }; + + private static async IAsyncEnumerable AsyncEnum( + IEnumerable items) + { + foreach (var item in items) + { + yield return item; + await Task.Yield(); + } + } + + private static Mock ClientReturning(LegacyGetCertificateResponse refetched) + { + var mock = new Mock(MockBehavior.Loose); + mock.Setup(c => c.ListCertificatesAsync( + It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnum(new[] { BodylessRevoked() })); + mock.Setup(c => c.GetCertificateAsync(Id, It.IsAny())) + .ReturnsAsync(refetched); + return mock; + } + + private static async Task> RunSync( + ICERTInextClient client, ICertificateDataReader reader) + { + var plugin = new CERTInextCAPlugin(client, reader, new CERTInextConfig()); + var buffer = new BlockingCollection(10); + await plugin.Synchronize(buffer, lastSync: null, fullSync: true, cancelToken: CancellationToken.None); + return buffer.ToList(); + } + + // ------------------------------------------------------------------------------------- + // Synchronize + // ------------------------------------------------------------------------------------- + + [Fact] + public async Task Sync_GatewayHoldsBody_EmitsBodylessRevokedUnchanged() + { + var reader = new Mock(MockBehavior.Strict); + reader.Setup(r => r.GetExpirationDateByRequestId(Id)).Returns(new DateTime(2027, 1, 1)); + + var results = await RunSync(ClientReturning(BodylessRevoked()).Object, reader.Object); + + results.Should().ContainSingle(); + results[0].Status.Should().Be((int)EndEntityStatus.REVOKED, + "an out-of-band CA revoke must still propagate when the gateway already holds the body"); + results[0].Certificate.Should().BeNull(); + results[0].RevocationDate.Should().NotBeNull(); + results[0].RevocationReason.Should().Be(1); + } + + [Fact] + public async Task Sync_GatewayRowWithoutBody_EmitsFailedWithoutRevocationData() + { + var reader = new Mock(MockBehavior.Strict); + reader.Setup(r => r.GetExpirationDateByRequestId(Id)).Returns((DateTime?)null); + + var results = await RunSync(ClientReturning(BodylessRevoked()).Object, reader.Object); + + results.Should().ContainSingle(); + results[0].Status.Should().Be((int)EndEntityStatus.FAILED); + results[0].Certificate.Should().BeNull(); + results[0].RevocationDate.Should().BeNull( + "a RevocationDate on a body-less row is what the gateway's revoked search crashes on"); + results[0].RevocationReason.Should().Be(0); + } + + [Fact] + public async Task Sync_NoGatewayRow_SkipsRecord() + { + var reader = new Mock(MockBehavior.Strict); + reader.Setup(r => r.GetExpirationDateByRequestId(Id)).Throws(new ArgumentException("no row")); + + var results = await RunSync(ClientReturning(BodylessRevoked()).Object, reader.Object); + + results.Should().BeEmpty("a brand-new body-less REVOKED row could never be un-poisoned"); + } + + [Fact] + public async Task Sync_ReaderThrowsUnexpected_SkipsRecord() + { + var reader = new Mock(MockBehavior.Strict); + reader.Setup(r => r.GetExpirationDateByRequestId(Id)).Throws(new InvalidOperationException("db down")); + + var results = await RunSync(ClientReturning(BodylessRevoked()).Object, reader.Object); + + results.Should().BeEmpty(); + } + + [Fact] + public async Task Sync_NoReaderInjected_SkipsRecord() + { + var results = await RunSync(ClientReturning(BodylessRevoked()).Object, reader: null); + + results.Should().BeEmpty(); + } + + [Fact] + public async Task Sync_RefetchFails_MetadataOnlyRevokedIsStillGuarded() + { + var mock = new Mock(MockBehavior.Loose); + mock.Setup(c => c.ListCertificatesAsync( + It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnum(new[] { BodylessRevoked() })); + mock.Setup(c => c.GetCertificateAsync(Id, It.IsAny())) + .ThrowsAsync(new Exception("TrackOrder 500")); + var reader = new Mock(MockBehavior.Strict); + reader.Setup(r => r.GetExpirationDateByRequestId(Id)).Returns((DateTime?)null); + + var results = await RunSync(mock.Object, reader.Object); + + results.Should().ContainSingle(); + results[0].Status.Should().Be((int)EndEntityStatus.FAILED); + results[0].RevocationDate.Should().BeNull(); + } + + [Fact] + public async Task Sync_RevokedWithBody_DoesNotConsultReader() + { + // Strict mock with no setups: any reader call fails the test. + var reader = new Mock(MockBehavior.Strict); + + var results = await RunSync( + ClientReturning(MockCertificateData.RevokedCertRecord(Id)).Object, reader.Object); + + results.Should().ContainSingle(); + results[0].Status.Should().Be((int)EndEntityStatus.REVOKED); + results[0].Certificate.Should().NotBeNullOrWhiteSpace(); + } + + // ------------------------------------------------------------------------------------- + // GetSingleRecord + // ------------------------------------------------------------------------------------- + + private static Task RunGetSingle(ICertificateDataReader reader) + { + var mock = new Mock(MockBehavior.Loose); + mock.Setup(c => c.GetCertificateAsync(Id, It.IsAny())) + .ReturnsAsync(BodylessRevoked()); + var plugin = new CERTInextCAPlugin(mock.Object, reader, new CERTInextConfig()); + return plugin.GetSingleRecord(Id); + } + + [Fact] + public async Task GetSingleRecord_GatewayHoldsBody_ReturnsRevoked() + { + var reader = new Mock(MockBehavior.Strict); + reader.Setup(r => r.GetExpirationDateByRequestId(Id)).Returns(new DateTime(2027, 1, 1)); + + var record = await RunGetSingle(reader.Object); + + record.Status.Should().Be((int)EndEntityStatus.REVOKED); + record.RevocationDate.Should().NotBeNull(); + } + + [Fact] + public async Task GetSingleRecord_GatewayRowWithoutBody_ReturnsFailed() + { + var reader = new Mock(MockBehavior.Strict); + reader.Setup(r => r.GetExpirationDateByRequestId(Id)).Returns((DateTime?)null); + + var record = await RunGetSingle(reader.Object); + + record.Status.Should().Be((int)EndEntityStatus.FAILED); + record.RevocationDate.Should().BeNull(); + record.RevocationReason.Should().Be(0); + } + + [Fact] + public async Task GetSingleRecord_NoGatewayRow_ReturnsFailed() + { + var reader = new Mock(MockBehavior.Strict); + reader.Setup(r => r.GetExpirationDateByRequestId(Id)).Throws(new ArgumentException("no row")); + + var record = await RunGetSingle(reader.Object); + + record.Status.Should().Be((int)EndEntityStatus.FAILED, "GetSingleRecord can't skip"); + record.RevocationDate.Should().BeNull(); + } + + [Fact] + public async Task GetSingleRecord_NoReaderInjected_ReturnsFailed() + { + var record = await RunGetSingle(reader: null); + + record.Status.Should().Be((int)EndEntityStatus.FAILED); + record.RevocationDate.Should().BeNull(); + } + } +} diff --git a/CERTInext.Tests/BoundedDcvSyncTests.cs b/CERTInext.Tests/BoundedDcvSyncTests.cs index 96b4e3b..5666f9b 100644 --- a/CERTInext.Tests/BoundedDcvSyncTests.cs +++ b/CERTInext.Tests/BoundedDcvSyncTests.cs @@ -1,3 +1,17 @@ +// Copyright 2026 Keyfactor +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + using System; using FluentAssertions; using Xunit; diff --git a/CERTInext.Tests/CERTInext.Tests.csproj b/CERTInext.Tests/CERTInext.Tests.csproj index 84ce7a6..32ac2c9 100644 --- a/CERTInext.Tests/CERTInext.Tests.csproj +++ b/CERTInext.Tests/CERTInext.Tests.csproj @@ -6,9 +6,9 @@ 12.0 false true - - false + + true $(DefineConstants);SUPPORTS_DCV @@ -18,9 +18,11 @@ + exist, so exclude these files unless SUPPORTS_DCV is defined. --> + + diff --git a/CERTInext.Tests/CERTInextCAPluginAuditLoggingTests.cs b/CERTInext.Tests/CERTInextCAPluginAuditLoggingTests.cs new file mode 100644 index 0000000..5c221bf --- /dev/null +++ b/CERTInext.Tests/CERTInextCAPluginAuditLoggingTests.cs @@ -0,0 +1,175 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.Logging; +using Microsoft.Extensions.Logging; +using Moq; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Pins the on/off behavior of the "Enrollment attempt started" audit log line in + /// for the LogSensitiveRequestData connector + /// setting. + /// + /// CERTInextCAPlugin._logger is a per-instance field assigned from + /// LogHandler.GetClassLogger<CERTInextCAPlugin>() at construction time (unlike + /// Client.CERTInextClient.Logger, which is a static readonly field resolved once + /// per process — not swappable after the fact). Swapping + /// before constructing a fresh plugin instance is therefore a genuine, narrow capture seam for + /// this one log line. All tests in this class run in the shared + /// collection (sequential within the class by xUnit default; the named collection also blocks + /// any other class opting into it from interleaving) and restore the original factory in a + /// finally block so the global static mutation can't outlive a single test. + /// + [Collection(LoggingStateCollection.Name)] + public class CERTInextCAPluginAuditLoggingTests + { + private sealed class CapturingLoggerProvider : ILoggerProvider + { + public ConcurrentQueue Messages { get; } = new(); + public ILogger CreateLogger(string categoryName) => new CapturingLogger(Messages); + public void Dispose() { } + + private sealed class CapturingLogger : ILogger + { + private readonly ConcurrentQueue _messages; + public CapturingLogger(ConcurrentQueue messages) => _messages = messages; + public IDisposable BeginScope(TState state) => null; + public bool IsEnabled(LogLevel logLevel) => true; + public void Log(LogLevel logLevel, EventId eventId, TState state, Exception exception, + Func formatter) + => _messages.Enqueue(formatter(state, exception)); + } + } + + private static Mock NewHappyPathMock() + { + var mock = new Mock(MockBehavior.Loose); + mock.Setup(c => c.EnrollCertificateAsync(It.IsAny(), It.IsAny())) + .ReturnsAsync(new API.EnrollCertificateResponse + { + Id = "ORD-AUDIT-001", + Status = "issued", + Certificate = MockCertificateData.FakePemCertificate + }); + return mock; + } + + /// + /// Runs once with a freshly-swapped capturing + /// logger factory in place — constructing the plugin only after the swap, so its + /// per-instance _logger field resolves through the capturing factory — and returns + /// every rendered log message the plugin emitted. RequesterName/RequesterEmail are driven + /// through the template parameters that EnrollmentParams.RequesterName/ + /// RequesterEmail read ( / + /// RequesterEmail), matching what the "Enrollment attempt started" line logs. + /// + private static async Task<(ConcurrentQueue Messages, string SubjectMarker)> CaptureEnrollLogMessagesAsync( + bool logSensitiveRequestData, string requesterName, string requesterEmail) + { + var provider = new CapturingLoggerProvider(); + var factory = LoggerFactory.Create(b => b.AddProvider(provider).SetMinimumLevel(LogLevel.Trace)); + + // LogHandler.Factory is a shared static — other test classes construct their own + // CERTInextCAPlugin instances concurrently (xUnit parallelizes across collections by + // default) and, purely by coincidence of timing, some of those may resolve their + // _logger through this same swapped factory while it's active, adding unrelated + // "Enrollment attempt started" lines to provider.Messages. A per-call unique subject + // is the only reliable way to pick this call's own line back out of that noise. + string subjectMarker = "audit-" + Guid.NewGuid().ToString("N"); + try + { + LogHandler.Factory = factory; + + var mock = NewHappyPathMock(); + var config = new CERTInextConfig + { + PickupRetries = 0, + LogSensitiveRequestData = logSensitiveRequestData + }; + // Constructed AFTER the factory swap so its _logger field resolves through it. + var plugin = new CERTInextCAPlugin(mock.Object, config); + + var productInfo = new EnrollmentProductInfo + { + ProductID = "DV SSL", + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = "842", + [Constants.EnrollmentParam.RequesterName] = requesterName, + [Constants.EnrollmentParam.RequesterEmail] = requesterEmail + } + }; + + await plugin.Enroll( + csr: MockCertificateData.FakeCsrPem, + subject: $"CN={subjectMarker}.example.com", + san: null, + productInfo: productInfo, + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + } + finally + { + // LogHandler.Factory is write-only (no getter to save/restore the prior value), + // so reset to the same NullLoggerFactory the class defaults to absent any host + // configuring a real one — matching every other test's ambient (unconfigured) + // logging state. + LogHandler.Factory = Microsoft.Extensions.Logging.Abstractions.NullLoggerFactory.Instance; + factory.Dispose(); + } + + return (provider.Messages, subjectMarker); + } + + private static string FindEnrollmentAttemptLine(ConcurrentQueue messages, string subjectMarker) + { + foreach (var m in messages) + { + if (m.Contains("Enrollment attempt started") && m.Contains(subjectMarker)) + return m; + } + return null; + } + + [Fact] + public async Task Enroll_LogSensitiveRequestDataFalse_AuditLineOmitsNameAndMasksEmail() + { + var (messages, marker) = await CaptureEnrollLogMessagesAsync( + logSensitiveRequestData: false, requesterName: "Jane Doe", requesterEmail: "jane.doe@example.com"); + + string line = FindEnrollmentAttemptLine(messages, marker); + line.Should().NotBeNull("the enrollment-attempt audit line must always be logged"); + line.Should().NotContain("Jane Doe", "the requester name must be dropped entirely when the flag is off"); + line.Should().NotContain("RequesterName=", "the RequesterName field itself must be absent from the line, not just blanked"); + line.Should().Contain("j***@example.com", "the requester email must be masked but keep its domain"); + line.Should().NotContain("jane.doe@example.com"); + } + + [Fact] + public async Task Enroll_LogSensitiveRequestDataTrue_AuditLineIncludesNameAndEmailInFull() + { + var (messages, marker) = await CaptureEnrollLogMessagesAsync( + logSensitiveRequestData: true, requesterName: "Jane Doe", requesterEmail: "jane.doe@example.com"); + + string line = FindEnrollmentAttemptLine(messages, marker); + line.Should().NotBeNull("the enrollment-attempt audit line must always be logged"); + line.Should().Contain("Jane Doe", "the requester name is logged in full when the flag is on"); + line.Should().Contain("jane.doe@example.com", "the requester email is logged in full when the flag is on"); + } + } +} diff --git a/CERTInext.Tests/CERTInextCAPluginCoverageTests.cs b/CERTInext.Tests/CERTInextCAPluginCoverageTests.cs index f684f7d..e3c9617 100644 --- a/CERTInext.Tests/CERTInextCAPluginCoverageTests.cs +++ b/CERTInext.Tests/CERTInextCAPluginCoverageTests.cs @@ -259,6 +259,59 @@ public async Task RenewOrReissue_CallsRenewApi_WhenCertWithinRenewalWindow() It.IsAny()), Times.Never); } + // --------------------------------------------------------------------------- + // A1d-2: renewal within window carries the template's product code onto the + // RenewCertificateRequest, not just the connector-level DefaultProductCode. + // --------------------------------------------------------------------------- + + [Fact] + public async Task RenewOrReissue_CallsRenewApi_UsesTemplateProductCode() + { + var clientMock = NewMock(); + var readerMock = NewReaderMock(); + + // Expiry is 30 days in the future, renewal window is 90 days → within window + DateTime expiry = DateTime.UtcNow.AddDays(30); + + readerMock + .Setup(r => r.GetRequestIDBySerialNumber(It.IsAny())) + .ReturnsAsync(MockCertificateData.CertId1); + + readerMock + .Setup(r => r.GetExpirationDateByRequestId(MockCertificateData.CertId1)) + .Returns(expiry); + + clientMock + .Setup(c => c.RenewCertificateAsync( + MockCertificateData.CertId1, + It.Is(r => r.ProfileId == MockCertificateData.ProfileIdClient), + It.IsAny())) + .ReturnsAsync(MockCertificateData.IssuedEnrollResponse("cert-renewed-002")); + + var plugin = new CERTInextCAPlugin(clientMock.Object, readerMock.Object); + + // ProfileId is a non-default value distinct from the connector's DefaultProductCode. + var productInfo = MakeProductInfo(profileId: MockCertificateData.ProfileIdClient, extras: new Dictionary + { + ["PriorCertSN"] = "AABBCCDDEEFF", + ["RenewalWindowDays"] = "90" + }); + + var result = await plugin.Enroll( + csr: MockCertificateData.FakeCsrPem, + subject: "CN=test.example.com", + san: null, + productInfo: productInfo, + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.RenewOrReissue); + + result.Status.Should().Be((int)EndEntityStatus.GENERATED); + clientMock.Verify(c => c.RenewCertificateAsync( + MockCertificateData.CertId1, + It.Is(r => r.ProfileId == MockCertificateData.ProfileIdClient), + It.IsAny()), Times.Once); + } + // --------------------------------------------------------------------------- // A1e: PriorCertSN present, cert already expired → new enroll // Semantics: useRenewalApi = expiry > now && expiry <= now + window. @@ -736,6 +789,188 @@ public void Initialize_Succeeds_WithValidApiKeyConfig() act.Should().NotThrow(); } + // --------------------------------------------------------------------------- + // M1 compliance fix: Initialize must enforce the same https-or-loopback rule as + // ValidateCAConnectionInfo on ApiUrl (and, in V1 OAuth mode, OAuthTokenUrl) — a + // connector saved before that rule existed would otherwise sail through on every + // gateway restart and keep sending credentials in cleartext. + // --------------------------------------------------------------------------- + + [Fact] + public void Initialize_Throws_WhenApiUrlIsHttp_NonLoopback() + { + var configProviderMock = new Mock(MockBehavior.Strict); + var certReaderMock = NewReaderMock(); + + configProviderMock.Setup(p => p.CAConnectionData) + .Returns(new Dictionary + { + ["ApiUrl"] = "http://ca.example.com", + ["AuthMode"] = "ApiKey", + ["ApiKey"] = "test-api-key-value", + ["Enabled"] = true + }); + + var plugin = new CERTInextCAPlugin(); + + Action act = () => plugin.Initialize(configProviderMock.Object, certReaderMock.Object); + + act.Should().Throw() + .WithMessage("*ApiUrl*https*"); + } + + [Fact] + public void Initialize_Throws_WhenApiUrlIsHttp_NonLoopback_EvenWithInjectedClient() + { + // _client ??= in Initialize lets tests inject a mock client and skip building a + // real CERTInextClient — but the config validation itself must still run + // unconditionally; an injected client must not bypass the cleartext-credential + // check on the saved config. + var configProviderMock = new Mock(MockBehavior.Strict); + var certReaderMock = NewReaderMock(); + + configProviderMock.Setup(p => p.CAConnectionData) + .Returns(new Dictionary + { + ["ApiUrl"] = "http://ca.example.com", + ["AuthMode"] = "ApiKey", + ["ApiKey"] = "test-api-key-value", + ["Enabled"] = true + }); + + var plugin = new CERTInextCAPlugin(NewMock().Object); + + Action act = () => plugin.Initialize(configProviderMock.Object, certReaderMock.Object); + + act.Should().Throw() + .WithMessage("*ApiUrl*https*"); + } + + [Theory] + [InlineData("http://localhost:8080")] + [InlineData("http://127.0.0.1:8080")] + [InlineData("http://[::1]:8080")] + public void Initialize_Succeeds_WhenApiUrlIsHttp_Loopback(string apiUrl) + { + var configProviderMock = new Mock(MockBehavior.Strict); + var certReaderMock = NewReaderMock(); + + configProviderMock.Setup(p => p.CAConnectionData) + .Returns(new Dictionary + { + ["ApiUrl"] = apiUrl, + ["AuthMode"] = "ApiKey", + ["ApiKey"] = "test-api-key-value", + ["Enabled"] = true + }); + + var plugin = new CERTInextCAPlugin(); + + Action act = () => plugin.Initialize(configProviderMock.Object, certReaderMock.Object); + + act.Should().NotThrow(); + } + + [Fact] + public void Initialize_Succeeds_WhenApiUrlIsHttps() + { + var configProviderMock = new Mock(MockBehavior.Strict); + var certReaderMock = NewReaderMock(); + + configProviderMock.Setup(p => p.CAConnectionData) + .Returns(new Dictionary + { + ["ApiUrl"] = "https://ca.example.com", + ["AuthMode"] = "ApiKey", + ["ApiKey"] = "test-api-key-value", + ["Enabled"] = true + }); + + var plugin = new CERTInextCAPlugin(); + + Action act = () => plugin.Initialize(configProviderMock.Object, certReaderMock.Object); + + act.Should().NotThrow(); + } + + [Fact] + public void Initialize_Throws_WhenOAuthTokenUrlIsHttp_NonLoopback() + { + var configProviderMock = new Mock(MockBehavior.Strict); + var certReaderMock = NewReaderMock(); + + configProviderMock.Setup(p => p.CAConnectionData) + .Returns(new Dictionary + { + ["ApiUrl"] = "https://ca.example.com", + ["AccountNumber"] = "12345", + ["AuthMode"] = "OAuth", + ["OAuthTokenUrl"] = "http://token.example.com", + ["OAuthClientId"] = "my-client", + ["OAuthClientSecret"] = "my-secret", + ["Enabled"] = true + }); + + var plugin = new CERTInextCAPlugin(); + + Action act = () => plugin.Initialize(configProviderMock.Object, certReaderMock.Object); + + act.Should().Throw() + .WithMessage("*OAuthTokenUrl*https*"); + } + + [Fact] + public void Initialize_Succeeds_WhenOAuthTokenUrlIsHttp_Loopback() + { + var configProviderMock = new Mock(MockBehavior.Strict); + var certReaderMock = NewReaderMock(); + + configProviderMock.Setup(p => p.CAConnectionData) + .Returns(new Dictionary + { + ["ApiUrl"] = "https://ca.example.com", + ["AccountNumber"] = "12345", + ["AuthMode"] = "OAuth", + ["OAuthTokenUrl"] = "http://localhost:9999", + ["OAuthClientId"] = "my-client", + ["OAuthClientSecret"] = "my-secret", + ["Enabled"] = true + }); + + var plugin = new CERTInextCAPlugin(); + + Action act = () => plugin.Initialize(configProviderMock.Object, certReaderMock.Object); + + act.Should().NotThrow(); + } + + [Fact] + public void Initialize_DoesNotCheckOAuthTokenUrl_WhenAuthModeIsNotOAuth() + { + // AccessKey mode never reads OAuthTokenUrl (CERTInextClient only builds the OAuth + // authenticator when AuthMode is OAuth/OAuth2) — a stray http OAuthTokenUrl value + // left over in a connector's saved config from a prior AuthMode switch must not + // block startup. + var configProviderMock = new Mock(MockBehavior.Strict); + var certReaderMock = NewReaderMock(); + + configProviderMock.Setup(p => p.CAConnectionData) + .Returns(new Dictionary + { + ["ApiUrl"] = "https://ca.example.com", + ["AuthMode"] = "ApiKey", + ["ApiKey"] = "test-api-key-value", + ["OAuthTokenUrl"] = "http://token.example.com", + ["Enabled"] = true + }); + + var plugin = new CERTInextCAPlugin(); + + Action act = () => plugin.Initialize(configProviderMock.Object, certReaderMock.Object); + + act.Should().NotThrow(); + } + // --------------------------------------------------------------------------- // C3a: Enroll passes ValidityDays, AutoApprove, RequesterName, RequesterEmail, KeyType // --------------------------------------------------------------------------- diff --git a/CERTInext.Tests/CERTInextCAPluginDcvTests.cs b/CERTInext.Tests/CERTInextCAPluginDcvTests.cs index 837ae8d..8794903 100644 --- a/CERTInext.Tests/CERTInextCAPluginDcvTests.cs +++ b/CERTInext.Tests/CERTInextCAPluginDcvTests.cs @@ -1,9 +1,13 @@ // Copyright 2024 Keyfactor // Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. -// At http://www.apache.org/licenses/LICENSE-2.0 +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. using System; using System.Collections.Generic; +using System.Linq; using System.Threading; using System.Threading.Tasks; using FluentAssertions; @@ -35,7 +39,8 @@ private static CERTInextConfig DcvConfig( int propagationDelaySeconds = 1, int timeoutMinutes = 1, int dcvWaitForChallengeSeconds = 0, - int dcvWaitForIssuanceSeconds = 0) => + int dcvWaitForIssuanceSeconds = 0, + int pickupRetries = 0) => new CERTInextConfig { DcvEnabled = enabled, @@ -45,7 +50,12 @@ private static CERTInextConfig DcvConfig( // behaviour and run fast. Tests that exercise the new wait paths can opt // in with a positive value (see WaitsForChallenge_ToAppear / WaitsForIssuance). DcvWaitForChallengeSeconds = dcvWaitForChallengeSeconds, - DcvWaitForIssuanceSeconds = dcvWaitForIssuanceSeconds + DcvWaitForIssuanceSeconds = dcvWaitForIssuanceSeconds, + // Disable the synchronous pickup poll by default (same reasoning as the wait + // budgets above): the DCV path owns issuance for these tests, and a DCV-disabled + // or no-factory case that ends on a pending result must not pay the real pickup + // Task.Delay loop. The dedicated pickup tests live in CERTInextCAPluginTests. + PickupRetries = pickupRetries }; private static Mock NewMock() => @@ -410,12 +420,12 @@ public async Task SetDomainValidatorFactory_SecondCall_OverridesFirst() [InlineData("5")] // OrderStatusId 5 = Order Rejected public async Task Dcv_Skipped_WhenOrderStatusIdIsTerminal_EvenIfDcvValidated(string terminalOrderStatusId) { - // Regression guard for the cached-DCV path: a cancelled or rejected order + // Guard for the cached-DCV path: a cancelled or rejected order // can still have domainVerification.Status="1" carried over from a prior // validated round. Without this guard the plugin would return true from // PerformDcvIfNeededAsync and the caller would spend the full // DcvWaitForIssuanceSeconds budget polling GetCertificate for a cert that - // is never going to issue. Per audit report B2 on PR #2. + // is never going to issue. var mock = NewMock(); mock.Setup(c => c.EnrollCertificateAsync(It.IsAny(), It.IsAny())) .ReturnsAsync(new EnrollCertificateResponse { Id = MockCertificateData.DcvOrderId, Status = "pending" }); @@ -437,17 +447,19 @@ public async Task Dcv_Skipped_WhenOrderStatusIdIsTerminal_EvenIfDcvValidated(str }); var validator = new FakeDomainValidator(); - // Issuance-wait budget > 0 so a wrong-path entry would manifest as a - // GetCertificate call we DON'T expect. + // Issuance-wait budget > 0 AND pickup ENABLED (pickupRetries > 0) so a wrong-path + // entry would manifest as a GetCertificate call we DON'T expect — this test must + // fail if either the DCV issuance-wait guard OR the synchronous-pickup gate + // (dcvIssuanceWaitRan) regresses and starts polling a cancelled/rejected order. var plugin = BuildPlugin(mock.Object, new FakeDomainValidatorFactory(validator), - DcvConfig(dcvWaitForIssuanceSeconds: 10)); + DcvConfig(dcvWaitForIssuanceSeconds: 10, pickupRetries: 5)); await Enroll(plugin); mock.Verify(c => c.GetCertificateAsync(It.IsAny(), It.IsAny()), Times.Never, - "Enroll must not enter WaitForIssuanceAfterDcvAsync when the order is " + - "cancelled/rejected, even if DCV happens to be in a 'validated' state"); + "Enroll must not enter WaitForIssuanceAfterDcvAsync OR the synchronous pickup poll " + + "when the order is cancelled/rejected, even if DCV happens to be in a 'validated' state"); validator.StagedRecords.Should().BeEmpty( "DCV staging must not run for a cancelled/rejected order"); } @@ -519,7 +531,7 @@ public async Task SyncDcvRetry_DoesSingleShotTrackOrder_WhenChallengeNotReady() // --------------------------------------------------------------------------- [Fact] - public async Task Dcv_Throws_WhenNoProviderForDomain() + public async Task Dcv_SkipsAndDefers_WhenNoProviderForDomain() { var mock = NewMock(); mock.Setup(c => c.EnrollCertificateAsync(It.IsAny(), It.IsAny())) @@ -531,17 +543,19 @@ public async Task Dcv_Throws_WhenNoProviderForDomain() mock.Setup(c => c.GetDcvAsync(MockCertificateData.DcvOrderId, MockCertificateData.DcvDomain, Constants.Dcv.MethodDnsTxt, It.IsAny())) .ReturnsAsync(MockCertificateData.DcvTokenResponse()); - // Factory returns null → no DNS provider configured + // Factory returns null → no DNS provider configured. This must not throw and fail the + // whole order — the "unresolvable" domain may just be a non-DNS Subject CN with no + // config-level way to prevent it (SubmitNonDnsSans only filters the SAN list, not the + // subject). It is logged loudly and deferred instead. var plugin = BuildPlugin(mock.Object, new FakeDomainValidatorFactory(validator: null)); Func act = () => Enroll(plugin); - await act.Should().ThrowAsync() - .WithMessage("*No DNS provider plugin is configured*"); + await act.Should().NotThrowAsync(); } [Fact] - public async Task Dcv_Throws_WhenStageValidationFails() + public async Task Dcv_SkipsAndDefers_WhenStageValidationFails() { var mock = NewMock(); mock.Setup(c => c.EnrollCertificateAsync(It.IsAny(), It.IsAny())) @@ -558,10 +572,12 @@ public async Task Dcv_Throws_WhenStageValidationFails() Func act = () => Enroll(plugin); - await act.Should().ThrowAsync() - .WithMessage("*Failed to stage DNS validation*DNS zone not writable*"); + // A StageValidation failure must not throw and fail the whole order. It + // is logged loudly and the domain is skipped/deferred — this is the only pending domain, + // so nothing gets staged and the order defers to the next sync cycle. + await act.Should().NotThrowAsync(); - // No VerifyDcv call — failed before reaching that step + // No VerifyDcv call — nothing was staged to verify mock.Verify(c => c.VerifyDcvAsync(It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny()), Times.Never); } @@ -584,9 +600,11 @@ public async Task Dcv_CleanupAlwaysCalled_EvenWhenVerifyDcvThrows() var validator = new FakeDomainValidator(); var plugin = BuildPlugin(mock.Object, new FakeDomainValidatorFactory(validator)); - Func act = () => Enroll(plugin); - - await act.Should().ThrowAsync().WithMessage("*DNS record not found*"); + // The order is already placed, so the VerifyDcv failure no longer fails Enroll (issue + // 0077): it is logged and the pending result carrying the order number is returned. + var result = await Enroll(plugin); + result.CARequestID.Should().Be(MockCertificateData.DcvOrderId); + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); // Cleanup must run even when VerifyDcv throws string expectedHostname = string.Format(Constants.Dcv.DefaultTxtRecordTemplate, MockCertificateData.DcvDomain); @@ -594,7 +612,7 @@ public async Task Dcv_CleanupAlwaysCalled_EvenWhenVerifyDcvThrows() } [Fact] - public async Task Dcv_Throws_WhenGetDcvReturnsNoToken() + public async Task Dcv_SkipsAndDefers_WhenGetDcvReturnsNoToken() { var mock = NewMock(); mock.Setup(c => c.EnrollCertificateAsync(It.IsAny(), It.IsAny())) @@ -611,8 +629,11 @@ public async Task Dcv_Throws_WhenGetDcvReturnsNoToken() Func act = () => Enroll(plugin); - await act.Should().ThrowAsync() - .WithMessage("*GetDcv returned no token*"); + // An empty token must not throw and fail the whole order. It is logged + // loudly (LogError) and the domain is skipped — the order defers to the next sync cycle + // rather than failing Enroll with an order already placed at the CA. + await act.Should().NotThrowAsync(); + validator.StagedRecords.Should().BeEmpty("the only pending domain returned no token, so nothing should have been staged"); } // --------------------------------------------------------------------------- @@ -681,11 +702,16 @@ public async Task Dcv_Defers_When_GetDcv_ReturnsInvalidRequestMessage_WithoutEms } [Fact] - public async Task Dcv_Rethrows_When_GetDcv_FailsWithUnrelatedError() + public async Task Dcv_SkipsAndDefers_WhenGetDcvFailsWithUnrelatedError() { - // Tolerance is narrow: a genuine server error (5xx, transport, auth) must still - // bubble up so the gateway treats the enrollment as failed and the operator can - // diagnose. This guards against accidentally swallowing every GetDcv exception. + // A genuine server error (5xx, transport, auth) from GetDcv must not bubble up and + // fail the whole enrollment: that would orphan the order. GetDcv's behavior for a + // non-DNS order-domain is unmeasured (see BuildSanList's sandbox-only caveat), so + // treating any unrecognized GetDcv error as fatal risks failing perfectly good + // co-tenant DNS domains on the same order over one domain's transient or CA-side + // issue, with the enrollment already placed at CERTInext and no catch anywhere above + // this call. The failure is still loud (LogError, with the underlying exception) — it + // just does not fail the call. var mock = NewMock(); mock.Setup(c => c.EnrollCertificateAsync(It.IsAny(), It.IsAny())) .ReturnsAsync(new EnrollCertificateResponse { Id = MockCertificateData.DcvOrderId, Status = "pending_dcv" }); @@ -700,8 +726,8 @@ public async Task Dcv_Rethrows_When_GetDcv_FailsWithUnrelatedError() var plugin = BuildPlugin(mock.Object, new FakeDomainValidatorFactory(validator)); Func act = () => Enroll(plugin); - await act.Should().ThrowAsync() - .WithMessage("*HTTP 500*"); + await act.Should().NotThrowAsync(); + validator.StagedRecords.Should().BeEmpty("the only pending domain's GetDcv call failed, so nothing should have been staged"); } // --------------------------------------------------------------------------- @@ -816,5 +842,812 @@ public async Task Dcv_WaitsForIssuance_AfterDcvVerifies() mock.Verify(c => c.GetCertificateAsync(MockCertificateData.DcvOrderId, It.IsAny()), Times.AtLeast(2), "plugin should have polled at least twice for issuance"); } + + // --------------------------------------------------------------------------- + // Undrainable pending domains must not strand the valid ones on the same order + // --------------------------------------------------------------------------- + + /// Builds a DomainVerificationDetail JsonElement for the given dcvStatus. + private static System.Text.Json.JsonElement DcvDetail(string dcvStatus) => + System.Text.Json.JsonSerializer.SerializeToElement(new DomainVerificationDetail + { + DcvMethod = Constants.Dcv.MethodDnsTxt, + DcvStatus = dcvStatus, + Status = "1" + }); + + /// + /// Builds a TrackOrder response whose domainVerification block lists several pending + /// domains, so tests can mix validatable and unvalidatable keys on one order. + /// + private static TrackOrderResponse DcvPendingTrackResponseMultiDomain( + string orderNumber, params string[] domains) + { + var detail = DcvDetail(Constants.Dcv.StatusPending); + var raw = new Dictionary(); + foreach (string d in domains) + raw[d] = detail; + + return new TrackOrderResponse + { + OrderDetails = new TrackOrderResponseDetails + { + OrderStatusId = "1", + CertificateStatusId = "1", + DomainVerification = new TrackOrderDomainVerification + { + Status = Constants.Dcv.StatusPending, + RawDomainEntries = raw + } + } + }; + } + + /// + /// Builds a TrackOrder response with one already-validated domain (dcvStatus=1) and one + /// still-pending, unresolvable domain (dcvStatus=0) — the shape CERTInext produces when it + /// has cached a prior DCV validation for the CN while a non-DNS SAN on the same order is + /// still outstanding. + /// + private static TrackOrderResponse DcvMixedStatusTrackResponse( + string validatedDomain, string pendingDomain) + { + var validated = DcvDetail(Constants.Dcv.StatusValidated); + var pending = DcvDetail(Constants.Dcv.StatusPending); + + return new TrackOrderResponse + { + OrderDetails = new TrackOrderResponseDetails + { + OrderStatusId = "1", + CertificateStatusId = "1", + DomainVerification = new TrackOrderDomainVerification + { + // Aggregate stays pending because one domain still is — this must not take + // the early "already validated" return at the top of the method. + Status = Constants.Dcv.StatusPending, + RawDomainEntries = new Dictionary + { + [validatedDomain] = validated, + [pendingDomain] = pending + } + } + } + }; + } + + /// + /// "The CN is always a pending domain too" is untrue whenever CERTInext has cached a prior + /// DCV validation for it (a case this same file's cached-validation branch documents), so a + /// non-DNS SAN sharing the order with an already-validated CN must not throw — it must defer + /// to the next sync cycle exactly like the single-domain case does. + /// + [Fact] + public async Task Dcv_CachedCnPlusUnresolvableSan_DefersWithoutThrowing() + { + const string order = MockCertificateData.DcvOrderId; + const string cn = MockCertificateData.DcvDomain; + const string ip = "192.0.2.10"; + + var mock = NewMock(); + mock.Setup(c => c.EnrollCertificateAsync( + It.IsAny(), It.IsAny())) + .ReturnsAsync(new EnrollCertificateResponse { Id = order, Status = "pending" }); + + mock.Setup(c => c.TrackOrderAsync(order, It.IsAny())) + .ReturnsAsync(DcvMixedStatusTrackResponse(validatedDomain: cn, pendingDomain: ip)); + + // The IP clears the FQDN regex and reaches GetDcv, per the sandbox-measured shape. + mock.Setup(c => c.GetDcvAsync(order, ip, Constants.Dcv.MethodDnsTxt, It.IsAny())) + .ReturnsAsync(MockCertificateData.DcvTokenResponse(MockCertificateData.DcvToken)); + + var validator = new FakeDomainValidator(); + // Resolves for the CN (a real, working DNS provider) but not for the IP literal — the + // scenario that must prove "a provider IS deployed" rather than "nothing is deployed". + var plugin = BuildPlugin( + mock.Object, + new FakeDomainValidatorFactory(validator, resolvableDomain: cn), + DcvConfig()); + + Func act = () => Enroll(plugin); + + await act.Should().NotThrowAsync( + "an unresolvable non-DNS SAN must defer the order to the next sync cycle, not fail " + + "the enrollment — the CN having cached DCV proves a provider is deployed and working, " + + "so this is not the 'nothing is deployed' misconfiguration case"); + + validator.StagedRecords.Should().BeEmpty( + "the only pending domain is unresolvable, so nothing should have been staged"); + } + + /// + /// A non-FQDN pending domain must be skipped, not thrown on. + /// + /// Non-DNS SANs are submitted to CERTInext, which registers them verbatim as order + /// domains, so an email/URI SAN turns up as a domainVerification key that fails the FQDN + /// check. That check must not throw for the whole order — it would escape Enroll (which + /// has no catch) after the order was already placed, leaving an orphaned order with no + /// TXT record staged for the *valid* domains beside it, and every sync retry would + /// re-throw so the order could never progress. + /// + [Fact] + public async Task Dcv_NonFqdnPendingDomain_IsSkipped_AndValidDomainStillStaged() + { + const string order = MockCertificateData.DcvOrderId; + const string good = MockCertificateData.DcvDomain; + const string bad = "admin@example.com"; // what an rfc822 SAN comes back as + + var mock = NewMock(); + + mock.Setup(c => c.EnrollCertificateAsync( + It.IsAny(), It.IsAny())) + .ReturnsAsync(new EnrollCertificateResponse { Id = order, Status = "pending_dcv" }); + + mock.SetupSequence(c => c.TrackOrderAsync(order, It.IsAny())) + .ReturnsAsync(DcvPendingTrackResponseMultiDomain(order, good, bad)) + .ReturnsAsync(MockCertificateData.DcvVerifiedTrackResponse(order, good)); + + // Only the valid domain should ever reach GetDcv/VerifyDcv. MockBehavior.Strict means + // an unexpected call for `bad` fails the test on its own. + mock.Setup(c => c.GetDcvAsync(order, good, Constants.Dcv.MethodDnsTxt, It.IsAny())) + .ReturnsAsync(MockCertificateData.DcvTokenResponse(MockCertificateData.DcvToken)); + mock.Setup(c => c.VerifyDcvAsync(order, good, Constants.Dcv.MethodDnsTxt, It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.GetCertificateAsync(order, It.IsAny())) + .ReturnsAsync(MockCertificateData.IssuedCertRecord(order)); + + var validator = new FakeDomainValidator(); + var plugin = BuildPlugin(mock.Object, new FakeDomainValidatorFactory(validator), + DcvConfig(dcvWaitForIssuanceSeconds: 10)); + + // Must not throw. + var result = await Enroll(plugin); + + string expectedHostname = string.Format(Constants.Dcv.DefaultTxtRecordTemplate, good); + validator.StagedRecords.Should().ContainSingle( + "the valid DNS domain must still be staged even though a co-tenant domain is unusable") + .Which.Should().Be((expectedHostname, MockCertificateData.DcvToken)); + + mock.Verify(c => c.GetDcvAsync(order, bad, It.IsAny(), It.IsAny()), + Times.Never, "a non-FQDN domain must never be sent to GetDcv"); + // A domain was skipped, so the order cannot issue: the post-DCV issuance wait must not run. + mock.Verify(c => c.GetCertificateAsync(order, It.IsAny()), Times.Never); + result.Status.Should().NotBe((int)EndEntityStatus.GENERATED); + } + + /// + /// The FQDN validation regex must not use ^...$ : in .NET's default (non-Multiline) + /// mode $ matches immediately before a single trailing '\n', not only at the true end of the + /// string. A domain value ending in '\n' would therefore pass as "valid" and reach several log + /// sinks unsanitized further down this same method — a CWE-117 log-injection route into the + /// DCV audit trail, reachable via any order visible through Synchronize/GetSingleRecord (not + /// just ones this plugin's own Enroll call placed, since TrackOrder's domainVerification keys + /// for an externally-created order are never trimmed by this plugin). The regex anchors + /// with \A/\z, which are absolute string-start/end regardless of trailing newlines. + /// + [Fact] + public async Task Dcv_DomainWithTrailingNewline_IsRejectedAsInvalid_AndValidDomainStillStaged() + { + const string order = MockCertificateData.DcvOrderId; + const string good = MockCertificateData.DcvDomain; + const string bad = "evil.example.com\n"; + + var mock = NewMock(); + + mock.Setup(c => c.EnrollCertificateAsync( + It.IsAny(), It.IsAny())) + .ReturnsAsync(new EnrollCertificateResponse { Id = order, Status = "pending_dcv" }); + + mock.SetupSequence(c => c.TrackOrderAsync(order, It.IsAny())) + .ReturnsAsync(DcvPendingTrackResponseMultiDomain(order, good, bad)) + .ReturnsAsync(MockCertificateData.DcvVerifiedTrackResponse(order, good)); + + // MockBehavior.Strict: an unexpected GetDcv call for `bad` fails the test on its own — + // if the regex fix regressed, this domain would reach GetDcv instead of being rejected + // by the FQDN check before the staging loop even starts. + mock.Setup(c => c.GetDcvAsync(order, good, Constants.Dcv.MethodDnsTxt, It.IsAny())) + .ReturnsAsync(MockCertificateData.DcvTokenResponse(MockCertificateData.DcvToken)); + mock.Setup(c => c.VerifyDcvAsync(order, good, Constants.Dcv.MethodDnsTxt, It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.GetCertificateAsync(order, It.IsAny())) + .ReturnsAsync(MockCertificateData.IssuedCertRecord(order)); + + var validator = new FakeDomainValidator(); + var plugin = BuildPlugin(mock.Object, new FakeDomainValidatorFactory(validator), + DcvConfig(dcvWaitForIssuanceSeconds: 10)); + + var result = await Enroll(plugin); + + string expectedHostname = string.Format(Constants.Dcv.DefaultTxtRecordTemplate, good); + validator.StagedRecords.Should().ContainSingle( + "the valid domain must still be staged even though a co-tenant domain carries a " + + "trailing newline") + .Which.Should().Be((expectedHostname, MockCertificateData.DcvToken)); + + mock.Verify(c => c.GetDcvAsync(order, bad, It.IsAny(), It.IsAny()), + Times.Never, "a domain with a trailing newline must never be sent to GetDcv"); + // A domain was skipped, so the order cannot issue: the post-DCV issuance wait must not run. + mock.Verify(c => c.GetCertificateAsync(order, It.IsAny()), Times.Never); + result.Status.Should().NotBe((int)EndEntityStatus.GENERATED); + } + + /// + /// The generic per-domain catch blocks around GetDcvAsync and StageValidation must not + /// catch OperationCanceledException along with genuine GetDcv/DNS-provider failures by + /// logging and skipping the domain as an ordinary per-domain failure. A cancellation (the + /// shared DcvTimeoutMinutes-bound token expiring mid-loop) is not that — it must propagate to + /// the outer catch instead, which is the only place that logs it correctly and is the + /// intended timeout-handling path documented at the top of this method's DCV timeout setup. + /// + [Fact] + public async Task Dcv_CancellationDuringGetDcv_PropagatesRatherThanBeingSkippedAsPerDomainFailure() + { + var mock = NewMock(); + mock.Setup(c => c.EnrollCertificateAsync(It.IsAny(), It.IsAny())) + .ReturnsAsync(new EnrollCertificateResponse { Id = MockCertificateData.DcvOrderId, Status = "pending_dcv" }); + + mock.Setup(c => c.TrackOrderAsync(MockCertificateData.DcvOrderId, It.IsAny())) + .ReturnsAsync(MockCertificateData.DcvPendingTrackResponse()); + + mock.Setup(c => c.GetDcvAsync(MockCertificateData.DcvOrderId, MockCertificateData.DcvDomain, Constants.Dcv.MethodDnsTxt, It.IsAny())) + .ThrowsAsync(new OperationCanceledException("DCV timeout budget exceeded")); + + var validator = new FakeDomainValidator(); + var plugin = BuildPlugin(mock.Object, new FakeDomainValidatorFactory(validator)); + + // The cancellation still reaches the outer catch inside PerformDcvIfNeededAsync (not the + // per-domain "GetDcv failed" skip) — pinned by the no-VerifyDcv assertion below — but + // since the order is already placed, EnrollNewAsync now absorbs it and returns the + // pending result carrying the order number instead of failing Enroll (issue 0077). + var result = await Enroll(plugin); + + result.CARequestID.Should().Be(MockCertificateData.DcvOrderId); + mock.Verify(c => c.VerifyDcvAsync(It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny()), Times.Never); + } + + /// + /// A pending domain that resolves no DNS provider (an IP-literal SAN passes the FQDN regex + /// but no zone can match it) must likewise be skipped rather than failing the whole order. + /// + [Fact] + public async Task Dcv_DomainWithNoResolvableValidator_IsSkipped_AndValidDomainStillStaged() + { + const string order = MockCertificateData.DcvOrderId; + const string good = MockCertificateData.DcvDomain; + const string ip = "192.0.2.10"; // what an iPAddress SAN comes back as + + var mock = NewMock(); + + mock.Setup(c => c.EnrollCertificateAsync( + It.IsAny(), It.IsAny())) + .ReturnsAsync(new EnrollCertificateResponse { Id = order, Status = "pending_dcv" }); + + mock.SetupSequence(c => c.TrackOrderAsync(order, It.IsAny())) + .ReturnsAsync(DcvPendingTrackResponseMultiDomain(order, good, ip)) + .ReturnsAsync(MockCertificateData.DcvVerifiedTrackResponse(order, good)); + + // The IP literal clears the FQDN filter, so GetDcv IS called for it; the dead end is + // that no validator resolves. Stub it so reaching that point is legitimate. + mock.Setup(c => c.GetDcvAsync(order, It.IsAny(), Constants.Dcv.MethodDnsTxt, It.IsAny())) + .ReturnsAsync(MockCertificateData.DcvTokenResponse(MockCertificateData.DcvToken)); + mock.Setup(c => c.VerifyDcvAsync(order, good, Constants.Dcv.MethodDnsTxt, It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.GetCertificateAsync(order, It.IsAny())) + .ReturnsAsync(MockCertificateData.IssuedCertRecord(order)); + + var validator = new FakeDomainValidator(); + var plugin = BuildPlugin( + mock.Object, + new FakeDomainValidatorFactory(validator, resolvableDomain: good), + DcvConfig(dcvWaitForIssuanceSeconds: 10)); + + var result = await Enroll(plugin); + + string expectedHostname = string.Format(Constants.Dcv.DefaultTxtRecordTemplate, good); + validator.StagedRecords.Should().ContainSingle( + "only the domain with a resolvable provider should be staged, and it must still be staged") + .Which.Should().Be((expectedHostname, MockCertificateData.DcvToken)); + // A domain was skipped, so the order cannot issue: the post-DCV issuance wait must not run. + mock.Verify(c => c.GetCertificateAsync(order, It.IsAny()), Times.Never); + result.Status.Should().NotBe((int)EndEntityStatus.GENERATED); + } + + /// + /// The compensating cleanup call after an early exit from staging (chiefly the + /// shared DcvTimeoutMinutes-bound token firing mid-loop, which this scenario + /// simulates via a domain whose GetDcv call raises OperationCanceledException) must not reuse + /// the same token the operation was cancelled by. A cooperative IDomainValidator that forwards + /// its token into its own HTTP calls (the reference CloudflareDomainValidator in this repo + /// does exactly that) would otherwise throw immediately on an already-cancelled token and + /// never even attempt the delete, silently leaving the TXT record published. + /// + /// CancellationToken.None would avoid that but removes the cleanup call's timeout bound + /// entirely, so the correct approach is a fresh token with its OWN short timeout: not + /// cancelled going in, but still bounded. + /// + [Fact] + public async Task Dcv_CleanupAfterCancellation_UsesAFreshBoundedToken_NotTheAmbientToken() + { + const string order = MockCertificateData.DcvOrderId; + const string good = "a.example.com"; + const string bad = "b.example.com"; + + var mock = NewMock(); + mock.Setup(c => c.EnrollCertificateAsync( + It.IsAny(), It.IsAny())) + .ReturnsAsync(new EnrollCertificateResponse { Id = order, Status = "pending_dcv" }); + + mock.Setup(c => c.TrackOrderAsync(order, It.IsAny())) + .ReturnsAsync(DcvPendingTrackResponseMultiDomain(order, good, bad)); + + mock.Setup(c => c.GetDcvAsync(order, good, Constants.Dcv.MethodDnsTxt, It.IsAny())) + .ReturnsAsync(MockCertificateData.DcvTokenResponse("token-a")); + // Domain 'good' is processed first (Dictionary enumeration order matches insertion order + // in practice for the small dictionaries this test builds); 'bad' then throws, driving the + // outer catch's cleanup of the already-staged 'good' entry. + mock.Setup(c => c.GetDcvAsync(order, bad, Constants.Dcv.MethodDnsTxt, It.IsAny())) + .ThrowsAsync(new OperationCanceledException("DCV timeout budget exceeded")); + + var validator = new FakeDomainValidator(); + var plugin = BuildPlugin(mock.Object, new FakeDomainValidatorFactory(validator)); + + // The mid-loop cancellation no longer fails Enroll (issue 0077: the order is already + // placed); the cleanup behavior asserted below is unchanged. + var result = await Enroll(plugin); + result.CARequestID.Should().Be(order); + + validator.StagedRecords.Should().ContainSingle( + "'good' must have staged before 'bad' threw, for this test to exercise cleanup at all"); + var cleanupToken = validator.CleanupTokens.Should().ContainSingle( + "the staged entry must go through the cancellation cleanup path exactly once").Subject; + + cleanupToken.IsCancellationRequested.Should().BeFalse( + "cleanup is a best-effort compensating action and must run with its own token, " + + "not the already-cancelled ambient one"); + cleanupToken.CanBeCanceled.Should().BeTrue( + "the cleanup call must still be bounded by its own timeout, not unbounded " + + "(CancellationToken.None) — a hanging DNS-provider call must not block forever"); + } + + /// + /// The routine, always-runs finally-block cleanup must run staged-domain cleanups + /// concurrently. Each cleanup call has its own independent + /// CleanupValidationTimeoutSeconds bound, but running them one after another would make + /// that bound per-call, not in aggregate — a UCC order with N staged domains could hold the + /// calling request open for up to N x the per-call ceiling if the DNS provider was merely + /// slow (not even hung) on every delete, which can exceed DcvTimeoutMinutes itself for a + /// realistic multi-SAN count. + /// + /// Proven directly via — the number + /// of CleanupValidation calls the validator observed in flight at once — rather than total + /// wall-clock time. An elapsed-time threshold is an unreliable proxy because the + /// surrounding DCV flow carries ~4s of fixed overhead unrelated to cleanup concurrency + /// (DcvConfig's 1s propagation delay plus WaitForDcvVerificationAsync's separate, + /// hardcoded 3s poll interval, Constants.Dcv.SyncPropagationDelaySeconds). The finally + /// block runs cleanup via Task.WhenAll; measuring peak concurrency proves that directly, + /// without being coupled to unrelated fixed delays elsewhere in the flow. + /// + [Fact] + public async Task Dcv_CleanupOfMultipleDomains_RunsConcurrently_NotSequentially() + { + const string order = MockCertificateData.DcvOrderId; + string[] domains = { "a.example.com", "b.example.com", "c.example.com" }; + var cleanupDelay = TimeSpan.FromMilliseconds(800); + + var mock = NewMock(); + mock.Setup(c => c.EnrollCertificateAsync( + It.IsAny(), It.IsAny())) + .ReturnsAsync(new EnrollCertificateResponse { Id = order, Status = "pending_dcv" }); + + var verifiedDetail = DcvDetail(Constants.Dcv.StatusValidated); + var verifiedRaw = new Dictionary(); + foreach (string d in domains) verifiedRaw[d] = verifiedDetail; + + mock.SetupSequence(c => c.TrackOrderAsync(order, It.IsAny())) + .ReturnsAsync(DcvPendingTrackResponseMultiDomain(order, domains)) + .ReturnsAsync(new TrackOrderResponse + { + OrderDetails = new TrackOrderResponseDetails + { + OrderStatusId = "1", + CertificateStatusId = "1", + DomainVerification = new TrackOrderDomainVerification + { + Status = Constants.Dcv.StatusValidated, + RawDomainEntries = verifiedRaw + } + } + }); + + foreach (string d in domains) + { + mock.Setup(c => c.GetDcvAsync(order, d, Constants.Dcv.MethodDnsTxt, It.IsAny())) + .ReturnsAsync(MockCertificateData.DcvTokenResponse($"token-{d}")); + mock.Setup(c => c.VerifyDcvAsync(order, d, Constants.Dcv.MethodDnsTxt, It.IsAny())) + .Returns(Task.CompletedTask); + } + mock.Setup(c => c.GetCertificateAsync(order, It.IsAny())) + .ReturnsAsync(MockCertificateData.IssuedCertRecord(order)); + + var validator = new FakeDomainValidator { CleanupDelay = cleanupDelay }; + var plugin = BuildPlugin(mock.Object, new FakeDomainValidatorFactory(validator), + DcvConfig(dcvWaitForIssuanceSeconds: 10)); + + await Enroll(plugin); + + validator.CleanedUpKeys.Should().HaveCount(3, "all three staged domains must be cleaned up"); + + // Direct proof of concurrency: all three CleanupValidation calls must have been in + // flight at the same instant. If cleanup ran sequentially, PeakConcurrentCleanups would + // be 1 regardless of how long the whole call took — this assertion doesn't depend on any + // wall-clock budget or on the fixed overhead elsewhere in the DCV flow. + validator.PeakConcurrentCleanups.Should().Be(3, + "cleanup for independent domains must run concurrently, not sequentially — " + + "all three CleanupValidation calls should have been in flight at once"); + } + + /// + /// A StageValidation failure on one domain of a multi-domain order must not + /// leave the TXT records already published for the earlier domains orphaned. Every + /// requested SAN is submitted, so multi-domain staging is the normal case and the + /// staging loop must be covered by the try/finally that owns cleanup. + /// + [Fact] + public async Task Dcv_StageFailureOnSecondDomain_DoesNotAbortTheGoodDomain() + { + const string order = MockCertificateData.DcvOrderId; + const string good = "a.example.com"; + const string bad = "b.example.com"; + + var mock = NewMock(); + mock.Setup(c => c.EnrollCertificateAsync( + It.IsAny(), It.IsAny())) + .ReturnsAsync(new EnrollCertificateResponse { Id = order, Status = "pending_dcv" }); + + // First TrackOrder call (inside PerformDcvIfNeededAsync) sees both domains pending; + // the second (WaitForDcvVerificationAsync's poll after staging/VerifyDcv) sees the one + // domain that actually got staged — 'good' — as verified. + mock.SetupSequence(c => c.TrackOrderAsync(order, It.IsAny())) + .ReturnsAsync(DcvPendingTrackResponseMultiDomain(order, good, bad)) + .ReturnsAsync(MockCertificateData.DcvVerifiedTrackResponse(order, good)); + + mock.Setup(c => c.GetDcvAsync(order, good, Constants.Dcv.MethodDnsTxt, It.IsAny())) + .ReturnsAsync(MockCertificateData.DcvTokenResponse("token-a")); + mock.Setup(c => c.GetDcvAsync(order, bad, Constants.Dcv.MethodDnsTxt, It.IsAny())) + .ReturnsAsync(MockCertificateData.DcvTokenResponse("token-b")); + + mock.Setup(c => c.VerifyDcvAsync(order, good, Constants.Dcv.MethodDnsTxt, It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.GetCertificateAsync(order, It.IsAny())) + .ReturnsAsync(MockCertificateData.IssuedCertRecord(order)); + + var validator = new FakeDomainValidator + { + ShouldFail = key => key.Contains(bad, StringComparison.OrdinalIgnoreCase) + }; + var plugin = BuildPlugin(mock.Object, new FakeDomainValidatorFactory(validator), + DcvConfig(dcvWaitForIssuanceSeconds: 10)); + + Func act = () => Enroll(plugin); + + // A StageValidation failure on one domain of a multi-domain order must not + // abort the whole order (which would fail the enrollment with an orphaned CERTInext + // order and orphan the 'good' domain's already-published TXT record). The bad domain is + // skipped (logged loudly) and the good domain proceeds through the normal DCV lifecycle. + await act.Should().NotThrowAsync(); + + string goodHostname = string.Format(Constants.Dcv.DefaultTxtRecordTemplate, good); + string badHostname = string.Format(Constants.Dcv.DefaultTxtRecordTemplate, bad); + + validator.StagedRecords.Should().ContainSingle( + "only the domain that did not fail to stage should ever have been staged") + .Which.key.Should().Be(goodHostname); + validator.CleanedUpKeys.Should().Contain(goodHostname, + "the good domain completes its normal verify-then-cleanup lifecycle"); + validator.CleanedUpKeys.Should().NotContain(badHostname, + "the bad domain was never staged, so there is nothing to clean up for it"); + } + + // --------------------------------------------------------------------------- + // Wildcard domains — TXT hostname must be derived from the BASE domain + // --------------------------------------------------------------------------- + // + // A wildcard DV order's TXT host must not be staged as + // "_emsign-validation.*.example.com" — a literal '*' DNS label is + // not queryable and leaves the order stuck pending. CERTInext's own GetDcv/VerifyDcv/ + // TrackOrder calls must still use the original "*."-prefixed domain string (that is what + // Track Order reports back per-domain); only the DNS-side hostname/zone resolution uses + // the base domain. + + /// Builds a verified-status multi-domain TrackOrder response, mirroring + /// but with every listed domain already + /// validated — used to drive WaitForDcvVerificationAsync's post-stage poll. + private static TrackOrderResponse DcvVerifiedTrackResponseMultiDomain( + string orderNumber, params string[] domains) + { + var detail = DcvDetail(Constants.Dcv.StatusValidated); + var raw = new Dictionary(); + foreach (string d in domains) + raw[d] = detail; + + return new TrackOrderResponse + { + OrderDetails = new TrackOrderResponseDetails + { + OrderStatusId = "2", + CertificateStatusId = "24", + DomainVerification = new TrackOrderDomainVerification + { + Status = Constants.Dcv.StatusValidated, + RawDomainEntries = raw + } + } + }; + } + + [Fact] + public async Task Dcv_WildcardDomain_StagesBaseDomainHostname_ButCallsCaWithWildcardDomain() + { + const string order = MockCertificateData.DcvOrderId; + const string baseName = MockCertificateData.DcvDomain; + string wildcard = "*." + baseName; + + var (mock, validator) = HappyPathMocks(orderNumber: order, domain: wildcard); + + var plugin = BuildPlugin(mock.Object, new FakeDomainValidatorFactory(validator), + DcvConfig(dcvWaitForIssuanceSeconds: 10)); + + var result = await Enroll(plugin); + + result.Status.Should().Be((int)EndEntityStatus.GENERATED); + + // The TXT hostname must be built from the base domain, not the literal "*.example.com" + // — a "*" DNS label is not queryable. + string expectedHostname = string.Format(Constants.Dcv.DefaultTxtRecordTemplate, baseName); + validator.StagedRecords.Should().ContainSingle() + .Which.key.Should().Be(expectedHostname); + validator.StagedRecords.Should().OnlyContain(r => !r.key.Contains('*'), + "a literal '*' DNS label can never be queried by the CA"); + + validator.CleanedUpKeys.Should().ContainSingle().Which.Should().Be(expectedHostname); + + // CERTInext's own API must still see the original wildcard domain string — that is + // what Track Order reports back per-domain. + mock.Verify(c => c.GetDcvAsync(order, wildcard, Constants.Dcv.MethodDnsTxt, It.IsAny()), + Times.Once); + mock.Verify(c => c.VerifyDcvAsync(order, wildcard, Constants.Dcv.MethodDnsTxt, It.IsAny()), + Times.Once); + } + + [Fact] + public async Task Dcv_NonWildcardDomain_HostnameDerivationUnchanged() + { + // Baseline: an ordinary (non-wildcard) domain must stage a TXT + // hostname built from the domain directly — StripWildcardPrefix is a no-op + // when there is no leading "*.". + var (mock, validator) = HappyPathMocks(); + var plugin = BuildPlugin(mock.Object, new FakeDomainValidatorFactory(validator), + DcvConfig(dcvWaitForIssuanceSeconds: 10)); + + var result = await Enroll(plugin); + + result.Status.Should().Be((int)EndEntityStatus.GENERATED); + string expectedHostname = string.Format(Constants.Dcv.DefaultTxtRecordTemplate, MockCertificateData.DcvDomain); + validator.StagedRecords.Should().ContainSingle() + .Which.Should().Be((expectedHostname, MockCertificateData.DcvToken)); + } + + [Fact] + public async Task Dcv_MultiDomain_ApexAndWildcardShareHostname_StagesOnceAndCleansUpOnce_ButVerifiesBothWithCa() + { + const string order = MockCertificateData.DcvOrderId; + const string apex = MockCertificateData.DcvDomain; + string wildcard = "*." + apex; + + var mock = NewMock(); + mock.Setup(c => c.EnrollCertificateAsync( + It.IsAny(), It.IsAny())) + .ReturnsAsync(new EnrollCertificateResponse { Id = order, Status = "pending_dcv" }); + + mock.SetupSequence(c => c.TrackOrderAsync(order, It.IsAny())) + .ReturnsAsync(DcvPendingTrackResponseMultiDomain(order, apex, wildcard)) + .ReturnsAsync(DcvVerifiedTrackResponseMultiDomain(order, apex, wildcard)); + + mock.Setup(c => c.GetDcvAsync(order, apex, Constants.Dcv.MethodDnsTxt, It.IsAny())) + .ReturnsAsync(MockCertificateData.DcvTokenResponse("token-shared")); + mock.Setup(c => c.GetDcvAsync(order, wildcard, Constants.Dcv.MethodDnsTxt, It.IsAny())) + .ReturnsAsync(MockCertificateData.DcvTokenResponse("token-shared")); + + mock.Setup(c => c.VerifyDcvAsync(order, apex, Constants.Dcv.MethodDnsTxt, It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.VerifyDcvAsync(order, wildcard, Constants.Dcv.MethodDnsTxt, It.IsAny())) + .Returns(Task.CompletedTask); + + mock.Setup(c => c.GetCertificateAsync(order, It.IsAny())) + .ReturnsAsync(MockCertificateData.IssuedCertRecord(order)); + + var validator = new FakeDomainValidator(); + var plugin = BuildPlugin(mock.Object, new FakeDomainValidatorFactory(validator), + DcvConfig(dcvWaitForIssuanceSeconds: 10)); + + var result = await Enroll(plugin); + + result.Status.Should().Be((int)EndEntityStatus.GENERATED); + + // Both domains collapse to the same base-domain TXT hostname — exactly ONE record + // must be staged (and cleaned up), not two, even though the order lists both the + // apex and its wildcard as separate domain entries. + string expectedHostname = string.Format(Constants.Dcv.DefaultTxtRecordTemplate, apex); + validator.StagedRecords.Should().ContainSingle( + "the apex and wildcard domains share one base-domain TXT hostname") + .Which.key.Should().Be(expectedHostname); + validator.CleanedUpKeys.Should().ContainSingle( + "the shared hostname must be cleaned up exactly once, not once per domain that used it") + .Which.Should().Be(expectedHostname); + + // CERTInext tracks DCV per domain entry, so both the apex and the wildcard still need + // their own CA-side GetDcv/VerifyDcv call even though they share one TXT record. + mock.Verify(c => c.GetDcvAsync(order, apex, Constants.Dcv.MethodDnsTxt, It.IsAny()), Times.Once); + mock.Verify(c => c.GetDcvAsync(order, wildcard, Constants.Dcv.MethodDnsTxt, It.IsAny()), Times.Once); + mock.Verify(c => c.VerifyDcvAsync(order, apex, Constants.Dcv.MethodDnsTxt, It.IsAny()), Times.Once); + mock.Verify(c => c.VerifyDcvAsync(order, wildcard, Constants.Dcv.MethodDnsTxt, It.IsAny()), Times.Once); + } + + [Fact] + public async Task Dcv_MultiDomain_ApexAndWildcardShareHostnameButDifferentTokens_StagesBothAndCleansUpBoth() + { + const string order = MockCertificateData.DcvOrderId; + const string apex = MockCertificateData.DcvDomain; + string wildcard = "*." + apex; + + var mock = NewMock(); + mock.Setup(c => c.EnrollCertificateAsync( + It.IsAny(), It.IsAny())) + .ReturnsAsync(new EnrollCertificateResponse { Id = order, Status = "pending_dcv" }); + + mock.SetupSequence(c => c.TrackOrderAsync(order, It.IsAny())) + .ReturnsAsync(DcvPendingTrackResponseMultiDomain(order, apex, wildcard)) + .ReturnsAsync(DcvVerifiedTrackResponseMultiDomain(order, apex, wildcard)); + + mock.Setup(c => c.GetDcvAsync(order, apex, Constants.Dcv.MethodDnsTxt, It.IsAny())) + .ReturnsAsync(MockCertificateData.DcvTokenResponse("token-apex")); + mock.Setup(c => c.GetDcvAsync(order, wildcard, Constants.Dcv.MethodDnsTxt, It.IsAny())) + .ReturnsAsync(MockCertificateData.DcvTokenResponse("token-wildcard")); + + mock.Setup(c => c.VerifyDcvAsync(order, apex, Constants.Dcv.MethodDnsTxt, It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.VerifyDcvAsync(order, wildcard, Constants.Dcv.MethodDnsTxt, It.IsAny())) + .Returns(Task.CompletedTask); + + mock.Setup(c => c.GetCertificateAsync(order, It.IsAny())) + .ReturnsAsync(MockCertificateData.IssuedCertRecord(order)); + + var validator = new FakeDomainValidator(); + var plugin = BuildPlugin(mock.Object, new FakeDomainValidatorFactory(validator), + DcvConfig(dcvWaitForIssuanceSeconds: 10)); + + var result = await Enroll(plugin); + + result.Status.Should().Be((int)EndEntityStatus.GENERATED); + + // Same base-domain hostname but two different CA tokens: a single record cannot satisfy + // both, so BOTH values must be staged at that hostname and both cleaned up. + string expectedHostname = string.Format(Constants.Dcv.DefaultTxtRecordTemplate, apex); + validator.StagedRecords.Should().HaveCount(2); + validator.StagedRecords.Select(r => r.key).Should().OnlyContain(k => k == expectedHostname); + validator.StagedRecords.Select(r => r.value).Should().BeEquivalentTo(new[] { "token-apex", "token-wildcard" }); + validator.CleanedUpKeys.Should().HaveCount(2); + validator.CleanedUpKeys.Should().OnlyContain(k => k == expectedHostname); + + mock.Verify(c => c.VerifyDcvAsync(order, apex, Constants.Dcv.MethodDnsTxt, It.IsAny()), Times.Once); + mock.Verify(c => c.VerifyDcvAsync(order, wildcard, Constants.Dcv.MethodDnsTxt, It.IsAny()), Times.Once); + } + + // --------------------------------------------------------------------------- + // Partial skip vs. all-staged: the post-DCV issuance wait + // --------------------------------------------------------------------------- + + /// + /// Regression: when some pending domains are skipped (here an IP-literal SAN with no DNS + /// provider) the order cannot issue, so Enroll must not hold the worker in the post-DCV + /// issuance wait. The staged domain must still be verified and its TXT record cleaned up; + /// sync DCV completes the order later. + /// + [Fact] + public async Task Dcv_PartialSkip_VerifiesAndCleansUpStagedDomains_ButSkipsIssuanceWait() + { + const string order = MockCertificateData.DcvOrderId; + const string good = MockCertificateData.DcvDomain; + const string ip = "192.0.2.10"; + + var mock = NewMock(); + mock.Setup(c => c.EnrollCertificateAsync( + It.IsAny(), It.IsAny())) + .ReturnsAsync(new EnrollCertificateResponse { Id = order, Status = "pending_dcv" }); + mock.SetupSequence(c => c.TrackOrderAsync(order, It.IsAny())) + .ReturnsAsync(DcvPendingTrackResponseMultiDomain(order, good, ip)) + .ReturnsAsync(MockCertificateData.DcvVerifiedTrackResponse(order, good)); + mock.Setup(c => c.GetDcvAsync(order, It.IsAny(), Constants.Dcv.MethodDnsTxt, It.IsAny())) + .ReturnsAsync(MockCertificateData.DcvTokenResponse(MockCertificateData.DcvToken)); + mock.Setup(c => c.VerifyDcvAsync(order, good, Constants.Dcv.MethodDnsTxt, It.IsAny())) + .Returns(Task.CompletedTask); + // Configured so that a (wrong) issuance wait would succeed and be observable. + mock.Setup(c => c.GetCertificateAsync(order, It.IsAny())) + .ReturnsAsync(MockCertificateData.IssuedCertRecord(order)); + + var validator = new FakeDomainValidator(); + var plugin = BuildPlugin( + mock.Object, + new FakeDomainValidatorFactory(validator, resolvableDomain: good), + DcvConfig(dcvWaitForIssuanceSeconds: 10)); + + var result = await Enroll(plugin); + + string goodHostname = string.Format(Constants.Dcv.DefaultTxtRecordTemplate, good); + validator.StagedRecords.Should().ContainSingle().Which.key.Should().Be(goodHostname); + mock.Verify(c => c.VerifyDcvAsync(order, good, Constants.Dcv.MethodDnsTxt, It.IsAny()), Times.Once); + validator.CleanedUpKeys.Should().ContainSingle().Which.Should().Be(goodHostname); + + mock.Verify(c => c.GetCertificateAsync(order, It.IsAny()), Times.Never, + "the order cannot issue while a domain is skipped, so the post-DCV issuance wait must not run"); + result.CARequestID.Should().Be(order); + result.Status.Should().NotBe((int)EndEntityStatus.GENERATED); + } + + /// + /// Counterpart: every pending domain staged and verified -> the issuance wait still runs and + /// the issued certificate is returned from Enroll. + /// + [Fact] + public async Task Dcv_AllDomainsStaged_StillRunsIssuanceWait() + { + const string order = MockCertificateData.DcvOrderId; + const string a = "a.example.com"; + const string b = "b.example.com"; + + var mock = NewMock(); + mock.Setup(c => c.EnrollCertificateAsync( + It.IsAny(), It.IsAny())) + .ReturnsAsync(new EnrollCertificateResponse { Id = order, Status = "pending_dcv" }); + + var verifiedDetail = DcvDetail(Constants.Dcv.StatusValidated); + var verifiedRaw = new Dictionary { [a] = verifiedDetail, [b] = verifiedDetail }; + mock.SetupSequence(c => c.TrackOrderAsync(order, It.IsAny())) + .ReturnsAsync(DcvPendingTrackResponseMultiDomain(order, a, b)) + .ReturnsAsync(new TrackOrderResponse + { + OrderDetails = new TrackOrderResponseDetails + { + OrderStatusId = "1", + CertificateStatusId = "1", + DomainVerification = new TrackOrderDomainVerification + { + Status = Constants.Dcv.StatusValidated, + RawDomainEntries = verifiedRaw + } + } + }); + foreach (string d in new[] { a, b }) + { + mock.Setup(c => c.GetDcvAsync(order, d, Constants.Dcv.MethodDnsTxt, It.IsAny())) + .ReturnsAsync(MockCertificateData.DcvTokenResponse($"token-{d}")); + mock.Setup(c => c.VerifyDcvAsync(order, d, Constants.Dcv.MethodDnsTxt, It.IsAny())) + .Returns(Task.CompletedTask); + } + mock.Setup(c => c.GetCertificateAsync(order, It.IsAny())) + .ReturnsAsync(MockCertificateData.IssuedCertRecord(order)); + + var validator = new FakeDomainValidator(); + var plugin = BuildPlugin(mock.Object, new FakeDomainValidatorFactory(validator), + DcvConfig(dcvWaitForIssuanceSeconds: 10)); + + var result = await Enroll(plugin); + + validator.StagedRecords.Should().HaveCount(2); + validator.CleanedUpKeys.Should().HaveCount(2); + mock.Verify(c => c.GetCertificateAsync(order, It.IsAny()), Times.Once, + "every domain was staged, so the post-DCV issuance wait must still run"); + result.Status.Should().Be((int)EndEntityStatus.GENERATED); + } } } diff --git a/CERTInext.Tests/CERTInextCAPluginRevokeV2AuditLoggingTests.cs b/CERTInext.Tests/CERTInextCAPluginRevokeV2AuditLoggingTests.cs new file mode 100644 index 0000000..c4711d9 --- /dev/null +++ b/CERTInext.Tests/CERTInextCAPluginRevokeV2AuditLoggingTests.cs @@ -0,0 +1,251 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.Logging; +using Microsoft.Extensions.Logging; +using Moq; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// V2 revoke denials must leave an audit record (CARequestID, product + /// family, HTTP status, EMS code) even though the denial is surfaced via an exception rather + /// than a normal return. Pins the plugin-level ( → + /// internal RevokeV2Async) log lines for: 404 (not found/not revokable), 422 ("not in a + /// revocable state" pre-flight and the general 422 denial), and both outcomes of the + /// unspecified-reason → cessation-of-operation retry. + /// + /// Uses the same -swap capture seam as + /// CERTInextCAPluginAuditLoggingTests (the plugin's _logger is a per-instance + /// field resolved at construction time, unlike CERTInextClient.Logger, which is + /// static readonly and not swappable after first use — see that class's remarks for + /// why client-level V2 log content isn't independently assertable in this harness). + /// + [Collection(LoggingStateCollection.Name)] + public class CERTInextCAPluginRevokeV2AuditLoggingTests + { + private sealed class CapturingLoggerProvider : ILoggerProvider + { + public ConcurrentQueue Messages { get; } = new(); + public ILogger CreateLogger(string categoryName) => new CapturingLogger(Messages); + public void Dispose() { } + + private sealed class CapturingLogger : ILogger + { + private readonly ConcurrentQueue _messages; + public CapturingLogger(ConcurrentQueue messages) => _messages = messages; + public IDisposable BeginScope(TState state) => null; + public bool IsEnabled(LogLevel logLevel) => true; + public void Log(LogLevel logLevel, EventId eventId, TState state, Exception exception, + Func formatter) + => _messages.Enqueue(formatter(state, exception)); + } + } + + private static CERTInextConfig V2Config() => new CERTInextConfig + { + UseV2Api = true, + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + AccountNumber = "12345", + AuthMode = "AccessKey", + ApiKey = "v1-key", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + PickupRetries = 0 + }; + + /// + /// Runs plugin.Revoke(orderId, hexSerial, reason) against a capturing logger + /// factory and returns every rendered log line plus whatever the call threw (the revoke + /// is always expected to fail or succeed deterministically per test). + /// + private static async Task<(ConcurrentQueue Messages, Exception Thrown)> CaptureRevokeLogMessagesAsync( + Mock mock, string orderId, uint reason) + { + var provider = new CapturingLoggerProvider(); + var factory = LoggerFactory.Create(b => b.AddProvider(provider).SetMinimumLevel(LogLevel.Trace)); + Exception thrown = null; + try + { + LogHandler.Factory = factory; + var plugin = new CERTInextCAPlugin(mock.Object, V2Config()); + try + { + await plugin.Revoke(orderId, "AABBCC", reason); + } + catch (Exception ex) + { + thrown = ex; + } + } + finally + { + LogHandler.Factory = Microsoft.Extensions.Logging.Abstractions.NullLoggerFactory.Instance; + factory.Dispose(); + } + + return (provider.Messages, thrown); + } + + private static string FindLine(ConcurrentQueue messages, string marker, params string[] mustContain) + { + foreach (var m in messages) + { + if (!m.Contains(marker)) continue; + bool allMatch = true; + foreach (var s in mustContain) + { + if (!m.Contains(s)) { allMatch = false; break; } + } + if (allMatch) return m; + } + return null; + } + + // --------------------------------------------------------------------------- + // 404 — "not found or not in a revokable state" + // --------------------------------------------------------------------------- + + [Fact] + public async Task RevokeV2_404Denial_LogsWarningWithAuditFields() + { + string orderId = "audit-404-" + Guid.NewGuid().ToString("N"); + var mock = new Mock(MockBehavior.Loose); + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync(orderId, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse { OrderId = orderId, Status = "issued" })); + mock.Setup(c => c.RevokeOrderV2Async( + Constants.ApiV2.FamilySsl, orderId, It.IsAny(), It.IsAny())) + .ThrowsAsync(new System.Collections.Generic.KeyNotFoundException( + $"V2 order '{orderId}' in family '{Constants.ApiV2.FamilySsl}' not found or not in a revokable state. EMS-913")); + + var (messages, thrown) = await CaptureRevokeLogMessagesAsync(mock, orderId, 4u); + + thrown.Should().BeOfType(); + string line = FindLine(messages, orderId, "V2 revocation denied", "HttpStatus=404"); + line.Should().NotBeNull("a 404 revoke denial must be audited with an explicit HTTP status"); + line.Should().Contain("EmsCode=EMS-913"); + line.Should().Contain(Constants.ApiV2.FamilySsl); + } + + // --------------------------------------------------------------------------- + // Not-GENERATED pre-flight rejection + // --------------------------------------------------------------------------- + + [Fact] + public async Task RevokeV2_NotGenerated_LogsErrorWithCurrentStatus() + { + string orderId = "audit-notgen-" + Guid.NewGuid().ToString("N"); + var mock = new Mock(MockBehavior.Loose); + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync(orderId, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse { OrderId = orderId, Status = "pending-dcv" })); + + var (messages, thrown) = await CaptureRevokeLogMessagesAsync(mock, orderId, 4u); + + thrown.Should().NotBeNull(); + thrown.Message.Should().Contain("cannot be revoked"); + string line = FindLine(messages, orderId, "not in a revocable state", "Status=pending-dcv"); + line.Should().NotBeNull("a not-GENERATED revoke rejection must be audited with the current CA status"); + line.Should().Contain(Constants.ApiV2.FamilySsl); + + // RevokeOrderV2Async must never have been called for a certificate that was never issued. + mock.Verify(c => c.RevokeOrderV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny()), + Times.Never); + } + + // --------------------------------------------------------------------------- + // General 422 denial (not the retry-eligible "Invalid Revoke Reason ID" case) + // --------------------------------------------------------------------------- + + [Fact] + public async Task RevokeV2_Generic422Denial_LogsWarningWithAuditFields() + { + string orderId = "audit-422-" + Guid.NewGuid().ToString("N"); + var mock = new Mock(MockBehavior.Loose); + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync(orderId, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse { OrderId = orderId, Status = "issued" })); + mock.Setup(c => c.RevokeOrderV2Async( + Constants.ApiV2.FamilySsl, orderId, It.IsAny(), It.IsAny())) + .ThrowsAsync(new InvalidOperationException("V2 revoke rejected. EMS-969 Revoke reason ID missing")); + + var (messages, thrown) = await CaptureRevokeLogMessagesAsync(mock, orderId, 4u); + + thrown.Should().BeOfType(); + thrown.Message.Should().Contain("EMS-969"); + string line = FindLine(messages, orderId, "V2 revocation denied", "HttpStatus=422"); + line.Should().NotBeNull("a non-retry-eligible 422 revoke denial must be audited"); + line.Should().Contain("EmsCode=EMS-969"); + } + + // --------------------------------------------------------------------------- + // Unspecified-reason retry: success and failure outcomes both log. + // --------------------------------------------------------------------------- + + [Fact] + public async Task RevokeV2_UnspecifiedReasonRetry_Success_LogsRetriedTrue() + { + string orderId = "audit-retry-ok-" + Guid.NewGuid().ToString("N"); + var mock = new Mock(MockBehavior.Loose); + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync(orderId, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse { OrderId = orderId, Status = "issued" })); + mock.Setup(c => c.RevokeOrderV2Async( + Constants.ApiV2.FamilySsl, orderId, It.IsAny(), It.IsAny())) + .Returns((string family, string id, V2RevokeRequest req, CancellationToken ct) => + { + if (req.Reason == Constants.RevocationReasonV2.Unspecified) + throw new InvalidOperationException("V2 revoke rejected. Unprocessable Entity: Invalid Revoke Reason ID"); + return Task.CompletedTask; + }); + + var (messages, thrown) = await CaptureRevokeLogMessagesAsync(mock, orderId, 0u); + + thrown.Should().BeNull(); + string retryWarn = FindLine(messages, orderId, "retrying once with 'cessation-of-operation'", "HttpStatus=422"); + retryWarn.Should().NotBeNull("the first rejection must be audited before the retry is attempted"); + string completeLine = FindLine(messages, orderId, "V2 revocation complete", "RetriedFromReason=unspecified"); + completeLine.Should().NotBeNull("a successful retry must be reflected in the completion audit line"); + } + + [Fact] + public async Task RevokeV2_UnspecifiedReasonRetry_Failure_LogsErrorAndRethrows() + { + string orderId = "audit-retry-fail-" + Guid.NewGuid().ToString("N"); + var mock = new Mock(MockBehavior.Loose); + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync(orderId, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse { OrderId = orderId, Status = "issued" })); + mock.Setup(c => c.RevokeOrderV2Async( + Constants.ApiV2.FamilySsl, orderId, It.IsAny(), It.IsAny())) + .Returns((string family, string id, V2RevokeRequest req, CancellationToken ct) => + { + if (req.Reason == Constants.RevocationReasonV2.Unspecified) + throw new InvalidOperationException("V2 revoke rejected. Unprocessable Entity: Invalid Revoke Reason ID"); + throw new InvalidOperationException("V2 revoke rejected. EMS-931 Order not in issued state"); + }); + + var (messages, thrown) = await CaptureRevokeLogMessagesAsync(mock, orderId, 0u); + + thrown.Should().BeOfType(); + thrown.Message.Should().Contain("EMS-931"); + string retryFailLine = FindLine(messages, orderId, "V2 revocation retry (cessation-of-operation) failed"); + retryFailLine.Should().NotBeNull("a failed retry attempt must leave its own audit record, not just surface via the exception"); + + // The retry failure must not be misreported as a successful completion. + FindLine(messages, orderId, "V2 revocation complete").Should().BeNull(); + } + } +} diff --git a/CERTInext.Tests/CERTInextCAPluginSyncRecentOrderTests.cs b/CERTInext.Tests/CERTInextCAPluginSyncRecentOrderTests.cs new file mode 100644 index 0000000..8a682ac --- /dev/null +++ b/CERTInext.Tests/CERTInextCAPluginSyncRecentOrderTests.cs @@ -0,0 +1,480 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Linq; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.Logging; +using Keyfactor.PKI.Enums.EJBCA; +using Microsoft.Extensions.Logging; +using Moq; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Issue 0090 (V1): Synchronize, full and incremental, must not emit a pending or issued order + /// created within the grace window (default 120 s plus a clock margin), because the gateway would + /// insert a row with that CARequestID and the in-flight enrollment's own save would then fail on + /// the unique (CA, CARequestID) index. Revoked and failed orders, unparseable dates and a + /// disabled window are unaffected. + /// + /// Log capture swaps , so the class is in the non-parallel logging + /// collection; assertions only consider messages carrying this test's unique order-id marker, + /// except the summary line. + /// + [Collection(LoggingStateCollection.Name)] + public class CERTInextCAPluginSyncRecentOrderTests + { + private static readonly int Margin = Constants.Api.SyncRecentOrderClockMarginSeconds; + private static readonly int DefaultGrace = Constants.Api.DefaultSyncRecentOrderGraceSeconds; + private static readonly DateTime Now = new DateTime(2026, 10, 15, 12, 0, 0, DateTimeKind.Utc); + + private const int Pending = (int)EndEntityStatus.EXTERNALVALIDATION; + private const int Issued = (int)EndEntityStatus.GENERATED; + + private sealed class CapturingLoggerProvider : ILoggerProvider + { + public ConcurrentQueue Messages { get; } = new(); + public ILogger CreateLogger(string categoryName) => new CapturingLogger(Messages); + public void Dispose() { } + + private sealed class CapturingLogger : ILogger + { + private readonly ConcurrentQueue _messages; + public CapturingLogger(ConcurrentQueue messages) => _messages = messages; + public IDisposable BeginScope(TState state) => null; + public bool IsEnabled(LogLevel logLevel) => true; + public void Log(LogLevel logLevel, EventId eventId, TState state, Exception exception, + Func formatter) + => _messages.Enqueue(logLevel + "|" + formatter(state, exception)); + } + } + + private static string NewId() => "ord_0090_" + Guid.NewGuid().ToString("N"); + + /// A listing row as the V1 order report produces it (no body). + private static LegacyGetCertificateResponse Row(string id, string status, double? ageSeconds) => + new LegacyGetCertificateResponse + { + Id = id, + Status = status, + Certificate = null, + ProfileId = MockCertificateData.ProfileIdTls, + Subject = "example.com", + OrderDate = ageSeconds.HasValue ? DateTime.UtcNow.AddSeconds(-ageSeconds.Value) : (DateTime?)null + }; + + private static async IAsyncEnumerable Rows( + IEnumerable rows) + { + foreach (var r in rows) + { + await Task.Yield(); + yield return r; + } + } + + /// Strict client mock: any call other than the listing (and setups added by the test) fails. + private static Mock ClientReturning( + params LegacyGetCertificateResponse[] rows) + { + var mock = new Mock(MockBehavior.Strict); + mock.Setup(c => c.ListCertificatesAsync( + It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(() => Rows(rows)); + return mock; + } + + private static void SetupDownload(Mock mock, string id) => + mock.Setup(c => c.GetCertificateAsync(id, It.IsAny())) + .ReturnsAsync(MockCertificateData.IssuedCertRecord(id)); + + /// Runs a sync with the logger factory swapped; returns emitted records and captured log lines. + private static async Task<(AnyCAPluginCertificate[] Records, List Log)> SyncAsync( + ICERTInextClient client, int? graceSeconds, bool fullSync, string marker, + DateTime? lastSync = null) + { + var provider = new CapturingLoggerProvider(); + var factory = LoggerFactory.Create(b => b.AddProvider(provider).SetMinimumLevel(LogLevel.Trace)); + var buffer = new BlockingCollection(100); + try + { + LogHandler.Factory = factory; + var config = new CERTInextConfig { PickupRetries = 0 }; + if (graceSeconds.HasValue) + config.SyncRecentOrderGraceSeconds = graceSeconds.Value; + // Constructed after the swap so the plugin's per-instance logger resolves through it. + var plugin = new CERTInextCAPlugin(client, config); + await plugin.Synchronize( + buffer, lastSync ?? DateTime.UtcNow.AddHours(-1), fullSync, CancellationToken.None); + } + finally + { + LogHandler.Factory = Microsoft.Extensions.Logging.Abstractions.NullLoggerFactory.Instance; + factory.Dispose(); + } + + var log = provider.Messages + .Where(m => m != null && (m.Contains(marker) || m.Contains("CERTInext synchronization complete"))) + .ToList(); + return (buffer.ToArray(), log); + } + + // --------------------------------------------------------------------------- + // Through Synchronize + // --------------------------------------------------------------------------- + + [Theory] + [InlineData(false)] + [InlineData(true)] + public async Task PendingAndRecent_IsNotEmitted_LogsIdAgeAndCountsInSummary(bool fullSync) + { + string id = NewId(); + var mock = ClientReturning(Row(id, "pending_approval", ageSeconds: 30)); + + var (records, log) = await SyncAsync(mock.Object, null, fullSync, marker: id); + + records.Should().BeEmpty("a pending order created 30 s ago may still be saving in its enrollment"); + log.Should().Contain(m => m.StartsWith("Information|") && m.Contains($"CARequestID={id}") + && m.Contains("AgeSeconds=") && m.Contains($"GraceSeconds={DefaultGrace}"), + "each hold-back is logged at Info with the order id and its age"); + log.Should().Contain(m => m.Contains("CERTInext synchronization complete") && m.Contains("RecentOrderDeferred=1"), + "the sync summary counts held-back orders"); + } + + [Theory] + [InlineData(false)] + [InlineData(true)] + public async Task IssuedAndRecent_IsNotEmitted_AndNothingIsDownloaded(bool fullSync) + { + string id = NewId(); + // Strict mock with no GetCertificateAsync setup: any download/track call would throw + // inside the per-order catch and be counted as an error, so verify it never happens. + var mock = ClientReturning(Row(id, "issued", ageSeconds: 10)); + + var (records, log) = await SyncAsync(mock.Object, null, fullSync, marker: id); + + records.Should().BeEmpty("an issued order created 10 s ago may still be saving in its enrollment"); + mock.Verify(c => c.GetCertificateAsync(It.IsAny(), It.IsAny()), Times.Never, + "a held-back issued order must not trigger a certificate download or track call"); + log.Should().Contain(m => m.StartsWith("Information|") && m.Contains($"CARequestID={id}")); + log.Should().Contain(m => m.Contains("CERTInext synchronization complete") + && m.Contains("RecentOrderDeferred=1") && m.Contains("Errors=0")); + } + + [Theory] + [InlineData(false)] + [InlineData(true)] + public async Task PendingAndOlderThanWindow_IsEmitted(bool fullSync) + { + string id = NewId(); + var mock = ClientReturning(Row(id, "pending_approval", ageSeconds: DefaultGrace + Margin + 30)); + + var (records, log) = await SyncAsync(mock.Object, null, fullSync, marker: id); + + records.Should().ContainSingle(); + records[0].CARequestID.Should().Be(id); + records[0].Status.Should().Be(Pending); + log.Should().NotContain(m => m.Contains($"CARequestID={id}") && m.Contains("holding back")); + } + + [Theory] + [InlineData(false)] + [InlineData(true)] + public async Task IssuedAndOlderThanWindow_IsEmitted_WithBodyFetchedAsBefore(bool fullSync) + { + string id = NewId(); + var mock = ClientReturning(Row(id, "issued", ageSeconds: DefaultGrace + Margin + 30)); + SetupDownload(mock, id); + + var (records, _) = await SyncAsync(mock.Object, null, fullSync, marker: id); + + records.Should().ContainSingle(); + records[0].Status.Should().Be(Issued); + records[0].Certificate.Should().Be(MockCertificateData.FakePemCertificate); + mock.Verify(c => c.GetCertificateAsync(id, It.IsAny()), Times.Once); + } + + [Fact] + public async Task RevokedAndRecent_IsAlwaysEmitted() + { + string id = NewId(); + var mock = ClientReturning(Row(id, "revoked", ageSeconds: 5)); + mock.Setup(c => c.GetCertificateAsync(id, It.IsAny())) + .ReturnsAsync(MockCertificateData.RevokedCertRecord(id)); + + var (records, log) = await SyncAsync(mock.Object, null, fullSync: false, marker: id); + + records.Should().ContainSingle(); + records[0].Status.Should().Be((int)EndEntityStatus.REVOKED); + log.Should().NotContain(m => m.Contains($"CARequestID={id}") && m.Contains("holding back")); + } + + [Fact] + public async Task FailedAndRecent_IsNotHeldBack_AndKeepsItsExistingSkip() + { + string id = NewId(); + var mock = ClientReturning(Row(id, "failed", ageSeconds: 5)); + + var (records, log) = await SyncAsync(mock.Object, null, fullSync: false, marker: id); + + records.Should().BeEmpty("a failed order has never been emitted (existing behavior)"); + log.Should().Contain(m => m.Contains("CERTInext synchronization complete") + && m.Contains("Skipped=1") && m.Contains("RecentOrderDeferred=0"), + "a failed order is skipped as before, not counted as held back"); + } + + [Theory] + [InlineData(false)] + [InlineData(true)] + public async Task MissingOrderDate_IsEmitted_FailOpen(bool fullSync) + { + string id = NewId(); + var mock = ClientReturning(Row(id, "pending_approval", ageSeconds: null)); + + var (records, _) = await SyncAsync(mock.Object, null, fullSync, marker: id); + + records.Should().ContainSingle("an unparseable or missing date must not hold an order back"); + records[0].CARequestID.Should().Be(id); + } + + [Fact] + public async Task FutureOrderDate_BeyondMargin_IsEmitted_FailOpen() + { + string id = NewId(); + var mock = ClientReturning(Row(id, "pending_approval", ageSeconds: -(Margin + 60))); + + var (records, _) = await SyncAsync(mock.Object, null, fullSync: false, marker: id); + + records.Should().ContainSingle("an order dated well in the future means the CA clock is untrustworthy"); + } + + [Fact] + public async Task ZeroGrace_DisablesTheHold() + { + string idPending = NewId(); + string idIssued = NewId(); + var mock = ClientReturning( + Row(idPending, "pending_approval", ageSeconds: 1), + Row(idIssued, "issued", ageSeconds: 1)); + SetupDownload(mock, idIssued); + + var (records, log) = await SyncAsync(mock.Object, graceSeconds: 0, fullSync: false, marker: idPending); + + records.Select(r => r.CARequestID).Should().BeEquivalentTo(new[] { idPending, idIssued }); + log.Should().Contain(m => m.Contains("CERTInext synchronization complete") && m.Contains("RecentOrderDeferred=0")); + } + + [Fact] + public async Task NegativeGrace_UsesTheDefault() + { + string id = NewId(); + var mock = ClientReturning(Row(id, "pending_approval", ageSeconds: 30)); + + var (records, _) = await SyncAsync(mock.Object, graceSeconds: -1, fullSync: false, marker: id); + + records.Should().BeEmpty("a negative setting falls back to the 120 s default, under which 30 s is recent"); + } + + [Fact] + public async Task ConfiguredGrace_IsHonoured() + { + string recent = NewId(); + string older = NewId(); + var mock = ClientReturning( + Row(recent, "pending_approval", ageSeconds: 8), + Row(older, "pending_approval", ageSeconds: 10 + Margin + 5)); + + var (records, _) = await SyncAsync(mock.Object, graceSeconds: 10, fullSync: false, marker: recent); + + records.Select(r => r.CARequestID).Should().BeEquivalentTo(new[] { older }, + "with a 10 s window an order 8 s old is held while one older than 10 s + margin is emitted"); + } + + [Fact] + public async Task MixedPage_HoldsOnlyTheRecentOnes() + { + string idRecentPending = NewId(); + string idRecentIssued = NewId(); + string idOldPending = NewId(); + string idOldIssued = NewId(); + var mock = ClientReturning( + Row(idRecentPending, "pending_approval", 15), + Row(idRecentIssued, "issued", 15), + Row(idOldPending, "pending_approval", 3600), + Row(idOldIssued, "issued", 3600)); + SetupDownload(mock, idOldIssued); + + var (records, log) = await SyncAsync(mock.Object, null, fullSync: false, marker: idRecentPending); + + records.Select(r => r.CARequestID).Should().BeEquivalentTo(new[] { idOldPending, idOldIssued }); + log.Should().Contain(m => m.Contains("CERTInext synchronization complete") && m.Contains("RecentOrderDeferred=2")); + } + + // --------------------------------------------------------------------------- + // Next-pass coverage: the listing filter is day-granular (UTC), so an incremental pass + // must look back far enough that an order held at the previous pass is still listed. + // --------------------------------------------------------------------------- + + private static async Task CapturedIssuedAfterAsync(int? graceSeconds, DateTime lastSync, bool fullSync) + { + DateTime? captured = DateTime.MaxValue; // sentinel + var mock = new Mock(MockBehavior.Strict); + mock.Setup(c => c.ListCertificatesAsync( + It.IsAny(), It.IsAny(), It.IsAny())) + .Returns((DateTime? ia, int ps, CancellationToken ct) => + { + captured = ia; + return Rows(new List()); + }); + await SyncAsync(mock.Object, graceSeconds, fullSync, marker: "none", lastSync: lastSync); + return captured; + } + + [Fact] + public async Task Incremental_ListingLooksBackByTheHoldWindow_SoAMidnightOrderIsRelisted() + { + // Previous pass started 00:00:10 UTC; an order created 23:58:30 the day before was held back there. + var lastSync = new DateTime(2026, 10, 16, 0, 0, 10, DateTimeKind.Utc); + + var issuedAfter = await CapturedIssuedAfterAsync(graceSeconds: null, lastSync, fullSync: false); + + issuedAfter.Should().NotBeNull(); + issuedAfter.Should().BeBefore(new DateTime(2026, 10, 16, 0, 0, 0, DateTimeKind.Utc), + "orderDateFrom is the UTC day of issuedAfter, so it must fall on the previous day to relist a 23:58:30 order"); + issuedAfter.Should().BeOnOrBefore(lastSync.AddSeconds(-(DefaultGrace + Margin))); + } + + [Fact] + public async Task Incremental_ZeroGrace_PassesLastSyncUnchanged() + { + var lastSync = new DateTime(2026, 10, 16, 0, 0, 10, DateTimeKind.Utc); + + var issuedAfter = await CapturedIssuedAfterAsync(graceSeconds: 0, lastSync, fullSync: false); + + issuedAfter.Should().Be(lastSync); + } + + [Fact] + public async Task FullSync_PassesNullIssuedAfter_EvenWithTheHoldActive() + { + var issuedAfter = await CapturedIssuedAfterAsync( + graceSeconds: null, new DateTime(2026, 10, 16, 0, 0, 10, DateTimeKind.Utc), fullSync: true); + + issuedAfter.Should().BeNull(); + } + + // --------------------------------------------------------------------------- + // Pure decision logic and boundaries + // --------------------------------------------------------------------------- + + [Theory] + [InlineData(Pending, 0, true)] + [InlineData(Pending, 30, true)] + [InlineData(Issued, 0, true)] + [InlineData(Issued, 30, true)] + [InlineData((int)EndEntityStatus.REVOKED, 30, false)] + [InlineData((int)EndEntityStatus.FAILED, 30, false)] + public void Gate_ByDispositionAndAge(int disposition, double ageSeconds, bool expectedHeld) + { + CERTInextCAPlugin.ShouldDeferRecentOrder( + disposition, Now.AddSeconds(-ageSeconds), Now, DefaultGrace, out _) + .Should().Be(expectedHeld); + } + + [Theory] + [InlineData(Pending)] + [InlineData(Issued)] + public void Gate_AgeBoundary_IsExclusiveAtGracePlusMargin(int disposition) + { + double limit = DefaultGrace + Margin; + + CERTInextCAPlugin.ShouldDeferRecentOrder( + disposition, Now.AddSeconds(-(limit - 0.001)), Now, DefaultGrace, out _) + .Should().BeTrue("just inside the window is still held"); + CERTInextCAPlugin.ShouldDeferRecentOrder( + disposition, Now.AddSeconds(-limit), Now, DefaultGrace, out _) + .Should().BeFalse("exactly grace + margin old is emitted"); + CERTInextCAPlugin.ShouldDeferRecentOrder( + disposition, Now.AddSeconds(-(limit + 0.001)), Now, DefaultGrace, out _) + .Should().BeFalse(); + } + + [Fact] + public void Gate_FutureDate_WithinMarginIsHeld_BeyondMarginFailsOpen() + { + CERTInextCAPlugin.ShouldDeferRecentOrder( + Pending, Now.AddSeconds(Margin), Now, DefaultGrace, out double ageAtMargin) + .Should().BeTrue("dated up to the margin ahead counts as age zero"); + ageAtMargin.Should().BeApproximately(-Margin, 0.0001); + + CERTInextCAPlugin.ShouldDeferRecentOrder( + Pending, Now.AddSeconds(Margin + 0.001), Now, DefaultGrace, out _) + .Should().BeFalse("further ahead than the margin is a clock disagreement: emit as today"); + } + + [Fact] + public void Gate_MissingDate_FailsOpen() + { + CERTInextCAPlugin.ShouldDeferRecentOrder(Pending, null, Now, DefaultGrace, out double age) + .Should().BeFalse(); + age.Should().Be(0); + } + + [Theory] + [InlineData(0)] + [InlineData(-1)] + public void Gate_NonPositiveGrace_Disables(int grace) + { + CERTInextCAPlugin.ShouldDeferRecentOrder(Pending, Now, Now, grace, out _).Should().BeFalse(); + } + + [Theory] + [InlineData(null, 120)] + [InlineData(0, 0)] + [InlineData(45, 45)] + [InlineData(-1, 120)] + [InlineData(-9999, 120)] + public void EffectiveGrace_DefaultZeroNegative(int? configured, int expected) + { + var config = new CERTInextConfig(); + if (configured.HasValue) config.SyncRecentOrderGraceSeconds = configured.Value; + + CERTInextCAPlugin.GetSyncRecentOrderGraceSeconds(config).Should().Be(expected); + } + + [Fact] + public void Config_DefaultsAndAnnotation() + { + new CERTInextConfig().SyncRecentOrderGraceSeconds.Should().Be(120); + + var annotations = CERTInextCAPluginConfig.GetCAConnectorAnnotations(); + annotations.Should().ContainKey(Constants.Config.SyncRecentOrderGraceSeconds); + annotations[Constants.Config.SyncRecentOrderGraceSeconds].DefaultValue.Should().Be(120); + annotations[Constants.Config.SyncRecentOrderGraceSeconds].Type.Should().Be("Number"); + } + + [Fact] + public void IssuedAfter_ShiftsBackByWindowPlusSlack_AndLeavesNullAndDisabledAlone() + { + var lastSync = new DateTime(2026, 10, 16, 0, 0, 10, DateTimeKind.Utc); + + CERTInextCAPlugin.GetSyncIssuedAfter(lastSync, 120) + .Should().Be(lastSync.AddSeconds(-(120 + Margin + Constants.Api.SyncRecentOrderLookbackSlackSeconds))); + CERTInextCAPlugin.GetSyncIssuedAfter(lastSync, 0).Should().Be(lastSync); + CERTInextCAPlugin.GetSyncIssuedAfter(null, 120).Should().BeNull(); + } + } +} diff --git a/CERTInext.Tests/CERTInextCAPluginTests.cs b/CERTInext.Tests/CERTInextCAPluginTests.cs index 3ec5df1..6b5f9e2 100644 --- a/CERTInext.Tests/CERTInextCAPluginTests.cs +++ b/CERTInext.Tests/CERTInextCAPluginTests.cs @@ -8,6 +8,7 @@ using System; using System.Collections.Concurrent; using System.Collections.Generic; +using System.Diagnostics; using System.Linq; using System.Threading; using System.Threading.Tasks; @@ -17,6 +18,9 @@ using Keyfactor.Extensions.CAPlugin.CERTInext.Client; using Keyfactor.PKI.Enums.EJBCA; using Moq; +using WireMock.RequestBuilders; +using WireMock.ResponseBuilders; +using WireMock.Server; using Xunit; namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests @@ -31,8 +35,20 @@ public class CERTInextCAPluginTests // Helpers // --------------------------------------------------------------------------- + // Pickup is disabled by default in the broad fixture (PickupRetries=0) — mirroring how + // DcvConfig defaults its wait budgets to 0 — so tests that don't care about the + // synchronous pickup don't pay its real Task.Delay-based poll. Tests that DO exercise + // pickup opt in via BuildPluginWithPickup. private static CERTInextCAPlugin BuildPlugin(ICERTInextClient client) => - new CERTInextCAPlugin(client); + new CERTInextCAPlugin(client, new CERTInextConfig { PickupRetries = 0 }); + + // Pickup-enabled fixture for the synchronous-pickup tests. PickupDelay is clamped to a + // 1s floor and the loop adds a fixed 5s initial delay, so these tests are intentionally + // a few seconds each. + private static CERTInextCAPlugin BuildPluginWithPickup( + ICERTInextClient client, int retries, int delaySeconds = 1) => + new CERTInextCAPlugin(client, + new CERTInextConfig { PickupRetries = retries, PickupDelayInSeconds = delaySeconds }); private static Mock NewMock() => new Mock(MockBehavior.Strict); @@ -164,6 +180,53 @@ await act.Should().ThrowAsync() .WithMessage("*valid absolute URI*"); } + [Fact] + public async Task ValidateCAConnectionInfo_Throws_WhenApiUrlIsHttp_NonLoopback() + { + var mock = NewMock(); + var plugin = BuildPlugin(mock.Object); + + var info = new Dictionary + { + ["ApiUrl"] = "http://ca.example.com", + ["AuthMode"] = "ApiKey", + ["ApiKey"] = "some-key" + }; + + Func act = () => plugin.ValidateCAConnectionInfo(info); + + await act.Should().ThrowAsync() + .WithMessage("*ApiUrl*https*"); + } + + [Theory] + [InlineData("http://localhost:8080")] + [InlineData("http://127.0.0.1:8080")] + [InlineData("http://[::1]:8080")] + public async Task ValidateCAConnectionInfo_AllowsHttp_ForLoopbackHosts(string apiUrl) + { + // Loopback http is allowed (e.g. a local WireMock/mock server in tests); this test + // only confirms the scheme check doesn't reject it — ApiKey mode fails on the next + // field it's missing (ApiKey), which still proves the ApiUrl check itself passed. + var mock = NewMock(); + var plugin = BuildPlugin(mock.Object); + + var info = new Dictionary + { + ["ApiUrl"] = apiUrl, + ["AuthMode"] = "ApiKey", + ["ApiKey"] = "some-key" + }; + + Func act = () => plugin.ValidateCAConnectionInfo(info); + + // No exception about ApiUrl specifically — any failure must come from the live + // connectivity check (NewMock's PingAsync is unstubbed under MockBehavior.Strict), + // not from the https scheme guard. + var ex = await act.Should().ThrowAsync(); + ex.Which.Message.Should().NotContain("ApiUrl"); + } + [Fact] public async Task ValidateCAConnectionInfo_Throws_WhenApiKeyMissingForApiKeyMode() { @@ -223,6 +286,92 @@ await act.Should().ThrowAsync() .WithMessage("*OAuthTokenUrl*required*"); } + // M2 compliance fix: OAuthTokenUrl receives the OAuth client secret on every token + // refresh (CERTInextClient.GetOrRefreshTokenAsync POSTs it there) — it must be held to + // the same https-or-loopback rule as ApiUrl, not just a non-empty check. + [Fact] + public async Task ValidateCAConnectionInfo_Throws_WhenOAuthTokenUrlIsHttp_NonLoopback() + { + var mock = NewMock(); + var plugin = BuildPlugin(mock.Object); + + var info = new Dictionary + { + ["ApiUrl"] = "https://ca.example.com", + ["AccountNumber"] = "12345", + ["AuthMode"] = "OAuth", + ["OAuthTokenUrl"] = "http://token.example.com", + ["OAuthClientId"] = "my-client", + ["OAuthClientSecret"] = "my-secret" + }; + + Func act = () => plugin.ValidateCAConnectionInfo(info); + + var ex = await act.Should().ThrowAsync(); + ex.Which.Message.Should().Contain("OAuthTokenUrl").And.Contain("https"); + mock.VerifyNoOtherCalls(); + } + + [Fact] + public async Task ValidateCAConnectionInfo_Throws_WhenOAuthTokenUrlIsNotUri() + { + var mock = NewMock(); + var plugin = BuildPlugin(mock.Object); + + var info = new Dictionary + { + ["ApiUrl"] = "https://ca.example.com", + ["AccountNumber"] = "12345", + ["AuthMode"] = "OAuth", + ["OAuthTokenUrl"] = "not-a-url", + ["OAuthClientId"] = "my-client", + ["OAuthClientSecret"] = "my-secret" + }; + + Func act = () => plugin.ValidateCAConnectionInfo(info); + + var ex = await act.Should().ThrowAsync(); + ex.Which.Message.Should().Contain("OAuthTokenUrl").And.Contain("valid absolute URI"); + } + + [Fact] + public async Task ValidateCAConnectionInfo_AllowsHttp_ForLoopbackOAuthTokenUrl() + { + // Full round trip through a loopback WireMock server standing in for both the + // OAuth token endpoint (OAuthTokenUrl is used as-is, no path appended — see + // CERTInextClient.GetOrRefreshTokenAsync) and the V1 ValidateCredentials ping — + // proves http-loopback is accepted end to end, not just by the synchronous guard. + using var server = WireMockServer.Start(); + server + .Given(Request.Create().WithPath("/").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody("{\"access_token\":\"test-token\",\"expires_in\":3600}")); + server + .Given(Request.Create().WithPath("/ValidateCredentials").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody("{\"meta\":{\"status\":\"1\"}}")); + + var plugin = BuildPlugin(NewMock().Object); + + var info = new Dictionary + { + ["ApiUrl"] = server.Urls[0] + "/", + ["AccountNumber"] = "12345", + ["AuthMode"] = "OAuth", + ["OAuthTokenUrl"] = server.Urls[0], + ["OAuthClientId"] = "my-client", + ["OAuthClientSecret"] = "my-secret" + }; + + Func act = () => plugin.ValidateCAConnectionInfo(info); + + await act.Should().NotThrowAsync(); + } + [Fact] public async Task ValidateCAConnectionInfo_Throws_WhenAuthModeIsInvalid() { @@ -289,6 +438,71 @@ await act.Should().ThrowAsync() .WithMessage("*ProfileId*required*"); } + // ValidateProductInfo builds its own CERTInextClient from connectionInfo (like + // ValidateCAConnectionInfo) rather than using the Moq-injected client, so these tests + // need a real WireMock server as ApiUrl. + + [Fact] + public async Task ValidateProductInfo_V1_Succeeds_WhenProductCodePresent() + { + using var server = WireMockServer.Start(); + server + .Given(Request.Create().WithPath("/GetProductDetails").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.GetProductDetailsJson())); + + var plugin = BuildPlugin(NewMock().Object); + var productInfo = new EnrollmentProductInfo + { + ProductID = "ssl", + ProductParameters = new Dictionary { ["ProductCode"] = MockCertificateData.ProfileIdTls } + }; + var connInfo = new Dictionary + { + ["ApiUrl"] = server.Urls[0], + ["AuthMode"] = "AccessKey", + ["ApiKey"] = "key", + ["AccountNumber"] = "12345" + }; + + Func act = () => plugin.ValidateProductInfo(productInfo, connInfo); + + await act.Should().NotThrowAsync(); + } + + [Fact] + public async Task ValidateProductInfo_V1_Throws_WhenProductCodeAbsent() + { + using var server = WireMockServer.Start(); + server + .Given(Request.Create().WithPath("/GetProductDetails").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.GetProductDetailsJson())); + + var plugin = BuildPlugin(NewMock().Object); + var productInfo = new EnrollmentProductInfo + { + ProductID = "ssl", + ProductParameters = new Dictionary { ["ProductCode"] = "999999" } + }; + var connInfo = new Dictionary + { + ["ApiUrl"] = server.Urls[0], + ["AuthMode"] = "AccessKey", + ["ApiKey"] = "key", + ["AccountNumber"] = "12345" + }; + + Func act = () => plugin.ValidateProductInfo(productInfo, connInfo); + + await act.Should().ThrowAsync() + .WithMessage("*not found*"); + } + // --------------------------------------------------------------------------- // Enroll — New // --------------------------------------------------------------------------- @@ -345,6 +559,217 @@ public async Task Enroll_New_ReturnsPendingStatus_WhenCaReturnsPendingApproval() result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); } + [Fact] + public async Task Enroll_New_ReturnsPendingStatus_WhenCaReportsIssuedButBodyMissing() + { + // CERTInext can report an "issued"/auto-approved certificateStatusId before the + // certificate bytes actually exist — the immediate GetCertificate download fails + // and the legacy client returns Status="issued" with Certificate=null. Reporting + // GENERATED with no PEM crashes the gateway framework's PEM parser downstream, so + // the plugin must demote this to pending rather than trust the raw status string. + var mock = NewMock(); + mock.Setup(c => c.EnrollCertificateAsync( + It.IsAny(), + It.IsAny())) + .ReturnsAsync(MockCertificateData.AutoApprovedNoBodyEnrollResponse()); + + var plugin = BuildPluginWithPickup(mock.Object, retries: 0); + + var result = await plugin.Enroll( + csr: MockCertificateData.FakeCsrPem, + subject: "CN=test.example.com", + san: null, + productInfo: MakeProductInfo(), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + result.Certificate.Should().BeNullOrEmpty(); + } + + // --------------------------------------------------------------------------- + // Synchronous certificate pickup (Sectigo parity) + // --------------------------------------------------------------------------- + + [Fact] + public async Task Pickup_Disabled_WhenPickupRetriesZero_ReturnsPendingWithoutPolling() + { + var mock = NewMock(); + mock.Setup(c => c.EnrollCertificateAsync( + It.IsAny(), It.IsAny())) + .ReturnsAsync(MockCertificateData.PendingEnrollResponse()); + + var plugin = BuildPluginWithPickup(mock.Object, retries: 0); + + var result = await plugin.Enroll( + csr: MockCertificateData.FakeCsrPem, subject: "CN=test.example.com", san: null, + productInfo: MakeProductInfo(), requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + mock.Verify(c => c.GetCertificateAsync(It.IsAny(), It.IsAny()), + Times.Never, "PickupRetries=0 must disable the synchronous pickup poll"); + } + + [Fact] + public async Task Pickup_ReturnsIssuedCert_WhenOrderIssuesDuringPoll() + { + var mock = NewMock(); + mock.Setup(c => c.EnrollCertificateAsync( + It.IsAny(), It.IsAny())) + .ReturnsAsync(MockCertificateData.PendingEnrollResponse()); + // The order finishes issuing by the time we poll: GetCertificate reports issued + PEM. + mock.Setup(c => c.GetCertificateAsync(It.IsAny(), It.IsAny())) + .ReturnsAsync(MockCertificateData.IssuedCertRecord()); + + var plugin = BuildPluginWithPickup(mock.Object, retries: 2); + + var result = await plugin.Enroll( + csr: MockCertificateData.FakeCsrPem, subject: "CN=test.example.com", san: null, + productInfo: MakeProductInfo(), requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.Status.Should().Be((int)EndEntityStatus.GENERATED); + result.Certificate.Should().NotBeNullOrEmpty("a synchronously-picked-up cert must carry its PEM"); + mock.Verify(c => c.GetCertificateAsync(It.IsAny(), It.IsAny()), + Times.AtLeastOnce); + } + + [Fact] + public async Task Pickup_SurfacesTerminalStatus_WhenOrderRevokedDuringPoll() + { + var mock = NewMock(); + mock.Setup(c => c.EnrollCertificateAsync( + It.IsAny(), It.IsAny())) + .ReturnsAsync(MockCertificateData.PendingEnrollResponse()); + mock.Setup(c => c.GetCertificateAsync(It.IsAny(), It.IsAny())) + .ReturnsAsync(MockCertificateData.RevokedCertRecord()); + + var plugin = BuildPluginWithPickup(mock.Object, retries: 3); + + var result = await plugin.Enroll( + csr: MockCertificateData.FakeCsrPem, subject: "CN=test.example.com", san: null, + productInfo: MakeProductInfo(), requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.Status.Should().Be((int)EndEntityStatus.REVOKED, + "a terminal status observed during pickup is surfaced immediately, not polled to exhaustion"); + } + + [Fact] + public async Task Pickup_ReturnsPending_WhenOrderNeverIssuesWithinBudget() + { + var mock = NewMock(); + mock.Setup(c => c.EnrollCertificateAsync( + It.IsAny(), It.IsAny())) + .ReturnsAsync(MockCertificateData.PendingEnrollResponse()); + // Every poll still reports pending — the budget is exhausted and Enroll returns the + // pending result for a later sync to complete. + mock.Setup(c => c.GetCertificateAsync(It.IsAny(), It.IsAny())) + .ReturnsAsync(MockCertificateData.PendingCertRecord()); + + var plugin = BuildPluginWithPickup(mock.Object, retries: 1); + + var result = await plugin.Enroll( + csr: MockCertificateData.FakeCsrPem, subject: "CN=test.example.com", san: null, + productInfo: MakeProductInfo(), requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + mock.Verify(c => c.GetCertificateAsync(It.IsAny(), It.IsAny()), + Times.AtLeastOnce, "an enabled pickup must actually poll before giving up"); + } + + // --------------------------------------------------------------------------- + // Pickup in-call ceiling clamp (issue 0014) + // --------------------------------------------------------------------------- + + /// + /// Regression for issue 0014: the old Constants.Pickup.MaxTotalWaitSeconds of 180s + /// exceeded Command's observed ~100s enrollment-call timeout, so a pickup that used its + /// allowed budget outlived the caller entirely. Now 75s. This pins the clamp arithmetic extracted + /// to against the current 75s ceiling + /// and 5s initial delay, independent of real polling delays. + /// + [Theory] + [InlineData(1, 70)] // (75-5)/1 = 70 + [InlineData(10, 7)] // (75-5)/10 = 7 - the documented default delay + [InlineData(36, 1)] // (75-5)/36 = 1 (floors below 2) + [InlineData(60, 1)] // (75-5)/60 = 1 (max delay clamp) + [InlineData(1000, 1)] // Math.Max(1, ...) floor - never returns 0 or negative + public void ComputeMaxPollRetries_MatchesCeilingArithmetic(int delaySeconds, int expectedMaxRetries) + { + CERTInextCAPlugin.ComputeMaxPollRetries(delaySeconds).Should().Be(expectedMaxRetries); + } + + /// + /// The unclamped defaults (5s initial + 5 retries x 10s = 55s) must keep fitting comfortably + /// under the 75s ceiling without ever being reduced - this is what every non-pathological + /// deployment actually runs with. + /// + [Fact] + public void ComputeMaxPollRetries_DefaultConfig_NeverClampsDefaultRetries() + { + int maxPollRetries = CERTInextCAPlugin.ComputeMaxPollRetries(Constants.Pickup.DefaultDelaySeconds); + + maxPollRetries.Should().BeGreaterOrEqualTo(Constants.Pickup.DefaultRetries, + "the documented default pickup budget must never be clamped by the in-call ceiling"); + } + + /// + /// The ceiling must leave headroom inside Command's enrollment-call budget for the order + /// submission and per-poll round trips that the ceiling does not count. + /// + [Fact] + public void PickupCeiling_FitsInsideCommandEnrollmentBudget() + { + Constants.Pickup.MaxTotalWaitSeconds.Should().BeLessThan(Constants.Pickup.CommandEnrollmentBudgetSeconds); + } + + /// + /// Regression for issue 0014: a configured pickup budget that would blow the 75s in-call + /// ceiling (PickupRetries=30, PickupDelay=60 - both at their individual per-factor clamps, + /// product ~1805s) must be capped so the plugin only ever polls + /// 's worth of attempts, not the full + /// configured count, and total in-call occupancy must stay under the ceiling. This is an + /// end-to-end exercise of the real Task.Delay-based pickup loop (not the pure-math + /// tests above), so it necessarily runs for real time - bounded well under the 75s ceiling + /// itself since the clamp is exactly what keeps it there. + /// + [Fact] + public async Task Pickup_ClampsToInCallCeiling_WhenConfiguredBudgetExceedsBound() + { + const int configuredRetries = 30; + const int configuredDelaySeconds = 60; + int expectedCappedRetries = CERTInextCAPlugin.ComputeMaxPollRetries(configuredDelaySeconds); + expectedCappedRetries.Should().Be(1, "sanity check on the scenario this test exercises"); + + var mock = NewMock(); + mock.Setup(c => c.EnrollCertificateAsync( + It.IsAny(), It.IsAny())) + .ReturnsAsync(MockCertificateData.PendingEnrollResponse()); + // Every poll reports pending, so the loop only stops when its (capped) retry count + // is exhausted - proving the configured 30 retries never actually ran. + mock.Setup(c => c.GetCertificateAsync(It.IsAny(), It.IsAny())) + .ReturnsAsync(MockCertificateData.PendingCertRecord()); + + var plugin = BuildPluginWithPickup(mock.Object, retries: configuredRetries, delaySeconds: configuredDelaySeconds); + + var stopwatch = Stopwatch.StartNew(); + var result = await plugin.Enroll( + csr: MockCertificateData.FakeCsrPem, subject: "CN=test.example.com", san: null, + productInfo: MakeProductInfo(), requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + stopwatch.Stop(); + + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + mock.Verify(c => c.GetCertificateAsync(It.IsAny(), It.IsAny()), + Times.Exactly(expectedCappedRetries), + "PickupRetries=30 must be capped to the in-call ceiling's worth of attempts, not run in full"); + stopwatch.Elapsed.Should().BeLessThan(TimeSpan.FromSeconds(Constants.Pickup.MaxTotalWaitSeconds), + "total in-call pickup occupancy must stay under the ceiling it is clamped to"); + } + [Fact] public async Task Enroll_New_Throws_WhenProfileIdNotSet() { @@ -369,6 +794,56 @@ await act.Should().ThrowAsync() .WithMessage("*ProfileId*required*"); } + [Fact] + public async Task Enroll_New_ThreadsTemplateSignerParamsOntoRequest() + { + var mock = NewMock(); + EnrollCertificateRequest captured = null; + mock.Setup(c => c.EnrollCertificateAsync( + It.IsAny(), + It.IsAny())) + .Callback((r, _) => captured = r) + .ReturnsAsync(MockCertificateData.IssuedEnrollResponse()); + + var plugin = BuildPlugin(mock.Object); + await plugin.Enroll( + MockCertificateData.FakeCsrPem, "CN=test.example.com", null, + MakeProductInfo(extras: new Dictionary + { + ["SignerName"] = "Template Signer", + ["SignerPlace"] = "Template Place", + ["SignerIp"] = "203.0.113.77" + }), + RequestFormat.PKCS10, EnrollmentType.New); + + captured.Should().NotBeNull(); + captured!.SignerName.Should().Be("Template Signer"); + captured.SignerPlace.Should().Be("Template Place"); + captured.SignerIp.Should().Be("203.0.113.77"); + } + + [Fact] + public async Task Enroll_New_BlankTemplateSignerParams_LeaveRequestSignerValuesNull() + { + var mock = NewMock(); + EnrollCertificateRequest captured = null; + mock.Setup(c => c.EnrollCertificateAsync( + It.IsAny(), + It.IsAny())) + .Callback((r, _) => captured = r) + .ReturnsAsync(MockCertificateData.IssuedEnrollResponse()); + + var plugin = BuildPlugin(mock.Object); + await plugin.Enroll( + MockCertificateData.FakeCsrPem, "CN=test.example.com", null, + MakeProductInfo(), RequestFormat.PKCS10, EnrollmentType.New); + + captured.Should().NotBeNull(); + captured!.SignerName.Should().BeNull(); + captured.SignerPlace.Should().BeNull(); + captured.SignerIp.Should().BeNull(); + } + [Fact] public async Task Enroll_Reissue_AlsoCallsEnrollAsync() { @@ -624,7 +1099,11 @@ public async Task Synchronize_DeltaSync_PassesLastSyncFilter() await plugin.Synchronize(buffer, lastSync: lastSync, fullSync: false, cancelToken: CancellationToken.None); // CompleteAdding() is called by Synchronize internally. - capturedIssuedAfter.Should().Be(lastSync); + // Issue 0090: the listing looks back by the hold-back window (120 s + 5 s margin + slack) + // so an order held at the previous pass is still in this pass's day-granular listing. + capturedIssuedAfter.Should().Be(CERTInextCAPlugin.GetSyncIssuedAfter( + lastSync, Constants.Api.DefaultSyncRecentOrderGraceSeconds)); + capturedIssuedAfter.Should().BeOnOrBefore(lastSync); } [Fact] @@ -966,6 +1445,44 @@ public async Task RenewOrReissue_UsesRenewApi_WhenCertExpiresWithinWindow() "cert expiring in 30 days should use the renewal API (within 90-day window)"); } + [Fact] + public async Task RenewOrReissue_Renewal_ThreadsTemplateSignerParamsOntoRequest() + { + var clientMock = new Mock(MockBehavior.Strict); + var readerMock = new Mock(MockBehavior.Strict); + + readerMock.Setup(r => r.GetRequestIDBySerialNumber(It.IsAny())) + .ReturnsAsync(MockCertificateData.CertId1); + readerMock.Setup(r => r.GetExpirationDateByRequestId(MockCertificateData.CertId1)) + .Returns(DateTime.UtcNow.AddDays(30)); + + RenewCertificateRequest captured = null; + clientMock.Setup(c => c.RenewCertificateAsync( + MockCertificateData.CertId1, + It.IsAny(), + It.IsAny())) + .Callback((_, r, _) => captured = r) + .ReturnsAsync(MockCertificateData.IssuedEnrollResponse("renewed-01")); + + var plugin = new CERTInextCAPlugin(clientMock.Object, readerMock.Object); + await plugin.Enroll( + MockCertificateData.FakeCsrPem, "CN=test.example.com", null, + MakeProductInfo(extras: new Dictionary + { + ["PriorCertSN"] = "AABB", + ["RenewalWindowDays"] = "90", + ["SignerName"] = "Template Signer", + ["SignerPlace"] = "Template Place", + ["SignerIp"] = "203.0.113.77" + }), + RequestFormat.PKCS10, EnrollmentType.RenewOrReissue); + + captured.Should().NotBeNull(); + captured!.SignerName.Should().Be("Template Signer"); + captured.SignerPlace.Should().Be("Template Place"); + captured.SignerIp.Should().Be("203.0.113.77"); + } + [Fact] public async Task RenewOrReissue_UsesNewEnroll_WhenCertExpiresOutsideWindow() { diff --git a/CERTInext.Tests/CERTInextCAPluginV2DcvTests.cs b/CERTInext.Tests/CERTInextCAPluginV2DcvTests.cs new file mode 100644 index 0000000..f649e94 --- /dev/null +++ b/CERTInext.Tests/CERTInextCAPluginV2DcvTests.cs @@ -0,0 +1,1387 @@ +// Copyright 2026 Keyfactor +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Linq; +using System.Text.Json; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Moq; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Tests confirming EMS-1080 ("Domain is already verified") from either + /// V2 DCV entry point (GetDcvV2Async or VerifyDcvV2Async) must be treated as + /// DCV already satisfied — skip TXT publish, proceed straight to tracking — not as a + /// failure deferred to the next sync cycle. Driven end-to-end through + /// (V2 path) so the assertions exercise the same + /// code path Command actually calls, using to observe + /// whether a TXT record was ever staged. + /// + public class CERTInextCAPluginV2DcvTests + { + private static Mock NewMock() => + new Mock(MockBehavior.Strict); + + private static CERTInextCAPlugin BuildV2DcvPlugin( + ICERTInextClient client, IDomainValidatorFactory factory, string dcvTxtRecordTemplate = null, + int pickupRetries = 0) => + new CERTInextCAPlugin(client, factory, new CERTInextConfig + { + UseV2Api = true, + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + AccountNumber = "12345", + AuthMode = "AccessKey", + ApiKey = "v1-key", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + SignerIp = "1.2.3.4", + SignerPlace = "New York", + PickupRetries = pickupRetries, + PickupDelayInSeconds = 1, + DcvEnabled = true, + DcvTimeoutMinutes = 1, + DcvPropagationDelaySeconds = 1, + DcvTxtRecordTemplate = dcvTxtRecordTemplate + }); + + private static EnrollmentProductInfo MakeV2ProductInfo() => + new EnrollmentProductInfo + { + ProductID = "DV SSL", + ProductParameters = new Dictionary(System.StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = "842", + ["ProductFamily"] = "ssl", + ["ProductVariant"] = "dv", + ["DomainName"] = "example.com" + } + }; + + private static Task Enroll(CERTInextCAPlugin plugin) => + plugin.Enroll( + csr: MockCertificateData.FakeCsrPem, + subject: "CN=example.com", + san: new Dictionary { ["dns"] = new[] { "example.com" } }, + productInfo: MakeV2ProductInfo(), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + private const string OrderId = "ord_ems1080_001"; + + private static V2CreateOrderResponse PlaceOrderResponse() => + new V2CreateOrderResponse { OrderId = OrderId, Status = "pending-dcv" }; + + private static V2OrderStatusResponse PendingDcvStatus() => + new V2OrderStatusResponse { OrderId = OrderId, Status = "pending-dcv", Domain = "example.com" }; + + private static V2OrderStatusResponse IssuedStatus() => + new V2OrderStatusResponse { OrderId = OrderId, Status = "issued", Domain = "example.com" }; + + private static V2CertificateDownloadResponse DownloadResponse() => + new V2CertificateDownloadResponse + { + OrderId = OrderId, + SerialNumber = "AA11BB22", + CertificatePem = MockCertificateData.FakePemCertificate + }; + + // --------------------------------------------------------------------------- + // GetDcv returns EMS-1080 + // --------------------------------------------------------------------------- + + [Fact] + public async Task PerformDcvV2_GetDcvReturnsEms1080_TreatedAsSatisfied_NoStagingAndProceedsToTracking() + { + var mock = NewMock(); + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = "842", ProductTypeId = "13", Active = true } // non-UCC + }); + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .ReturnsAsync(PlaceOrderResponse()); + + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + // 1st call: post-CSR check (pending-dcv). 2nd+: the PerformDcvV2IfNeededAsync poll + // loop and EnrollV2Async's post-DCV re-check both see "issued" immediately. + mock.SetupSequence(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(PendingDcvStatus()) + .ReturnsAsync(IssuedStatus()) + .ReturnsAsync(IssuedStatus()); + + mock.Setup(c => c.GetDcvV2Async(OrderId, It.IsAny(), It.IsAny())) + .ThrowsAsync(new System.Exception( + $"CERTInext V2 API error during 'V2 get DCV challenge'. HTTP 422. " + + "Unprocessable Entity: EMS-1080 Domain is already verified.")); + + mock.Setup(c => c.DownloadCertificateV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(DownloadResponse()); + + var validator = new FakeDomainValidator(); + var plugin = BuildV2DcvPlugin(mock.Object, new FakeDomainValidatorFactory(validator)); + + var result = await Enroll(plugin); + + result.Status.Should().Be((int)EndEntityStatus.GENERATED, + "EMS-1080 must be treated as DCV satisfied, not a failure — the order should " + + "proceed to tracking and come back issued"); + validator.StagedRecords.Should().BeEmpty( + "GetDcv returning EMS-1080 means there is no fresh challenge to publish"); + + // VerifyDcv must never be reached — there is nothing to verify when GetDcv itself + // reports the domain is already verified. + mock.Verify(c => c.VerifyDcvV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny()), + Times.Never); + } + + // --------------------------------------------------------------------------- + // VerifyDcv returns EMS-1080 + // --------------------------------------------------------------------------- + + [Fact] + public async Task PerformDcvV2_VerifyDcvReturnsEms1080_TreatedAsSatisfied_ProceedsToTracking() + { + var mock = NewMock(); + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = "842", ProductTypeId = "13", Active = true } // non-UCC + }); + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .ReturnsAsync(PlaceOrderResponse()); + + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + mock.SetupSequence(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(PendingDcvStatus()) + .ReturnsAsync(IssuedStatus()) + .ReturnsAsync(IssuedStatus()); + + // GetDcv succeeds normally and returns a token to publish... + mock.Setup(c => c.GetDcvV2Async(OrderId, It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvChallengeResponse + { + Token = "dcv-token-abc123", + TokenExpiryDate = "2026-12-31 23:59:59" + }); + + // ...but by the time VerifyDcv is called, the domain became already-verified. + mock.Setup(c => c.VerifyDcvV2Async(OrderId, "example.com", It.IsAny(), It.IsAny())) + .ThrowsAsync(new System.Exception( + $"CERTInext V2 API error during 'V2 verify DCV'. HTTP 422. " + + "Unprocessable Entity: EMS-1080 Domain is already verified.")); + + mock.Setup(c => c.DownloadCertificateV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(DownloadResponse()); + + var validator = new FakeDomainValidator(); + var plugin = BuildV2DcvPlugin(mock.Object, new FakeDomainValidatorFactory(validator)); + + var result = await Enroll(plugin); + + result.Status.Should().Be((int)EndEntityStatus.GENERATED, + "EMS-1080 from VerifyDcv must be treated as verified, not a failure — the order " + + "should proceed to tracking and come back issued"); + + // The TXT record was staged (GetDcv succeeded) — this exercises the "verified between + // GetDcv and VerifyDcv" race rather than the GetDcv-level no-op. + validator.StagedRecords.Should().ContainSingle(); + validator.CleanedUpKeys.Should().ContainSingle( + "staged records are always cleaned up, including on the EMS-1080 verify path"); + } + + // --------------------------------------------------------------------------- + // Live GetDcv response shape has no fileNameContent + // --------------------------------------------------------------------------- + + /// + /// A live fresh-domain GetDcv challenge response comes back as exactly + /// {"tokenExpiryDate":"...","token":"..."} — no + /// orderNumber/domainName/dcvMethod/fileNameContent. + /// If modeled fileNameContent + /// instead of token, this shape would deserialize with a null token, which would + /// drive PerformDcvV2IfNeededAsync's null-token guard and leave the order stuck at + /// EXTERNALVALIDATION forever (no TXT ever staged, no exception, just a returned + /// false). This constructs the response exactly as the DTO + /// deserializes the real live body, and proves the plugin extracts and publishes the + /// token instead of deferring. + /// + [Fact] + public async Task PerformDcvV2_LiveShapeTokenOnly_StagesTxtRecord_DoesNotHitNullTokenGuard() + { + var mock = NewMock(); + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = "842", ProductTypeId = "13", Active = true } // non-UCC + }); + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .ReturnsAsync(PlaceOrderResponse()); + + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + mock.SetupSequence(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(PendingDcvStatus()) + .ReturnsAsync(IssuedStatus()) + .ReturnsAsync(IssuedStatus()); + + // Real live shape: only Token/TokenExpiryDate are + // ever populated — no OrderNumber/DomainName/DcvMethod exist on the DTO. + const string liveToken = "D6026954B9EB7D31E3FE8B2194F07087"; + mock.Setup(c => c.GetDcvV2Async(OrderId, It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvChallengeResponse + { + Token = liveToken, + TokenExpiryDate = "2026-09-27 15:27:00" + }); + + mock.Setup(c => c.VerifyDcvV2Async(OrderId, "example.com", It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvVerifyResponse { OverallStatus = "VERIFIED" }); + + mock.Setup(c => c.DownloadCertificateV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(DownloadResponse()); + + var validator = new FakeDomainValidator(); + var plugin = BuildV2DcvPlugin(mock.Object, new FakeDomainValidatorFactory(validator)); + + var result = await Enroll(plugin); + + result.Status.Should().Be((int)EndEntityStatus.GENERATED, + "the live token-only shape must be extracted and published, not deferred by " + + "the null-token guard"); + + validator.StagedRecords.Should().ContainSingle( + "GetDcv returned a real token, so a TXT record must be staged from it") + .Which.Should().Be(("_emsign-validation.example.com", liveToken), + "the staged value must come from the Token property, not a " + + "FileNameContent property; the hostname uses the default " + + "DcvTxtRecordTemplate since none is configured here"); + + mock.Verify(c => c.VerifyDcvV2Async( + OrderId, "example.com", It.IsAny(), It.IsAny()), + Times.Once); + } + + // --------------------------------------------------------------------------- + // DcvTxtRecordTemplate must be honored by the V2 + // DCV path, not hardcoded to "_emudhra-challenge.{domain}" — mirrors V1's + // PerformDcvIfNeededAsync (config value if set, else Constants.Dcv.DefaultTxtRecordTemplate). + // --------------------------------------------------------------------------- + + [Fact] + public async Task PerformDcvV2_ConfiguredTxtRecordTemplate_IsHonored() + { + var mock = NewMock(); + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = "842", ProductTypeId = "13", Active = true } // non-UCC + }); + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .ReturnsAsync(PlaceOrderResponse()); + + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + mock.SetupSequence(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(PendingDcvStatus()) + .ReturnsAsync(IssuedStatus()) + .ReturnsAsync(IssuedStatus()); + + const string token = "configured-template-token"; + mock.Setup(c => c.GetDcvV2Async(OrderId, It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvChallengeResponse { Token = token, TokenExpiryDate = "2026-12-31 23:59:59" }); + + mock.Setup(c => c.VerifyDcvV2Async(OrderId, "example.com", It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvVerifyResponse { OverallStatus = "VERIFIED" }); + + mock.Setup(c => c.DownloadCertificateV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(DownloadResponse()); + + var validator = new FakeDomainValidator(); + var plugin = BuildV2DcvPlugin( + mock.Object, new FakeDomainValidatorFactory(validator), + dcvTxtRecordTemplate: "_custom-dcv-check.{0}"); + + var result = await Enroll(plugin); + + result.Status.Should().Be((int)EndEntityStatus.GENERATED); + validator.StagedRecords.Should().ContainSingle() + .Which.Should().Be(("_custom-dcv-check.example.com", token), + "the configured DcvTxtRecordTemplate must be used to build the TXT " + + "hostname, not a hardcoded '_emudhra-challenge' label"); + } + + [Fact] + public async Task PerformDcvV2_UnconfiguredTxtRecordTemplate_UsesV1Default() + { + var mock = NewMock(); + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = "842", ProductTypeId = "13", Active = true } // non-UCC + }); + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .ReturnsAsync(PlaceOrderResponse()); + + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + mock.SetupSequence(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(PendingDcvStatus()) + .ReturnsAsync(IssuedStatus()) + .ReturnsAsync(IssuedStatus()); + + const string token = "default-template-token"; + mock.Setup(c => c.GetDcvV2Async(OrderId, It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvChallengeResponse { Token = token, TokenExpiryDate = "2026-12-31 23:59:59" }); + + mock.Setup(c => c.VerifyDcvV2Async(OrderId, "example.com", It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvVerifyResponse { OverallStatus = "VERIFIED" }); + + mock.Setup(c => c.DownloadCertificateV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(DownloadResponse()); + + var validator = new FakeDomainValidator(); + // No dcvTxtRecordTemplate override — must fall back to the same default V1 uses. + var plugin = BuildV2DcvPlugin(mock.Object, new FakeDomainValidatorFactory(validator)); + + await Enroll(plugin); + + validator.StagedRecords.Should().ContainSingle() + .Which.Should().Be(("_emsign-validation.example.com", token), + "with no DcvTxtRecordTemplate configured, V2 must fall back to " + + "Constants.Dcv.DefaultTxtRecordTemplate (the same default V1 uses) rather " + + "than a separate, hardcoded V2 literal"); + } + + // --------------------------------------------------------------------------- + // The inline DCV path owns the in-call issuance wait — EnrollV2Async must + // not stack a second PickUpEnrolledCertificateV2Async poll on top of it. + // --------------------------------------------------------------------------- + + [Fact] + public async Task EnrollV2_DcvRan_SkipsPickupPoll_EvenThoughPickupIsEnabled() + { + var mock = NewMock(); + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = "842", ProductTypeId = "13", Active = true } // non-UCC + }); + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .ReturnsAsync(PlaceOrderResponse()); + + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + // 1st call: post-CSR check (pending-dcv). 2nd: PerformDcvV2IfNeededAsync's own + // tracking poll (step 4) — moves to a *different* pending state so that inner loop + // breaks (DCV steps completed) without the order having actually issued. 3rd: + // EnrollV2Async's post-DCV re-check, observing the same still-pending state. If the + // pickup poll incorrectly ran afterward, a 4th TrackOrderV2Async call would occur. + mock.SetupSequence(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(PendingDcvStatus()) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "pending-organization-verification", Domain = "example.com" }) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "pending-organization-verification", Domain = "example.com" }); + + mock.Setup(c => c.GetDcvV2Async(OrderId, It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvChallengeResponse { Token = "dcv-token-xyz", TokenExpiryDate = "2026-12-31 23:59:59" }); + mock.Setup(c => c.VerifyDcvV2Async(OrderId, "example.com", It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvVerifyResponse { OverallStatus = "VERIFIED" }); + + var validator = new FakeDomainValidator(); + // PickupRetries > 0 and clamped to a fast 1s delay — if the dcvV2Ran gate didn't + // work, this budget is easily enough for the pickup poll to run and this test would + // observe extra TrackOrderV2Async/DownloadCertificateV2Async calls. + var plugin = BuildV2DcvPlugin(mock.Object, new FakeDomainValidatorFactory(validator), pickupRetries: 5); + + var result = await Enroll(plugin); + + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION, + "the order never actually issued — DCV ran, but the order is still pending elsewhere"); + result.CARequestID.Should().Be(OrderId); + mock.Verify(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny()), + Times.Exactly(3), + "a pickup poll must not stack on top of the inline DCV wait — no 4th TrackOrderV2Async call"); + mock.Verify(c => c.DownloadCertificateV2Async( + It.IsAny(), It.IsAny(), It.IsAny()), Times.Never); + } + + // --------------------------------------------------------------------------- + // A REVOKED disposition discovered on the post-DCV status re-check must be + // mapped to FAILED, not returned as a body-less REVOKED record — mirrors + // EnrollV2_DcvRan_SkipsPickupPoll_EvenThoughPickupIsEnabled above, but the second + // TrackOrderV2Async observation is "revoked" instead of another pending state. + // --------------------------------------------------------------------------- + + [Fact] + public async Task EnrollV2_PostDcvRecheckRevoked_ReturnsFailed_NotBodylessRevoked() + { + var mock = NewMock(); + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = "842", ProductTypeId = "13", Active = true } // non-UCC + }); + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .ReturnsAsync(PlaceOrderResponse()); + + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + // 1st call: post-CSR check (pending-dcv), triggers the inline DCV block. 2nd: + // PerformDcvV2SingleDomainAsync's own internal step-4 poll (it calls + // TrackOrderV2Async itself to wait out "pending-dcv" — see its doc comment) observes + // "revoked", which is != "pending-dcv" so that poll loop breaks and DCV reports done. + // 3rd: EnrollV2Async's own post-DCV re-check observes the same revoked status. + mock.SetupSequence(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(PendingDcvStatus()) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "revoked", Domain = "example.com" }) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "revoked", Domain = "example.com" }); + + mock.Setup(c => c.GetDcvV2Async(OrderId, It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvChallengeResponse { Token = "dcv-token-revoked", TokenExpiryDate = "2026-12-31 23:59:59" }); + mock.Setup(c => c.VerifyDcvV2Async(OrderId, "example.com", It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvVerifyResponse { OverallStatus = "VERIFIED" }); + + var validator = new FakeDomainValidator(); + // Pickup enabled to prove the poll is correctly skipped (dcvV2Ran) rather than + // masking the revoked status behind additional polling/downloads. + var plugin = BuildV2DcvPlugin(mock.Object, new FakeDomainValidatorFactory(validator), pickupRetries: 5); + + var result = await Enroll(plugin); + + result.Status.Should().Be((int)EndEntityStatus.FAILED, + "a REVOKED disposition discovered on the post-DCV re-check has no certificate " + + "body and must never be reported as REVOKED"); + result.Certificate.Should().BeNull(); + result.CARequestID.Should().Be(OrderId); + result.StatusMessage.Should().Contain(OrderId).And.Contain("revoked"); + + mock.Verify(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny()), + Times.Exactly(3), + "the pickup poll must not run on top of the inline DCV wait — no 4th TrackOrderV2Async call"); + mock.Verify(c => c.DownloadCertificateV2Async( + It.IsAny(), It.IsAny(), It.IsAny()), Times.Never); + } + + // --------------------------------------------------------------------------- + // Synchronize (V2) — DCV-during-sync age-window / per-pass-cap gating. + // Reuses EvaluateDcvSyncEligibility/DcvSyncDecision — the same bounds V1 sync uses, + // applied to the V2 /reports/orders path. + // --------------------------------------------------------------------------- + + private static async IAsyncEnumerable AsyncEnumerable(params T[] items) + { + foreach (var item in items) + yield return item; + await Task.CompletedTask; + } + + private static OrderReportEntryV2 PendingDcvRow(string orderNumber, DateTime orderDateUtc) => + new OrderReportEntryV2 + { + OrderNumber = orderNumber, + OrderStatus = "Order Accepted", + CertificateStatus = "Pending for Approver", + DomainName = "example.com", + OrderDate = orderDateUtc.ToString("o") + }; + + [Fact] + public async Task SynchronizeV2_PendingDcvOrder_AgedOutOfWindow_SkipsDcv_EmitsPendingWithoutResolvingFamily() + { + var mock = NewMock(); + var oldRow = PendingDcvRow("ord_old_001", DateTime.UtcNow.AddHours(-48)); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable(oldRow)); + + // Age window of 1h — the 48h-old order above is well outside it. + var config = new CERTInextConfig + { + UseV2Api = true, ApiUrl = "https://v2.certinext.io", + OAuthClientId = "c", OAuthClientSecret = "s", + DcvEnabled = true, DcvTimeoutMinutes = 1, DcvPropagationDelaySeconds = 1, + DcvSyncMaxOrderAgeHours = 1, DcvSyncMaxPerPass = 0 + }; + var plugin = new CERTInextCAPlugin(mock.Object, new FakeDomainValidatorFactory(new FakeDomainValidator()), config); + + var buffer = new BlockingCollection(100); + await plugin.Synchronize(buffer, DateTime.UtcNow.AddDays(-1), true, CancellationToken.None); + + var records = buffer.ToArray(); + records.Should().ContainSingle(r => r.CARequestID == "ord_old_001" + && r.Status == (int)EndEntityStatus.EXTERNALVALIDATION); + + // Aged-out rows must not even resolve a family — that's the point of the age gate. + mock.Verify(c => c.ResolveAndTrackOrderV2WithFamilyAsync( + It.IsAny(), It.IsAny()), Times.Never); + mock.Verify(c => c.GetDcvV2Async( + It.IsAny(), It.IsAny(), It.IsAny()), Times.Never); + } + + [Fact] + public async Task SynchronizeV2_PendingDcvOrders_ExceedingPerPassCap_OnlyAttemptsUpToCap() + { + var mock = NewMock(); + var row1 = PendingDcvRow("ord_cap_001", DateTime.UtcNow.AddMinutes(-30)); + var row2 = PendingDcvRow("ord_cap_002", DateTime.UtcNow.AddMinutes(-20)); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable(row1, row2)); + + // Only the first (cap=1) row should ever have its family resolved. + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync("ord_cap_001", It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse + { + OrderId = "ord_cap_001", Status = "pending-dcv", Domain = "example.com" + })); + + // Fail fast at GetDcv so PerformDcvV2IfNeededAsync returns false quickly without + // needing the full staging/verify chain mocked — the point of this test is the cap + // gate, not the DCV flow itself. + mock.Setup(c => c.GetDcvV2Async("ord_cap_001", It.IsAny(), It.IsAny())) + .ThrowsAsync(new Exception("simulated transient GetDcv failure")); + + var config = new CERTInextConfig + { + UseV2Api = true, ApiUrl = "https://v2.certinext.io", + OAuthClientId = "c", OAuthClientSecret = "s", + DcvEnabled = true, DcvTimeoutMinutes = 1, DcvPropagationDelaySeconds = 1, + DcvSyncMaxOrderAgeHours = 0, DcvSyncMaxPerPass = 1 + }; + var plugin = new CERTInextCAPlugin(mock.Object, new FakeDomainValidatorFactory(new FakeDomainValidator()), config); + + var buffer = new BlockingCollection(100); + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + var records = buffer.ToArray(); + records.Should().HaveCount(2); + records.Should().OnlyContain(r => r.Status == (int)EndEntityStatus.EXTERNALVALIDATION); + + mock.Verify(c => c.ResolveAndTrackOrderV2WithFamilyAsync("ord_cap_001", It.IsAny()), Times.Once); + mock.Verify(c => c.ResolveAndTrackOrderV2WithFamilyAsync("ord_cap_002", It.IsAny()), Times.Never); + } + + // --------------------------------------------------------------------------- + // UCC additionalDomains SANs must get DCV-validated too — the V2 DCV + // machinery must not only ever drive the order's primary domain. These tests exercise the + // generalized PerformDcvV2MultiDomainAsync path (driven from Track Order's + // verifications.domain.domains[] block) end to end through Enroll/Synchronize, the + // same way the EMS-1080 tests above exercise the single-domain path. + // --------------------------------------------------------------------------- + + private static V2DomainVerificationEntry DomainEntry( + string domain, string dcvStatus, string dcvMethod = null, string verifiedAt = null) => + new V2DomainVerificationEntry + { + Domain = domain, + DomainStatus = "ACTIVE", + DcvStatus = dcvStatus, + DcvMethod = dcvMethod, + VerifiedAt = verifiedAt, + CaaStatus = "SKIPPED" + }; + + private static V2OrderStatusResponse StatusWithDomains(string status, params V2DomainVerificationEntry[] domains) => + new V2OrderStatusResponse + { + OrderId = OrderId, + Status = status, + Domain = domains.FirstOrDefault()?.Domain, + Verifications = new V2Verifications + { + Domain = new V2DomainVerification { Status = "PENDING", Domains = domains.ToList() } + } + }; + + private const string UccPrimary = "example.com"; + private const string UccSanA = "a.pending-san.example.com"; + private const string UccSanB = "b.pending-san.example.com"; + + [Fact] + public async Task PerformDcvV2_Ucc_PrimaryVerified_TwoPendingSans_StagesAndVerifiesOnlyPendingSans_CleansUpAll() + { + var mock = NewMock(); + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = "842", ProductTypeId = "13", Active = true } + }); + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .ReturnsAsync(PlaceOrderResponse()); + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + // 1st TrackOrder call (post-CSR check): primary already VERIFIED, both SANs PENDING. + // Every call after that (the WaitForDomainsVerifiedV2Async poll, and EnrollV2Async's + // own post-DCV re-check) sees the order fully issued with every domain VERIFIED. + int trackCalls = 0; + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(() => + { + trackCalls++; + return trackCalls == 1 + ? StatusWithDomains("pending-dcv", + DomainEntry(UccPrimary, "VERIFIED", "dns-txt"), + DomainEntry(UccSanA, "PENDING"), + DomainEntry(UccSanB, "PENDING")) + : StatusWithDomains("issued", + DomainEntry(UccPrimary, "VERIFIED", "dns-txt"), + DomainEntry(UccSanA, "VERIFIED", "dns-txt"), + DomainEntry(UccSanB, "VERIFIED", "dns-txt")); + }); + + mock.Setup(c => c.GetDcvV2Async(OrderId, UccSanA, It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvChallengeResponse { Token = "token-a", TokenExpiryDate = "2026-12-31 23:59:59" }); + mock.Setup(c => c.GetDcvV2Async(OrderId, UccSanB, It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvChallengeResponse { Token = "token-b", TokenExpiryDate = "2026-12-31 23:59:59" }); + + mock.Setup(c => c.VerifyDcvV2Async(OrderId, UccSanA, It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvVerifyResponse { OverallStatus = "VERIFIED" }); + mock.Setup(c => c.VerifyDcvV2Async(OrderId, UccSanB, It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvVerifyResponse { OverallStatus = "VERIFIED" }); + + mock.Setup(c => c.DownloadCertificateV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(DownloadResponse()); + + var validator = new FakeDomainValidator(); + var plugin = BuildV2DcvPlugin(mock.Object, new FakeDomainValidatorFactory(validator)); + + var result = await Enroll(plugin); + + result.Status.Should().Be((int)EndEntityStatus.GENERATED); + + validator.StagedRecords.Select(r => r.key).Should().BeEquivalentTo( + new[] { $"_emsign-validation.{UccSanA}", $"_emsign-validation.{UccSanB}" }, + "only the two pending SANs should be staged — the already-VERIFIED primary must never be re-challenged"); + + validator.CleanedUpKeys.Should().BeEquivalentTo( + new[] { $"_emsign-validation.{UccSanA}", $"_emsign-validation.{UccSanB}" }, + "every staged record must be cleaned up"); + + mock.Verify(c => c.GetDcvV2Async(OrderId, UccPrimary, It.IsAny(), It.IsAny()), Times.Never); + mock.Verify(c => c.VerifyDcvV2Async(OrderId, UccPrimary, It.IsAny(), It.IsAny()), Times.Never); + } + + [Fact] + public async Task PerformDcvV2_Ucc_OneSanVerifyFails_OtherStillVerified_AllCleanedUp_OrderStaysPending() + { + var mock = NewMock(); + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = "842", ProductTypeId = "13", Active = true } + }); + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .ReturnsAsync(PlaceOrderResponse()); + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + // 1st call: post-CSR, both SANs pending. Every later call (the poll for the one SAN + // that DID verify, and EnrollV2Async's post-DCV re-check): SanA verified, SanB still + // pending — the order legitimately cannot advance further this pass. + int trackCalls = 0; + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(() => + { + trackCalls++; + return trackCalls == 1 + ? StatusWithDomains("pending-dcv", + DomainEntry(UccPrimary, "VERIFIED", "dns-txt"), + DomainEntry(UccSanA, "PENDING"), + DomainEntry(UccSanB, "PENDING")) + : StatusWithDomains("pending-dcv", + DomainEntry(UccPrimary, "VERIFIED", "dns-txt"), + DomainEntry(UccSanA, "VERIFIED", "dns-txt"), + DomainEntry(UccSanB, "PENDING")); + }); + + mock.Setup(c => c.GetDcvV2Async(OrderId, UccSanA, It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvChallengeResponse { Token = "token-a", TokenExpiryDate = "2026-12-31 23:59:59" }); + mock.Setup(c => c.GetDcvV2Async(OrderId, UccSanB, It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvChallengeResponse { Token = "token-b", TokenExpiryDate = "2026-12-31 23:59:59" }); + + mock.Setup(c => c.VerifyDcvV2Async(OrderId, UccSanA, It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvVerifyResponse { OverallStatus = "VERIFIED" }); + mock.Setup(c => c.VerifyDcvV2Async(OrderId, UccSanB, It.IsAny(), It.IsAny())) + .ThrowsAsync(new Exception("simulated transient verify failure for SanB")); + + var validator = new FakeDomainValidator(); + // PickupRetries > 0 (mirrors the single-domain test above): confirms dcvV2Ran still + // gates the pickup poll even on the partial-failure multi-domain path. + var plugin = BuildV2DcvPlugin(mock.Object, new FakeDomainValidatorFactory(validator), pickupRetries: 5); + + var result = await Enroll(plugin); + + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION, + "SanB never verified, so the order must stay pending — not be treated as failed or issued"); + result.CARequestID.Should().Be(OrderId); + + validator.CleanedUpKeys.Should().BeEquivalentTo( + new[] { $"_emsign-validation.{UccSanA}", $"_emsign-validation.{UccSanB}" }, + "both staged records must be cleaned up regardless of SanB's verify failure"); + + mock.Verify(c => c.VerifyDcvV2Async(OrderId, UccSanA, It.IsAny(), It.IsAny()), Times.Once); + mock.Verify(c => c.VerifyDcvV2Async(OrderId, UccSanB, It.IsAny(), It.IsAny()), Times.Once); + mock.Verify(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny()), + Times.Exactly(3), + "a pickup poll must not stack on top of the inline DCV wait — no 4th TrackOrderV2Async call"); + mock.Verify(c => c.DownloadCertificateV2Async( + It.IsAny(), It.IsAny(), It.IsAny()), Times.Never); + } + + [Fact] + public async Task SynchronizeV2_Ucc_OneSanStillPendingFromAnEarlierPass_OnlyThatSanIsProcessed() + { + var mock = NewMock(); + const string syncOrderId = "ord_ucc_sync_001"; + var row = PendingDcvRow(syncOrderId, DateTime.UtcNow.AddMinutes(-10)); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable(row)); + + // Primary and SanA were already verified on an earlier sync pass; only SanB remains. + var pendingStatus = new V2OrderStatusResponse + { + OrderId = syncOrderId, + Status = "pending-dcv", + Domain = UccPrimary, + Verifications = new V2Verifications + { + Domain = new V2DomainVerification + { + Status = "PENDING", + Domains = new List + { + DomainEntry(UccPrimary, "VERIFIED", "dns-txt"), + DomainEntry(UccSanA, "VERIFIED", "dns-txt"), + DomainEntry(UccSanB, "PENDING") + } + } + } + }; + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync(syncOrderId, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, pendingStatus)); + + mock.Setup(c => c.GetDcvV2Async(syncOrderId, UccSanB, It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvChallengeResponse { Token = "token-b", TokenExpiryDate = "2026-12-31 23:59:59" }); + mock.Setup(c => c.VerifyDcvV2Async(syncOrderId, UccSanB, It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvVerifyResponse { OverallStatus = "VERIFIED" }); + + var issuedStatus = new V2OrderStatusResponse + { + OrderId = syncOrderId, + Status = "issued", + Domain = UccPrimary, + Verifications = new V2Verifications + { + Domain = new V2DomainVerification + { + Status = "VERIFIED", + Domains = new List + { + DomainEntry(UccPrimary, "VERIFIED", "dns-txt"), + DomainEntry(UccSanA, "VERIFIED", "dns-txt"), + DomainEntry(UccSanB, "VERIFIED", "dns-txt") + } + } + } + }; + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), syncOrderId, It.IsAny())) + .ReturnsAsync(issuedStatus); + mock.Setup(c => c.ResolveAndTrackOrderV2Async(syncOrderId, It.IsAny())) + .ReturnsAsync(issuedStatus); + mock.Setup(c => c.ResolveAndDownloadCertificateV2Async(syncOrderId, It.IsAny())) + .ReturnsAsync(new V2CertificateDownloadResponse + { + OrderId = syncOrderId, SerialNumber = "AA11BB22", CertificatePem = MockCertificateData.FakePemCertificate + }); + + var config = new CERTInextConfig + { + UseV2Api = true, ApiUrl = "https://v2.certinext.io", + OAuthClientId = "c", OAuthClientSecret = "s", + DcvEnabled = true, DcvTimeoutMinutes = 1, DcvPropagationDelaySeconds = 1, + DcvSyncMaxOrderAgeHours = 0, DcvSyncMaxPerPass = 0 + }; + var validator = new FakeDomainValidator(); + var plugin = new CERTInextCAPlugin(mock.Object, new FakeDomainValidatorFactory(validator), config); + + var buffer = new BlockingCollection(100); + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + buffer.ToArray().Should().ContainSingle(r => r.CARequestID == syncOrderId); + + mock.Verify(c => c.GetDcvV2Async(syncOrderId, UccSanB, It.IsAny(), It.IsAny()), Times.Once); + mock.Verify(c => c.GetDcvV2Async(syncOrderId, UccSanA, It.IsAny(), It.IsAny()), Times.Never); + mock.Verify(c => c.GetDcvV2Async(syncOrderId, UccPrimary, It.IsAny(), It.IsAny()), Times.Never); + mock.Verify(c => c.GetDcvV2Async(It.IsAny(), It.IsAny(), It.IsAny()), Times.Never, + "the no-domain single-domain-fallback overload must not be used once domainEntries is populated"); + + validator.StagedRecords.Should().ContainSingle(); + validator.CleanedUpKeys.Should().ContainSingle(); + } + + [Fact] + public async Task PerformDcvV2_DomainsArrayAbsent_UsesSingleDomainFallback_NeverThePerDomainOverload() + { + var mock = NewMock(); + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = "842", ProductTypeId = "13", Active = true } + }); + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .ReturnsAsync(PlaceOrderResponse()); + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + // No Verifications block anywhere in this sequence — the single-domain shape. + mock.SetupSequence(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(PendingDcvStatus()) + .ReturnsAsync(IssuedStatus()) + .ReturnsAsync(IssuedStatus()); + + mock.Setup(c => c.GetDcvV2Async(OrderId, It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvChallengeResponse { Token = "legacy-token", TokenExpiryDate = "2026-12-31 23:59:59" }); + mock.Setup(c => c.VerifyDcvV2Async(OrderId, "example.com", It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvVerifyResponse { OverallStatus = "VERIFIED" }); + mock.Setup(c => c.DownloadCertificateV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(DownloadResponse()); + + var validator = new FakeDomainValidator(); + var plugin = BuildV2DcvPlugin(mock.Object, new FakeDomainValidatorFactory(validator)); + + var result = await Enroll(plugin); + + result.Status.Should().Be((int)EndEntityStatus.GENERATED); + validator.StagedRecords.Should().ContainSingle(); + + // The 4-argument (per-domain) overload is a distinct method — confirming it was + // never called proves the domainEntries-absent case took the single-domain path, + // not the generalized multi-domain one, keeping today's primary-domain + // behaviour exactly. + mock.Verify(c => c.GetDcvV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny()), + Times.Never); + } + + [Fact] + public async Task PerformDcvV2_Ucc_Ems1080OnPendingSan_TreatedAsVerified_NotAnError_NoStagingOrVerify() + { + var mock = NewMock(); + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = "842", ProductTypeId = "13", Active = true } + }); + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .ReturnsAsync(PlaceOrderResponse()); + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + int trackCalls = 0; + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(() => + { + trackCalls++; + return trackCalls == 1 + ? StatusWithDomains("pending-dcv", + DomainEntry(UccPrimary, "VERIFIED", "dns-txt"), + DomainEntry(UccSanA, "PENDING")) + : StatusWithDomains("issued", + DomainEntry(UccPrimary, "VERIFIED", "dns-txt"), + DomainEntry(UccSanA, "VERIFIED", "dns-txt")); + }); + + // EMS-1080 at GetDcv for the pending SAN — the domain became verified CA-side + // between Track Order reporting it pending and this challenge fetch. + mock.Setup(c => c.GetDcvV2Async(OrderId, UccSanA, It.IsAny(), It.IsAny())) + .ThrowsAsync(new Exception( + "CERTInext V2 API error during 'V2 get DCV challenge (per-domain)'. HTTP 422. " + + "Unprocessable Entity: EMS-1080 Domain is already verified.")); + + mock.Setup(c => c.DownloadCertificateV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(DownloadResponse()); + + var validator = new FakeDomainValidator(); + var plugin = BuildV2DcvPlugin(mock.Object, new FakeDomainValidatorFactory(validator)); + + var result = await Enroll(plugin); + + result.Status.Should().Be((int)EndEntityStatus.GENERATED, + "EMS-1080 on a pending SAN must be treated as already verified, not a failure"); + validator.StagedRecords.Should().BeEmpty( + "EMS-1080 at GetDcv means there is no fresh challenge to publish for this SAN"); + validator.CleanedUpKeys.Should().BeEmpty("nothing was staged, so there is nothing to clean up"); + + mock.Verify(c => c.VerifyDcvV2Async( + OrderId, UccSanA, It.IsAny(), It.IsAny()), + Times.Never, + "VerifyDcv must never be reached for a domain GetDcv already reported as verified"); + } + + [Fact] + public void V2OrderStatusResponse_Deserializes_PendingSanDomainsArray_WithoutDcvMethod() + { + // Pending-SAN challenge shape: pending entries carry no "dcvMethod" key at all; it + // only appears once an entry reaches VERIFIED. + const string rawJson = @"{ + ""orderId"": ""7465857196"", + ""status"": ""pending-approval"", + ""domain"": ""ucc-pending-202609290046.dcv-test.scrup.org"", + ""verifications"": { + ""domain"": { + ""status"": ""PENDING"", + ""domains"": [ + {""domain"":""a.pending-202609290046.example.com"",""domainStatus"":""ACTIVE"",""dcvStatus"":""PENDING"",""caaStatus"":""SKIPPED""}, + {""domain"":""b.pending-202609290046.example.com"",""domainStatus"":""ACTIVE"",""dcvStatus"":""PENDING"",""caaStatus"":""SKIPPED""}, + {""domain"":""ucc-pending-202609290046.dcv-test.scrup.org"",""domainStatus"":""ACTIVE"",""dcvMethod"":""dns-txt"",""dcvStatus"":""VERIFIED"",""verifiedAt"":""2026-09-29T00:46:09Z"",""caaStatus"":""PASSED""} + ] + }, + ""empty"": false + } + }"; + + // Null-forgiving here: System.Text.Json's Deserialize is annotated to return + // T?, but a successfully-parsed non-null JSON object (as above) never actually + // produces a null reference — the Should().NotBeNull() below is the runtime + // guarantee backing that, which the compiler's static analysis can't see through. + var result = JsonSerializer.Deserialize(rawJson)!; + + result.Should().NotBeNull(); + result.Verifications.Should().NotBeNull(); + result.Verifications.Domain.Should().NotBeNull(); + result.Verifications.Domain.Status.Should().Be("PENDING"); + result.Verifications.Domain.Domains.Should().HaveCount(3); + + var sanA = result.Verifications.Domain.Domains.Single(d => d.Domain == "a.pending-202609290046.example.com"); + sanA.DcvStatus.Should().Be("PENDING"); + sanA.DcvMethod.Should().BeNull("pending entries carry no dcvMethod key at all — absent, not present-but-null-looking"); + sanA.VerifiedAt.Should().BeNull(); + + var verifiedPrimary = result.Verifications.Domain.Domains.Single( + d => d.Domain == "ucc-pending-202609290046.dcv-test.scrup.org"); + verifiedPrimary.DcvStatus.Should().Be("VERIFIED"); + verifiedPrimary.DcvMethod.Should().Be("dns-txt"); + verifiedPrimary.VerifiedAt.Should().Be("2026-09-29T00:46:09Z"); + } + + // --------------------------------------------------------------------------- + // DCV exists only for the SSL/TLS family. Spec: the DCV endpoints live + // under /ssl-certificates only; Private PKI: "No DCV - your CA trusts you"; Document + // Signer has no DCV step. PerformDcvV2IfNeededAsync's family gate must stop every caller + // (Enroll, GetSingleRecord, Synchronize) from hitting a nonexistent + // /{family}/{orderId}/dcv endpoint for a non-SSL order that is merely pending. + // --------------------------------------------------------------------------- + + private static void SetupDcvCallsSoStrictMockDoesNotThrow(Mock mock) + { + // Set up (rather than leave unset) so a regression would be recorded as an invocation + // and caught by Verify(Times.Never), instead of throwing a MockException that + // PerformDcvV2IfNeededAsync's own error handling might swallow. + mock.Setup(c => c.GetDcvV2Async(It.IsAny(), It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvChallengeResponse { Token = "should-never-be-fetched" }); + mock.Setup(c => c.GetDcvV2Async(It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvChallengeResponse { Token = "should-never-be-fetched" }); + mock.Setup(c => c.VerifyDcvV2Async(It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvVerifyResponse()); + } + + private static void VerifyNoDcvCalls(Mock mock, FakeDomainValidator validator) + { + mock.Verify(c => c.GetDcvV2Async(It.IsAny(), It.IsAny(), It.IsAny()), Times.Never); + mock.Verify(c => c.GetDcvV2Async(It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny()), Times.Never); + mock.Verify(c => c.VerifyDcvV2Async(It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny()), Times.Never); + validator.StagedRecords.Should().BeEmpty("no TXT record may be published for a non-SSL order"); + } + + [Fact] + public async Task Enroll_V2_PrivatePki_PendingOrder_NeverAttemptsDcv_EvenWithDcvEnabled() + { + const string pkiOrderId = "ord_pki_dcv_001"; + var mock = NewMock(); + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = pkiOrderId, Status = "pending-csr" }); + mock.Setup(c => c.SubmitCsrV2Async( + Constants.ApiV2.FamilyPrivatePki, pkiOrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + // Even a (spec-impossible) pending-dcv status, with a domain block, must not trigger DCV. + mock.Setup(c => c.TrackOrderV2Async(Constants.ApiV2.FamilyPrivatePki, pkiOrderId, It.IsAny())) + .ReturnsAsync(StatusWithDomains("pending-dcv", DomainEntry("intranet.acme.local", "PENDING"))); + SetupDcvCallsSoStrictMockDoesNotThrow(mock); + + var validator = new FakeDomainValidator(); + var plugin = BuildV2DcvPlugin(mock.Object, new FakeDomainValidatorFactory(validator)); + + var result = await plugin.Enroll( + csr: MockCertificateData.FakeCsrPem, + subject: "CN=intranet.acme.local", + san: new Dictionary { ["dnsname"] = new[] { "intranet.acme.local" } }, + productInfo: new EnrollmentProductInfo + { + ProductID = "DV SSL", + ProductParameters = new Dictionary(System.StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = "149", + ["ProductFamily"] = "private-pki", + ["ProductVariant"] = "intranet-ssl" + } + }, + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + result.CARequestID.Should().Be(pkiOrderId); + VerifyNoDcvCalls(mock, validator); + } + + [Fact] + public async Task GetSingleRecord_V2_PrivatePkiOrder_PendingWithDomain_NeverAttemptsDcv() + { + const string pkiOrderId = "ord_pki_dcv_002"; + var mock = NewMock(); + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync(pkiOrderId, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilyPrivatePki, new V2OrderStatusResponse + { + OrderId = pkiOrderId, Status = "pending-dcv", Domain = "intranet.acme.local" + })); + SetupDcvCallsSoStrictMockDoesNotThrow(mock); + + var validator = new FakeDomainValidator(); + var plugin = BuildV2DcvPlugin(mock.Object, new FakeDomainValidatorFactory(validator)); + + var record = await plugin.GetSingleRecord(pkiOrderId); + + record.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + VerifyNoDcvCalls(mock, validator); + } + + [Fact] + public async Task SynchronizeV2_PendingPrivatePkiOrder_ResolvedToPrivatePkiFamily_NeverAttemptsDcv() + { + // A private-pki order in pending-approval surfaces in /reports/orders exactly like a + // pending DV order ("Order Accepted" / "Pending for Approver", with a domainName) — sync + // must resolve its family correctly rather than calling /private-pki-certificates/{id}/dcv. + var mock = NewMock(); + var row = PendingDcvRow("ord_pki_sync_001", DateTime.UtcNow.AddMinutes(-10)); + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable(row)); + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync("ord_pki_sync_001", It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilyPrivatePki, new V2OrderStatusResponse + { + OrderId = "ord_pki_sync_001", Status = "pending-approval" + })); + SetupDcvCallsSoStrictMockDoesNotThrow(mock); + + var validator = new FakeDomainValidator(); + var config = new CERTInextConfig + { + UseV2Api = true, ApiUrl = "https://v2.certinext.io", + OAuthClientId = "c", OAuthClientSecret = "s", + DcvEnabled = true, DcvTimeoutMinutes = 1, DcvPropagationDelaySeconds = 1, + DcvSyncMaxOrderAgeHours = 0, DcvSyncMaxPerPass = 0 + }; + var plugin = new CERTInextCAPlugin(mock.Object, new FakeDomainValidatorFactory(validator), config); + + var buffer = new BlockingCollection(100); + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + buffer.ToArray().Should().ContainSingle(r => r.CARequestID == "ord_pki_sync_001" + && r.Status == (int)EndEntityStatus.EXTERNALVALIDATION); + VerifyNoDcvCalls(mock, validator); + } + + // --------------------------------------------------------------------------- + // Wildcard domains — TXT hostname must be derived from the BASE domain + // --------------------------------------------------------------------------- + // + // A wildcard V2 DV order's TXT host must not be staged as + // "_emsign-validation.*.example.com" — a literal '*' DNS label is + // not queryable and leaves the order stuck pending. CERTInext's own GetDcvV2/VerifyDcvV2/ + // TrackOrderV2 calls must still use the original "*."-prefixed domain string; only the + // DNS-side hostname/zone resolution uses the base domain. + + [Fact] + public async Task PerformDcvV2_WildcardSingleDomain_StagesBaseDomainHostname_ButCallsCaWithWildcardDomain() + { + const string baseName = "example.com"; + string wildcard = "*." + baseName; + + var mock = NewMock(); + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = "842", ProductTypeId = "13", Active = true } + }); + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .ReturnsAsync(PlaceOrderResponse()); + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + mock.SetupSequence(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "pending-dcv", Domain = wildcard }) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "issued", Domain = wildcard }) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "issued", Domain = wildcard }); + + mock.Setup(c => c.GetDcvV2Async(OrderId, It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvChallengeResponse { Token = "wildcard-token", TokenExpiryDate = "2026-12-31 23:59:59" }); + + mock.Setup(c => c.VerifyDcvV2Async(OrderId, wildcard, It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvVerifyResponse { OverallStatus = "VERIFIED" }); + + mock.Setup(c => c.DownloadCertificateV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(DownloadResponse()); + + var validator = new FakeDomainValidator(); + var plugin = BuildV2DcvPlugin(mock.Object, new FakeDomainValidatorFactory(validator)); + + var productInfo = new EnrollmentProductInfo + { + ProductID = "DV SSL", + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = "842", + ["ProductFamily"] = "ssl", + ["ProductVariant"] = "dv", + ["DomainName"] = wildcard + } + }; + + var result = await plugin.Enroll( + csr: MockCertificateData.FakeCsrPem, + subject: $"CN={wildcard}", + san: new Dictionary { ["dns"] = new[] { wildcard } }, + productInfo: productInfo, + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.Status.Should().Be((int)EndEntityStatus.GENERATED); + + // The TXT hostname must be built from the base domain, not the literal + // "*.example.com" — a "*" DNS label is not queryable. + validator.StagedRecords.Should().ContainSingle() + .Which.key.Should().Be($"_emsign-validation.{baseName}"); + validator.StagedRecords.Should().OnlyContain(r => !r.key.Contains('*'), + "a literal '*' DNS label can never be queried by the CA"); + + // CERTInext's own API must still see the original wildcard domain string. + mock.Verify(c => c.VerifyDcvV2Async(OrderId, wildcard, It.IsAny(), It.IsAny()), + Times.Once); + } + + [Fact] + public async Task PerformDcvV2_Ucc_ApexAndWildcardShareHostname_StagesOnceAndCleansUpOnce_ButVerifiesBothWithCa() + { + const string apex = "example.com"; + string wildcard = "*." + apex; + + var mock = NewMock(); + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = "842", ProductTypeId = "13", Active = true } + }); + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .ReturnsAsync(PlaceOrderResponse()); + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + // 1st call (post-CSR check): both the apex and its wildcard are pending. Every later + // call (WaitForDomainsVerifiedV2Async's poll, and EnrollV2Async's post-DCV re-check) + // sees the order fully issued with both VERIFIED. + int trackCalls = 0; + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(() => + { + trackCalls++; + return trackCalls == 1 + ? StatusWithDomains("pending-dcv", + DomainEntry(apex, "PENDING"), + DomainEntry(wildcard, "PENDING")) + : StatusWithDomains("issued", + DomainEntry(apex, "VERIFIED", "dns-txt"), + DomainEntry(wildcard, "VERIFIED", "dns-txt")); + }); + + mock.Setup(c => c.GetDcvV2Async(OrderId, apex, It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvChallengeResponse { Token = "token-shared", TokenExpiryDate = "2026-12-31 23:59:59" }); + mock.Setup(c => c.GetDcvV2Async(OrderId, wildcard, It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvChallengeResponse { Token = "token-shared", TokenExpiryDate = "2026-12-31 23:59:59" }); + + mock.Setup(c => c.VerifyDcvV2Async(OrderId, apex, It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvVerifyResponse { OverallStatus = "VERIFIED" }); + mock.Setup(c => c.VerifyDcvV2Async(OrderId, wildcard, It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvVerifyResponse { OverallStatus = "VERIFIED" }); + + mock.Setup(c => c.DownloadCertificateV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(DownloadResponse()); + + var validator = new FakeDomainValidator(); + var plugin = BuildV2DcvPlugin(mock.Object, new FakeDomainValidatorFactory(validator)); + + var result = await Enroll(plugin); + + result.Status.Should().Be((int)EndEntityStatus.GENERATED); + + // The apex and its wildcard collapse to the same base-domain TXT hostname AND carry the + // same token — exactly ONE record must be staged (and cleaned up), not two. + validator.StagedRecords.Should().ContainSingle( + "the apex and wildcard domains share one base-domain TXT hostname") + .Which.key.Should().Be($"_emsign-validation.{apex}"); + validator.CleanedUpKeys.Should().ContainSingle( + "the shared hostname must be cleaned up exactly once, not once per domain that used it") + .Which.Should().Be($"_emsign-validation.{apex}"); + + // CERTInext tracks DCV per domain entry, so both the apex and the wildcard still need + // their own CA-side GetDcv/VerifyDcv call even though they share one TXT record. + mock.Verify(c => c.GetDcvV2Async(OrderId, apex, It.IsAny(), It.IsAny()), Times.Once); + mock.Verify(c => c.GetDcvV2Async(OrderId, wildcard, It.IsAny(), It.IsAny()), Times.Once); + mock.Verify(c => c.VerifyDcvV2Async(OrderId, apex, It.IsAny(), It.IsAny()), Times.Once); + mock.Verify(c => c.VerifyDcvV2Async(OrderId, wildcard, It.IsAny(), It.IsAny()), Times.Once); + } + + [Fact] + public async Task PerformDcvV2_Ucc_ApexAndWildcardShareHostnameButDifferentTokens_StagesBothAndCleansUpBoth() + { + const string apex = "example.com"; + string wildcard = "*." + apex; + + var mock = NewMock(); + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = "842", ProductTypeId = "13", Active = true } + }); + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .ReturnsAsync(PlaceOrderResponse()); + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + int trackCalls = 0; + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(() => + { + trackCalls++; + return trackCalls == 1 + ? StatusWithDomains("pending-dcv", + DomainEntry(apex, "PENDING"), + DomainEntry(wildcard, "PENDING")) + : StatusWithDomains("issued", + DomainEntry(apex, "VERIFIED", "dns-txt"), + DomainEntry(wildcard, "VERIFIED", "dns-txt")); + }); + + mock.Setup(c => c.GetDcvV2Async(OrderId, apex, It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvChallengeResponse { Token = "token-apex", TokenExpiryDate = "2026-12-31 23:59:59" }); + mock.Setup(c => c.GetDcvV2Async(OrderId, wildcard, It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvChallengeResponse { Token = "token-wildcard", TokenExpiryDate = "2026-12-31 23:59:59" }); + + mock.Setup(c => c.VerifyDcvV2Async(OrderId, apex, It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvVerifyResponse { OverallStatus = "VERIFIED" }); + mock.Setup(c => c.VerifyDcvV2Async(OrderId, wildcard, It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2DcvVerifyResponse { OverallStatus = "VERIFIED" }); + + mock.Setup(c => c.DownloadCertificateV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(DownloadResponse()); + + var validator = new FakeDomainValidator(); + var plugin = BuildV2DcvPlugin(mock.Object, new FakeDomainValidatorFactory(validator)); + + var result = await Enroll(plugin); + + result.Status.Should().Be((int)EndEntityStatus.GENERATED); + + // Same base-domain hostname but two different CA tokens: a single record cannot satisfy + // both, so BOTH values must be staged at that hostname and both cleaned up. + string hostname = $"_emsign-validation.{apex}"; + validator.StagedRecords.Should().HaveCount(2); + validator.StagedRecords.Select(r => r.key).Should().OnlyContain(k => k == hostname); + validator.StagedRecords.Select(r => r.value).Should().BeEquivalentTo(new[] { "token-apex", "token-wildcard" }); + validator.CleanedUpKeys.Should().HaveCount(2); + validator.CleanedUpKeys.Should().OnlyContain(k => k == hostname); + + mock.Verify(c => c.VerifyDcvV2Async(OrderId, apex, It.IsAny(), It.IsAny()), Times.Once); + mock.Verify(c => c.VerifyDcvV2Async(OrderId, wildcard, It.IsAny(), It.IsAny()), Times.Once); + } + } +} diff --git a/CERTInext.Tests/CERTInextCAPluginV2EnrollRevokedTests.cs b/CERTInext.Tests/CERTInextCAPluginV2EnrollRevokedTests.cs new file mode 100644 index 0000000..e0a23db --- /dev/null +++ b/CERTInext.Tests/CERTInextCAPluginV2EnrollRevokedTests.cs @@ -0,0 +1,251 @@ +// Copyright 2026 Keyfactor +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; +using System.Collections.Generic; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Moq; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// At enroll time the gateway never holds a stored + /// certificate body for a brand-new V2 order, so a REVOKED disposition surfaced from + /// EnrollV2Async — whether observed on the post-CSR-submit status check or during the + /// synchronous pickup poll (PickUpEnrolledCertificateV2Async) — is always body-less. + /// Letting that flow straight through to 's + /// caller as Status=REVOKED, Certificate=null is exactly the shape that poisons + /// the gateway (RevocationDate never clears; every later revoked-certificate + /// search calls FromDER(null) and 500s). These tests drive that handling end-to-end through + /// (V2 path), mirroring + /// CERTInextCAPluginV2PickupTests's mocking patterns. The DCV-gated variant of this + /// scenario (REVOKED observed on the post-DCV status re-check) lives in + /// CERTInextCAPluginV2DcvTests since it needs a domain validator factory and only + /// compiles when SUPPORTS_DCV is defined. + /// + public class CERTInextCAPluginV2EnrollRevokedTests + { + private static Mock NewMock() => + new Mock(MockBehavior.Strict); + + private static CERTInextCAPlugin BuildV2PluginWithPickup( + ICERTInextClient client, int retries, int delaySeconds = 1) => + new CERTInextCAPlugin(client, new CERTInextConfig + { + UseV2Api = true, + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + AccountNumber = "12345", + AuthMode = "AccessKey", + ApiKey = "v1-key", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + SignerIp = "1.2.3.4", + SignerPlace = "New York", + PickupRetries = retries, + PickupDelayInSeconds = delaySeconds + }); + + private static EnrollmentProductInfo MakeV2ProductInfo() => + new EnrollmentProductInfo + { + ProductID = "DV SSL", + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = "842", + ["ProductFamily"] = "ssl", + ["ProductVariant"] = "dv", + ["DomainName"] = "example.com" + } + }; + + /// + /// Every V2 enrollment resolves the requested product's productTypeID from the + /// live Catalog to decide UCC-ness — any Strict-mock enroll test must stub this call + /// regardless of whether the test cares about UCC behavior (mirrors StubCatalog in + /// CERTInextCAPluginV2PickupTests.cs). + /// + private static void StubCatalog(Mock mock) => + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = "842", ProductTypeId = "13", Active = true } // non-UCC + }); + + private const string OrderId = "ord_revoked_001"; + + private static Task Enroll(CERTInextCAPlugin plugin) => + plugin.Enroll( + csr: MockCertificateData.FakeCsrPem, + subject: "CN=example.com", + san: new Dictionary(), + productInfo: MakeV2ProductInfo(), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + private static void StubPlaceAndSubmit(Mock mock, string initialStatus) => + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = OrderId, Status = initialStatus }); + + // --------------------------------------------------------------------------- + // REVOKED on the status check immediately after CSR submit -> FAILED + // --------------------------------------------------------------------------- + + [Fact] + public async Task Enroll_RevokedImmediatelyAfterCsrSubmit_ReturnsFailed_NotBodylessRevoked() + { + var mock = NewMock(); + StubCatalog(mock); + StubPlaceAndSubmit(mock, "pending-csr"); + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + // The very first status check after CSR submission already reports the order as + // revoked — there was never a chance for a certificate body to exist. + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "revoked" }); + + var plugin = BuildV2PluginWithPickup(mock.Object, retries: 3); + + var result = await Enroll(plugin); + + result.Status.Should().Be((int)EndEntityStatus.FAILED, + "a REVOKED order observed right after CSR submission has no certificate body and " + + "must never be reported as REVOKED"); + result.Certificate.Should().BeNull(); + result.CARequestID.Should().Be(OrderId); + result.StatusMessage.Should().Contain(OrderId).And.Contain("revoked"); + + // A terminal (non-EXTERNALVALIDATION) disposition must never enter the pickup poll. + mock.Verify(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny()), + Times.Once, "a terminal REVOKED disposition observed pre-poll must not trigger the pickup poll"); + mock.Verify(c => c.DownloadCertificateV2Async( + It.IsAny(), It.IsAny(), It.IsAny()), Times.Never); + } + + // --------------------------------------------------------------------------- + // REVOKED discovered during the synchronous pickup poll -> FAILED + // --------------------------------------------------------------------------- + + [Fact] + public async Task Enroll_RevokedDuringPickupPoll_ReturnsFailed_NotBodylessRevoked() + { + var mock = NewMock(); + StubCatalog(mock); + StubPlaceAndSubmit(mock, "pending-csr"); + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + // Post-CSR check is still pending; the first (and only) poll attempt observes the + // order was revoked at the CA before ever issuing. + mock.SetupSequence(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "pending-dcv" }) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "revoked" }); + + var plugin = BuildV2PluginWithPickup(mock.Object, retries: 3); + + var result = await Enroll(plugin); + + result.Status.Should().Be((int)EndEntityStatus.FAILED, + "a REVOKED disposition discovered mid-poll has no certificate body and must never " + + "be reported as REVOKED"); + result.Certificate.Should().BeNull(); + result.CARequestID.Should().Be(OrderId); + result.StatusMessage.Should().Contain(OrderId).And.Contain("revoked"); + + mock.Verify(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny()), + Times.Exactly(2), "the poll must stop at the first terminal observation, not run all 3 retries"); + mock.Verify(c => c.DownloadCertificateV2Async( + It.IsAny(), It.IsAny(), It.IsAny()), Times.Never); + } + + // --------------------------------------------------------------------------- + // A genuinely FAILED disposition must pass through unchanged + // --------------------------------------------------------------------------- + + [Fact] + public async Task Enroll_FailedDuringPickupPoll_StaysFailed() + { + var mock = NewMock(); + StubCatalog(mock); + StubPlaceAndSubmit(mock, "pending-csr"); + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + mock.SetupSequence(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "pending-dcv" }) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "rejected" }); + + var plugin = BuildV2PluginWithPickup(mock.Object, retries: 3); + + var result = await Enroll(plugin); + + result.Status.Should().Be((int)EndEntityStatus.FAILED, + "a genuinely FAILED disposition must pass through the REVOKED->FAILED " + + "normalization unchanged"); + result.CARequestID.Should().Be(OrderId); + } + + // --------------------------------------------------------------------------- + // A genuinely issued certificate must pass through unchanged + // --------------------------------------------------------------------------- + + [Fact] + public async Task Enroll_IssuedDuringPickupPoll_StaysGenerated_WithCertificate() + { + var mock = NewMock(); + StubCatalog(mock); + StubPlaceAndSubmit(mock, "pending-csr"); + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + mock.SetupSequence(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "pending-dcv" }) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "issued" }); + + mock.Setup(c => c.DownloadCertificateV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(new V2CertificateDownloadResponse + { + OrderId = OrderId, + SerialNumber = "AABBCC", + CertificatePem = MockCertificateData.FakePemCertificate + }); + + var plugin = BuildV2PluginWithPickup(mock.Object, retries: 2); + + var result = await Enroll(plugin); + + result.Status.Should().Be((int)EndEntityStatus.GENERATED, + "a genuinely issued certificate must pass through the REVOKED->FAILED " + + "normalization unchanged"); + result.Certificate.Should().StartWith("-----BEGIN CERTIFICATE-----"); + result.CARequestID.Should().Be(OrderId); + } + } +} diff --git a/CERTInext.Tests/CERTInextCAPluginV2PickupTests.cs b/CERTInext.Tests/CERTInextCAPluginV2PickupTests.cs new file mode 100644 index 0000000..5c92bbe --- /dev/null +++ b/CERTInext.Tests/CERTInextCAPluginV2PickupTests.cs @@ -0,0 +1,282 @@ +// Copyright 2026 Keyfactor +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; +using System.Collections.Generic; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Moq; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Coverage for the V2 synchronous certificate-pickup poll, analogous to + /// PickUpEnrolledCertificateAsync (V1). These tests exercise + /// PickUpEnrolledCertificateV2Async end-to-end through + /// (V2 path), the same way CERTInextCAPluginTests's "Synchronous certificate pickup" + /// section exercises the V1 method. No domain validator factory is configured here, so the + /// inline DCV block (when compiled) short-circuits immediately (factory null) and never sets + /// dcvV2Ran — DCV-vs-pickup interaction is covered separately in + /// CERTInextCAPluginV2DcvTests. + /// + public class CERTInextCAPluginV2PickupTests + { + private static Mock NewMock() => + new Mock(MockBehavior.Strict); + + // PickupDelay is clamped to a 1s floor and the loop adds a fixed 5s initial delay + // (Constants.Pickup.InitialDelaySeconds), so these tests are intentionally a few + // seconds each — mirrors BuildPluginWithPickup in CERTInextCAPluginTests.cs. + private static CERTInextCAPlugin BuildV2PluginWithPickup( + ICERTInextClient client, int retries, int delaySeconds = 1) => + new CERTInextCAPlugin(client, new CERTInextConfig + { + UseV2Api = true, + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + AccountNumber = "12345", + AuthMode = "AccessKey", + ApiKey = "v1-key", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + SignerIp = "1.2.3.4", + SignerPlace = "New York", + PickupRetries = retries, + PickupDelayInSeconds = delaySeconds + }); + + private static EnrollmentProductInfo MakeV2ProductInfo() => + new EnrollmentProductInfo + { + ProductID = "DV SSL", + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = "842", + ["ProductFamily"] = "ssl", + ["ProductVariant"] = "dv", + ["DomainName"] = "example.com" + } + }; + + /// + /// Every V2 enrollment resolves the requested product's productTypeID from the + /// live Catalog to decide UCC-ness — any Strict-mock enroll test must stub this call + /// regardless of whether the test cares about UCC behavior (mirrors StubCatalog in + /// CERTInextCAPluginV2Tests.cs). + /// + private static void StubCatalog(Mock mock) => + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = "842", ProductTypeId = "13", Active = true } // non-UCC + }); + + private const string OrderId = "ord_pickup_001"; + + private static Task Enroll(CERTInextCAPlugin plugin) => + plugin.Enroll( + csr: MockCertificateData.FakeCsrPem, + subject: "CN=example.com", + san: new Dictionary(), + productInfo: MakeV2ProductInfo(), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + private static void StubPlaceAndSubmit(Mock mock, string initialStatus) => + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = OrderId, Status = initialStatus }); + + // --------------------------------------------------------------------------- + // pending -> issued on a later poll -> GENERATED + chain + // --------------------------------------------------------------------------- + + [Fact] + public async Task Pickup_ReturnsIssuedCert_WhenOrderIssuesDuringLaterPoll() + { + var mock = NewMock(); + StubCatalog(mock); + StubPlaceAndSubmit(mock, "pending-csr"); + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + // 1st call: post-CSR check (still pending). 2nd: 1st poll attempt (still pending). + // 3rd: 2nd poll attempt — the order has now issued. + mock.SetupSequence(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "pending-dcv" }) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "pending-dcv" }) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "issued" }); + + mock.Setup(c => c.DownloadCertificateV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(new V2CertificateDownloadResponse + { + OrderId = OrderId, + SerialNumber = "AABBCC", + CertificatePem = MockCertificateData.FakePemCertificate + }); + + var plugin = BuildV2PluginWithPickup(mock.Object, retries: 2); + + var result = await Enroll(plugin); + + result.Status.Should().Be((int)EndEntityStatus.GENERATED); + result.CARequestID.Should().Be(OrderId); + result.Certificate.Should().StartWith("-----BEGIN CERTIFICATE-----"); + mock.Verify(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny()), + Times.Exactly(3)); + mock.Verify(c => c.DownloadCertificateV2Async(It.IsAny(), OrderId, It.IsAny()), + Times.Once); + } + + // --------------------------------------------------------------------------- + // issued but the first download fails -> retried -> GENERATED + // --------------------------------------------------------------------------- + + [Fact] + public async Task Pickup_RetriesDownload_WhenFirstDownloadAttemptFails() + { + var mock = NewMock(); + StubCatalog(mock); + StubPlaceAndSubmit(mock, "pending-csr"); + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + // Post-CSR check is still pending, so EnrollV2Async's own immediate-download branch + // is never reached — both "issued" observations below come from the pickup poll. + mock.SetupSequence(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "pending-dcv" }) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "issued" }) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "issued" }); + + mock.SetupSequence(c => c.DownloadCertificateV2Async(It.IsAny(), OrderId, It.IsAny())) + .ThrowsAsync(new Exception("simulated transient download failure")) + .ReturnsAsync(new V2CertificateDownloadResponse + { + OrderId = OrderId, + SerialNumber = "AABBCC", + CertificatePem = MockCertificateData.FakePemCertificate + }); + + var plugin = BuildV2PluginWithPickup(mock.Object, retries: 2); + + var result = await Enroll(plugin); + + result.Status.Should().Be((int)EndEntityStatus.GENERATED); + result.Certificate.Should().StartWith("-----BEGIN CERTIFICATE-----"); + mock.Verify(c => c.DownloadCertificateV2Async(It.IsAny(), OrderId, It.IsAny()), + Times.Exactly(2), "the first download failure must not abort the poll"); + } + + // --------------------------------------------------------------------------- + // still pending at budget -> pending with CARequestID + // --------------------------------------------------------------------------- + + [Fact] + public async Task Pickup_ReturnsPendingWithCARequestID_WhenOrderNeverIssuesWithinBudget() + { + var mock = NewMock(); + StubCatalog(mock); + StubPlaceAndSubmit(mock, "pending-csr"); + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + // Every poll (including the post-CSR check) still reports pending. + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "pending-dcv" }); + + var plugin = BuildV2PluginWithPickup(mock.Object, retries: 1); + + var result = await Enroll(plugin); + + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + result.CARequestID.Should().Be(OrderId); + mock.Verify(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny()), + Times.AtLeast(2), "an enabled pickup must actually poll before giving up"); + mock.Verify(c => c.DownloadCertificateV2Async( + It.IsAny(), It.IsAny(), It.IsAny()), Times.Never); + } + + // --------------------------------------------------------------------------- + // PickupRetries=0 -> no polling + // --------------------------------------------------------------------------- + + [Fact] + public async Task Pickup_Disabled_WhenPickupRetriesZero_ReturnsPendingWithoutPolling() + { + var mock = NewMock(); + StubCatalog(mock); + StubPlaceAndSubmit(mock, "pending-csr"); + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "pending-dcv" }); + + var plugin = BuildV2PluginWithPickup(mock.Object, retries: 0); + + var result = await Enroll(plugin); + + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + result.CARequestID.Should().Be(OrderId); + // Only the single post-CSR status check should have run — no pickup polling at all. + mock.Verify(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny()), + Times.Once, "PickupRetries=0 must disable the V2 synchronous pickup poll"); + mock.Verify(c => c.DownloadCertificateV2Async( + It.IsAny(), It.IsAny(), It.IsAny()), Times.Never); + } + + // --------------------------------------------------------------------------- + // FAILED mid-poll -> returned as-is + // --------------------------------------------------------------------------- + + [Fact] + public async Task Pickup_SurfacesTerminalFailedStatus_WhenOrderRejectedDuringPoll() + { + var mock = NewMock(); + StubCatalog(mock); + StubPlaceAndSubmit(mock, "pending-csr"); + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + // Post-CSR check is pending; the first (and only) poll attempt observes a terminal + // "rejected" status, which StatusMapper.V2StatusToRequestDisposition maps to FAILED. + mock.SetupSequence(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "pending-dcv" }) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "rejected" }); + + var plugin = BuildV2PluginWithPickup(mock.Object, retries: 3); + + var result = await Enroll(plugin); + + result.Status.Should().Be((int)EndEntityStatus.FAILED, + "a terminal status observed during pickup is surfaced immediately, not polled to exhaustion"); + result.CARequestID.Should().Be(OrderId); + mock.Verify(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny()), + Times.Exactly(2), "the poll must stop at the first terminal observation, not run all 3 retries"); + } + } +} diff --git a/CERTInext.Tests/CERTInextCAPluginV2SyncRecentOrderTests.cs b/CERTInext.Tests/CERTInextCAPluginV2SyncRecentOrderTests.cs new file mode 100644 index 0000000..8d003a0 --- /dev/null +++ b/CERTInext.Tests/CERTInextCAPluginV2SyncRecentOrderTests.cs @@ -0,0 +1,478 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Linq; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.Logging; +using Keyfactor.PKI.Enums.EJBCA; +using Microsoft.Extensions.Logging; +using Moq; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Issue 0090: the V2 sync (full or incremental) must not emit a pending or issued order created + /// within the grace window (default 120 s plus a clock margin), because the gateway would insert + /// a row with that CARequestID and the in-flight enrollment's own save would then fail on the + /// unique (CA, CARequestID) index. A held-back issued order is not downloaded either. Revoked + /// and failed rows and unparseable dates are unaffected. + /// + /// Log capture swaps (same seam and same non-parallel + /// collection as ); assertions only consider messages + /// carrying this test's unique order-id marker, except the summary line, which is checked + /// positively only. + /// + [Collection(LoggingStateCollection.Name)] + public class CERTInextCAPluginV2SyncRecentOrderTests + { + private static readonly int Margin = Constants.Api.SyncRecentOrderClockMarginSeconds; + private static readonly int DefaultGrace = Constants.Api.DefaultSyncRecentOrderGraceSeconds; + + private sealed class CapturingLoggerProvider : ILoggerProvider + { + public ConcurrentQueue Messages { get; } = new(); + public ILogger CreateLogger(string categoryName) => new CapturingLogger(Messages); + public void Dispose() { } + + private sealed class CapturingLogger : ILogger + { + private readonly ConcurrentQueue _messages; + public CapturingLogger(ConcurrentQueue messages) => _messages = messages; + public IDisposable BeginScope(TState state) => null; + public bool IsEnabled(LogLevel logLevel) => true; + public void Log(LogLevel logLevel, EventId eventId, TState state, Exception exception, + Func formatter) + => _messages.Enqueue(logLevel + "|" + formatter(state, exception)); + } + } + + private static string NewId() => "ord_0090_" + Guid.NewGuid().ToString("N"); + + private static OrderReportEntryV2 Row( + string id, string orderStatus, string certificateStatus, string orderDate) => + new OrderReportEntryV2 + { + OrderNumber = id, + OrderStatus = orderStatus, + CertificateStatus = certificateStatus, + DomainName = "example.com", + ProductCode = "842", + OrderDate = orderDate + }; + + private static string Ago(double seconds) => + DateTime.UtcNow.AddSeconds(-seconds).ToString("yyyy-MM-ddTHH:mm:ss'Z'"); + + private static async IAsyncEnumerable Rows(params OrderReportEntryV2[] rows) + { + foreach (var r in rows) yield return r; + await Task.CompletedTask; + } + + private static CERTInextCAPlugin BuildPlugin(ICERTInextClient client, int? graceSeconds = null) + { + var config = new CERTInextConfig + { + UseV2Api = true, + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + AccountNumber = "12345", + AuthMode = "AccessKey", + ApiKey = "v1-key", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + SignerIp = "1.2.3.4", + SignerPlace = "New York", + PickupRetries = 0 + }; + if (graceSeconds.HasValue) + config.SyncRecentOrderGraceSeconds = graceSeconds.Value; + + // A reader that says the gateway already holds a body keeps revoked rows from tripping + // the bodyless-REVOKED guard, which is not what these tests are about. + var reader = new Mock(); + reader.Setup(r => r.GetExpirationDateByRequestId(It.IsAny())).Returns(DateTime.UtcNow.AddDays(30)); + return new CERTInextCAPlugin(client, config, reader.Object); + } + + private static Mock ClientReturning(params OrderReportEntryV2[] rows) + { + var mock = new Mock(); + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(() => Rows(rows)); + return mock; + } + + /// Runs a sync with the logger factory swapped; returns emitted records and captured log lines. + private static async Task<(AnyCAPluginCertificate[] Records, List Log)> SyncAsync( + ICERTInextClient client, int? graceSeconds, bool fullSync, string marker) + { + var provider = new CapturingLoggerProvider(); + var factory = LoggerFactory.Create(b => b.AddProvider(provider).SetMinimumLevel(LogLevel.Trace)); + var buffer = new BlockingCollection(100); + try + { + LogHandler.Factory = factory; + var plugin = BuildPlugin(client, graceSeconds); // constructed after the swap + await plugin.Synchronize(buffer, DateTime.UtcNow.AddHours(-1), fullSync, CancellationToken.None); + } + finally + { + LogHandler.Factory = Microsoft.Extensions.Logging.Abstractions.NullLoggerFactory.Instance; + factory.Dispose(); + } + + var log = provider.Messages + .Where(m => m != null && (m.Contains(marker) || m.Contains("V2 synchronization complete"))) + .ToList(); + return (buffer.ToArray(), log); + } + + // --------------------------------------------------------------------------- + // Skip / emit decisions through Synchronize + // --------------------------------------------------------------------------- + + [Fact] + public async Task Incremental_PendingAndRecent_IsNotEmitted_LogsIdAgeAndCountsInSummary() + { + string id = NewId(); + var mock = ClientReturning(Row(id, "Order Accepted", "Approved by System", Ago(30))); + + var (records, log) = await SyncAsync(mock.Object, null, fullSync: false, marker: id); + + records.Should().BeEmpty("a pending order created 30 s ago may still be saving in its enrollment"); + log.Should().Contain(m => m.StartsWith("Information|") && m.Contains($"CARequestID={id}") + && m.Contains("AgeSeconds=") && m.Contains($"GraceSeconds={DefaultGrace}"), + "each hold-back is logged at Info with the order id and its age"); + log.Should().Contain(m => m.Contains("V2 synchronization complete") && m.Contains("RecentOrdersDeferred=1"), + "the sync summary counts held-back orders"); + } + + [Fact] + public async Task Incremental_PendingAndOlderThanWindow_IsEmitted() + { + string id = NewId(); + var mock = ClientReturning(Row(id, "Order Accepted", "Approved by System", Ago(DefaultGrace + Margin + 30))); + + var (records, log) = await SyncAsync(mock.Object, null, fullSync: false, marker: id); + + records.Should().ContainSingle(); + records[0].CARequestID.Should().Be(id); + records[0].Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + log.Should().NotContain(m => m.Contains($"CARequestID={id}") && m.Contains("holding back")); + } + + private static void SetupDownload(Mock mock, string id) => + mock.Setup(c => c.ResolveAndDownloadCertificateV2Async(id, It.IsAny())) + .ReturnsAsync(new V2CertificateDownloadResponse + { + OrderId = id, CertificatePem = MockCertificateData.FakePemCertificate + }); + + [Theory] + [InlineData(false)] + [InlineData(true)] + public async Task IssuedAndRecent_IsHeldBack_NoDownloadCall(bool fullSync) + { + string id = NewId(); + var mock = ClientReturning(Row(id, "Order Fulfilled", "Certificate Downloaded", Ago(10))); + SetupDownload(mock, id); + + var (records, log) = await SyncAsync(mock.Object, null, fullSync, marker: id); + + records.Should().BeEmpty("an issued order created 10 s ago may still be saving in its enrollment"); + mock.Verify(c => c.ResolveAndDownloadCertificateV2Async(id, It.IsAny()), Times.Never, + "a held-back issued order must not cost a certificate download"); + log.Should().Contain(m => m.StartsWith("Information|") && m.Contains($"CARequestID={id}") + && m.Contains("holding back")); + log.Should().Contain(m => m.Contains("V2 synchronization complete") && m.Contains("RecentOrdersDeferred=1")); + } + + [Theory] + [InlineData(false)] + [InlineData(true)] + public async Task IssuedAndOlderThanWindow_IsEmitted_WithCertificate(bool fullSync) + { + string id = NewId(); + var mock = ClientReturning( + Row(id, "Order Fulfilled", "Certificate Downloaded", Ago(DefaultGrace + Margin + 30))); + SetupDownload(mock, id); + + var (records, _) = await SyncAsync(mock.Object, null, fullSync, marker: id); + + records.Should().ContainSingle(); + records[0].CARequestID.Should().Be(id); + records[0].Status.Should().Be((int)EndEntityStatus.GENERATED); + records[0].Certificate.Should().NotBeNullOrEmpty(); + mock.Verify(c => c.ResolveAndDownloadCertificateV2Async(id, It.IsAny()), Times.Once); + } + + [Fact] + public async Task Incremental_IssuedFoundViaTrackFallback_AndRecent_IsHeldBack_NoDownloadCall() + { + string id = NewId(); + var mock = ClientReturning(Row(id, "Something New", "Also New", Ago(20))); + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync(id, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse + { + OrderId = id, Status = "issued", Domain = "example.com" + })); + SetupDownload(mock, id); + + var (records, _) = await SyncAsync(mock.Object, null, fullSync: false, marker: id); + + records.Should().BeEmpty(); + mock.Verify(c => c.ResolveAndDownloadCertificateV2Async(id, It.IsAny()), Times.Never); + } + + [Theory] + [InlineData(false)] + [InlineData(true)] + public async Task RevokedAndRecent_IsEmitted(bool fullSync) + { + string id = NewId(); + var mock = ClientReturning(Row(id, "Revoked", "Certificate Revoked", Ago(10))); + + var (records, _) = await SyncAsync(mock.Object, null, fullSync, marker: id); + + records.Should().ContainSingle(); + records[0].Status.Should().Be((int)EndEntityStatus.REVOKED); + } + + [Theory] + [InlineData(false)] + [InlineData(true)] + public async Task FailedAndRecent_IsUnaffected_StillSkippedAsTerminal_NotCountedAsHeldBack(bool fullSync) + { + string id = NewId(); + var mock = ClientReturning(Row(id, "Order Cancelled", null, Ago(10))); + + var (records, log) = await SyncAsync(mock.Object, null, fullSync, marker: id); + + records.Should().BeEmpty("a failed/cancelled order is skipped exactly as before"); + log.Should().NotContain(m => m.Contains("RecentOrdersDeferred=1")); + } + + [Fact] + public async Task FullSync_PendingAndRecent_IsHeldBack() + { + string id = NewId(); + var mock = ClientReturning(Row(id, "Order Accepted", "Approved by System", Ago(5))); + + var (records, log) = await SyncAsync(mock.Object, null, fullSync: true, marker: id); + + records.Should().BeEmpty("a full sync can also race an in-flight enrollment"); + log.Should().Contain(m => m.StartsWith("Information|") && m.Contains($"CARequestID={id}") + && m.Contains("holding back")); + log.Should().Contain(m => m.Contains("V2 synchronization complete") && m.Contains("RecentOrdersDeferred=1")); + } + + [Fact] + public async Task FullSync_PendingAndOlderThanWindow_IsEmitted() + { + string id = NewId(); + var mock = ClientReturning(Row(id, "Order Accepted", "Approved by System", Ago(DefaultGrace + Margin + 30))); + + var (records, _) = await SyncAsync(mock.Object, null, fullSync: true, marker: id); + + records.Should().ContainSingle(); + records[0].Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + } + + [Fact] + public async Task FullSync_MixedPage_HoldsBackOnlyTheRecentPendingAndIssued() + { + string recentPending = NewId(), recentIssued = NewId(), oldPending = NewId(), oldIssued = NewId(), revoked = NewId(); + int old = DefaultGrace + Margin + 60; + var mock = ClientReturning( + Row(recentPending, "Order Accepted", "Approved by System", Ago(8)), + Row(recentIssued, "Order Fulfilled", "Certificate Downloaded", Ago(9)), + Row(oldPending, "Order Accepted", "Approved by System", Ago(old)), + Row(oldIssued, "Order Fulfilled", "Certificate Downloaded", Ago(old)), + Row(revoked, "Revoked", "Certificate Revoked", Ago(8))); + SetupDownload(mock, recentIssued); + SetupDownload(mock, oldIssued); + + var (records, _) = await SyncAsync(mock.Object, null, fullSync: true, marker: recentPending); + + records.Select(r => r.CARequestID).Should().BeEquivalentTo(new[] { oldPending, oldIssued, revoked }); + mock.Verify(c => c.ResolveAndDownloadCertificateV2Async(recentIssued, It.IsAny()), Times.Never); + } + + [Theory] + [InlineData("")] + [InlineData(null)] + [InlineData("not-a-date")] + [InlineData("14/99/2026 25:61")] + public async Task Incremental_PendingWithMissingOrUnparseableDate_FailsOpen_IsEmitted(string orderDate) + { + string id = NewId(); + var mock = ClientReturning(Row(id, "Order Accepted", "Approved by System", orderDate)); + + var (records, _) = await SyncAsync(mock.Object, null, fullSync: false, marker: id); + + records.Should().ContainSingle("without a trustworthy order date the row is emitted as before"); + records[0].CARequestID.Should().Be(id); + } + + [Fact] + public async Task Incremental_PendingFoundViaTrackFallback_AndRecent_IsNotEmitted() + { + string id = NewId(); + // Unrecognised display strings force the live TrackOrder fallback, which says pending. + var mock = ClientReturning(Row(id, "Something New", "Also New", Ago(20))); + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync(id, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse + { + OrderId = id, Status = "pending-approval", Domain = "example.com" + })); + + var (records, _) = await SyncAsync(mock.Object, null, fullSync: false, marker: id); + + records.Should().BeEmpty(); + } + + [Theory] + [InlineData(false)] + [InlineData(true)] + public async Task GraceZero_DisablesTheHoldBack_PendingAndIssued(bool fullSync) + { + string pending = NewId(), issued = NewId(); + var mock = ClientReturning( + Row(pending, "Order Accepted", "Approved by System", Ago(5)), + Row(issued, "Order Fulfilled", "Certificate Downloaded", Ago(5))); + SetupDownload(mock, issued); + + var (records, _) = await SyncAsync(mock.Object, graceSeconds: 0, fullSync: fullSync, marker: pending); + + records.Select(r => r.CARequestID).Should().BeEquivalentTo(new[] { pending, issued }, + "SyncRecentOrderGraceSeconds=0 restores the old behaviour"); + } + + [Fact] + public async Task Incremental_GraceConfigured_UsesConfiguredWindow() + { + string heldId = NewId(); + string emittedId = NewId(); + // Window = 10 s grace + margin. 5 s old is inside it; 30 s old is outside it (but + // would be inside the 120 s default, so this proves the setting is honoured). + var mock = ClientReturning( + Row(heldId, "Order Accepted", "Approved by System", Ago(5)), + Row(emittedId, "Order Accepted", "Approved by System", Ago(30))); + + var (records, _) = await SyncAsync(mock.Object, graceSeconds: 10, fullSync: false, marker: heldId); + + records.Select(r => r.CARequestID).Should().Equal(emittedId); + } + + // --------------------------------------------------------------------------- + // The decision and config helpers + // --------------------------------------------------------------------------- + + [Theory] + [InlineData(0, true)] // order created this instant + [InlineData(119, true)] + [InlineData(124, true)] // inside grace + margin + [InlineData(126, false)] // just past grace + margin + [InlineData(3600, false)] + [InlineData(-3, true)] // CA clock slightly ahead, within the margin + [InlineData(-60, false)] // CA clock far ahead: untrustworthy, fail open + public void ShouldDeferRecentOrder_Pending_AgeBoundaries(double ageSeconds, bool expectDefer) + { + var now = new DateTime(2026, 10, 15, 12, 0, 0, DateTimeKind.Utc); + + bool deferred = CERTInextCAPlugin.ShouldDeferRecentOrder( + (int)EndEntityStatus.EXTERNALVALIDATION, now.AddSeconds(-ageSeconds), now, DefaultGrace, out double age); + + deferred.Should().Be(expectDefer); + age.Should().BeApproximately(ageSeconds, 0.001); + } + + [Theory] + [InlineData(0, true)] // order created this instant + [InlineData(119, true)] + [InlineData(124, true)] // inside grace + margin + [InlineData(126, false)] // just past grace + margin + [InlineData(3600, false)] + [InlineData(-3, true)] // CA clock slightly ahead, within the margin + [InlineData(-60, false)] // CA clock far ahead: untrustworthy, fail open + public void ShouldDeferRecentOrder_Issued_AgeBoundaries(double ageSeconds, bool expectDefer) + { + var now = new DateTime(2026, 10, 15, 12, 0, 0, DateTimeKind.Utc); + + bool deferred = CERTInextCAPlugin.ShouldDeferRecentOrder( + (int)EndEntityStatus.GENERATED, now.AddSeconds(-ageSeconds), now, DefaultGrace, out double age); + + deferred.Should().Be(expectDefer); + age.Should().BeApproximately(ageSeconds, 0.001); + } + + [Fact] + public void ShouldDeferRecentOrder_GraceZero_NeverDeferred() + { + var now = new DateTime(2026, 10, 15, 12, 0, 0, DateTimeKind.Utc); + + CERTInextCAPlugin.ShouldDeferRecentOrder( + (int)EndEntityStatus.EXTERNALVALIDATION, now.AddSeconds(-1), now, 0, out _) + .Should().BeFalse(); + } + + [Theory] + [InlineData((int)EndEntityStatus.REVOKED)] + [InlineData((int)EndEntityStatus.FAILED)] + public void ShouldDeferRecentOrder_RevokedAndFailed_NeverDeferred(int disposition) + { + var now = new DateTime(2026, 10, 15, 12, 0, 0, DateTimeKind.Utc); + + CERTInextCAPlugin.ShouldDeferRecentOrder(disposition, now.AddSeconds(-1), now, DefaultGrace, out _) + .Should().BeFalse(); + } + + [Fact] + public void ShouldDeferRecentOrder_NoOrderDate_FailsOpen() + { + CERTInextCAPlugin.ShouldDeferRecentOrder( + (int)EndEntityStatus.EXTERNALVALIDATION, null, DateTime.UtcNow, DefaultGrace, out _) + .Should().BeFalse(); + } + + [Theory] + [InlineData(null, 120)] + [InlineData(120, 120)] + [InlineData(45, 45)] + [InlineData(0, 0)] + [InlineData(-1, 120)] + public void GetSyncRecentOrderGraceSeconds_ZeroDisables_NegativeFallsBackToDefault(int? configured, int expected) + { + var config = new CERTInextConfig(); + if (configured.HasValue) config.SyncRecentOrderGraceSeconds = configured.Value; + + CERTInextCAPlugin.GetSyncRecentOrderGraceSeconds(config).Should().Be(expected); + } + + [Fact] + public void Annotations_SyncRecentOrderGraceSeconds_PresentWithDefault() + { + var annotations = CERTInextCAPluginConfig.GetCAConnectorAnnotations(); + + annotations.Should().ContainKey(Constants.Config.SyncRecentOrderGraceSeconds); + annotations[Constants.Config.SyncRecentOrderGraceSeconds].DefaultValue.Should().Be(DefaultGrace); + annotations[Constants.Config.SyncRecentOrderGraceSeconds].Type.Should().Be("Number"); + } + } +} diff --git a/CERTInext.Tests/CERTInextCAPluginV2Tests.cs b/CERTInext.Tests/CERTInextCAPluginV2Tests.cs new file mode 100644 index 0000000..a6228c2 --- /dev/null +++ b/CERTInext.Tests/CERTInextCAPluginV2Tests.cs @@ -0,0 +1,2033 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.Extensions.CAPlugin.CERTInext; +using Keyfactor.PKI.Enums.EJBCA; +using Moq; +using WireMock.RequestBuilders; +using WireMock.ResponseBuilders; +using WireMock.Server; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Moq-based unit tests that verify V2 dispatch in . + /// All V2 client methods are mocked — no network calls are made. + /// + public class CERTInextCAPluginV2Tests + { + // --------------------------------------------------------------------------- + // Helpers + // --------------------------------------------------------------------------- + + private static Mock NewMock() => + new Mock(MockBehavior.Strict); + + private static CERTInextCAPlugin BuildV2Plugin( + ICERTInextClient client, + bool ignoreExpired = false, + string dcvTxtRecordTemplate = null, + string requestorIsdCode = null, + string requestorMobileNumber = null, + ICertificateDataReader certDataReader = null, + string organizationNumber = null, + string defaultProductCode = null) => + new CERTInextCAPlugin(client, new CERTInextConfig + { + UseV2Api = true, + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + AccountNumber = "12345", + AuthMode = "AccessKey", + ApiKey = "v1-key", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + SignerIp = "1.2.3.4", + SignerPlace = "New York", + OrganizationNumber = organizationNumber, + DefaultProductCode = defaultProductCode, + PickupRetries = 0, + IgnoreExpired = ignoreExpired, + DcvTxtRecordTemplate = dcvTxtRecordTemplate, + RequestorIsdCode = requestorIsdCode, + RequestorMobileNumber = requestorMobileNumber + }, certDataReader); + + /// + /// A mock whose + /// returns a date, + /// simulating a gateway row that already holds a certificate body. Tests that exercise + /// revocation-detail/ProductId logic on a REVOKED-with-no-body record use this so the + /// bodyless-REVOKED guard () + /// lets the record through unchanged, keeping these tests focused on their own concern. + /// + private static ICertificateDataReader GatewayHoldsBodyReader(DateTime? expiry = null) + { + var mock = new Mock(); + mock.Setup(r => r.GetExpirationDateByRequestId(It.IsAny())) + .Returns(expiry ?? DateTime.UtcNow.AddDays(30)); + return mock.Object; + } + + private static EnrollmentProductInfo MakeV2ProductInfo( + string productCode = "842", + string productFamily = "ssl", + string productVariant = "dv", + string domainName = "example.com") + { + return new EnrollmentProductInfo + { + ProductID = "DV SSL", + ProductParameters = new Dictionary(System.StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = productCode, + ["ProductFamily"] = productFamily, + ["ProductVariant"] = productVariant, + ["DomainName"] = domainName + } + }; + } + + /// + /// Stubs — every V2 enrollment now + /// resolves the requested product's productTypeID from the live Catalog to decide + /// UCC-ness, so any Strict-mock enroll test must + /// stub this call regardless of whether the test cares about UCC behavior. + /// + private static void StubCatalog(Mock mock, string productCode, string productTypeId) => + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = productCode, ProductTypeId = productTypeId, Active = true } + }); + + // --------------------------------------------------------------------------- + // Ping routes to V2 + // --------------------------------------------------------------------------- + + [Fact] + public async Task Ping_V2Enabled_CallsPingV2Async() + { + var mock = NewMock(); + mock.Setup(c => c.PingV2Async(It.IsAny())) + .Returns(Task.CompletedTask); + + var plugin = BuildV2Plugin(mock.Object); + await plugin.Ping(); + + mock.Verify(c => c.PingV2Async(It.IsAny()), Times.Once); + } + + [Fact] + public async Task Ping_V2Enabled_DoesNotCallV1Ping() + { + var mock = new Mock(); // Loose — verifying absence + mock.Setup(c => c.PingV2Async(It.IsAny())) + .Returns(Task.CompletedTask); + + var plugin = BuildV2Plugin(mock.Object); + await plugin.Ping(); + + mock.Verify(c => c.PingAsync(It.IsAny()), Times.Never); + } + + // --------------------------------------------------------------------------- + // Enroll routes to V2 + // --------------------------------------------------------------------------- + + [Fact] + public async Task Enroll_V2Enabled_PlacesV2Order_PendingResult() + { + var mock = NewMock(); + StubCatalog(mock, "842", "13"); // non-UCC (DV SSL) + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2CreateOrderResponse + { + OrderId = MockCertificateData.V2OrderId1, + RequestId = "req_001", + Status = "pending-dcv" + }); + + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), MockCertificateData.V2OrderId1, + It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.TrackOrderV2Async( + It.IsAny(), MockCertificateData.V2OrderId1, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = MockCertificateData.V2OrderId1, Status = "pending-dcv" }); + + var plugin = BuildV2Plugin(mock.Object); + var result = await plugin.Enroll( + MockCertificateData.FakeCsrPem, + "CN=example.com, O=Acme", + new Dictionary(), + MakeV2ProductInfo(), + RequestFormat.PKCS10, + EnrollmentType.New); + + result.CARequestID.Should().Be(MockCertificateData.V2OrderId1); + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + } + + [Fact] + public async Task Enroll_V2Enabled_IssuedImmediately_DownloadsCert() + { + var mock = NewMock(); + StubCatalog(mock, "842", "13"); // non-UCC (DV SSL) + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2CreateOrderResponse + { + OrderId = MockCertificateData.V2OrderId1, + Status = "issued" + }); + + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), MockCertificateData.V2OrderId1, + It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.TrackOrderV2Async( + It.IsAny(), MockCertificateData.V2OrderId1, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = MockCertificateData.V2OrderId1, Status = "issued" }); + + mock.Setup(c => c.DownloadCertificateV2Async( + It.IsAny(), MockCertificateData.V2OrderId1, It.IsAny())) + .ReturnsAsync(new V2CertificateDownloadResponse + { + OrderId = MockCertificateData.V2OrderId1, + SerialNumber = "AABBCC", + CertificatePem = MockCertificateData.FakePemCertificate + }); + + var plugin = BuildV2Plugin(mock.Object); + var result = await plugin.Enroll( + MockCertificateData.FakeCsrPem, + "CN=example.com, O=Acme", + new Dictionary(), + MakeV2ProductInfo(), + RequestFormat.PKCS10, + EnrollmentType.New); + + result.CARequestID.Should().Be(MockCertificateData.V2OrderId1); + result.Status.Should().Be((int)EndEntityStatus.GENERATED); + result.Certificate.Should().StartWith("-----BEGIN CERTIFICATE-----"); + } + + // By design: V2 has no distinct renewal endpoint the plugin uses — CERTInext's + // `/reissue` endpoint exists but is intentionally not called. RenewOrReissue places a + // brand-new order via the same PlaceOrderV2Async path as a fresh enrollment; the prior + // order/certificate is left issued rather than revoked or reused. + [Fact] + public async Task Enroll_V2Enabled_RenewOrReissue_PlacesNewOrderByDesign() + { + var mock = NewMock(); + StubCatalog(mock, "842", "13"); // non-UCC (DV SSL) + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2CreateOrderResponse + { + OrderId = MockCertificateData.V2OrderId2, + Status = "pending-csr" + }); + + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), MockCertificateData.V2OrderId2, + It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.TrackOrderV2Async( + It.IsAny(), MockCertificateData.V2OrderId2, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = MockCertificateData.V2OrderId2, Status = "pending-validation" }); + + var plugin = BuildV2Plugin(mock.Object); + var result = await plugin.Enroll( + MockCertificateData.FakeCsrPem, + "CN=example.com, O=Acme", + new Dictionary(), + MakeV2ProductInfo(), + RequestFormat.PKCS10, + EnrollmentType.RenewOrReissue); + + result.CARequestID.Should().Be(MockCertificateData.V2OrderId2); + mock.Verify(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny()), Times.Once); + } + + // --------------------------------------------------------------------------- + // GetSingleRecord routes to V2 + // --------------------------------------------------------------------------- + + [Fact] + public async Task GetSingleRecord_V2Enabled_UsesResolveAndTrack() + { + var mock = NewMock(); + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync( + MockCertificateData.V2OrderId1, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse + { + OrderId = MockCertificateData.V2OrderId1, + Status = "issued", + ProductVariant = "dv" + })); + + mock.Setup(c => c.ResolveAndDownloadCertificateV2Async( + MockCertificateData.V2OrderId1, It.IsAny())) + .ReturnsAsync(new V2CertificateDownloadResponse + { + OrderId = MockCertificateData.V2OrderId1, + SerialNumber = "AABB", + CertificatePem = MockCertificateData.FakePemCertificate + }); + + var plugin = BuildV2Plugin(mock.Object); + var record = await plugin.GetSingleRecord(MockCertificateData.V2OrderId1); + + record.CARequestID.Should().Be(MockCertificateData.V2OrderId1); + record.Status.Should().Be((int)EndEntityStatus.GENERATED); + record.Certificate.Should().StartWith("-----BEGIN CERTIFICATE-----"); + + mock.Verify(c => c.ResolveAndTrackOrderV2WithFamilyAsync( + MockCertificateData.V2OrderId1, It.IsAny()), Times.Once); + } + + [Fact] + public async Task GetSingleRecord_V2Enabled_DoesNotCallV1GetCertificate() + { + var mock = new Mock(); // Loose + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync( + It.IsAny(), It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse { OrderId = "ord_x", Status = "pending-dcv" })); + + var plugin = BuildV2Plugin(mock.Object); + await plugin.GetSingleRecord("ord_x"); + + mock.Verify(c => c.GetCertificateAsync(It.IsAny(), It.IsAny()), Times.Never); + } + + // --------------------------------------------------------------------------- + // GetSingleRecord — RevocationDate/RevocationReason + // --------------------------------------------------------------------------- + + [Fact] + public async Task GetSingleRecord_V2Enabled_Revoked_PopulatesRevocationDateAndReason() + { + var mock = NewMock(); + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync( + MockCertificateData.V2OrderId1, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse + { + OrderId = MockCertificateData.V2OrderId1, + Status = "revoked", + ProductVariant = "dv", + Revocation = new V2RevocationDetails + { + Status = "Certificate Revoked", + Reason = "cessation-of-operation", + ProcessedAt = new DateTime(2026, 9, 24, 20, 44, 41, DateTimeKind.Utc) + } + })); + + // This record has no certificate body, so the bodyless-REVOKED guard + // would otherwise downgrade it to FAILED — a reader that reports the gateway + // already holds a body keeps this test focused on revocation-detail population. + var plugin = BuildV2Plugin(mock.Object, certDataReader: GatewayHoldsBodyReader()); + var record = await plugin.GetSingleRecord(MockCertificateData.V2OrderId1); + + record.Status.Should().Be((int)EndEntityStatus.REVOKED); + record.RevocationDate.Should().Be(new DateTime(2026, 9, 24, 20, 44, 41, DateTimeKind.Utc)); + record.RevocationReason.Should().Be(5); // cessation-of-operation + } + + [Fact] + public async Task GetSingleRecord_V2Enabled_NotRevoked_RevocationFieldsDefault() + { + var mock = NewMock(); + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync( + MockCertificateData.V2OrderId1, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse + { + OrderId = MockCertificateData.V2OrderId1, + Status = "issued", + ProductVariant = "dv" + })); + + mock.Setup(c => c.ResolveAndDownloadCertificateV2Async( + MockCertificateData.V2OrderId1, It.IsAny())) + .ReturnsAsync(new V2CertificateDownloadResponse + { + OrderId = MockCertificateData.V2OrderId1, + SerialNumber = "AABB", + CertificatePem = MockCertificateData.FakePemCertificate + }); + + var plugin = BuildV2Plugin(mock.Object); + var record = await plugin.GetSingleRecord(MockCertificateData.V2OrderId1); + + record.RevocationDate.Should().BeNull(); + record.RevocationReason.Should().Be(0); + } + + // --------------------------------------------------------------------------- + // Revoke routes to V2 + // --------------------------------------------------------------------------- + + [Fact] + public async Task Revoke_V2Enabled_ResolvesAndRevokes() + { + var mock = new Mock(); // Loose + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync( + MockCertificateData.V2OrderId1, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse + { + OrderId = MockCertificateData.V2OrderId1, + Status = "issued" + })); + + mock.Setup(c => c.RevokeOrderV2Async( + Constants.ApiV2.FamilySsl, MockCertificateData.V2OrderId1, + It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + var plugin = BuildV2Plugin(mock.Object); + var status = await plugin.Revoke(MockCertificateData.V2OrderId1, "AABB", 4u); + + status.Should().Be((int)EndEntityStatus.REVOKED); + } + + [Fact] + public async Task Revoke_V2Enabled_DoesNotCallV1RevokeCertificate() + { + var mock = new Mock(); + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync( + It.IsAny(), It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse { Status = "issued", OrderId = "ord_x" })); + + mock.Setup(c => c.RevokeOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + var plugin = BuildV2Plugin(mock.Object); + await plugin.Revoke("ord_x", "AA", 1u); + + mock.Verify(c => c.RevokeCertificateAsync( + It.IsAny(), It.IsAny(), It.IsAny()), Times.Never); + } + + // --------------------------------------------------------------------------- + // Reason code fallback: CERTInext rejects 4 of the 9 spec-documented + // reason values (422 "Invalid Revoke Reason ID") — unspecified (CRL + // 0), ca-compromise (CRL 2), certificate-hold (CRL 6), aa-compromise (CRL 10). The + // plugin retries exactly once with an accepted fallback for each: cessation-of- + // operation for unspecified/certificate-hold, key-compromise for the two + // *-compromise reasons. A reason outside that known-rejected set is never retried. + // --------------------------------------------------------------------------- + + private static Mock SetupRevokeReasonRejectionMock(List seenReasons) + { + var mock = new Mock(); + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync( + MockCertificateData.V2OrderId1, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse + { + OrderId = MockCertificateData.V2OrderId1, + Status = "issued" + })); + + mock.Setup(c => c.RevokeOrderV2Async( + Constants.ApiV2.FamilySsl, MockCertificateData.V2OrderId1, + It.IsAny(), It.IsAny())) + .Returns((string family, string orderId, V2RevokeRequest req, CancellationToken ct) => + { + seenReasons.Add(req.Reason); + bool firstAttemptRejected = + req.Reason == Constants.RevocationReasonV2.Unspecified || + req.Reason == Constants.RevocationReasonV2.CACompromise || + req.Reason == Constants.RevocationReasonV2.CertificateHold || + req.Reason == Constants.RevocationReasonV2.AACompromise; + if (firstAttemptRejected && seenReasons.Count == 1) + throw new InvalidOperationException("V2 revoke rejected. Unprocessable Entity: Invalid Revoke Reason ID"); + return Task.CompletedTask; + }); + return mock; + } + + [Theory] + // Command's default when no explicit reason is given. + [InlineData(0u, Constants.RevocationReasonV2.Unspecified, Constants.RevocationReasonV2.CessationOfOperation)] + [InlineData(2u, Constants.RevocationReasonV2.CACompromise, Constants.RevocationReasonV2.KeyCompromise)] + [InlineData(6u, Constants.RevocationReasonV2.CertificateHold, Constants.RevocationReasonV2.CessationOfOperation)] + [InlineData(10u, Constants.RevocationReasonV2.AACompromise, Constants.RevocationReasonV2.KeyCompromise)] + public async Task Revoke_V2Enabled_KnownRejectedReason_RetriesWithExpectedFallback( + uint crlReason, string expectedOriginal, string expectedFallback) + { + var seenReasons = new List(); + var mock = SetupRevokeReasonRejectionMock(seenReasons); + + var plugin = BuildV2Plugin(mock.Object); + var status = await plugin.Revoke(MockCertificateData.V2OrderId1, "AABB", crlReason); + + status.Should().Be((int)EndEntityStatus.REVOKED); + seenReasons.Should().Equal(expectedOriginal, expectedFallback); + } + + [Fact] + public async Task Revoke_V2Enabled_RejectedReasonNotInFallbackSet_DoesNotRetry() + { + var mock = new Mock(); + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync( + MockCertificateData.V2OrderId1, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse + { + OrderId = MockCertificateData.V2OrderId1, + Status = "issued" + })); + + // CRL reason 4 (superseded) maps to "superseded", which is + // actually accepted — it is not in the known-rejected fallback set, so even + // if the CA somehow rejected it with the same "Invalid Revoke Reason ID" message, + // the plugin must surface the failure as-is rather than retry. + mock.Setup(c => c.RevokeOrderV2Async( + Constants.ApiV2.FamilySsl, MockCertificateData.V2OrderId1, + It.IsAny(), It.IsAny())) + .ThrowsAsync(new InvalidOperationException("V2 revoke rejected. Unprocessable Entity: Invalid Revoke Reason ID")); + + var plugin = BuildV2Plugin(mock.Object); + var ex = await Assert.ThrowsAsync( + () => plugin.Revoke(MockCertificateData.V2OrderId1, "AABB", 4u)); + + ex.Message.Should().Contain("Invalid Revoke Reason ID"); + mock.Verify(c => c.RevokeOrderV2Async( + Constants.ApiV2.FamilySsl, MockCertificateData.V2OrderId1, + It.IsAny(), It.IsAny()), Times.Once); + } + + // --------------------------------------------------------------------------- + // A revoke 404 after the family is already resolved + // must not be reported as a family miss. + // --------------------------------------------------------------------------- + + [Fact] + public async Task Revoke_V2Enabled_RevokeReturns404AfterFamilyResolved_ReportsNotRevokable_NotFamilyMiss() + { + var mock = new Mock(); // Loose + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync( + MockCertificateData.V2OrderId1, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse + { + OrderId = MockCertificateData.V2OrderId1, + Status = "issued" + })); + + // Order is confirmed to live in the SSL family (TrackOrder above succeeded), + // but the revoke call itself 404s — per spec that means "not revokable", + // not "wrong family". The plugin must not retry other families for it. + mock.Setup(c => c.RevokeOrderV2Async( + Constants.ApiV2.FamilySsl, MockCertificateData.V2OrderId1, + It.IsAny(), It.IsAny())) + .ThrowsAsync(new KeyNotFoundException( + $"V2 order '{MockCertificateData.V2OrderId1}' in family '{Constants.ApiV2.FamilySsl}' " + + "not found or not in a revokable state.")); + + var plugin = BuildV2Plugin(mock.Object); + var ex = await Assert.ThrowsAsync( + () => plugin.Revoke(MockCertificateData.V2OrderId1, "AABB", 4u)); + + ex.Message.Should().Contain("not found or not in a revokable state"); + ex.Message.Should().NotContain("any product family", + "a 404 after the family was already resolved must not be mislabeled as a family miss"); + + // Must not have probed the other two families. + mock.Verify(c => c.RevokeOrderV2Async( + Constants.ApiV2.FamilyPrivatePki, It.IsAny(), + It.IsAny(), It.IsAny()), Times.Never); + mock.Verify(c => c.RevokeOrderV2Async( + Constants.ApiV2.FamilySignature, It.IsAny(), + It.IsAny(), It.IsAny()), Times.Never); + } + + // --------------------------------------------------------------------------- + // Synchronize (V2) — uses V2 /reports/orders, not V1 GetOrderReport. + // --------------------------------------------------------------------------- + + private static OrderReportEntryV2 ReportRow( + string orderNumber, string orderStatus, string certificateStatus, + string domainName = "example.com", string productCode = "842", + string certificateExpiryDate = null) => + new OrderReportEntryV2 + { + OrderNumber = orderNumber, + OrderStatus = orderStatus, + CertificateStatus = certificateStatus, + DomainName = domainName, + ProductCode = productCode, + OrderDate = System.DateTime.UtcNow.AddHours(-1).ToString("o"), + CertificateExpiryDate = certificateExpiryDate + }; + + [Fact] + public async Task Synchronize_V2Enabled_UsesListOrdersV2Async_NotV1ListCertificates() + { + var mock = new Mock(); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable()); + + var plugin = BuildV2Plugin(mock.Object); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + mock.Verify(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny()), Times.AtLeastOnce); + mock.Verify(c => c.ListCertificatesAsync( + It.IsAny(), It.IsAny(), It.IsAny()), Times.Never); + } + + [Fact] + public async Task Synchronize_V2Enabled_IssuedRow_DownloadsCertificateBody() + { + var mock = new Mock(); + var row = ReportRow("ord_v2sync_001", "Order Fulfilled", "Certificate Downloaded"); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable(row)); + + mock.Setup(c => c.ResolveAndDownloadCertificateV2Async("ord_v2sync_001", It.IsAny())) + .ReturnsAsync(new V2CertificateDownloadResponse + { + OrderId = "ord_v2sync_001", + SerialNumber = "AABBCC", + CertificatePem = MockCertificateData.FakePemCertificate + }); + + var plugin = BuildV2Plugin(mock.Object); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + var records = buffer.ToArray(); + records.Should().ContainSingle(); + records[0].CARequestID.Should().Be("ord_v2sync_001"); + records[0].Status.Should().Be((int)EndEntityStatus.GENERATED); + records[0].Certificate.Should().StartWith("-----BEGIN CERTIFICATE-----"); + records[0].ProductID.Should().Be("842"); + + // Recognised report-status strings must not need a live track fallback. + mock.Verify(c => c.ResolveAndTrackOrderV2WithFamilyAsync( + It.IsAny(), It.IsAny()), Times.Never); + } + + [Fact] + public async Task Synchronize_V2Enabled_UnrecognizedStatus_FallsBackToLiveTrack() + { + var mock = new Mock(); + // "Something New" is deliberately not in the known display-string vocabulary, + // which is not guaranteed exhaustive. + var row = ReportRow("ord_v2sync_002", "Something New", "Also New"); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable(row)); + + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync("ord_v2sync_002", It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse + { + OrderId = "ord_v2sync_002", Status = "issued", Domain = "example.com" + })); + + mock.Setup(c => c.ResolveAndDownloadCertificateV2Async("ord_v2sync_002", It.IsAny())) + .ReturnsAsync(new V2CertificateDownloadResponse + { + OrderId = "ord_v2sync_002", + CertificatePem = MockCertificateData.FakePemCertificate + }); + + var plugin = BuildV2Plugin(mock.Object); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + var records = buffer.ToArray(); + records.Should().ContainSingle(); + records[0].Status.Should().Be((int)EndEntityStatus.GENERATED, + "an unrecognised report status must fall back to the authoritative live track " + + "call rather than being dropped or guessed"); + + mock.Verify(c => c.ResolveAndTrackOrderV2WithFamilyAsync( + "ord_v2sync_002", It.IsAny()), Times.Once); + } + + [Fact] + public async Task Synchronize_V2Enabled_RevokedRow_EmittedAsRevoked() + { + var mock = new Mock(); + var row = ReportRow("ord_v2sync_003", "Revoked", "Certificate Revoked"); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable(row)); + + // This row has no certificate body, so the bodyless-REVOKED guard would + // otherwise downgrade/skip it — a reader that reports the gateway already holds a + // body keeps this test focused on "revoked rows never attempt a download". + var plugin = BuildV2Plugin(mock.Object, certDataReader: GatewayHoldsBodyReader()); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + var records = buffer.ToArray(); + records.Should().ContainSingle(); + records[0].Status.Should().Be((int)EndEntityStatus.REVOKED); + + // Revoked rows have no body to download. + mock.Verify(c => c.ResolveAndDownloadCertificateV2Async( + It.IsAny(), It.IsAny()), Times.Never); + } + + // --------------------------------------------------------------------------- + // Synchronize — RevocationDate/RevocationReason. OrderReportEntryV2 + // carries no revocation reason/date of its own — only a live TrackOrder response's + // nested `revocation` object does, so these fields require a resolved + // V2OrderStatusResponse regardless of which code path got there. + // --------------------------------------------------------------------------- + + [Fact] + public async Task Synchronize_V2Enabled_RevokedRow_ViaDisplayString_PopulatesRevocationDetails() + { + var mock = new Mock(); + // "Revoked"/"Certificate Revoked" resolve via the report's own display-string + // vocabulary (TryMapV2ReportDisplayStatus) with no live track call — the revocation + // detail must be fetched lazily, on top of that, specifically for this row. + var row = ReportRow("ord_v2sync_004", "Revoked", "Certificate Revoked"); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable(row)); + + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync("ord_v2sync_004", It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse + { + OrderId = "ord_v2sync_004", + Status = "revoked", + Revocation = new V2RevocationDetails + { + Status = "Certificate Revoked", + Reason = "key-compromise", + ProcessedAt = new System.DateTime(2026, 9, 24, 20, 44, 41, System.DateTimeKind.Utc) + } + })); + + // No certificate body on this row — a reader that reports the gateway + // already holds a body keeps this test focused on revocation-detail population + // rather than the bodyless-REVOKED guard (covered separately). + var plugin = BuildV2Plugin(mock.Object, certDataReader: GatewayHoldsBodyReader()); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + var records = buffer.ToArray(); + records.Should().ContainSingle(); + records[0].Status.Should().Be((int)EndEntityStatus.REVOKED); + records[0].RevocationDate.Should().Be(new System.DateTime(2026, 9, 24, 20, 44, 41, System.DateTimeKind.Utc)); + records[0].RevocationReason.Should().Be(1); // key-compromise + + mock.Verify(c => c.ResolveAndTrackOrderV2WithFamilyAsync( + "ord_v2sync_004", It.IsAny()), Times.Once); + } + + [Fact] + public async Task Synchronize_V2Enabled_RevokedRow_ViaUnresolvedFallback_PopulatesRevocationDetails() + { + var mock = new Mock(); + // Deliberately unrecognized display strings so disposition resolves via the + // unresolved-status fallback, which already performs a live TrackOrder call — + // trackedStatus (and its Revocation) is already populated before the + // revocation-specific lazy-fetch in Synchronize would otherwise need to run one. + var row = ReportRow("ord_v2sync_005", "Something New", "Also New"); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable(row)); + + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync("ord_v2sync_005", It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse + { + OrderId = "ord_v2sync_005", + Status = "revoked", + Revocation = new V2RevocationDetails + { + Status = "Certificate Revoked", + Reason = "superseded", + ProcessedAt = new System.DateTime(2026, 1, 2, 3, 4, 5, System.DateTimeKind.Utc) + } + })); + + // No certificate body on this row — a reader that reports the gateway + // already holds a body keeps this test focused on revocation-detail population + // rather than the bodyless-REVOKED guard (covered separately). + var plugin = BuildV2Plugin(mock.Object, certDataReader: GatewayHoldsBodyReader()); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + var records = buffer.ToArray(); + records.Should().ContainSingle(); + records[0].RevocationDate.Should().Be(new System.DateTime(2026, 1, 2, 3, 4, 5, System.DateTimeKind.Utc)); + records[0].RevocationReason.Should().Be(4); // superseded + + // Only the one fallback call — the revocation-specific lazy-fetch must not + // double-call when trackedStatus is already populated. + mock.Verify(c => c.ResolveAndTrackOrderV2WithFamilyAsync( + "ord_v2sync_005", It.IsAny()), Times.Once); + } + + [Fact] + public async Task Synchronize_V2Enabled_NotRevokedRow_RevocationFieldsDefault() + { + var mock = new Mock(); + var row = ReportRow("ord_v2sync_006", "Order Fulfilled", "Certificate Downloaded"); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable(row)); + + mock.Setup(c => c.ResolveAndDownloadCertificateV2Async("ord_v2sync_006", It.IsAny())) + .ReturnsAsync(new V2CertificateDownloadResponse + { + OrderId = "ord_v2sync_006", + CertificatePem = MockCertificateData.FakePemCertificate + }); + + var plugin = BuildV2Plugin(mock.Object); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + var records = buffer.ToArray(); + records.Should().ContainSingle(); + records[0].RevocationDate.Should().BeNull(); + records[0].RevocationReason.Should().Be(0); + + // Not revoked — must not incur the revocation-detail lazy-fetch at all. + mock.Verify(c => c.ResolveAndTrackOrderV2WithFamilyAsync( + It.IsAny(), It.IsAny()), Times.Never); + } + + // --------------------------------------------------------------------------- + // Synchronize — ProductID preference: report row's ProductCode vs. a lazily- + // fetched trackedStatus.ProductVariant. No new live call is added + // by this preference — it only reads whatever trackedStatus already exists in + // local scope from one of the three pre-existing lazy-fetch branches (unresolved- + // status fallback, DCV attempt, revoked-row lookup). + // --------------------------------------------------------------------------- + + [Fact] + public async Task Synchronize_V2Enabled_ProductId_PrefersReportRowProductCode_OverTrackedStatus() + { + var mock = new Mock(); + // Unrecognised display strings force the unresolved-status fallback, which + // populates trackedStatus (with a *different* ProductVariant) — the report + // row's own non-empty ProductCode must still win. + var row = ReportRow("ord_v2sync_035a", "Something New", "Also New", productCode: "842"); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable(row)); + + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync("ord_v2sync_035a", It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse + { + OrderId = "ord_v2sync_035a", + Status = "revoked", + ProductVariant = "ov-ucc" + })); + + // No certificate body on this row — a reader that reports the gateway + // already holds a body keeps this test focused on ProductID preference rather than + // the bodyless-REVOKED guard (covered separately). + var plugin = BuildV2Plugin(mock.Object, certDataReader: GatewayHoldsBodyReader()); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + var records = buffer.ToArray(); + records.Should().ContainSingle(); + records[0].ProductID.Should().Be("842", "the report row's own ProductCode must be " + + "preferred over trackedStatus.ProductVariant whenever it is present"); + + // No extra call beyond the fallback the unresolved status already required. + mock.Verify(c => c.ResolveAndTrackOrderV2WithFamilyAsync( + "ord_v2sync_035a", It.IsAny()), Times.Once); + } + + [Fact] + public async Task Synchronize_V2Enabled_ProductId_FallsBackToTrackedStatusProductVariant_WhenReportRowEmpty() + { + var mock = new Mock(); + var row = ReportRow("ord_v2sync_035b", "Something New", "Also New", productCode: ""); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable(row)); + + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync("ord_v2sync_035b", It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse + { + OrderId = "ord_v2sync_035b", + Status = "revoked", + ProductVariant = "ov-ucc" + })); + + // No certificate body on this row — a reader that reports the gateway + // already holds a body keeps this test focused on ProductID preference rather than + // the bodyless-REVOKED guard (covered separately). + var plugin = BuildV2Plugin(mock.Object, certDataReader: GatewayHoldsBodyReader()); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + var records = buffer.ToArray(); + records.Should().ContainSingle(); + records[0].ProductID.Should().Be("ov-ucc", "when the report row's ProductCode is " + + "empty, an already-populated trackedStatus.ProductVariant must be used instead " + + "of leaving the field empty"); + } + + [Fact] + public async Task Synchronize_V2Enabled_ProductId_EmptyWhenReportRowEmptyAndNoTrackedStatusFetched() + { + var mock = new Mock(); + // Recognised display strings resolve disposition without any live track call, + // so trackedStatus is never populated for this row. + var row = ReportRow("ord_v2sync_035c", "Order Fulfilled", "Certificate Downloaded", productCode: ""); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable(row)); + + mock.Setup(c => c.ResolveAndDownloadCertificateV2Async("ord_v2sync_035c", It.IsAny())) + .ReturnsAsync(new V2CertificateDownloadResponse + { + OrderId = "ord_v2sync_035c", + CertificatePem = MockCertificateData.FakePemCertificate + }); + + var plugin = BuildV2Plugin(mock.Object); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + var records = buffer.ToArray(); + records.Should().ContainSingle(); + records[0].ProductID.Should().Be(string.Empty, "with no ProductCode and no " + + "trackedStatus fetched for this row, ProductID must stay empty rather than " + + "crash or guess a value"); + + // Confirms trackedStatus really is null here — no fetch was ever made for this row. + mock.Verify(c => c.ResolveAndTrackOrderV2WithFamilyAsync( + It.IsAny(), It.IsAny()), Times.Never); + } + + [Fact] + public async Task Synchronize_V2Enabled_ProductId_EmptyWhenTrackedStatusProductVariantAlsoEmpty() + { + var mock = new Mock(); + var row = ReportRow("ord_v2sync_035d", "Something New", "Also New", productCode: ""); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable(row)); + + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync("ord_v2sync_035d", It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse + { + OrderId = "ord_v2sync_035d", + Status = "revoked", + ProductVariant = null + })); + + // No certificate body on this row — a reader that reports the gateway + // already holds a body keeps this test focused on ProductID preference rather than + // the bodyless-REVOKED guard (covered separately). + var plugin = BuildV2Plugin(mock.Object, certDataReader: GatewayHoldsBodyReader()); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + var records = buffer.ToArray(); + records.Should().ContainSingle(); + records[0].ProductID.Should().Be(string.Empty, "when both the report row's " + + "ProductCode and trackedStatus.ProductVariant are empty/null, ProductID must " + + "stay empty rather than guess a value"); + } + + [Fact] + public async Task Synchronize_V2Enabled_TerminalStatus_SkippedNotEmitted() + { + var mock = new Mock(); + var row = ReportRow("ord_v2sync_004", "Order Cancelled", null); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable(row)); + + var plugin = BuildV2Plugin(mock.Object); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + buffer.ToArray().Should().BeEmpty("terminal/cancelled orders are skipped, not emitted"); + } + + [Fact] + public async Task Synchronize_V2Enabled_IncrementalSync_RequestsLookbackWindow() + { + var mock = new Mock(); + string capturedFrom = null; + var lastSync = new System.DateTime(2026, 6, 15, 12, 0, 0, System.DateTimeKind.Utc); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Callback((from, to, size, ct) => capturedFrom = from) + .Returns(AsyncEnumerable()); + + var plugin = BuildV2Plugin(mock.Object); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, lastSync, fullSync: false, CancellationToken.None); + + // Default lookback is 72h (Constants.ApiV2.DefaultSyncLookbackHours) — the requested + // 'from' must be lastSync minus that window, not lastSync itself (the + // from/to filter's order-date-vs-issue-date semantics are not documented). + var expectedFrom = lastSync.AddHours(-Constants.ApiV2.DefaultSyncLookbackHours).ToString("yyyy-MM-dd"); + capturedFrom.Should().Be(expectedFrom); + } + + [Fact] + public async Task Synchronize_V2Enabled_FullSync_RequestsNoFromFilter() + { + var mock = new Mock(); + string capturedFrom = "unset"; + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Callback((from, to, size, ct) => capturedFrom = from) + .Returns(AsyncEnumerable()); + + var plugin = BuildV2Plugin(mock.Object); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, System.DateTime.UtcNow, fullSync: true, CancellationToken.None); + + capturedFrom.Should().BeNull("a full sync requests the entire order history, not a bounded window"); + } + + // --------------------------------------------------------------------------- + // Synchronize — IgnoreExpired. V1's Synchronize skips expired + // certs when IgnoreExpired is configured; SynchronizeV2Async must have an equivalent + // check using the report row (OrderReportEntryV2.CertificateExpiryDate). That field's + // format is not guaranteed, + // so an unparseable/missing value must NOT be skipped. + // --------------------------------------------------------------------------- + + [Fact] + public async Task Synchronize_V2Enabled_IgnoreExpired_ExpiredCert_Skipped() + { + var mock = new Mock(); + var row = ReportRow( + "ord_v2sync_expired_001", "Order Fulfilled", "Certificate Downloaded", + certificateExpiryDate: System.DateTime.UtcNow.AddDays(-30).ToString("o")); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable(row)); + + var plugin = BuildV2Plugin(mock.Object, ignoreExpired: true); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + buffer.ToArray().Should().BeEmpty( + "an expired certificate must be skipped entirely when IgnoreExpired=true"); + + // Skipped before any status/download work — no live calls should be made for this row. + mock.Verify(c => c.ResolveAndDownloadCertificateV2Async( + It.IsAny(), It.IsAny()), Times.Never); + mock.Verify(c => c.ResolveAndTrackOrderV2WithFamilyAsync( + It.IsAny(), It.IsAny()), Times.Never); + } + + [Fact] + public async Task Synchronize_V2Enabled_IgnoreExpired_NonExpiredCert_Kept() + { + var mock = new Mock(); + var row = ReportRow( + "ord_v2sync_expired_002", "Order Fulfilled", "Certificate Downloaded", + certificateExpiryDate: System.DateTime.UtcNow.AddDays(30).ToString("o")); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable(row)); + + mock.Setup(c => c.ResolveAndDownloadCertificateV2Async("ord_v2sync_expired_002", It.IsAny())) + .ReturnsAsync(new V2CertificateDownloadResponse + { + OrderId = "ord_v2sync_expired_002", + CertificatePem = MockCertificateData.FakePemCertificate + }); + + var plugin = BuildV2Plugin(mock.Object, ignoreExpired: true); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + var records = buffer.ToArray(); + records.Should().ContainSingle( + "a certificate that has not yet expired must still be emitted even with " + + "IgnoreExpired=true"); + records[0].CARequestID.Should().Be("ord_v2sync_expired_002"); + } + + [Fact] + public async Task Synchronize_V2Enabled_IgnoreExpired_UnparseableExpiryDate_NotSkipped() + { + var mock = new Mock(); + var row = ReportRow( + "ord_v2sync_expired_003", "Order Fulfilled", "Certificate Downloaded", + certificateExpiryDate: "not-a-real-date"); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable(row)); + + mock.Setup(c => c.ResolveAndDownloadCertificateV2Async("ord_v2sync_expired_003", It.IsAny())) + .ReturnsAsync(new V2CertificateDownloadResponse + { + OrderId = "ord_v2sync_expired_003", + CertificatePem = MockCertificateData.FakePemCertificate + }); + + var plugin = BuildV2Plugin(mock.Object, ignoreExpired: true); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + buffer.ToArray().Should().ContainSingle( + "an unparseable CertificateExpiryDate must not be treated as expired — the row " + + "should be emitted, not silently dropped"); + } + + [Fact] + public async Task Synchronize_V2Enabled_IgnoreExpired_MissingExpiryDate_NotSkipped() + { + var mock = new Mock(); + var row = ReportRow( + "ord_v2sync_expired_004", "Order Fulfilled", "Certificate Downloaded", + certificateExpiryDate: null); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable(row)); + + mock.Setup(c => c.ResolveAndDownloadCertificateV2Async("ord_v2sync_expired_004", It.IsAny())) + .ReturnsAsync(new V2CertificateDownloadResponse + { + OrderId = "ord_v2sync_expired_004", + CertificatePem = MockCertificateData.FakePemCertificate + }); + + var plugin = BuildV2Plugin(mock.Object, ignoreExpired: true); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + buffer.ToArray().Should().ContainSingle( + "a missing CertificateExpiryDate (empty until issuance per the DTO's doc " + + "comment) must not be treated as expired"); + } + + [Fact] + public async Task Synchronize_V2Enabled_IgnoreExpiredFalse_ExpiredCert_NotSkipped() + { + var mock = new Mock(); + var row = ReportRow( + "ord_v2sync_expired_005", "Order Fulfilled", "Certificate Downloaded", + certificateExpiryDate: System.DateTime.UtcNow.AddDays(-30).ToString("o")); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable(row)); + + mock.Setup(c => c.ResolveAndDownloadCertificateV2Async("ord_v2sync_expired_005", It.IsAny())) + .ReturnsAsync(new V2CertificateDownloadResponse + { + OrderId = "ord_v2sync_expired_005", + CertificatePem = MockCertificateData.FakePemCertificate + }); + + // IgnoreExpired defaults to false — the filter must be opt-in. + var plugin = BuildV2Plugin(mock.Object); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + buffer.ToArray().Should().ContainSingle( + "with IgnoreExpired left at its default (false), expired certs must still be emitted"); + } + + // --------------------------------------------------------------------------- + // Chain PEM assembly — Enroll V2 with chainPem + // --------------------------------------------------------------------------- + + [Fact] + public async Task Enroll_V2_WithChainPem_ConcatenatesLeafAndIntermediate() + { + var mock = NewMock(); + StubCatalog(mock, "842", "13"); // non-UCC (DV SSL) + + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2CreateOrderResponse + { + OrderId = "ord_chain_test", + Status = "issued" + }); + + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), "ord_chain_test", + It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.TrackOrderV2Async( + It.IsAny(), "ord_chain_test", It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = "ord_chain_test", Status = "issued" }); + + // Download response includes a chain PEM entry + mock.Setup(c => c.DownloadCertificateV2Async( + It.IsAny(), "ord_chain_test", It.IsAny())) + .ReturnsAsync(new V2CertificateDownloadResponse + { + OrderId = "ord_chain_test", + SerialNumber = "AABBCC", + CertificatePem = MockCertificateData.FakePemCertificate, + ChainPem = new System.Collections.Generic.List + { + MockCertificateData.FakeIntermediatePemCertificate + } + }); + + mock.Setup(c => c.Dispose()); + + mock.Setup(c => c.Dispose()); + + var plugin = BuildV2Plugin(mock.Object); + var result = await plugin.Enroll( + MockCertificateData.FakeCsrPem, + "CN=example.com", + new Dictionary(), + MakeV2ProductInfo(productVariant: "dv"), + RequestFormat.PKCS10, + EnrollmentType.New); + + result.CARequestID.Should().Be("ord_chain_test"); + result.Status.Should().Be((int)EndEntityStatus.GENERATED); + // Full chain must contain both leaf and intermediate + result.Certificate.Should().Contain("-----BEGIN CERTIFICATE-----"); + result.Certificate.Should().Contain("INTERMEDIATE", + because: "chain PEM from the CA should be appended to the leaf"); + } + + [Fact] + public async Task Enroll_V2_WithoutChainPem_ReturnsCertificatePemOnly() + { + var mock = NewMock(); + StubCatalog(mock, "842", "13"); // non-UCC (DV SSL) + + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = "ord_nochain", Status = "issued" }); + + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), "ord_nochain", + It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.TrackOrderV2Async( + It.IsAny(), "ord_nochain", It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = "ord_nochain", Status = "issued" }); + + mock.Setup(c => c.DownloadCertificateV2Async( + It.IsAny(), "ord_nochain", It.IsAny())) + .ReturnsAsync(new V2CertificateDownloadResponse + { + OrderId = "ord_nochain", + CertificatePem = MockCertificateData.FakePemCertificate, + ChainPem = null + }); + + mock.Setup(c => c.Dispose()); + + var plugin = BuildV2Plugin(mock.Object); + var result = await plugin.Enroll( + MockCertificateData.FakeCsrPem, + "CN=example.com", + new Dictionary(), + MakeV2ProductInfo(productVariant: "dv"), + RequestFormat.PKCS10, + EnrollmentType.New); + + result.Certificate.Should().Be(MockCertificateData.FakePemCertificate, + because: "no chainPem means only the leaf cert is returned"); + } + + // --------------------------------------------------------------------------- + // ValidateCAConnectionInfo — consolidated config. + // + // V2 mode: a single ApiUrl (required in both modes) plus OAuthClientId/OAuthClientSecret. + // V1-only fields (AccountNumber, AuthMode, ApiKey, ...) are NOT required when UseV2Api + // is true. + // --------------------------------------------------------------------------- + + [Fact] + public async Task ValidateCAConnectionInfo_V2_Throws_WhenApiUrlMissing() + { + var plugin = BuildV2Plugin(NewMock().Object); + var info = new Dictionary + { + ["UseV2Api"] = true, + ["OAuthClientId"] = "my-client", + ["OAuthClientSecret"] = "my-secret" + // No ApiUrl + }; + + Func act = () => plugin.ValidateCAConnectionInfo(info); + + await act.Should().ThrowAsync() + .WithMessage("*ApiUrl*required*"); + } + + [Fact] + public async Task ValidateCAConnectionInfo_V2_Throws_WhenApiUrlIsNotUri() + { + var plugin = BuildV2Plugin(NewMock().Object); + var info = new Dictionary + { + ["UseV2Api"] = true, + ["ApiUrl"] = "not-a-url", + ["OAuthClientId"] = "my-client", + ["OAuthClientSecret"] = "my-secret" + }; + + Func act = () => plugin.ValidateCAConnectionInfo(info); + + await act.Should().ThrowAsync() + .WithMessage("*ApiUrl*valid absolute URI*"); + } + + [Fact] + public async Task ValidateCAConnectionInfo_V2_Throws_WhenOAuthClientIdMissing() + { + var plugin = BuildV2Plugin(NewMock().Object); + var info = new Dictionary + { + ["UseV2Api"] = true, + ["ApiUrl"] = "https://v2.certinext.io", + // No OAuthClientId + ["OAuthClientSecret"] = "my-secret" + }; + + Func act = () => plugin.ValidateCAConnectionInfo(info); + + await act.Should().ThrowAsync() + .WithMessage("*OAuthClientId*required*"); + } + + [Fact] + public async Task ValidateCAConnectionInfo_V2_Throws_WhenOAuthClientSecretMissing() + { + var plugin = BuildV2Plugin(NewMock().Object); + var info = new Dictionary + { + ["UseV2Api"] = true, + ["ApiUrl"] = "https://v2.certinext.io", + ["OAuthClientId"] = "my-client" + // No OAuthClientSecret + }; + + Func act = () => plugin.ValidateCAConnectionInfo(info); + + await act.Should().ThrowAsync() + .WithMessage("*OAuthClientSecret*required*"); + } + + [Fact] + public async Task ValidateCAConnectionInfo_V2_DoesNotRequireV1Credentials() + { + // No AccountNumber, AuthMode, or ApiKey at all — V1 credentials must be optional + // when UseV2Api is true. Uses a real WireMock server so the live V2 + // ping (the only other thing this method does) succeeds. + using var server = WireMockServer.Start(); + server + .Given(Request.Create().WithPath("/oauth/token").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2TokenResponseJson())); + server + .Given(Request.Create().WithPath("/api/certinext/v2/auth/me").UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2AuthMeJson())); + + var plugin = BuildV2Plugin(NewMock().Object); + var info = new Dictionary + { + ["UseV2Api"] = true, + ["ApiUrl"] = server.Urls[0], + ["OAuthClientId"] = "my-client", + ["OAuthClientSecret"] = "my-secret", + ["SignerPlace"] = "New York" // required for V2 + // No AccountNumber / AuthMode / ApiKey at all. + }; + + Func act = () => plugin.ValidateCAConnectionInfo(info); + + await act.Should().NotThrowAsync( + "V1 credentials (AccountNumber/AuthMode/ApiKey) must not be required when UseV2Api is true"); + } + + [Fact] + public async Task ValidateCAConnectionInfo_V1_UseV2ApiFalse_StillRequiresAccountNumberAndAuthMode() + { + // UseV2Api false (the default/legacy path) — V1 requirements are unchanged, and the + // (now nonexistent) V2-only fields must never appear in the resulting error. + var plugin = BuildV2Plugin(NewMock().Object); + var info = new Dictionary + { + ["ApiUrl"] = "https://v1.certinext.io", + ["UseV2Api"] = false + // No AccountNumber, no AuthMode/ApiKey. + }; + + Func act = () => plugin.ValidateCAConnectionInfo(info); + + var ex = await act.Should().ThrowAsync(); + ex.Which.Message.Should().Contain("AccountNumber") + .And.NotContain("ApiUrlV2").And.NotContain("OAuthClientId").And.NotContain("OAuthClientSecret"); + } + + [Fact] + public async Task ValidateCAConnectionInfo_AllV2FieldsPresent_Passes() + { + using var server = WireMockServer.Start(); + server + .Given(Request.Create().WithPath("/oauth/token").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2TokenResponseJson())); + server + .Given(Request.Create().WithPath("/api/certinext/v2/auth/me").UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2AuthMeJson())); + + var plugin = BuildV2Plugin(NewMock().Object); + var info = new Dictionary + { + ["UseV2Api"] = true, + ["ApiUrl"] = server.Urls[0], + ["OAuthClientId"] = "my-client", + ["OAuthClientSecret"] = "my-secret", + ["SignerPlace"] = "New York" // required for V2 + }; + + Func act = () => plugin.ValidateCAConnectionInfo(info); + + await act.Should().NotThrowAsync( + "ApiUrl and OAuthClientId/OAuthClientSecret are present and valid, and the live V2 ping succeeds"); + } + + // --------------------------------------------------------------------------- + // ValidateProductInfo — V2. ValidateProductInfo builds its own + // CERTInextClient from connectionInfo rather than using the Moq-injected client (like + // ValidateCAConnectionInfo), so these tests use a real WireMock server as ApiUrl. + // --------------------------------------------------------------------------- + + private static void StubV2TokenAndAuthMe(WireMockServer server) + { + server + .Given(Request.Create().WithPath("/oauth/token").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2TokenResponseJson())); + } + + private static Dictionary BuildV2ConnectionInfo(string apiUrl, string defaultProductCode = null) + { + var info = new Dictionary + { + ["UseV2Api"] = true, + ["ApiUrl"] = apiUrl, + ["OAuthClientId"] = "my-client", + ["OAuthClientSecret"] = "my-secret" + }; + if (!string.IsNullOrWhiteSpace(defaultProductCode)) + info["DefaultProductCode"] = defaultProductCode; + return info; + } + + private static EnrollmentProductInfo BuildProductInfo(string productCode) => new EnrollmentProductInfo + { + ProductID = "ssl", + ProductParameters = new Dictionary { ["ProductCode"] = productCode } + }; + + [Fact] + public async Task ValidateProductInfo_V2_Succeeds_WhenProductCodeInCatalog() + { + using var server = WireMockServer.Start(); + StubV2TokenAndAuthMe(server); + server + .Given(Request.Create().WithPath("/api/certinext/v2/catalog/products").UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.GetCatalogProductsV2NestedJson())); + + var plugin = BuildV2Plugin(NewMock().Object); + var connInfo = BuildV2ConnectionInfo(server.Urls[0]); + var productInfo = BuildProductInfo(MockCertificateData.ProfileIdTls); + + Func act = () => plugin.ValidateProductInfo(productInfo, connInfo); + + await act.Should().NotThrowAsync(); + + // In V2 mode this must go through the V2 catalog, + // never the V1-only GetProductDetails endpoint. + server.LogEntries.Should().NotContain(e => e.RequestMessage.Path == "/GetProductDetails"); + server.LogEntries.Should().Contain(e => e.RequestMessage.Path == "/api/certinext/v2/catalog/products"); + } + + [Fact] + public async Task ValidateProductInfo_V2_Throws_WhenProductCodeNotInCatalog() + { + using var server = WireMockServer.Start(); + StubV2TokenAndAuthMe(server); + server + .Given(Request.Create().WithPath("/api/certinext/v2/catalog/products").UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.GetCatalogProductsV2NestedJson())); + + var plugin = BuildV2Plugin(NewMock().Object); + var connInfo = BuildV2ConnectionInfo(server.Urls[0]); + var productInfo = BuildProductInfo("999999"); + + Func act = () => plugin.ValidateProductInfo(productInfo, connInfo); + + await act.Should().ThrowAsync() + .WithMessage("*not found*"); + } + + [Fact] + public async Task ValidateProductInfo_V2_Throws_WhenCatalogEmpty() + { + using var server = WireMockServer.Start(); + StubV2TokenAndAuthMe(server); + server + .Given(Request.Create().WithPath("/api/certinext/v2/catalog/products").UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.GetCatalogProductsV2EmptyJson())); + + var plugin = BuildV2Plugin(NewMock().Object); + var connInfo = BuildV2ConnectionInfo(server.Urls[0]); + var productInfo = BuildProductInfo(MockCertificateData.ProfileIdTls); + + Func act = () => plugin.ValidateProductInfo(productInfo, connInfo); + + // No soft-accept on an empty/unusable catalog — must match V1's strict behaviour. + await act.Should().ThrowAsync() + .WithMessage("*not found*"); + } + + [Fact] + public async Task ValidateProductInfo_V2_Throws_WhenCatalogReturnsError() + { + using var server = WireMockServer.Start(); + StubV2TokenAndAuthMe(server); + server + .Given(Request.Create().WithPath("/api/certinext/v2/catalog/products").UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(500) + .WithHeader("Content-Type", "application/json") + .WithBody("{\"secretApiKeyLeak\":\"should-not-appear-in-message\"}")); + + var plugin = BuildV2Plugin(NewMock().Object); + var connInfo = BuildV2ConnectionInfo(server.Urls[0]); + var productInfo = BuildProductInfo(MockCertificateData.ProfileIdTls); + + Func act = () => plugin.ValidateProductInfo(productInfo, connInfo); + + var ex = await act.Should().ThrowAsync() + .WithMessage("*Unable to validate*"); + ex.Which.Message.Should().NotContain("secretApiKeyLeak"); + } + + // --------------------------------------------------------------------------- + // productTypeID correctness check — catches a code that exists in the + // catalog but means a different product than the one selected, for both the + // explicit-override case and the no-override/fallback case. ValidateProductInfo + // must reject these, not just check catalog-existence. + // --------------------------------------------------------------------------- + + [Fact] + public async Task ValidateProductInfo_V2_Throws_WhenProductCodeExistsButProductTypeIdMismatchesSelectedProduct() + { + // Template selects "OV SSL" (expects productTypeID "16") but overrides ProductCode to + // "842", which the live catalog (stubbed here) resolves to productTypeID "13" = DV + // SSL. The code exists — a pure existence check would pass this — but it means a + // different product than the one selected. + using var server = WireMockServer.Start(); + StubV2TokenAndAuthMe(server); + server + .Given(Request.Create().WithPath("/api/certinext/v2/catalog/products").UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(@"[{""productCode"":""842"",""productName"":""DV SSL Certificate"",""productTypeID"":""13""}]")); + + var plugin = BuildV2Plugin(NewMock().Object); + var connInfo = BuildV2ConnectionInfo(server.Urls[0]); + var productInfo = new EnrollmentProductInfo + { + ProductID = Constants.Products.OvSsl, + ProductParameters = new Dictionary { ["ProductCode"] = "842" } + }; + + Func act = () => plugin.ValidateProductInfo(productInfo, connInfo); + + await act.Should().ThrowAsync() + .WithMessage("*does not correspond to the selected product*"); + } + + // --------------------------------------------------------------------------- + // No explicit ProductCode on a V2 template. X-Product-Code is the spec's optional override + // (CERTInext resolves the product from the variant / wildcard shape / additionalDomains), + // so there is nothing to look up and nothing ambiguous to reject: the catalog is not even + // consulted, whatever it contains (no match, several same-type entries, a DefaultProductCode + // that names another type). + // --------------------------------------------------------------------------- + + [Theory] + [InlineData("OV SSL", @"[{""productCode"":""846"",""productName"":""OV SSL Certificate"",""productTypeID"":""16""}]", null)] + [InlineData("EV SSL", @"[{""productCode"":""842"",""productName"":""DV SSL Certificate"",""productTypeID"":""13""}]", null)] + [InlineData("DV SSL", @"[{""productCode"":""917"",""productName"":""SSL DV 1 month"",""productTypeID"":""13""},{""productCode"":""842"",""productName"":""DV SSL Certificate"",""productTypeID"":""13""}]", null)] + [InlineData("DV SSL", @"[{""productCode"":""917"",""productTypeID"":""13""},{""productCode"":""842"",""productTypeID"":""13""},{""productCode"":""846"",""productTypeID"":""16""}]", "846")] + public async Task ValidateProductInfo_V2_NoExplicitProductCode_Passes_WithoutAnyCatalogCall( + string productId, string catalogBody, string defaultProductCode) + { + using var server = WireMockServer.Start(); + StubV2TokenAndAuthMe(server); + server + .Given(Request.Create().WithPath("/api/certinext/v2/catalog/products").UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(catalogBody)); + + var plugin = BuildV2Plugin(NewMock().Object); + var connInfo = BuildV2ConnectionInfo(server.Urls[0], defaultProductCode: defaultProductCode); + var productInfo = new EnrollmentProductInfo + { + ProductID = productId, + ProductParameters = new Dictionary() + }; + + Func act = () => plugin.ValidateProductInfo(productInfo, connInfo); + + await act.Should().NotThrowAsync(); + server.LogEntries.Should().NotContain(e => e.RequestMessage.Path == "/api/certinext/v2/catalog/products", + "no X-Product-Code is sent without an explicit ProductCode, so no catalog check is needed"); + } + + // --------------------------------------------------------------------------- + // Bodyless-REVOKED guard. A V2 REVOKED record with no certificate + // body must never reach the gateway buffer / be returned as-is unless + // ICertificateDataReader.GetExpirationDateByRequestId confirms the gateway + // already holds a body for that CARequestID (DecideBodylessRevokedRecord). + // --------------------------------------------------------------------------- + + [Fact] + public async Task Synchronize_RevokedNoBody_GatewayHoldsBody_EmitsBodylessRevoked() + { + var mock = new Mock(); + var row = ReportRow("ord_bodyless_a", "Revoked", "Certificate Revoked"); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable(row)); + + var readerMock = new Mock(); + readerMock.Setup(r => r.GetExpirationDateByRequestId("ord_bodyless_a")) + .Returns(DateTime.UtcNow.AddDays(45)); + + var plugin = BuildV2Plugin(mock.Object, certDataReader: readerMock.Object); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + var records = buffer.ToArray(); + records.Should().ContainSingle( + "the gateway already holds a body for this order, so the revoke must " + + "still propagate as a bodyless REVOKED record") + .Which.Status.Should().Be((int)EndEntityStatus.REVOKED); + records[0].Certificate.Should().BeNullOrEmpty(); + + readerMock.Verify(r => r.GetExpirationDateByRequestId("ord_bodyless_a"), Times.Once); + } + + [Fact] + public async Task Synchronize_RevokedNoBody_GatewayRowHasNoBody_EmitsFailedNotRevoked() + { + var mock = new Mock(); + var row = ReportRow("ord_bodyless_b", "Revoked", "Certificate Revoked"); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable(row)); + + var readerMock = new Mock(); + readerMock.Setup(r => r.GetExpirationDateByRequestId("ord_bodyless_b")) + .Returns((DateTime?)null); // row exists, but the gateway holds no body + + var plugin = BuildV2Plugin(mock.Object, certDataReader: readerMock.Object); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + var records = buffer.ToArray(); + records.Should().ContainSingle( + "a gateway row with no body must be downgraded to FAILED, never left as a " + + "bodyless REVOKED record") + .Which.Status.Should().Be((int)EndEntityStatus.FAILED); + records[0].Certificate.Should().BeNullOrEmpty(); + records[0].RevocationDate.Should().BeNull(); + records[0].RevocationReason.Should().Be(0); + } + + [Fact] + public async Task Synchronize_RevokedNoBody_NoGatewayRow_SkipsRecordEntirely() + { + var mock = new Mock(); + var row = ReportRow("ord_bodyless_c", "Revoked", "Certificate Revoked"); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable(row)); + + var readerMock = new Mock(); + readerMock.Setup(r => r.GetExpirationDateByRequestId("ord_bodyless_c")) + .Throws(new ArgumentException("No certificate/CA request exists for the specified request ID.")); + + var plugin = BuildV2Plugin(mock.Object, certDataReader: readerMock.Object); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + buffer.ToArray().Should().BeEmpty( + "the gateway has never seen this order — creating a bodyless REVOKED row would " + + "poison it (RevocationDate is never cleared by the gateway)"); + } + + [Fact] + public async Task Synchronize_RevokedNoBody_ReaderThrowsUnexpectedException_SkipsRecord() + { + var mock = new Mock(); + var row = ReportRow("ord_bodyless_d", "Revoked", "Certificate Revoked"); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable(row)); + + var readerMock = new Mock(); + readerMock.Setup(r => r.GetExpirationDateByRequestId("ord_bodyless_d")) + .Throws(new InvalidOperationException("gateway database unavailable")); + + var plugin = BuildV2Plugin(mock.Object, certDataReader: readerMock.Object); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + buffer.ToArray().Should().BeEmpty( + "an unexpected reader failure must not risk emitting a bodyless REVOKED record — " + + "the revoke is only delayed to a later sync"); + } + + [Fact] + public async Task Synchronize_RevokedNoBody_NoCertificateDataReaderInjected_SkipsRecord() + { + var mock = new Mock(); + var row = ReportRow("ord_bodyless_e", "Revoked", "Certificate Revoked"); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable(row)); + + // No certDataReader supplied — BuildV2Plugin defaults it to null. + var plugin = BuildV2Plugin(mock.Object); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + buffer.ToArray().Should().BeEmpty( + "with no reader available to consult, the plugin must not risk creating a " + + "poisoned gateway row"); + } + + [Fact] + public async Task Synchronize_BodylessRevokedGuard_GeneratedRow_NeverConsultsReader() + { + var mock = new Mock(); + var row = ReportRow("ord_bodyless_f", "Order Fulfilled", "Certificate Downloaded"); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable(row)); + mock.Setup(c => c.ResolveAndDownloadCertificateV2Async("ord_bodyless_f", It.IsAny())) + .ReturnsAsync(new V2CertificateDownloadResponse + { + OrderId = "ord_bodyless_f", + CertificatePem = MockCertificateData.FakePemCertificate + }); + + // Strict with no setups — any call at all fails the test. Confirms the bodyless- + // REVOKED guard is scoped to REVOKED-with-no-body and never touches the GENERATED path. + var readerMock = new Mock(MockBehavior.Strict); + var plugin = BuildV2Plugin(mock.Object, certDataReader: readerMock.Object); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + var records = buffer.ToArray(); + records.Should().ContainSingle() + .Which.Status.Should().Be((int)EndEntityStatus.GENERATED); + records[0].Certificate.Should().StartWith("-----BEGIN CERTIFICATE-----"); + + readerMock.VerifyNoOtherCalls(); + } + + [Fact] + public async Task Synchronize_BodylessRevokedGuard_MixedBatch_NeverEmitsBodylessRevokedWithoutReaderConfirmation() + { + var mock = new Mock(); + var rowHoldsBody = ReportRow("ord_mix_holds", "Revoked", "Certificate Revoked"); + var rowNoBody = ReportRow("ord_mix_nobody", "Revoked", "Certificate Revoked"); + var rowNoRow = ReportRow("ord_mix_norow", "Revoked", "Certificate Revoked"); + + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnumerable(rowHoldsBody, rowNoBody, rowNoRow)); + + var readerMock = new Mock(); + readerMock.Setup(r => r.GetExpirationDateByRequestId("ord_mix_holds")) + .Returns(DateTime.UtcNow.AddDays(60)); + readerMock.Setup(r => r.GetExpirationDateByRequestId("ord_mix_nobody")) + .Returns((DateTime?)null); + readerMock.Setup(r => r.GetExpirationDateByRequestId("ord_mix_norow")) + .Throws(new ArgumentException("no such request id")); + + var plugin = BuildV2Plugin(mock.Object, certDataReader: readerMock.Object); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + var records = buffer.ToArray(); + + // Core invariant: no record with Status=REVOKED and no certificate + // body may reach the gateway buffer unless the reader confirmed the gateway + // already holds a body for that specific CARequestID. + records.Should().NotContain(r => + r.Status == (int)EndEntityStatus.REVOKED && string.IsNullOrEmpty(r.Certificate) + && r.CARequestID != "ord_mix_holds"); + + records.Should().ContainSingle(r => r.CARequestID == "ord_mix_holds") + .Which.Status.Should().Be((int)EndEntityStatus.REVOKED); + records.Should().ContainSingle(r => r.CARequestID == "ord_mix_nobody") + .Which.Status.Should().Be((int)EndEntityStatus.FAILED); + records.Should().NotContain(r => r.CARequestID == "ord_mix_norow"); + } + + [Fact] + public async Task GetSingleRecord_RevokedNoBody_GatewayHoldsBody_ReturnsRevoked() + { + var mock = NewMock(); + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync( + MockCertificateData.V2OrderId1, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse + { + OrderId = MockCertificateData.V2OrderId1, + Status = "revoked", + ProductVariant = "dv" + })); + + var readerMock = new Mock(); + readerMock.Setup(r => r.GetExpirationDateByRequestId(MockCertificateData.V2OrderId1)) + .Returns(DateTime.UtcNow.AddDays(10)); + + var plugin = BuildV2Plugin(mock.Object, certDataReader: readerMock.Object); + var record = await plugin.GetSingleRecord(MockCertificateData.V2OrderId1); + + record.Status.Should().Be((int)EndEntityStatus.REVOKED); + record.Certificate.Should().BeNullOrEmpty(); + } + + [Fact] + public async Task GetSingleRecord_RevokedNoBody_GatewayRowHasNoBody_ReturnsFailed() + { + var mock = NewMock(); + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync( + MockCertificateData.V2OrderId1, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse + { + OrderId = MockCertificateData.V2OrderId1, + Status = "revoked", + ProductVariant = "dv", + Revocation = new V2RevocationDetails + { + Status = "Certificate Revoked", + Reason = "cessation-of-operation", + ProcessedAt = DateTime.UtcNow + } + })); + + var readerMock = new Mock(); + readerMock.Setup(r => r.GetExpirationDateByRequestId(MockCertificateData.V2OrderId1)) + .Returns((DateTime?)null); + + var plugin = BuildV2Plugin(mock.Object, certDataReader: readerMock.Object); + var record = await plugin.GetSingleRecord(MockCertificateData.V2OrderId1); + + record.Status.Should().Be((int)EndEntityStatus.FAILED); + record.Certificate.Should().BeNullOrEmpty(); + record.RevocationDate.Should().BeNull(); + record.RevocationReason.Should().Be(0); + } + + [Fact] + public async Task GetSingleRecord_RevokedNoBody_NoGatewayRow_ReturnsFailed() + { + var mock = NewMock(); + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync( + MockCertificateData.V2OrderId1, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse + { + OrderId = MockCertificateData.V2OrderId1, + Status = "revoked" + })); + + var readerMock = new Mock(); + readerMock.Setup(r => r.GetExpirationDateByRequestId(MockCertificateData.V2OrderId1)) + .Throws(new ArgumentException("no such request id")); + + var plugin = BuildV2Plugin(mock.Object, certDataReader: readerMock.Object); + var record = await plugin.GetSingleRecord(MockCertificateData.V2OrderId1); + + record.Should().NotBeNull( + "GetSingleRecord cannot skip — it must return something even when the gateway " + + "has no row for this order"); + record.Status.Should().Be((int)EndEntityStatus.FAILED); + record.Certificate.Should().BeNullOrEmpty(); + record.RevocationDate.Should().BeNull(); + } + + [Fact] + public async Task GetSingleRecord_RevokedNoBody_NoCertificateDataReaderInjected_ReturnsFailed() + { + var mock = NewMock(); + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync( + MockCertificateData.V2OrderId1, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse + { + OrderId = MockCertificateData.V2OrderId1, + Status = "revoked" + })); + + // No certDataReader supplied — BuildV2Plugin defaults it to null. + var plugin = BuildV2Plugin(mock.Object); + var record = await plugin.GetSingleRecord(MockCertificateData.V2OrderId1); + + record.Status.Should().Be((int)EndEntityStatus.FAILED); + } + + [Fact] + public async Task GetSingleRecord_BodylessRevokedGuard_GeneratedRecord_NeverConsultsReader() + { + var mock = NewMock(); + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync( + MockCertificateData.V2OrderId1, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse + { + OrderId = MockCertificateData.V2OrderId1, + Status = "issued", + ProductVariant = "dv" + })); + mock.Setup(c => c.ResolveAndDownloadCertificateV2Async( + MockCertificateData.V2OrderId1, It.IsAny())) + .ReturnsAsync(new V2CertificateDownloadResponse + { + OrderId = MockCertificateData.V2OrderId1, + CertificatePem = MockCertificateData.FakePemCertificate + }); + + // Strict with no setups — confirms the bodyless-revoked guard never touches GENERATED. + var readerMock = new Mock(MockBehavior.Strict); + var plugin = BuildV2Plugin(mock.Object, certDataReader: readerMock.Object); + + var record = await plugin.GetSingleRecord(MockCertificateData.V2OrderId1); + + record.Status.Should().Be((int)EndEntityStatus.GENERATED); + readerMock.VerifyNoOtherCalls(); + } + + // --------------------------------------------------------------------------- + // Helpers + // --------------------------------------------------------------------------- + + private static async IAsyncEnumerable AsyncEnumerable(params T[] items) + { + foreach (var item in items) + yield return item; + await Task.CompletedTask; + } + } +} diff --git a/CERTInext.Tests/CERTInextClientRequestShapeTests.cs b/CERTInext.Tests/CERTInextClientRequestShapeTests.cs index 4e59495..d6809e5 100644 --- a/CERTInext.Tests/CERTInextClientRequestShapeTests.cs +++ b/CERTInext.Tests/CERTInextClientRequestShapeTests.cs @@ -143,57 +143,100 @@ public async Task OrganizationNumber_Blank_OmitsOrganizationDetailsBlock() } // ----------------------------------------------------------------------- - // GroupNumber → delegationInformation block + // Legacy (wrong) field placements must never reappear. CERTInext reads + // groupNumber / autoSecureWWW from orderDetails and the technical contact as + // poc* fields; the shapes below were ignored by the API. + // ----------------------------------------------------------------------- + + private static void AssertNoLegacyFieldShapes(JsonElement orderDetails) + { + orderDetails.TryGetProperty("delegationInformation", out _).Should().BeFalse( + "delegationInformation{groupNumber} is not read by CERTInext — groupNumber belongs on orderDetails"); + orderDetails.GetProperty("certificateInformation").TryGetProperty("autoSecureWWW", out _).Should().BeFalse( + "autoSecureWWW is read from orderDetails, not certificateInformation"); + CollectPropertyNames(orderDetails) + .Where(n => n.StartsWith("tpc", StringComparison.Ordinal)) + .Should().BeEmpty("the technical contact uses poc* field names, not tpc*"); + } + + private static System.Collections.Generic.IEnumerable CollectPropertyNames(JsonElement element) + { + if (element.ValueKind == JsonValueKind.Object) + { + foreach (var prop in element.EnumerateObject()) + { + yield return prop.Name; + foreach (var nested in CollectPropertyNames(prop.Value)) + yield return nested; + } + } + else if (element.ValueKind == JsonValueKind.Array) + { + foreach (var item in element.EnumerateArray()) + foreach (var nested in CollectPropertyNames(item)) + yield return nested; + } + } + + // ----------------------------------------------------------------------- + // GroupNumber → orderDetails.groupNumber // ----------------------------------------------------------------------- [Fact] - public async Task GroupNumber_Set_EmitsDelegationInformation() + public async Task GroupNumber_Set_EmitsOrderDetailsGroupNumber() { StubHappyEnroll(); var cfg = MinimalConfig(); - cfg.GroupNumber = "2171775848"; + cfg.GroupNumber = "1000000001"; await BuildClient(cfg).EnrollCertificateAsync(BasicEnrollRequest()); var orderDetails = CapturedOrderBody(); - orderDetails.TryGetProperty("delegationInformation", out var delegation).Should().BeTrue(); - delegation.GetProperty("groupNumber").GetString().Should().Be("2171775848"); + orderDetails.GetProperty("groupNumber").GetString().Should().Be("1000000001"); + AssertNoLegacyFieldShapes(orderDetails); } - [Fact] - public async Task GroupNumber_Blank_OmitsDelegationInformation() + [Theory] + [InlineData(null)] + [InlineData("")] + [InlineData(" ")] + public async Task GroupNumber_Blank_OmitsGroupNumber(string blank) { StubHappyEnroll(); var cfg = MinimalConfig(); - cfg.GroupNumber = string.Empty; + cfg.GroupNumber = blank; await BuildClient(cfg).EnrollCertificateAsync(BasicEnrollRequest()); var orderDetails = CapturedOrderBody(); - orderDetails.TryGetProperty("delegationInformation", out _).Should().BeFalse(); + orderDetails.TryGetProperty("groupNumber", out _).Should().BeFalse(); + AssertNoLegacyFieldShapes(orderDetails); } // ----------------------------------------------------------------------- - // technicalPointOfContact — overrides + requestor fallback + // technicalPointOfContact — poc* fields, name split, requestor fallback // ----------------------------------------------------------------------- [Fact] - public async Task TechnicalContact_AllSet_EmitsExplicitValues() + public async Task TechnicalContact_AllSet_EmitsPocFields() { StubHappyEnroll(); var cfg = MinimalConfig(); - cfg.TechnicalContactName = "Jane Smith"; - cfg.TechnicalContactEmail = "tpc@example.com"; + cfg.TechnicalContactName = "Jane Q Smith"; + cfg.TechnicalContactEmail = "poc@example.com"; cfg.TechnicalContactIsdCode = "44"; cfg.TechnicalContactMobileNumber = "5559999999"; await BuildClient(cfg).EnrollCertificateAsync(BasicEnrollRequest()); - var tpc = CapturedOrderBody().GetProperty("technicalPointOfContact"); - tpc.GetProperty("tpcName").GetString().Should().Be("Jane Smith"); - tpc.GetProperty("tpcEmail").GetString().Should().Be("tpc@example.com"); - tpc.GetProperty("tpcIsdCode").GetString().Should().Be("44"); - tpc.GetProperty("tpcMobileNumber").GetString().Should().Be("5559999999"); + var od = CapturedOrderBody(); + var poc = od.GetProperty("technicalPointOfContact"); + poc.GetProperty("pocFirstName").GetString().Should().Be("Jane"); + poc.GetProperty("pocLastName").GetString().Should().Be("Q Smith"); + poc.GetProperty("pocEmail").GetString().Should().Be("poc@example.com"); + poc.GetProperty("pocIsdCode").GetString().Should().Be("44"); + poc.GetProperty("pocMobileNumber").GetString().Should().Be("5559999999"); + AssertNoLegacyFieldShapes(od); } [Fact] @@ -209,17 +252,141 @@ public async Task TechnicalContact_AllBlank_FallsBackToRequestorDefaults() await BuildClient(cfg).EnrollCertificateAsync(BasicEnrollRequest()); - var tpc = CapturedOrderBody().GetProperty("technicalPointOfContact"); - tpc.GetProperty("tpcName").GetString().Should().Be(cfg.RequestorName); - tpc.GetProperty("tpcEmail").GetString().Should().Be(cfg.RequestorEmail); - tpc.GetProperty("tpcIsdCode").GetString().Should().Be(cfg.RequestorIsdCode); - tpc.GetProperty("tpcMobileNumber").GetString().Should().Be(cfg.RequestorMobileNumber); + var poc = CapturedOrderBody().GetProperty("technicalPointOfContact"); + // MinimalConfig RequestorName = "Default Requestor" + poc.GetProperty("pocFirstName").GetString().Should().Be("Default"); + poc.GetProperty("pocLastName").GetString().Should().Be("Requestor"); + poc.GetProperty("pocEmail").GetString().Should().Be(cfg.RequestorEmail); + poc.GetProperty("pocIsdCode").GetString().Should().Be(cfg.RequestorIsdCode); + poc.GetProperty("pocMobileNumber").GetString().Should().Be(cfg.RequestorMobileNumber); + } + + [Fact] + public async Task TechnicalContact_SingleTokenName_FillsFirstAndLast() + { + StubHappyEnroll(); + var cfg = MinimalConfig(); + cfg.TechnicalContactName = " Operations "; + + await BuildClient(cfg).EnrollCertificateAsync(BasicEnrollRequest()); + + var poc = CapturedOrderBody().GetProperty("technicalPointOfContact"); + poc.GetProperty("pocFirstName").GetString().Should().Be("Operations"); + poc.GetProperty("pocLastName").GetString().Should().Be("Operations"); + } + + [Fact] + public async Task TechnicalContact_PerFieldFallback_MixesOverridesAndRequestorValues() + { + StubHappyEnroll(); + var cfg = MinimalConfig(); + cfg.TechnicalContactName = string.Empty; // → requestor name + cfg.TechnicalContactEmail = "poc@example.com"; // override + cfg.TechnicalContactIsdCode = string.Empty; // → requestor ISD + cfg.TechnicalContactMobileNumber = "5551112222"; // override + + await BuildClient(cfg).EnrollCertificateAsync(BasicEnrollRequest()); + + var poc = CapturedOrderBody().GetProperty("technicalPointOfContact"); + poc.GetProperty("pocFirstName").GetString().Should().Be("Default"); + poc.GetProperty("pocLastName").GetString().Should().Be("Requestor"); + poc.GetProperty("pocEmail").GetString().Should().Be("poc@example.com"); + poc.GetProperty("pocIsdCode").GetString().Should().Be(cfg.RequestorIsdCode); + poc.GetProperty("pocMobileNumber").GetString().Should().Be("5551112222"); + } + + [Fact] + public async Task TechnicalContact_NoEmailResolved_OmitsBlock() + { + StubHappyEnroll(); + var cfg = MinimalConfig(); + cfg.RequestorEmail = string.Empty; + cfg.TechnicalContactEmail = " "; + cfg.TechnicalContactName = "Jane Smith"; + + await BuildClient(cfg).EnrollCertificateAsync(BasicEnrollRequest()); + + var od = CapturedOrderBody(); + od.TryGetProperty("technicalPointOfContact", out _).Should().BeFalse( + "a POC with no email would now be validated by CERTInext — omit it rather than reject the order"); + AssertNoLegacyFieldShapes(od); + } + + [Theory] + [InlineData("", "")] + [InlineData(" ", "")] + [InlineData("", " ")] + public async Task TechnicalContact_NoNameResolved_OmitsBlock_OnEnroll(string technicalName, string requestorName) + { + StubHappyEnroll(); + var cfg = MinimalConfig(); + cfg.TechnicalContactName = technicalName; + cfg.RequestorName = requestorName; + // Email resolves fine — only the name is missing. + cfg.TechnicalContactEmail = "poc@example.com"; + + await BuildClient(cfg).EnrollCertificateAsync(BasicEnrollRequest()); + + var od = CapturedOrderBody(); + od.TryGetProperty("technicalPointOfContact", out _).Should().BeFalse( + "CERTInext requires the POC name inside the block — omit it rather than send empty first/last names"); + AssertNoLegacyFieldShapes(od); + } + + [Fact] + public async Task TechnicalContact_NoNameResolved_OmitsBlock_OnRenewal() + { + StubHappyEnroll(); + var cfg = MinimalConfig(); + cfg.TechnicalContactName = string.Empty; + cfg.RequestorName = string.Empty; + cfg.TechnicalContactEmail = "poc@example.com"; + + var renewReq = new RenewCertificateRequest + { + Csr = MockCertificateData.FakeCsrPem, + ProfileId = "842", + ValidityDays = 365, + Comment = "Renewal test" + }; + + await BuildClient(cfg).RenewCertificateAsync(MockCertificateData.OrderNumber1, renewReq); + + var od = CapturedOrderBody(); + od.TryGetProperty("technicalPointOfContact", out _).Should().BeFalse( + "renewal shares the enroll builder and must also omit a POC block with no name"); + AssertNoLegacyFieldShapes(od); + } + + [Fact] + public async Task TechnicalContact_RenewalWithRequesterName_EmitsBlockFromRequesterName() + { + StubHappyEnroll(); + var cfg = MinimalConfig(); + cfg.TechnicalContactName = string.Empty; + cfg.RequestorName = string.Empty; // config blank, but the renewal request supplies a name + cfg.TechnicalContactEmail = "poc@example.com"; + + var renewReq = new RenewCertificateRequest + { + Csr = MockCertificateData.FakeCsrPem, + ProfileId = "842", + ValidityDays = 365, + RequesterName = "Renew Requester", + Comment = "Renewal test" + }; + + await BuildClient(cfg).RenewCertificateAsync(MockCertificateData.OrderNumber1, renewReq); + + var poc = CapturedOrderBody().GetProperty("technicalPointOfContact"); + poc.GetProperty("pocFirstName").GetString().Should().Be("Renew"); + poc.GetProperty("pocLastName").GetString().Should().Be("Requester"); } // ----------------------------------------------------------------------- // SSL order body defaults — AccountingModel / EmailNotifications / // SubscriptionAutoRenew / SubscriptionRenewCriteriaDays / - // SubscriptionValidityYears / AutoSecureWww + // SubscriptionValidityYears / AutoSecureWww (→ orderDetails.autoSecureWWW) // ----------------------------------------------------------------------- [Fact] @@ -245,7 +412,8 @@ public async Task SslBodyDefaults_AreEmitted_FromCustomConnectorValues() sub.GetProperty("autoRenew").GetString().Should().Be("1"); sub.GetProperty("renewCriteria").GetString().Should().Be("60"); - od.GetProperty("certificateInformation").GetProperty("autoSecureWWW").GetString().Should().Be("1"); + od.GetProperty("autoSecureWWW").GetString().Should().Be("1"); + AssertNoLegacyFieldShapes(od); } [Fact] @@ -266,9 +434,26 @@ public async Task SslBodyDefaults_AreSafeFallbacks_WhenConfigUntouched() sub.GetProperty("autoRenew").GetString().Should().Be("0"); sub.GetProperty("renewCriteria").GetString().Should().Be("30"); - od.GetProperty("certificateInformation").GetProperty("autoSecureWWW").GetString().Should().Be("0"); + od.GetProperty("autoSecureWWW").GetString().Should().Be("0", + "the documented AutoSecureWww default of 0 must actually be sent, or CERTInext applies its own default of 1"); + AssertNoLegacyFieldShapes(od); + } + + [Theory] + [InlineData(null)] + [InlineData("")] + public async Task AutoSecureWww_Blank_SendsZero(string blank) + { + StubHappyEnroll(); + var cfg = MinimalConfig(); + cfg.AutoSecureWww = blank; + + await BuildClient(cfg).EnrollCertificateAsync(BasicEnrollRequest()); + + CapturedOrderBody().GetProperty("autoSecureWWW").GetString().Should().Be("0"); } + // ----------------------------------------------------------------------- // ValidityDays request-parameter still overrides the connector default // ----------------------------------------------------------------------- @@ -288,5 +473,450 @@ public async Task ValidityDays_OnRequest_OverridesConnectorDefault() CapturedOrderBody().GetProperty("subscriptionDetails") .GetProperty("validity").GetString().Should().Be("2"); } + + // ----------------------------------------------------------------------- + // New enrollment — blank-value fallbacks (local issues/0071). Config/template + // strings default to "", so null-coalesce fallbacks never fired. + // ----------------------------------------------------------------------- + + [Theory] + [InlineData(null)] + [InlineData("")] + [InlineData(" ")] + public async Task Enroll_ProfileIdBlank_FallsBackToConnectorDefaultProductCode(string blankProfileId) + { + StubHappyEnroll(); + var cfg = MinimalConfig(); + cfg.DefaultProductCode = "connector-default-code"; + var req = BasicEnrollRequest(); + req.ProfileId = blankProfileId; + + await BuildClient(cfg).EnrollCertificateAsync(req); + + CapturedOrderBody().GetProperty("productCode").GetString().Should().Be("connector-default-code", + "a blank template ProductCode must fall back to the connector's DefaultProductCode"); + } + + [Fact] + public async Task Enroll_ProfileIdSet_UsesTemplateProductCodeOverConnectorDefault() + { + StubHappyEnroll(); + var cfg = MinimalConfig(); + cfg.DefaultProductCode = "connector-default-code"; + + await BuildClient(cfg).EnrollCertificateAsync(BasicEnrollRequest()); + + CapturedOrderBody().GetProperty("productCode").GetString().Should().Be("842"); + } + + [Theory] + [InlineData(null)] + [InlineData("")] + [InlineData(" ")] + public async Task Enroll_SignerNameAndPlaceBlank_FallBackToDefaults(string blank) + { + StubHappyEnroll(); + var cfg = MinimalConfig(); + cfg.RequestorName = blank; + cfg.SignerPlace = blank; + + await BuildClient(cfg).EnrollCertificateAsync(BasicEnrollRequest()); + + var agreement = CapturedOrderBody().GetProperty("agreementDetails"); + agreement.GetProperty("signerName").GetString().Should().Be("Keyfactor Gateway"); + agreement.GetProperty("signerPlace").GetString().Should().Be("Gateway"); + } + + [Fact] + public async Task Enroll_SignerNameAndPlaceConfigured_AreSentVerbatim() + { + StubHappyEnroll(); + var cfg = MinimalConfig(); // RequestorName "Default Requestor", SignerPlace "Austin" + + await BuildClient(cfg).EnrollCertificateAsync(BasicEnrollRequest()); + + var agreement = CapturedOrderBody().GetProperty("agreementDetails"); + agreement.GetProperty("signerName").GetString().Should().Be("Default Requestor"); + agreement.GetProperty("signerPlace").GetString().Should().Be("Austin"); + } + + // ----------------------------------------------------------------------- + // agreementDetails precedence: template value -> connector value -> default. + // Blank (null/""/whitespace) at either level falls through. + // ----------------------------------------------------------------------- + + [Fact] + public async Task Enroll_TemplateSignerValues_WinOverConnectorValues() + { + StubHappyEnroll(); + var cfg = MinimalConfig(); // connector: "Default Requestor" / "Austin" / 203.0.113.10 + var req = BasicEnrollRequest(); + req.SignerName = "Template Signer"; + req.SignerPlace = "Template Place"; + req.SignerIp = "198.51.100.7"; + + await BuildClient(cfg).EnrollCertificateAsync(req); + + var agreement = CapturedOrderBody().GetProperty("agreementDetails"); + agreement.GetProperty("signerName").GetString().Should().Be("Template Signer"); + agreement.GetProperty("signerPlace").GetString().Should().Be("Template Place"); + agreement.GetProperty("signerIP").GetString().Should().Be("198.51.100.7"); + } + + [Theory] + [InlineData(null)] + [InlineData("")] + [InlineData(" ")] + public async Task Enroll_BlankTemplateSignerValues_FallBackToConnectorValues(string blank) + { + StubHappyEnroll(); + var cfg = MinimalConfig(); + var req = BasicEnrollRequest(); + req.SignerName = blank; + req.SignerPlace = blank; + req.SignerIp = blank; + + await BuildClient(cfg).EnrollCertificateAsync(req); + + var agreement = CapturedOrderBody().GetProperty("agreementDetails"); + agreement.GetProperty("signerName").GetString().Should().Be("Default Requestor"); + agreement.GetProperty("signerPlace").GetString().Should().Be("Austin"); + agreement.GetProperty("signerIP").GetString().Should().Be("203.0.113.10"); + } + + [Fact] + public async Task Enroll_TemplateAndConnectorSignerBlank_UseBuiltInDefaults() + { + StubHappyEnroll(); + var cfg = MinimalConfig(); + cfg.RequestorName = ""; + cfg.SignerPlace = " "; + cfg.SignerIp = ""; + var req = BasicEnrollRequest(); + req.SignerName = " "; + + await BuildClient(cfg).EnrollCertificateAsync(req); + + var agreement = CapturedOrderBody().GetProperty("agreementDetails"); + agreement.GetProperty("signerName").GetString().Should().Be("Keyfactor Gateway"); + agreement.GetProperty("signerPlace").GetString().Should().Be("Gateway"); + agreement.GetProperty("signerIP").GetString().Should().Be("127.0.0.1"); + } + + [Fact] + public async Task Renewal_TemplateSignerValues_WinOverConnectorValues() + { + StubHappyEnroll(); + var cfg = MinimalConfig(); + var renewReq = new RenewCertificateRequest + { + Csr = MockCertificateData.FakeCsrPem, + ProfileId = "842", + Comment = "Renewal test", + SignerName = "Template Signer", + SignerPlace = "Template Place", + SignerIp = "198.51.100.7" + }; + + await BuildClient(cfg).RenewCertificateAsync(MockCertificateData.OrderNumber1, renewReq); + + var agreement = CapturedOrderBody().GetProperty("agreementDetails"); + agreement.GetProperty("signerName").GetString().Should().Be("Template Signer"); + agreement.GetProperty("signerPlace").GetString().Should().Be("Template Place"); + agreement.GetProperty("signerIP").GetString().Should().Be("198.51.100.7"); + } + + [Theory] + [InlineData(null)] + [InlineData("")] + [InlineData(" ")] + public async Task Renewal_BlankTemplateSignerValues_FallBackToConnectorThenDefaults(string blank) + { + StubHappyEnroll(); + var cfg = MinimalConfig(); + var renewReq = new RenewCertificateRequest + { + Csr = MockCertificateData.FakeCsrPem, + ProfileId = "842", + Comment = "Renewal test", + SignerName = blank, + SignerPlace = blank, + SignerIp = blank + }; + + await BuildClient(cfg).RenewCertificateAsync(MockCertificateData.OrderNumber1, renewReq); + + var agreement = CapturedOrderBody().GetProperty("agreementDetails"); + agreement.GetProperty("signerName").GetString().Should().Be("Default Requestor"); + agreement.GetProperty("signerPlace").GetString().Should().Be("Austin"); + agreement.GetProperty("signerIP").GetString().Should().Be("203.0.113.10"); + } + + [Fact] + public async Task Renewal_TemplateAndConnectorSignerBlank_UseBuiltInDefaults() + { + StubHappyEnroll(); + var cfg = MinimalConfig(); + cfg.RequestorName = ""; + cfg.SignerPlace = ""; + cfg.SignerIp = ""; + var renewReq = new RenewCertificateRequest + { + Csr = MockCertificateData.FakeCsrPem, + ProfileId = "842", + Comment = "Renewal test" + }; + + await BuildClient(cfg).RenewCertificateAsync(MockCertificateData.OrderNumber1, renewReq); + + var agreement = CapturedOrderBody().GetProperty("agreementDetails"); + agreement.GetProperty("signerName").GetString().Should().Be("Keyfactor Gateway"); + agreement.GetProperty("signerPlace").GetString().Should().Be("Gateway"); + agreement.GetProperty("signerIP").GetString().Should().Be("127.0.0.1"); + } + + // ----------------------------------------------------------------------- + // RenewCertificateAsync — productCode resolution + // Renewals go out as a fresh GenerateOrderSSL order; the product code must + // come from the template (RenewCertificateRequest.ProfileId) when supplied, + // falling back to the connector's DefaultProductCode only when it is not. + // ----------------------------------------------------------------------- + + [Fact] + public async Task RenewCertificateAsync_ProfileIdSet_UsesTemplateProductCode() + { + StubHappyEnroll(); + var cfg = MinimalConfig(); + cfg.DefaultProductCode = "connector-default-code"; + + var renewReq = new RenewCertificateRequest + { + Csr = MockCertificateData.FakeCsrPem, + ProfileId = "template-product-code", + ValidityDays = 365, + Comment = "Renewal test" + }; + + await BuildClient(cfg).RenewCertificateAsync(MockCertificateData.OrderNumber1, renewReq); + + CapturedOrderBody().GetProperty("productCode").GetString() + .Should().Be("template-product-code", + "the template's own product code must win over the connector default"); + } + + [Theory] + [InlineData(null)] + [InlineData("")] + [InlineData(" ")] + public async Task RenewCertificateAsync_ProfileIdBlank_FallsBackToConnectorDefault(string blankProfileId) + { + StubHappyEnroll(); + var cfg = MinimalConfig(); + cfg.DefaultProductCode = "connector-default-code"; + + var renewReq = new RenewCertificateRequest + { + Csr = MockCertificateData.FakeCsrPem, + ProfileId = blankProfileId, + ValidityDays = 365, + Comment = "Renewal test" + }; + + await BuildClient(cfg).RenewCertificateAsync(MockCertificateData.OrderNumber1, renewReq); + + CapturedOrderBody().GetProperty("productCode").GetString() + .Should().Be("connector-default-code", + "a blank ProfileId must fall back to the connector's DefaultProductCode, not an empty string"); + } + + // ----------------------------------------------------------------------- + // RenewCertificateAsync — full order-details shape. Renewal shares the + // new-enrollment builder, so it must send every field a new order sends and + // follow the connector's validity / autoRenew / emailNotifications / + // accountingModel settings (previously hard-coded validity="1" and DTO + // defaults autoRenew="1" / emailNotifications="1", and omitted groupNumber, + // autoSecureWWW, technical contact, organizationDetails and remarks). + // ----------------------------------------------------------------------- + + private static CERTInextConfig FullyConfiguredConfig() + { + var cfg = MinimalConfig(); + cfg.GroupNumber = "1000000001"; + cfg.OrganizationNumber = "2000000002"; + cfg.AccountingModel = "1"; + cfg.EmailNotifications = "0"; + cfg.SubscriptionValidityYears = "3"; + cfg.SubscriptionAutoRenew = "0"; + cfg.SubscriptionRenewCriteriaDays = "60"; + cfg.AutoSecureWww = "0"; + cfg.TechnicalContactName = "Pat Example"; + cfg.TechnicalContactEmail = "poc@example.com"; + cfg.TechnicalContactIsdCode = "44"; + cfg.TechnicalContactMobileNumber = "5553334444"; + return cfg; + } + + [Fact] + public async Task RenewCertificateAsync_SendsFullOrderDetails_FromConnectorConfig() + { + StubHappyEnroll(); + var cfg = FullyConfiguredConfig(); + + var renewReq = new RenewCertificateRequest + { + Csr = MockCertificateData.FakeCsrPem, + Subject = "CN=renew.example.com,O=Example", + ProfileId = "842", + Sans = new System.Collections.Generic.List + { + new SanEntry { Type = "dns", Value = "renew.example.com" }, + new SanEntry { Type = "dns", Value = "alt.example.com" } + }, + ValidityYears = 2, + RequesterName = "Renew Requester", + RequesterEmail = "renew@example.com", + Comment = "Renewed via Keyfactor Command. Prior ID: ORD-AAA-111." + }; + + await BuildClient(cfg).RenewCertificateAsync(MockCertificateData.OrderNumber1, renewReq); + + var od = CapturedOrderBody(); + od.GetProperty("productCode").GetString().Should().Be("842"); + od.GetProperty("accountingModel").GetString().Should().Be("1"); + od.GetProperty("saveAndHold").GetString().Should().Be("0"); + od.GetProperty("emailNotifications").GetString().Should().Be("0"); + od.GetProperty("groupNumber").GetString().Should().Be("1000000001"); + od.GetProperty("autoSecureWWW").GetString().Should().Be("0"); + + var org = od.GetProperty("organizationDetails"); + org.GetProperty("preVetting").GetString().Should().Be("1"); + org.GetProperty("organizationNumber").GetString().Should().Be("2000000002"); + + var requestor = od.GetProperty("requestorInformation"); + requestor.GetProperty("requestorName").GetString().Should().Be("Renew Requester"); + requestor.GetProperty("requestorEmail").GetString().Should().Be("renew@example.com"); + requestor.GetProperty("requestorIsdCode").GetString().Should().Be(cfg.RequestorIsdCode); + requestor.GetProperty("requestorMobileNumber").GetString().Should().Be(cfg.RequestorMobileNumber); + + var sub = od.GetProperty("subscriptionDetails"); + sub.GetProperty("validity").GetString().Should().Be("2", "the plugin-supplied ValidityYears must win"); + sub.GetProperty("autoRenew").GetString().Should().Be("0"); + sub.GetProperty("renewCriteria").GetString().Should().Be("60"); + + var ci = od.GetProperty("certificateInformation"); + ci.GetProperty("domainName").GetString().Should().Be("renew.example.com"); + ci.GetProperty("additionalDomains").EnumerateArray().Select(e => e.GetString()) + .Should().Equal("alt.example.com"); + + var poc = od.GetProperty("technicalPointOfContact"); + poc.GetProperty("pocFirstName").GetString().Should().Be("Pat"); + poc.GetProperty("pocLastName").GetString().Should().Be("Example"); + poc.GetProperty("pocEmail").GetString().Should().Be("poc@example.com"); + poc.GetProperty("pocIsdCode").GetString().Should().Be("44"); + poc.GetProperty("pocMobileNumber").GetString().Should().Be("5553334444"); + + od.GetProperty("csr").GetString().Should().Be(MockCertificateData.FakeCsrPem); + od.GetProperty("agreementDetails").GetProperty("acceptAgreement").GetString().Should().Be("1"); + od.GetProperty("additionalInformation").GetProperty("remarks").GetString() + .Should().Be("Renewed via Keyfactor Command. Prior ID: ORD-AAA-111."); + + AssertNoLegacyFieldShapes(od); + } + + [Fact] + public async Task RenewCertificateAsync_NoValidityOnRequest_UsesConnectorValidity() + { + StubHappyEnroll(); + var cfg = MinimalConfig(); + cfg.SubscriptionValidityYears = "3"; + + var renewReq = new RenewCertificateRequest + { + Csr = MockCertificateData.FakeCsrPem, + Subject = "CN=renew.example.com", + ProfileId = "842" + }; + + await BuildClient(cfg).RenewCertificateAsync(MockCertificateData.OrderNumber1, renewReq); + + CapturedOrderBody().GetProperty("subscriptionDetails").GetProperty("validity").GetString() + .Should().Be("3", "renewal must no longer hard-code validity=1"); + } + + [Fact] + public async Task RenewCertificateAsync_ValidityDays_ConvertsToYears() + { + StubHappyEnroll(); + var cfg = MinimalConfig(); + cfg.SubscriptionValidityYears = "1"; + + var renewReq = new RenewCertificateRequest + { + Csr = MockCertificateData.FakeCsrPem, + Subject = "CN=renew.example.com", + ProfileId = "842", + ValidityDays = 730 + }; + + await BuildClient(cfg).RenewCertificateAsync(MockCertificateData.OrderNumber1, renewReq); + + CapturedOrderBody().GetProperty("subscriptionDetails").GetProperty("validity").GetString() + .Should().Be("2"); + } + + [Fact] + public async Task RenewCertificateAsync_ConfigUntouched_UsesConnectorDefaultsNotDtoDefaults() + { + StubHappyEnroll(); + var cfg = MinimalConfig(); + + var renewReq = new RenewCertificateRequest + { + Csr = MockCertificateData.FakeCsrPem, + Subject = "CN=renew.example.com", + ProfileId = "842" + }; + + await BuildClient(cfg).RenewCertificateAsync(MockCertificateData.OrderNumber1, renewReq); + + var od = CapturedOrderBody(); + od.GetProperty("accountingModel").GetString().Should().Be("2"); + od.GetProperty("emailNotifications").GetString().Should().Be("0", + "the connector default (0) must apply, not the DTO default (1)"); + od.GetProperty("subscriptionDetails").GetProperty("autoRenew").GetString().Should().Be("0", + "the connector default (0) must apply, not the DTO default (1)"); + od.GetProperty("subscriptionDetails").GetProperty("renewCriteria").GetString().Should().Be("30"); + od.GetProperty("autoSecureWWW").GetString().Should().Be("0"); + od.TryGetProperty("groupNumber", out _).Should().BeFalse(); + od.TryGetProperty("organizationDetails", out _).Should().BeFalse(); + od.GetProperty("technicalPointOfContact").GetProperty("pocEmail").GetString() + .Should().Be(cfg.RequestorEmail); + od.GetProperty("additionalInformation").GetProperty("remarks").GetString() + .Should().NotBeNullOrWhiteSpace(); + AssertNoLegacyFieldShapes(od); + } + + // ----------------------------------------------------------------------- + // SplitContactName — TechnicalContactName → pocFirstName / pocLastName + // ----------------------------------------------------------------------- + + [Theory] + [InlineData("Jane Smith", "Jane", "Smith")] + [InlineData("Jane Q Smith", "Jane", "Q Smith")] + [InlineData(" Jane Smith ", "Jane", "Smith")] + [InlineData("Jane\tSmith", "Jane", "Smith")] + [InlineData("Jane Q Smith", "Jane", "Q Smith")] + [InlineData("Operations", "Operations", "Operations")] + [InlineData(" Operations ", "Operations", "Operations")] + [InlineData("", "", "")] + [InlineData(" ", "", "")] + [InlineData(null, "", "")] + public void SplitContactName_SplitsOnFirstWhitespaceRun(string input, string expectedFirst, string expectedLast) + { + var (first, last) = CERTInextClient.SplitContactName(input); + + first.Should().Be(expectedFirst); + last.Should().Be(expectedLast); + } } } diff --git a/CERTInext.Tests/CERTInextClientTests.cs b/CERTInext.Tests/CERTInextClientTests.cs index e473e89..2dc8324 100644 --- a/CERTInext.Tests/CERTInextClientTests.cs +++ b/CERTInext.Tests/CERTInextClientTests.cs @@ -581,6 +581,30 @@ public async Task ListCertificatesAsync_RespectsIssuedAfterFilter() _server.LogEntries.Should().Contain(e => e.RequestMessage.Path == "/GetOrderReport"); } + // Issue 0090: the sync hold-back relies on the listing's orderDate being whole-second UTC. + // Live GetOrderReport rows carry "yyyy-MM-dd HH:mm:ss" with no zone marker (verified + // 2026-10-15 against plugin/gateway UTC timestamps); it must parse as that UTC instant. + [Fact] + public async Task ListCertificatesAsync_ParsesLiveOrderDateFormat_AsUtcWholeSeconds() + { + _server + .Given(Request.Create().WithPath("/GetOrderReport").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.OrderReportSinglePageJson() + .Replace("\"orderDate\":\"2024-06-01\"", "\"orderDate\":\"2026-10-15 18:59:52\""))); + + var client = BuildClient(); + var results = new List(); + await foreach (var cert in client.ListCertificatesAsync(issuedAfter: null, pageSize: 100)) + results.Add(cert); + + results.Should().HaveCount(1); + results[0].OrderDate.Should().Be(new DateTime(2026, 10, 15, 18, 59, 52, DateTimeKind.Utc)); + (results[0].OrderDate?.Kind).Should().Be(DateTimeKind.Utc); + } + // --------------------------------------------------------------------------- // GetProfilesAsync (legacy) — calls POST /GetProductDetails // --------------------------------------------------------------------------- @@ -790,6 +814,42 @@ await act.Should().ThrowAsync() .WithMessage("*GetDcv failed*"); } + /// + /// This client is built with ThrowOnAnyError=false, so RestSharp catches a + /// cancelled HttpClient.SendAsync internally and returns a non-throwing, unsuccessful + /// RestResponse instead of propagating OperationCanceledException. ExecuteWithRetryAsync + /// must surface that as OperationCanceledException rather than passing the response to + /// DeserializeOrThrow, which would wrap it in a plain Exception — indistinguishable from + /// a genuine API failure. A caller such as PerformDcvIfNeededAsync's per-domain + /// "catch (OperationCanceledException) { throw; }" guard (which stops a DCV timeout from + /// being mislabeled as an ordinary per-domain failure) depends on seeing the real + /// cancellation — a gap a Moq-level test of the plugin alone cannot expose, since a mock + /// can be told to throw whatever type is asked for. This test exercises the real client + /// against a real (if local) HTTP call, which is the only way to pin the actual failure + /// mode. + /// + [Fact] + public async Task GetDcvAsync_ThrowsOperationCanceled_WhenCancellationTokenIsCancelled() + { + _server + .Given(Request.Create().WithPath("/GetDcv").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.GetDcvSuccessJson())); + + var client = BuildClient(); + using var cts = new CancellationTokenSource(); + cts.Cancel(); + + Func act = () => client.GetDcvAsync( + MockCertificateData.OrderNumber1, "example.com", Constants.Dcv.MethodDnsTxt, cts.Token); + + await act.Should().ThrowAsync( + "a cancelled token must surface as a genuine cancellation, not get wrapped into a " + + "plain Exception that a caller's cancellation-specific catch clause cannot recognize"); + } + [Fact] public async Task GetDcvAsync_Throws_WhenServerReturns401() { diff --git a/CERTInext.Tests/CERTInextClientV2Tests.cs b/CERTInext.Tests/CERTInextClientV2Tests.cs new file mode 100644 index 0000000..01d9e3c --- /dev/null +++ b/CERTInext.Tests/CERTInextClientV2Tests.cs @@ -0,0 +1,1671 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Generic; +using System.Linq; +using System.Reflection; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using WireMock.RequestBuilders; +using WireMock.ResponseBuilders; +using WireMock.Server; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// WireMock-based tests for V2 REST API methods on . + /// A real WireMockServer handles the V2 token endpoint and all V2 REST paths so + /// serialisation, routing, and token caching are fully exercised. + /// + public class CERTInextClientV2Tests : IDisposable + { + private readonly WireMockServer _server; + private readonly string _baseUrl; + + public CERTInextClientV2Tests() + { + _server = WireMockServer.Start(); + _baseUrl = _server.Urls[0]; + } + + public void Dispose() => _server.Stop(); + + // --------------------------------------------------------------------------- + // Helpers + // --------------------------------------------------------------------------- + + private CERTInextClient BuildV2Client(string groupNumber = null) => + new CERTInextClient(new CERTInextConfig + { + // A single ApiUrl serves both V1 and V2. + ApiUrl = _baseUrl, + AuthMode = "AccessKey", + ApiKey = "test-v1-key", + AccountNumber = "12345", + UseV2Api = true, + OAuthClientId = "my-v2-client", + OAuthClientSecret = "my-v2-secret", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + PageSize = 100, + // Unset by default (matches CERTInextConfig.GroupNumber's own default of + // string.Empty) — individual test cases override this explicitly. + GroupNumber = groupNumber ?? string.Empty + }); + + private void StubV2Token(int expiresIn = 3600) + { + _server + .Given(Request.Create() + .WithPath("/oauth/token") + .UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2TokenResponseJson(expiresIn))); + } + + // --------------------------------------------------------------------------- + // Token fetch + // --------------------------------------------------------------------------- + + [Fact] + public async Task PingV2Async_FetchesTokenAndCallsAuthMe() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath("/api/certinext/v2/auth/me") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2AuthMeJson())); + + using var client = BuildV2Client(); + await client.PingV2Async(); + + // Verify both token and auth/me endpoints were called + _server.LogEntries.Should().Contain(e => e.RequestMessage.Path == "/oauth/token"); + _server.LogEntries.Should().Contain(e => e.RequestMessage.Path == "/api/certinext/v2/auth/me"); + } + + [Fact] + public async Task GetAuthMeV2Async_ReturnsAccountNumber() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath("/api/certinext/v2/auth/me") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2AuthMeJson("99887766"))); + + using var client = BuildV2Client(); + var result = await client.GetAuthMeV2Async(); + + result.AccountNumber.Should().Be("99887766"); + result.AuthType.Should().Be("oauth2"); + } + + [Fact] + public async Task PingV2Async_TokenCached_OnlyOneFetch() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath("/api/certinext/v2/auth/me") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2AuthMeJson())); + + using var client = BuildV2Client(); + await client.PingV2Async(); + await client.PingV2Async(); // second call — should reuse cached token + + var tokenCalls = 0; + foreach (var entry in _server.LogEntries) + if (entry.RequestMessage.Path == "/oauth/token") tokenCalls++; + + tokenCalls.Should().Be(1, "token should be cached after the first fetch"); + } + + // --------------------------------------------------------------------------- + // PlaceOrderV2Async + // --------------------------------------------------------------------------- + + [Fact] + public async Task PlaceOrderV2Async_ReturnsPendingOrder() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath("/api/certinext/v2/ssl-certificates") + .UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(201) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2CreateOrderPendingJson(MockCertificateData.V2OrderId1))); + + using var client = BuildV2Client(); + var result = await client.PlaceOrderV2Async( + Constants.ApiV2.FamilySsl, + "842", + new V2CreateSslOrderRequest + { + ProductVariant = "dv", + Requestor = new V2Requestor { Name = "Test", Email = "t@t.com", Phone = "555", Designation = "IT" }, + Certificate = new V2CertificateParams { Domain = "example.com" }, + Subscription = new V2SubscriptionParams { ValidityYears = 1 }, + Agreement = new V2AgreementParams { SignerName = "Test", SignerPlace = "NY", Accepted = true } + }); + + result.OrderId.Should().Be(MockCertificateData.V2OrderId1); + result.Status.Should().Be("pending-dcv"); + } + + [Fact] + public async Task PlaceOrderV2Async_SetsProductCodeHeader() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath("/api/certinext/v2/ssl-certificates") + .UsingPost() + .WithHeader("X-Product-Code", "842")) + .RespondWith(Response.Create() + .WithStatusCode(201) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2CreateOrderPendingJson())); + + using var client = BuildV2Client(); + var result = await client.PlaceOrderV2Async( + Constants.ApiV2.FamilySsl, "842", + new V2CreateSslOrderRequest + { + Requestor = new V2Requestor { Name = "T", Email = "t@t.com", Phone = "1", Designation = "IT" }, + Certificate = new V2CertificateParams { Domain = "example.com" }, + Subscription = new V2SubscriptionParams(), + Agreement = new V2AgreementParams { SignerName = "T", SignerPlace = "NY", Accepted = true } + }); + + result.Should().NotBeNull(); + } + + // --------------------------------------------------------------------------- + // The create call must always be pinned to a product. The CSR now travels inline, and an + // unpinned SSL create auto-resolves to a PFX product (live: 917) that never issues, so a + // null/blank product code on SSL / Private PKI is rejected before any HTTP call. + // --------------------------------------------------------------------------- + + // X-Product-Code is the spec's optional override: a blank code is a normal, supported + // call that omits the header and lets CERTInext's wrapper resolve the product. + [Theory] + [InlineData(null)] + [InlineData("")] + [InlineData(" ")] + public async Task PlaceOrderV2Async_Ssl_NullOrBlankProductCode_OmitsHeader_AndStillPlacesOrder(string productCode) + { + StubV2Token(); + _server + .Given(Request.Create().WithPath("/api/certinext/v2/ssl-certificates").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(201) + .WithHeader("Content-Type", "application/json") + .WithBody("{\"orderId\":\"ord_nohdr_001\",\"requestId\":\"req_9\",\"status\":\"pending-dcv\"," + + "\"resolvedProductCode\":\"842\"}")); + + using var client = BuildV2Client(); + var response = await client.PlaceOrderV2Async( + Constants.ApiV2.FamilySsl, productCode, + new V2CreateSslOrderRequest + { + Requestor = new V2Requestor { Name = "T", Email = "t@t.com", Phone = "1", Designation = "IT" }, + Certificate = new V2CertificateParams { Domain = "example.com" }, + Subscription = new V2SubscriptionParams(), + Agreement = new V2AgreementParams { SignerName = "T", SignerPlace = "NY", Accepted = true }, + Csr = MockCertificateData.FakeCsrPem + }); + + var entry = _server.LogEntries.Single(e => e.RequestMessage.Path == "/api/certinext/v2/ssl-certificates"); + entry.RequestMessage.Headers.Should().NotContainKey("X-Product-Code", + "an unset ProductCode must not be sent, not even as an empty header"); + response.OrderId.Should().Be("ord_nohdr_001"); + response.ResolvedProductCode.Should().Be("842", + "the create response's resolvedProductCode is captured so the plugin can log it"); + } + + [Fact] + public async Task PlaceOrderV2Async_Ssl_NonBlankProductCode_StillSendsHeader() + { + StubV2Token(); + _server + .Given(Request.Create().WithPath("/api/certinext/v2/ssl-certificates").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(201) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2CreateOrderPendingJson())); + + using var client = BuildV2Client(); + await client.PlaceOrderV2Async( + Constants.ApiV2.FamilySsl, "842", + new V2CreateSslOrderRequest + { + Requestor = new V2Requestor { Name = "T", Email = "t@t.com", Phone = "1", Designation = "IT" }, + Certificate = new V2CertificateParams { Domain = "example.com" }, + Subscription = new V2SubscriptionParams(), + Agreement = new V2AgreementParams { SignerName = "T", SignerPlace = "NY", Accepted = true } + }); + + var entry = _server.LogEntries.Last(e => e.RequestMessage.Path == "/api/certinext/v2/ssl-certificates"); + entry.RequestMessage.Headers.Should().ContainKey("X-Product-Code") + .WhoseValue.Should().Contain("842"); + } + + [Theory] + [InlineData(null)] + [InlineData("")] + public async Task PlaceOrderV2Async_PrivatePki_NullOrBlankProductCode_OmitsHeader_AndStillPlacesOrder(string productCode) + { + StubV2Token(); + _server + .Given(Request.Create().WithPath("/api/certinext/v2/private-pki-certificates").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(201) + .WithHeader("Content-Type", "application/json") + .WithBody("{\"orderId\":\"ord_pki_002\",\"requestId\":\"req_3\",\"status\":\"pending-approval\"," + + "\"variant\":\"intranet-ssl\",\"hostname\":\"intranet.example.com\"}")); + + using var client = BuildV2Client(); + var response = await client.PlaceOrderV2Async(productCode, new V2CreatePrivatePkiOrderRequest + { + Variant = "intranet-ssl", + Hostname = "intranet.example.com", + Requestor = new V2Requestor { Name = "DevOps", Email = "devops@example.com" }, + Subscription = new V2SubscriptionParams { ValidityYears = 1 } + }); + + response.OrderId.Should().Be("ord_pki_002"); + var entry = _server.LogEntries.Single(e => e.RequestMessage.Path == "/api/certinext/v2/private-pki-certificates"); + entry.RequestMessage.Headers.Should().NotContainKey("X-Product-Code"); + } + + [Fact] + public async Task PlaceOrderV2Async_Signature_NullProductCode_OmitsProductCodeHeader() + { + StubV2Token(); + _server + .Given(Request.Create().WithPath("/api/certinext/v2/signature-certificates").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(201) + .WithHeader("Content-Type", "application/json") + .WithBody("{\"orderId\":\"ord_sig_002\",\"requestId\":\"req_4\",\"status\":\"pending-documents\"," + + "\"subjectType\":\"natural-person\",\"subjectDisplayName\":\"Test Person\"}")); + + using var client = BuildV2Client(); + await client.PlaceOrderV2Async(null, new V2CreateSignatureOrderRequest + { + SubjectType = "natural-person", + Requestor = new V2Requestor { Name = "Test Person", Email = "test.person@example.com" }, + Subject = new V2SignatureSubject { FirstName = "Test", LastName = "Person", Email = "test.person@example.com" } + }); + + var entry = _server.LogEntries.Last(e => e.RequestMessage.Path == "/api/certinext/v2/signature-certificates"); + entry.RequestMessage.Headers.Should().NotContainKey("X-Product-Code"); + } + + // --------------------------------------------------------------------------- + // V2CertificateParams.AdditionalDomains wire serialization + // --------------------------------------------------------------------------- + + [Fact] + public async Task PlaceOrderV2Async_UccOrder_IncludesAdditionalDomainsInWireBody() + { + StubV2Token(); + _server + .Given(Request.Create().WithPath("/api/certinext/v2/ssl-certificates").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(201) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2CreateOrderPendingJson())); + + using var client = BuildV2Client(); + await client.PlaceOrderV2Async( + Constants.ApiV2.FamilySsl, "844", + new V2CreateSslOrderRequest + { + ProductVariant = "dv", + Requestor = new V2Requestor { Name = "T", Email = "t@t.com", Phone = "1", Designation = "IT" }, + Certificate = new V2CertificateParams + { + Domain = "example.com", + AdditionalDomains = new List { "san1.example.com", "san2.example.com" } + }, + Subscription = new V2SubscriptionParams(), + Agreement = new V2AgreementParams { SignerName = "T", SignerPlace = "NY", Accepted = true } + }); + + string requestBody = _server.LogEntries.Last(e => e.RequestMessage.Path == "/api/certinext/v2/ssl-certificates") + .RequestMessage.Body; + requestBody.Should().Contain("\"additionalDomains\""); + requestBody.Should().Contain("san1.example.com"); + requestBody.Should().Contain("san2.example.com"); + } + + [Fact] + public async Task PlaceOrderV2Async_SingleDomainOrder_OmitsAdditionalDomainsFromWireBody() + { + StubV2Token(); + _server + .Given(Request.Create().WithPath("/api/certinext/v2/ssl-certificates").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(201) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2CreateOrderPendingJson())); + + using var client = BuildV2Client(); + await client.PlaceOrderV2Async( + Constants.ApiV2.FamilySsl, "842", + new V2CreateSslOrderRequest + { + ProductVariant = "dv", + Requestor = new V2Requestor { Name = "T", Email = "t@t.com", Phone = "1", Designation = "IT" }, + Certificate = new V2CertificateParams { Domain = "example.com" }, // AdditionalDomains left null + Subscription = new V2SubscriptionParams(), + Agreement = new V2AgreementParams { SignerName = "T", SignerPlace = "NY", Accepted = true } + }); + + string requestBody = _server.LogEntries.Last(e => e.RequestMessage.Path == "/api/certinext/v2/ssl-certificates") + .RequestMessage.Body; + requestBody.Should().NotContain("additionalDomains", + "single-domain orders must not send additionalDomains at all"); + } + + // --------------------------------------------------------------------------- + // Family-specific PlaceOrderV2Async overloads + // --------------------------------------------------------------------------- + + [Fact] + public async Task PlaceOrderV2Async_PrivatePki_PostsPrivatePkiBodyToPrivatePkiPath_WithProductCodeHeader() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath("/api/certinext/v2/private-pki-certificates") + .UsingPost() + .WithHeader("X-Product-Code", "149")) + .RespondWith(Response.Create() + .WithStatusCode(201) + .WithHeader("Content-Type", "application/json") + .WithBody("{\"orderId\":\"ord_pki_001\",\"requestId\":\"req_1\",\"status\":\"pending-csr\"," + + "\"variant\":\"intranet-ssl\",\"hostname\":\"intranet.acme.local\",\"resolvedProductCode\":\"149\"}")); + + using var client = BuildV2Client(); + var result = await client.PlaceOrderV2Async("149", new V2CreatePrivatePkiOrderRequest + { + Variant = "intranet-ssl", + Hostname = "intranet.acme.local", + AdditionalHosts = new List { "portal.acme.local", "10.0.0.50" }, + Requestor = new V2Requestor { Name = "DevOps Team", Email = "devops@acme.com" }, + Subscription = new V2SubscriptionParams { ValidityYears = 1 } + }); + + result.OrderId.Should().Be("ord_pki_001"); + result.Status.Should().Be("pending-csr"); + + var entry = _server.LogEntries.Last(e => e.RequestMessage.Path == "/api/certinext/v2/private-pki-certificates"); + entry.RequestMessage.Headers.Should().ContainKey("Idempotency-Key"); + entry.RequestMessage.Body.Should().NotBeNullOrEmpty(); + using var body = System.Text.Json.JsonDocument.Parse(entry.RequestMessage.Body ?? string.Empty); + body.RootElement.GetProperty("variant").GetString().Should().Be("intranet-ssl"); + body.RootElement.GetProperty("hostname").GetString().Should().Be("intranet.acme.local"); + body.RootElement.GetProperty("additionalHosts").EnumerateArray().Select(e => e.GetString()) + .Should().Equal("portal.acme.local", "10.0.0.50"); + body.RootElement.TryGetProperty("productVariant", out _).Should().BeFalse(); + body.RootElement.TryGetProperty("certificate", out _).Should().BeFalse(); + body.RootElement.TryGetProperty("agreement", out _).Should().BeFalse(); + _server.LogEntries.Should().NotContain(e => e.RequestMessage.Path == "/api/certinext/v2/ssl-certificates"); + } + + [Fact] + public async Task PlaceOrderV2Async_Signature_PostsSignatureBodyToSignaturePath_WithProductCodeHeader() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath("/api/certinext/v2/signature-certificates") + .UsingPost() + .WithHeader("X-Product-Code", "819")) + .RespondWith(Response.Create() + .WithStatusCode(201) + .WithHeader("Content-Type", "application/json") + .WithBody("{\"orderId\":\"ord_sig_001\",\"requestId\":\"req_2\",\"status\":\"pending-documents\"," + + "\"subjectType\":\"natural-person\",\"subjectDisplayName\":\"Sarah Johnson\",\"resolvedProductCode\":\"819\"}")); + + using var client = BuildV2Client(); + var result = await client.PlaceOrderV2Async("819", new V2CreateSignatureOrderRequest + { + SubjectType = "natural-person", + Requestor = new V2Requestor { Name = "Sarah Johnson", Email = "sarah.johnson@example.com" }, + Subject = new V2SignatureSubject { FirstName = "Sarah", LastName = "Johnson", Email = "sarah.johnson@example.com" } + }); + + result.OrderId.Should().Be("ord_sig_001"); + + var entry = _server.LogEntries.Last(e => e.RequestMessage.Path == "/api/certinext/v2/signature-certificates"); + entry.RequestMessage.Body.Should().NotBeNullOrEmpty(); + using var body = System.Text.Json.JsonDocument.Parse(entry.RequestMessage.Body ?? string.Empty); + body.RootElement.GetProperty("subjectType").GetString().Should().Be("natural-person"); + body.RootElement.GetProperty("subject").GetProperty("email").GetString().Should().Be("sarah.johnson@example.com"); + } + + [Theory] + [InlineData(Constants.ApiV2.FamilyPrivatePki)] + [InlineData(Constants.ApiV2.FamilySignature)] + public async Task PlaceOrderV2Async_SslBody_ToNonSslFamily_Throws_AndSendsNothing(string family) + { + // The SSL overload must not substitute any slug into the URL unchecked, + // which would let a private-pki/signature template send the SSL body to the wrong family. + StubV2Token(); + + using var client = BuildV2Client(); + Func act = () => client.PlaceOrderV2Async( + family, "149", + new V2CreateSslOrderRequest + { + Requestor = new V2Requestor { Name = "T", Email = "t@t.com" }, + Certificate = new V2CertificateParams { Domain = "example.com" } + }); + + await act.Should().ThrowAsync().WithMessage($"*{family}*"); + _server.LogEntries.Should().NotContain(e => e.RequestMessage.Path.StartsWith("/api/certinext/v2/"), + "no order request may be sent when the SSL body is aimed at another family"); + } + + // --------------------------------------------------------------------------- + // TrackOrderV2Async + // --------------------------------------------------------------------------- + + [Fact] + public async Task TrackOrderV2Async_Issued_ReturnsIssuedStatus() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/ssl-certificates/{MockCertificateData.V2OrderId1}") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2TrackOrderIssuedJson(MockCertificateData.V2OrderId1))); + + using var client = BuildV2Client(); + var result = await client.TrackOrderV2Async(Constants.ApiV2.FamilySsl, MockCertificateData.V2OrderId1); + + result.Status.Should().Be("issued"); + result.OrderId.Should().Be(MockCertificateData.V2OrderId1); + } + + [Fact] + public async Task TrackOrderV2Async_NotFound_ThrowsKeyNotFoundException() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/ssl-certificates/nonexistent") + .UsingGet()) + .RespondWith(Response.Create().WithStatusCode(404)); + + using var client = BuildV2Client(); + await Assert.ThrowsAsync( + () => client.TrackOrderV2Async(Constants.ApiV2.FamilySsl, "nonexistent")); + } + + // --------------------------------------------------------------------------- + // TrackOrderV2Async — nested `revocation` object + // --------------------------------------------------------------------------- + + [Fact] + public async Task TrackOrderV2Async_Revoked_DeserializesNestedRevocationObject() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/ssl-certificates/{MockCertificateData.V2OrderId1}") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2TrackOrderRevokedJson( + MockCertificateData.V2OrderId1, + reason: "cessation-of-operation", + processedAt: "2026-09-24T20:44:41Z"))); + + using var client = BuildV2Client(); + var result = await client.TrackOrderV2Async(Constants.ApiV2.FamilySsl, MockCertificateData.V2OrderId1); + + result.Status.Should().Be("revoked"); + // `revocation` is a nested object — not flat top-level + // revocationReason/revocationDate properties. + result.Revocation.Should().NotBeNull(); + result.Revocation!.Status.Should().Be("Certificate Revoked"); + result.Revocation.Reason.Should().Be("cessation-of-operation"); + result.Revocation.ProcessedAt.Should().Be( + new DateTime(2026, 9, 24, 20, 44, 41, DateTimeKind.Utc)); + } + + [Fact] + public async Task TrackOrderV2Async_NotRevoked_RevocationIsNull() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/ssl-certificates/{MockCertificateData.V2OrderId1}") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2TrackOrderIssuedJson(MockCertificateData.V2OrderId1))); + + using var client = BuildV2Client(); + var result = await client.TrackOrderV2Async(Constants.ApiV2.FamilySsl, MockCertificateData.V2OrderId1); + + // The `revocation` key is absent entirely (not present-but-null) on + // an order that has never been revoked. + result.Revocation.Should().BeNull(); + } + + // --------------------------------------------------------------------------- + // DownloadCertificateV2Async + // --------------------------------------------------------------------------- + + [Fact] + public async Task DownloadCertificateV2Async_ReturnsPem() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/ssl-certificates/{MockCertificateData.V2OrderId1}/certificate") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2CertificateDownloadJson(MockCertificateData.V2OrderId1))); + + using var client = BuildV2Client(); + var result = await client.DownloadCertificateV2Async(Constants.ApiV2.FamilySsl, MockCertificateData.V2OrderId1); + + result.CertificatePem.Should().StartWith("-----BEGIN CERTIFICATE-----"); + result.SerialNumber.Should().Be("0A1B2C3D4E5F"); + result.OrderId.Should().Be(MockCertificateData.V2OrderId1); + } + + [Fact] + public async Task DownloadCertificateV2Async_422Ems1165_ThrowsNotGeneratedException_WithTheUsualMessage() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/ssl-certificates/{MockCertificateData.V2OrderId1}/certificate") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(422) + .WithHeader("Content-Type", "application/problem+json") + .WithBody("{\"type\":\"https://api.certinext.io/errors/unprocessable-entity\"," + + "\"title\":\"Unprocessable Entity\",\"status\":422,\"detail\":\"EMS-1165 Invalid request status.\"}")); + + using var client = BuildV2Client(); + Func act = () => client.DownloadCertificateV2Async(Constants.ApiV2.FamilySsl, MockCertificateData.V2OrderId1); + + var ex = (await act.Should().ThrowAsync()).Which; + ex.Message.Should().Contain("HTTP 422").And.Contain("EMS-1165").And.Contain("V2 download certificate"); + CERTInextCAPlugin.IsCertificateNotGeneratedYet(ex).Should().BeTrue(); + } + + [Fact] + public async Task DownloadCertificateV2Async_Other422_StaysAGenericFailure() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/ssl-certificates/{MockCertificateData.V2OrderId1}/certificate") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(422) + .WithHeader("Content-Type", "application/problem+json") + .WithBody("{\"title\":\"Unprocessable Entity\",\"status\":422,\"detail\":\"EMS-1164 Domain Name is not matching.\"}")); + + using var client = BuildV2Client(); + Func act = () => client.DownloadCertificateV2Async(Constants.ApiV2.FamilySsl, MockCertificateData.V2OrderId1); + + var ex = (await act.Should().ThrowAsync()).Which; + ex.Should().NotBeOfType(); + CERTInextCAPlugin.IsCertificateNotGeneratedYet(ex).Should().BeFalse(); + } + + [Fact] + public async Task TrackOrderV2Async_CapturesOrderStateAndCertificateState() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/ssl-certificates/{MockCertificateData.V2OrderId1}") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody("{\"orderId\":\"" + MockCertificateData.V2OrderId1 + "\",\"status\":\"issued\"," + + "\"orderState\":\"Order Accepted\",\"certificateState\":\"Approved by System\"}")); + + using var client = BuildV2Client(); + var status = await client.TrackOrderV2Async(Constants.ApiV2.FamilySsl, MockCertificateData.V2OrderId1); + + status.Status.Should().Be("issued"); + status.OrderState.Should().Be("Order Accepted"); + status.CertificateState.Should().Be("Approved by System"); + } + + // --------------------------------------------------------------------------- + // RevokeOrderV2Async + // --------------------------------------------------------------------------- + + [Fact] + public async Task RevokeOrderV2Async_SuccessfulRevoke() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/ssl-certificates/{MockCertificateData.V2OrderId1}/revoke") + .UsingPost()) + .RespondWith(Response.Create().WithStatusCode(204)); + + using var client = BuildV2Client(); + // Should not throw + await client.RevokeOrderV2Async( + Constants.ApiV2.FamilySsl, + MockCertificateData.V2OrderId1, + new V2RevokeRequest { Reason = "superseded", Note = "Replaced." }); + } + + [Fact] + public async Task RevokeOrderV2Async_422_ThrowsInvalidOperationException() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/ssl-certificates/{MockCertificateData.V2OrderId1}/revoke") + .UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(422) + .WithHeader("Content-Type", "application/problem+json") + .WithBody(MockCertificateData.V2ProblemDetailsJson(422, "Unprocessable Entity", "Order not in issued state", "EMS-931"))); + + using var client = BuildV2Client(); + await Assert.ThrowsAsync( + () => client.RevokeOrderV2Async( + Constants.ApiV2.FamilySsl, + MockCertificateData.V2OrderId1, + new V2RevokeRequest { Reason = "superseded" })); + } + + // --------------------------------------------------------------------------- + // The 422 message must reflect the CA's actual detail + // rather than presuming "order not in issued state" for every 422. + // --------------------------------------------------------------------------- + + [Fact] + public async Task RevokeOrderV2Async_422_LabelsByActualDetail_NotHardcodedIssuedStateMessage() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/ssl-certificates/{MockCertificateData.V2OrderId1}/revoke") + .UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(422) + .WithHeader("Content-Type", "application/problem+json") + // Sandbox behavior for a revoke attempted while the + // order is still internally finalizing — no EMS code in this detail. + .WithBody(MockCertificateData.V2ProblemDetailsJson( + 422, "Unprocessable Entity", "Certificate Request still being processed"))); + + using var client = BuildV2Client(); + var ex = await Assert.ThrowsAsync( + () => client.RevokeOrderV2Async( + Constants.ApiV2.FamilySsl, + MockCertificateData.V2OrderId1, + new V2RevokeRequest { Reason = "superseded" })); + + ex.Message.Should().Contain("still being processed"); + ex.Message.Should().NotContain("not in issued state", + "the message must reflect the CA's actual detail text, not a hardcoded assumption"); + } + + [Fact] + public async Task RevokeOrderV2Async_422_DistinctEmsCode_LabelsByThatCode() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/ssl-certificates/{MockCertificateData.V2OrderId1}/revoke") + .UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(422) + .WithHeader("Content-Type", "application/problem+json") + .WithBody(MockCertificateData.V2ProblemDetailsJson( + 422, "Unprocessable Entity", "EMS-969 Revoke reason ID missing"))); + + using var client = BuildV2Client(); + var ex = await Assert.ThrowsAsync( + () => client.RevokeOrderV2Async( + Constants.ApiV2.FamilySsl, + MockCertificateData.V2OrderId1, + new V2RevokeRequest { Reason = "superseded" })); + + ex.Message.Should().Contain("EMS-969"); + ex.Message.Should().NotContain("not in issued state"); + } + + [Fact] + public async Task RevokeOrderV2Async_404_ThrowsNotFoundOrNotRevokable_NotGenericNotFound() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/ssl-certificates/{MockCertificateData.V2OrderId1}/revoke") + .UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(404) + .WithHeader("Content-Type", "application/problem+json") + .WithBody(MockCertificateData.V2ProblemDetailsJson( + 404, "Not Found", "Order not found or not in a revokable state."))); + + using var client = BuildV2Client(); + var ex = await Assert.ThrowsAsync( + () => client.RevokeOrderV2Async( + Constants.ApiV2.FamilySsl, + MockCertificateData.V2OrderId1, + new V2RevokeRequest { Reason = "superseded" })); + + ex.Message.Should().Contain("not found or not in a revokable state"); + } + + // --------------------------------------------------------------------------- + // Product-family resolution + // --------------------------------------------------------------------------- + + [Fact] + public async Task ResolveAndTrackOrderV2Async_FindsOrderInSslFamily() + { + StubV2Token(); + // SSL family finds the order + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/ssl-certificates/{MockCertificateData.V2OrderId1}") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2TrackOrderIssuedJson(MockCertificateData.V2OrderId1))); + + using var client = BuildV2Client(); + var result = await client.ResolveAndTrackOrderV2Async(MockCertificateData.V2OrderId1); + + result.OrderId.Should().Be(MockCertificateData.V2OrderId1); + result.Status.Should().Be("issued"); + } + + [Fact] + public async Task ResolveAndTrackOrderV2Async_FindsOrderInPrivatePkiFamily() + { + StubV2Token(); + // SSL → 404, private-pki → 200 + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/ssl-certificates/{MockCertificateData.V2OrderId2}") + .UsingGet()) + .RespondWith(Response.Create().WithStatusCode(404)); + + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/private-pki-certificates/{MockCertificateData.V2OrderId2}") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2TrackOrderIssuedJson(MockCertificateData.V2OrderId2))); + + using var client = BuildV2Client(); + var result = await client.ResolveAndTrackOrderV2Async(MockCertificateData.V2OrderId2); + + result.OrderId.Should().Be(MockCertificateData.V2OrderId2); + } + + [Fact] + public async Task ResolveAndTrackOrderV2Async_NotInAnyFamily_ThrowsKeyNotFoundException() + { + StubV2Token(); + foreach (var family in new[] { "ssl-certificates", "private-pki-certificates", "signature-certificates" }) + { + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/{family}/ord_missing") + .UsingGet()) + .RespondWith(Response.Create().WithStatusCode(404)); + } + + using var client = BuildV2Client(); + await Assert.ThrowsAsync( + () => client.ResolveAndTrackOrderV2Async("ord_missing")); + } + + // --------------------------------------------------------------------------- + // GetDcvV2Async + // --------------------------------------------------------------------------- + + [Fact] + public async Task GetDcvV2Async_ReturnsChallengeWithToken() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/ssl-certificates/{MockCertificateData.V2OrderId1}/dcv") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2DcvChallengeJson("my-dcv-token"))); + + using var client = BuildV2Client(); + var result = await client.GetDcvV2Async(MockCertificateData.V2OrderId1, Constants.ApiV2.FamilySsl); + + result.Token.Should().Be("my-dcv-token"); + result.TokenExpiryDate.Should().Be("2026-12-31 23:59:59"); + } + + /// + /// The live GetDcv response on a fresh-domain order comes + /// back as exactly {"tokenExpiryDate":"...","token":"..."} — a shape that + /// matches neither the spec's worked example (orderNumber/domainName/ + /// dcvMethod/fileNameContent) nor + /// the spec's prose (method/txtToken). Deserializing against the wrong + /// shape leaves FileNameContent null (unmapped JSON properties are silently + /// ignored), which drives the plugin's null-token guard and strands the order at + /// EXTERNALVALIDATION forever. This pins the real field name (token) against + /// the exact live body, verbatim. + /// + [Fact] + public async Task GetDcvV2Async_LiveShape_DeserializesTokenField_NotFileNameContent() + { + StubV2Token(); + const string liveBody = @"{""tokenExpiryDate"":""2026-09-27 15:27:00"",""token"":""D6026954B9EB7D31E3FE8B2194F07087""}"; + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/ssl-certificates/{MockCertificateData.V2OrderId1}/dcv") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(liveBody)); + + using var client = BuildV2Client(); + var result = await client.GetDcvV2Async(MockCertificateData.V2OrderId1, Constants.ApiV2.FamilySsl); + + result.Should().NotBeNull(); + result.Token.Should().Be("D6026954B9EB7D31E3FE8B2194F07087", + "the live wire field is 'token', not 'fileNameContent'"); + result.TokenExpiryDate.Should().Be("2026-09-27 15:27:00"); + } + + [Fact] + public async Task GetDcvV2Async_NonSuccess_Throws() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/ssl-certificates/{MockCertificateData.V2OrderId1}/dcv") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(400) + .WithHeader("Content-Type", "application/problem+json") + .WithBody(MockCertificateData.V2ProblemDetailsJson(400, "Bad Request", "Order not found"))); + + using var client = BuildV2Client(); + await Assert.ThrowsAsync( + () => client.GetDcvV2Async(MockCertificateData.V2OrderId1, Constants.ApiV2.FamilySsl)); + } + + // --------------------------------------------------------------------------- + // VerifyDcvV2Async + // --------------------------------------------------------------------------- + + [Fact] + public async Task VerifyDcvV2Async_200Ok_ReturnsVerified() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/ssl-certificates/{MockCertificateData.V2OrderId1}/dcv/verify") + .UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2DcvVerifySuccessJson())); + + using var client = BuildV2Client(); + var result = await client.VerifyDcvV2Async(MockCertificateData.V2OrderId1, "example.com", Constants.ApiV2.FamilySsl); + + result.OverallStatus.Should().Be("VERIFIED"); + } + + [Fact] + public async Task VerifyDcvV2Async_204NoContent_ReturnsVerified() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/ssl-certificates/{MockCertificateData.V2OrderId1}/dcv/verify") + .UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(204)); + + using var client = BuildV2Client(); + var result = await client.VerifyDcvV2Async(MockCertificateData.V2OrderId1, "example.com", Constants.ApiV2.FamilySsl); + + result.OverallStatus.Should().Be("VERIFIED"); + } + + [Fact] + public async Task VerifyDcvV2Async_422_ThrowsInvalidOperationException() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/ssl-certificates/{MockCertificateData.V2OrderId1}/dcv/verify") + .UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(422) + .WithHeader("Content-Type", "application/problem+json") + .WithBody(MockCertificateData.V2ProblemDetailsJson(422, "Unprocessable Entity", "DNS record not found"))); + + using var client = BuildV2Client(); + var ex = await Assert.ThrowsAsync( + () => client.VerifyDcvV2Async(MockCertificateData.V2OrderId1, "example.com", Constants.ApiV2.FamilySsl)); + + ex.Message.Should().Contain("DCV verification failed"); + } + + [Fact] + public async Task VerifyDcvV2Async_SendsDnsTxtMethod() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/ssl-certificates/{MockCertificateData.V2OrderId1}/dcv/verify") + .UsingPost() + .WithBody(b => b != null && b.Contains("\"dns-txt\""))) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2DcvVerifySuccessJson())); + + using var client = BuildV2Client(); + var result = await client.VerifyDcvV2Async(MockCertificateData.V2OrderId1, "example.com", Constants.ApiV2.FamilySsl); + + result.OverallStatus.Should().Be("VERIFIED"); + } + + // --------------------------------------------------------------------------- + // DownloadCertificateV2Async — chain PEM assembly + // --------------------------------------------------------------------------- + + [Fact] + public async Task DownloadCertificateV2Async_WithChainPem_DeserializesChain() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/ssl-certificates/{MockCertificateData.V2OrderId1}/certificate") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2CertificateDownloadWithChainJson(MockCertificateData.V2OrderId1))); + + using var client = BuildV2Client(); + var result = await client.DownloadCertificateV2Async(Constants.ApiV2.FamilySsl, MockCertificateData.V2OrderId1); + + result.CertificatePem.Should().StartWith("-----BEGIN CERTIFICATE-----"); + result.ChainPem.Should().NotBeNullOrEmpty("API returned a chainPem array"); + result.ChainPem.Should().HaveCount(1); + result.ChainPem[0].Should().Contain("INTERMEDIATE"); + } + + [Fact] + public async Task DownloadCertificateV2Async_WithoutChainPem_ChainIsNull() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/ssl-certificates/{MockCertificateData.V2OrderId1}/certificate") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2CertificateDownloadJson(MockCertificateData.V2OrderId1))); + + using var client = BuildV2Client(); + var result = await client.DownloadCertificateV2Async(Constants.ApiV2.FamilySsl, MockCertificateData.V2OrderId1); + + result.CertificatePem.Should().StartWith("-----BEGIN CERTIFICATE-----"); + result.ChainPem.Should().BeNullOrEmpty("API did not return chainPem"); + } + + // --------------------------------------------------------------------------- + // Token refresh when expired + // --------------------------------------------------------------------------- + + [Fact] + public async Task Token_CachedAndReused_WhenNotNearExpiry() + { + // Restates PingV2Async_TokenCached_OnlyOneFetch's proof via GetAuthMeV2Async — kept + // as its own case (G11) so cache-reuse and expiry-refetch (below) are each one + // single-purpose test rather than folded into one. + StubV2Token(); + _server + .Given(Request.Create() + .WithPath("/api/certinext/v2/auth/me") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2AuthMeJson())); + + using var client = BuildV2Client(); + await client.GetAuthMeV2Async(); + await client.GetAuthMeV2Async(); + + TokenFetchCount(_server).Should().Be(1, "a non-expired cached token must be reused"); + } + + /// + /// G11: a cached token past its early-expiry window must be re-fetched via a fresh + /// client_credentials call — never via refresh_token. Per the V2 spec, + /// refresh tokens are single-use and refreshing invalidates the current access token, so + /// this locks in the client's current (safe) behaviour of only ever using + /// client_credentials. + /// + /// The real cache TTL floors at 30 seconds (Math.Max(expires_in - 60, 30) in + /// GetOrRefreshV2TokenAsync), which is too slow to wait out in a unit test — so this + /// reaches into the private _v2TokenExpiry field via reflection to simulate the + /// passage of time instead of actually waiting. + /// + [Fact] + public async Task Token_RefetchedViaClientCredentials_WhenPastEarlyExpiryWindow() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath("/api/certinext/v2/auth/me") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2AuthMeJson())); + + using var client = BuildV2Client(); + await client.GetAuthMeV2Async(); + TokenFetchCount(_server).Should().Be(1); + + // Simulate the cached token having entered/passed its early-expiry window. + SetV2TokenExpiry(client, DateTime.UtcNow.AddSeconds(-1)); + + await client.GetAuthMeV2Async(); + TokenFetchCount(_server).Should().Be(2, + "a token past its early-expiry window must be re-fetched, not reused"); + + // Every /oauth/token call must use client_credentials — never refresh_token, even + // though the stubbed token response includes a refresh_token field. + foreach (var entry in _server.LogEntries.Where(e => e.RequestMessage.Path == "/oauth/token")) + { + string body = entry.RequestMessage.Body ?? string.Empty; + body.Should().Contain("grant_type=client_credentials"); + body.Should().NotContain("grant_type=refresh_token", + "refresh tokens are single-use per the V2 spec — the client must never send this grant proactively"); + } + } + + private static int TokenFetchCount(WireMockServer server) => + server.LogEntries.Count(e => e.RequestMessage.Path == "/oauth/token"); + + private static void SetV2TokenExpiry(CERTInextClient client, DateTime value) + { + var field = typeof(CERTInextClient) + .GetField("_v2TokenExpiry", BindingFlags.NonPublic | BindingFlags.Instance); + field.Should().NotBeNull("test relies on CERTInextClient's private _v2TokenExpiry field existing"); + field!.SetValue(client, value); + } + + // --------------------------------------------------------------------------- + // G2: OAuth2 token failure hints (401 invalid_client vs 403 unauthorized_client) + // --------------------------------------------------------------------------- + + [Fact] + public async Task GetOrRefreshV2Token_Throws_DistinctHint_On401InvalidClient() + { + _server + .Given(Request.Create().WithPath("/oauth/token").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(401) + .WithHeader("Content-Type", "application/json") + .WithBody(@"{""error"":""invalid_client"",""error_description"":""Client authentication failed.""}")); + + using var client = BuildV2Client(); + + Func act = () => client.PingV2Async(); + + await act.Should().ThrowAsync() + .WithMessage("*401*") + .Where(ex => ex.Message.Contains("ClientId", StringComparison.OrdinalIgnoreCase) + || ex.Message.Contains("ClientSecret", StringComparison.OrdinalIgnoreCase)); + } + + [Fact] + public async Task GetOrRefreshV2Token_Throws_DistinctHint_On403UnauthorizedClient() + { + _server + .Given(Request.Create().WithPath("/oauth/token").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(403) + .WithHeader("Content-Type", "application/json") + .WithBody(@"{""error"":""unauthorized_client"",""error_description"":""Key not generated in OAuth mode.""}")); + + using var client = BuildV2Client(); + + Func act = () => client.PingV2Async(); + + await act.Should().ThrowAsync() + .WithMessage("*403*") + .Where(ex => ex.Message.Contains("OAuth mode", StringComparison.OrdinalIgnoreCase)); + } + + [Fact] + public async Task GetOrRefreshV2Token_401And403_ProduceDifferentMessages() + { + // The two hints must actually differ — otherwise the distinction above is cosmetic. + _server + .Given(Request.Create().WithPath("/oauth/token").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(401) + .WithHeader("Content-Type", "application/json") + .WithBody(@"{""error"":""invalid_client""}")); + using var client401 = BuildV2Client(); + Exception ex401 = null; + try { await client401.PingV2Async(); } catch (Exception ex) { ex401 = ex; } + + _server.Reset(); + _server + .Given(Request.Create().WithPath("/oauth/token").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(403) + .WithHeader("Content-Type", "application/json") + .WithBody(@"{""error"":""unauthorized_client""}")); + using var client403 = BuildV2Client(); + Exception ex403 = null; + try { await client403.PingV2Async(); } catch (Exception ex) { ex403 = ex; } + + ex401.Should().NotBeNull(); + ex403.Should().NotBeNull(); + ex401!.Message.Should().NotBe(ex403!.Message); + } + + [Fact] + public async Task GetOrRefreshV2Token_Throws_WhenTokenResponseLacksAccessToken() + { + _server + .Given(Request.Create().WithPath("/oauth/token").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(@"{""token_type"":""Bearer"",""expires_in"":3600}")); + + using var client = BuildV2Client(); + + Func act = () => client.PingV2Async(); + + await act.Should().ThrowAsync() + .WithMessage("*access_token*"); + } + + // --------------------------------------------------------------------------- + // G12: RFC 7807 field-level errors surfaced in the exception message + // --------------------------------------------------------------------------- + + [Fact] + public async Task ThrowOnV2Failure_IncludesFieldLevelErrors_FromProblemJson() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/ssl-certificates/{MockCertificateData.V2OrderId1}") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(400) + .WithHeader("Content-Type", "application/problem+json") + .WithBody( + @"{""type"":""https://api.certinext.io/errors/validation""," + + @"""title"":""Bad Request"",""status"":400," + + @"""detail"":""Body malformed""," + + @"""errors"":[{""field"":""certificate.domain"",""message"":""must not be blank""}]}")); + + using var client = BuildV2Client(); + + Func act = () => client.TrackOrderV2Async(Constants.ApiV2.FamilySsl, MockCertificateData.V2OrderId1); + + await act.Should().ThrowAsync() + .WithMessage("*certificate.domain*must not be blank*"); + } + + // --------------------------------------------------------------------------- + // ListOrdersV2Async — V2 /reports/orders page enumeration + // --------------------------------------------------------------------------- + + [Fact] + public async Task ListOrdersV2Async_MultiplePages_EnumeratesAllRowsInOrder() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath("/api/certinext/v2/reports/orders") + .WithParam("page", "1") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2OrdersReportJson( + page: 1, totalPages: 2, orderNumbers: new[] { "ord_p1_001", "ord_p1_002" }))); + _server + .Given(Request.Create() + .WithPath("/api/certinext/v2/reports/orders") + .WithParam("page", "2") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2OrdersReportJson( + page: 2, totalPages: 2, orderNumbers: new[] { "ord_p2_001" }))); + + using var client = BuildV2Client(); + var results = new List(); + await foreach (var row in client.ListOrdersV2Async(pageSize: 2)) + results.Add(row); + + results.Should().HaveCount(3); + results.ConvertAll(r => r.OrderNumber).Should().Equal("ord_p1_001", "ord_p1_002", "ord_p2_001"); + } + + [Fact] + public async Task ListOrdersV2Async_NoRows_ReturnsEmpty() + { + StubV2Token(); + _server + .Given(Request.Create().WithPath("/api/certinext/v2/reports/orders").UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2OrdersReportJson(page: 1, totalPages: 1, orderNumbers: Array.Empty()))); + + using var client = BuildV2Client(); + var results = new List(); + await foreach (var row in client.ListOrdersV2Async()) + results.Add(row); + + results.Should().BeEmpty(); + } + + [Fact] + public async Task ListOrdersV2Async_PassesFromAndToAsQueryParams() + { + StubV2Token(); + // Only matches if from/to were actually sent as query params — if the client + // dropped them, WireMock's default (unmatched) 404 response would make + // ThrowOnV2Failure throw, and the test would fail. + _server + .Given(Request.Create() + .WithPath("/api/certinext/v2/reports/orders") + .WithParam("from", "2026-01-01") + .WithParam("to", "2026-12-31") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2OrdersReportJson(page: 1, totalPages: 1, orderNumbers: Array.Empty()))); + + using var client = BuildV2Client(); + var results = new List(); + await foreach (var row in client.ListOrdersV2Async(from: "2026-01-01", to: "2026-12-31")) + results.Add(row); + + results.Should().BeEmpty(); + } + + // --------------------------------------------------------------------------- + // ListOrdersV2Async — GroupNumber query param + // --------------------------------------------------------------------------- + + [Fact] + public async Task ListOrdersV2Async_GroupNumberConfigured_PassesGroupNumberQueryParam() + { + StubV2Token(); + // Only matches if groupNumber was actually sent as a query param — if the client + // dropped it, WireMock's default (unmatched) 404 response would make + // ThrowOnV2Failure throw, and the test would fail. + _server + .Given(Request.Create() + .WithPath("/api/certinext/v2/reports/orders") + .WithParam("groupNumber", "GRP-555") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2OrdersReportJson(page: 1, totalPages: 1, orderNumbers: Array.Empty()))); + + using var client = BuildV2Client(groupNumber: "GRP-555"); + var results = new List(); + await foreach (var row in client.ListOrdersV2Async()) + results.Add(row); + + results.Should().BeEmpty(); + } + + [Fact] + public async Task ListOrdersV2Async_GroupNumberBlank_OmitsGroupNumberQueryParam() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath("/api/certinext/v2/reports/orders") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2OrdersReportJson(page: 1, totalPages: 1, orderNumbers: Array.Empty()))); + + using var client = BuildV2Client(groupNumber: string.Empty); + var results = new List(); + await foreach (var row in client.ListOrdersV2Async()) + results.Add(row); + + results.Should().BeEmpty(); + + string rawQuery = _server.LogEntries + .Last(e => e.RequestMessage.Path == "/api/certinext/v2/reports/orders") + .RequestMessage.RawQuery ?? string.Empty; + rawQuery.Should().NotContain("groupNumber", + "an unconfigured GroupNumber must not appear on the orders-report query string"); + } + + [Fact] + public async Task ListOrdersV2Async_PageSizeOver100_ClampedServerRequest() + { + StubV2Token(); + // Only matches size=100 — if the client sent the raw 500 through, this would 404. + _server + .Given(Request.Create() + .WithPath("/api/certinext/v2/reports/orders") + .WithParam("size", "100") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2OrdersReportJson(page: 1, totalPages: 1, orderNumbers: Array.Empty()))); + + using var client = BuildV2Client(); + var results = new List(); + await foreach (var row in client.ListOrdersV2Async(pageSize: 500)) + results.Add(row); + + results.Should().BeEmpty(); + } + + [Fact] + public async Task ListOrdersV2Async_NonSuccessResponse_Throws() + { + StubV2Token(); + _server + .Given(Request.Create().WithPath("/api/certinext/v2/reports/orders").UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(500) + .WithHeader("Content-Type", "application/problem+json") + .WithBody(@"{""title"":""Internal Server Error"",""status"":500,""detail"":""boom""}")); + + using var client = BuildV2Client(); + + Func act = async () => + { + await foreach (var _ in client.ListOrdersV2Async()) { } + }; + + await act.Should().ThrowAsync().WithMessage("*V2 list orders*"); + } + + // --------------------------------------------------------------------------- + // GetProductDetailsV2Async / ParseProductDetailsV2Response + // --------------------------------------------------------------------------- + + [Fact] + public async Task GetProductDetailsV2Async_NestedCategoryEnvelope_FlattensProducts() + { + StubV2Token(); + _server + .Given(Request.Create().WithPath("/api/certinext/v2/catalog/products").UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.GetCatalogProductsV2NestedJson())); + + using var client = BuildV2Client(); + List products = await client.GetProductDetailsV2Async(); + + products.Should().HaveCount(2); + products.Should().ContainSingle(p => p.ProductCode == MockCertificateData.ProfileIdTls + && p.ProductName == "TLS Server" + && p.ProductType == "SSL/TLS Certificates" + && p.ProductTypeId == "13" + && p.Active); + products.Should().ContainSingle(p => p.ProductCode == MockCertificateData.ProfileIdClient); + } + + // --------------------------------------------------------------------------- + // GetProductDetailsV2Async — GroupNumber query param + // --------------------------------------------------------------------------- + + [Fact] + public async Task GetProductDetailsV2Async_GroupNumberConfigured_PassesGroupNumberQueryParam() + { + StubV2Token(); + // Only matches if groupNumber was actually sent as a query param — if the client + // dropped it, WireMock's default (unmatched) 404 response would make + // ThrowOnV2Failure throw, and the test would fail. + _server + .Given(Request.Create() + .WithPath("/api/certinext/v2/catalog/products") + .WithParam("groupNumber", "GRP-555") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.GetCatalogProductsV2NestedJson())); + + using var client = BuildV2Client(groupNumber: "GRP-555"); + List products = await client.GetProductDetailsV2Async(); + + products.Should().HaveCount(2); + } + + [Fact] + public async Task GetProductDetailsV2Async_GroupNumberBlank_OmitsGroupNumberQueryParam() + { + StubV2Token(); + _server + .Given(Request.Create() + .WithPath("/api/certinext/v2/catalog/products") + .UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.GetCatalogProductsV2NestedJson())); + + using var client = BuildV2Client(groupNumber: string.Empty); + List products = await client.GetProductDetailsV2Async(); + + products.Should().HaveCount(2); + + string rawQuery = _server.LogEntries + .Last(e => e.RequestMessage.Path == "/api/certinext/v2/catalog/products") + .RequestMessage.RawQuery ?? string.Empty; + rawQuery.Should().NotContain("groupNumber", + "an unconfigured GroupNumber must not appear on the catalog query string"); + } + + // --------------------------------------------------------------------------- + // ProductTypeId flattening: productTypeID + // must survive every catalog response shape so EnrollV2Async can detect UCC products. + // --------------------------------------------------------------------------- + + [Fact] + public async Task GetProductDetailsV2Async_NestedCategoryEnvelope_UccProductTypeId_Preserved() + { + StubV2Token(); + _server + .Given(Request.Create().WithPath("/api/certinext/v2/catalog/products").UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(@"{ + ""products"":[ + { ""categoryName"":""SSL/TLS Certificates"", ""categoryID"":""1"", ""currencyType"":""USD"", + ""products"":[ + {""productCode"":""844"",""productName"":""DV SSL Certificate UCC"",""productTypeID"":""15""}, + {""productCode"":""842"",""productName"":""DV SSL Certificate"",""productTypeID"":""13""} + ] + } + ] +}")); + + using var client = BuildV2Client(); + List products = await client.GetProductDetailsV2Async(); + + products.Should().ContainSingle(p => p.ProductCode == "844" && p.ProductTypeId == "15", + "UCC product's productTypeID must survive the nested-category flattening"); + products.Should().ContainSingle(p => p.ProductCode == "842" && p.ProductTypeId == "13"); + } + + [Fact] + public async Task GetProductDetailsV2Async_FlatProductIdRow_UccProductTypeId_Preserved() + { + StubV2Token(); + _server + .Given(Request.Create().WithPath("/api/certinext/v2/catalog/products").UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(@"{ + ""products"":[ + {""productId"":""845"",""productName"":""DV SSL Certificate Wildcard UCC"",""masterProductName"":""DV SSL Certificate Wildcard UCC"",""productTypeID"":""21""} + ] +}")); + + using var client = BuildV2Client(); + List products = await client.GetProductDetailsV2Async(); + + products.Should().ContainSingle(p => p.ProductCode == "845" && p.ProductTypeId == "21", + "UCC product's productTypeID must survive the flat productId row shape"); + } + + [Fact] + public async Task GetProductDetailsV2Async_FlatProductCodeRow_UccProductTypeId_Preserved() + { + StubV2Token(); + _server + .Given(Request.Create().WithPath("/api/certinext/v2/catalog/products").UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(@"[ + {""productCode"":""851"",""productName"":""EV SSL Certificate UCC"",""productType"":""SSL/TLS Certificates"",""productTypeID"":""20"",""active"":true} +]")); + + using var client = BuildV2Client(); + List products = await client.GetProductDetailsV2Async(); + + products.Should().ContainSingle(p => p.ProductCode == "851" && p.ProductTypeId == "20", + "UCC product's productTypeID must survive the flat productCode row shape (direct DTO deserialize)"); + } + + [Fact] + public async Task GetProductDetailsV2Async_FlatProductIdRows_MapsToProductCode() + { + StubV2Token(); + _server + .Given(Request.Create().WithPath("/api/certinext/v2/catalog/products").UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.GetCatalogProductsV2FlatJson())); + + using var client = BuildV2Client(); + List products = await client.GetProductDetailsV2Async(); + + products.Should().HaveCount(2); + products.Should().Contain(p => p.ProductCode == MockCertificateData.ProfileIdTls && p.Active); + } + + [Fact] + public async Task GetProductDetailsV2Async_BareArray_Parses() + { + StubV2Token(); + _server + .Given(Request.Create().WithPath("/api/certinext/v2/catalog/products").UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.GetCatalogProductsV2BareArrayJson())); + + using var client = BuildV2Client(); + List products = await client.GetProductDetailsV2Async(); + + products.Should().ContainSingle(p => p.ProductCode == MockCertificateData.ProfileIdTls); + } + + [Fact] + public async Task GetProductDetailsV2Async_EmptyCatalog_ReturnsEmptyList() + { + StubV2Token(); + _server + .Given(Request.Create().WithPath("/api/certinext/v2/catalog/products").UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.GetCatalogProductsV2EmptyJson())); + + using var client = BuildV2Client(); + List products = await client.GetProductDetailsV2Async(); + + products.Should().BeEmpty(); + } + } +} diff --git a/CERTInext.Tests/CaErrorTextMaskingTests.cs b/CERTInext.Tests/CaErrorTextMaskingTests.cs new file mode 100644 index 0000000..1971ca6 --- /dev/null +++ b/CERTInext.Tests/CaErrorTextMaskingTests.cs @@ -0,0 +1,281 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Linq; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.Extensions.CAPlugin.CERTInext.Models; +using Microsoft.Extensions.Logging; +using WireMock.RequestBuilders; +using WireMock.ResponseBuilders; +using WireMock.Server; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// CA-supplied error text (meta.errorMessage / legacy message) may echo a request + /// value such as an email. With LogSensitiveRequestData off, email-shaped tokens are masked + /// (via MaskEmail) and CR/LF stripped in both the log line and the exception message that + /// Command stores; the rest of the text is preserved. With the flag on the text is verbatim. + /// All data is synthetic. + /// + [Collection(LoggingStateCollection.Name)] + public class CaErrorTextMaskingTests : IDisposable + { + private const string Email = "jane.doe@example.com"; + private const string MaskedEmail = "j***@example.com"; + + private readonly WireMockServer _server = WireMockServer.Start(); + + public void Dispose() => _server.Stop(); + + // --------------------------------------------------------------------------- + // LogSanitizer.SanitizeCaText + // --------------------------------------------------------------------------- + + [Theory] + [InlineData("Invalid requestorEmail jane.doe@example.com for order", "Invalid requestorEmail j***@example.com for order")] + [InlineData("Email 'jane.doe@example.com'.", "Email 'j***@example.com'.")] + [InlineData("Sent to jane.doe@example.com.", "Sent to j***@example.com.")] + [InlineData("a@b.example.org and c+tag@sub.example.co.uk differ", "a***@b.example.org and c***@sub.example.co.uk differ")] + [InlineData("EMS-956 Invalid Request for this API.", "EMS-956 Invalid Request for this API.")] + [InlineData("Inactive Account User.", "Inactive Account User.")] + [InlineData("no at-sign, handle@ only, @example.com alone", "no at-sign, handle@ only, @example.com alone")] + public void SanitizeCaText_FlagOff_MasksOnlyEmailTokens(string input, string expected) + { + LogSanitizer.SanitizeCaText(input, false).Should().Be(expected); + } + + [Fact] + public void SanitizeCaText_FlagOff_StripsCrLfAndTab() + { + LogSanitizer.SanitizeCaText("first\r\nsecond\tthird", false) + .Should().Be("first\\r\\nsecond\\tthird"); + } + + [Fact] + public void SanitizeCaText_FlagOn_IsVerbatim() + { + string text = "Bad " + Email + "\r\nline two"; + LogSanitizer.SanitizeCaText(text, true).Should().Be(text); + } + + [Fact] + public void SanitizeCaText_NullAndEmpty_PassThrough() + { + LogSanitizer.SanitizeCaText(null, false).Should().BeNull(); + LogSanitizer.SanitizeCaText(string.Empty, false).Should().BeEmpty(); + } + + [Fact] + public void SanitizeCaText_IsIdempotent() + { + string once = LogSanitizer.SanitizeCaText("Bad " + Email, false); + LogSanitizer.SanitizeCaText(once, false).Should().Be(once); + } + + [Fact] + public void SanitizeCaText_LargeInputWithoutAtSign_CompletesQuickly() + { + string big = new string('a', 64 * 1024); + var sw = System.Diagnostics.Stopwatch.StartNew(); + LogSanitizer.SanitizeCaText(big, false).Should().Be(big); + sw.Elapsed.Should().BeLessThan(TimeSpan.FromSeconds(1)); + } + + // --------------------------------------------------------------------------- + // ExtractErrorMessage + // --------------------------------------------------------------------------- + + [Fact] + public void ExtractErrorMessage_MetaBody_FlagOff_MasksEmailKeepsCodeAndStatus() + { + string body = "{\"meta\":{\"status\":\"0\",\"errorCode\":\"EMS-100\",\"errorMessage\":\"Invalid requestorEmail " + Email + " (field requestorEmail)\"}}"; + + CERTInextClient.ExtractErrorMessage(body, "op", 400) + .Should().Be($"CERTInext error during 'op' (HTTP 400): Invalid requestorEmail {MaskedEmail} (field requestorEmail) [EMS-100]"); + } + + [Fact] + public void ExtractErrorMessage_MetaBody_FlagOn_IsVerbatim() + { + string body = "{\"meta\":{\"status\":\"0\",\"errorCode\":\"EMS-100\",\"errorMessage\":\"Invalid requestorEmail " + Email + "\"}}"; + + CERTInextClient.ExtractErrorMessage(body, "op", 400, logSensitiveRequestData: true) + .Should().Be($"CERTInext error during 'op' (HTTP 400): Invalid requestorEmail {Email} [EMS-100]"); + } + + [Fact] + public void ExtractErrorMessage_MetaBody_FlagOff_StripsCrLf() + { + // JSON \r\n escapes decode to real CR/LF characters. + string body = "{\"meta\":{\"errorCode\":\"EMS-100\",\"errorMessage\":\"line one\\r\\nforged line\"}}"; + + string msg = CERTInextClient.ExtractErrorMessage(body, "op"); + + msg.Should().NotContain("\r").And.NotContain("\n"); + msg.Should().Contain("line one\\r\\nforged line"); + } + + [Fact] + public void ExtractErrorMessage_LegacyBody_FlagOffMasksFlagOnVerbatim() + { + string body = "{\"message\":\"Unknown user " + Email + "\"}"; + + CERTInextClient.ExtractErrorMessage(body, "op", 503) + .Should().Be($"CERTInext error during 'op' (HTTP 503): Unknown user {MaskedEmail}"); + CERTInextClient.ExtractErrorMessage(body, "op", 503, logSensitiveRequestData: true) + .Should().Be($"CERTInext error during 'op' (HTTP 503): Unknown user {Email}"); + } + + [Fact] + public void ExtractErrorMessage_OmittedFlag_FailsClosed() + { + string body = "{\"message\":\"Unknown user " + Email + "\"}"; + + CERTInextClient.ExtractErrorMessage(body, "op").Should().NotContain(Email); + } + + // --------------------------------------------------------------------------- + // End to end through the client: log line and exception message + // --------------------------------------------------------------------------- + + private sealed class CapturingLogger : ILogger + { + public ConcurrentQueue<(LogLevel Level, string Message)> Entries { get; } = new(); + public IDisposable BeginScope(TState state) => null; + public bool IsEnabled(LogLevel logLevel) => true; + public void Log(LogLevel logLevel, EventId eventId, TState state, Exception exception, + Func formatter) + => Entries.Enqueue((logLevel, formatter(state, exception))); + } + + private CERTInextClient BuildClient(bool logSensitiveRequestData) => new CERTInextClient(new CERTInextConfig + { + ApiUrl = _server.Urls[0], + AuthMode = "AccessKey", + ApiKey = "synthetic-access-key", + AccountNumber = "9988776655", + LogSensitiveRequestData = logSensitiveRequestData + }); + + private async Task<(Exception Error, List Lines)> RunAsync( + bool logSensitiveRequestData, string path, int status, string body, string marker, + Func call) + { + _server.Reset(); + _server.Given(Request.Create().WithPath("/" + path).UsingPost()) + .RespondWith(Response.Create().WithStatusCode(status) + .WithHeader("Content-Type", "application/json").WithBody(body)); + + var client = BuildClient(logSensitiveRequestData); + var logger = new CapturingLogger(); + Exception error = null; + using (CERTInextClient.OverrideLoggerForTests(logger)) + { + try { await call(client); } + catch (Exception ex) { error = ex; } + } + + // The client logger is process-wide; scope to lines carrying this call's marker. + var lines = logger.Entries.Select(e => e.Message) + .Where(m => m != null && m.Contains(marker)).ToList(); + return (error, lines); + } + + private static string MetaFailureBody(string marker, string errorCode = "EMS-100") => + "{\"meta\":{\"status\":\"0\",\"errorCode\":\"" + errorCode + "\",\"errorMessage\":\"" + marker + + " Invalid requestorEmail " + Email + " for field requestorEmail\\r\\nforged\"}}"; + + // The ErrorMessage= field of the "CERTInext API non-success" line (the ResponseBody= field + // that follows is redacted separately by ApplyLoggingRedaction). + private static string ErrorMessageField(IEnumerable lines) + { + string failure = lines.Single(l => l.StartsWith("CERTInext API non-success")); + int start = failure.IndexOf("ErrorMessage=", StringComparison.Ordinal); + int end = failure.IndexOf(", ResponseBody=", StringComparison.Ordinal); + return failure.Substring(start, end - start); + } + + [Fact] + public async Task TrackOrder_MetaFailure_FlagOff_MasksEmailInLogAndException() + { + string marker = "m-" + Guid.NewGuid().ToString("N"); + var (error, lines) = await RunAsync(false, "TrackOrder", 200, MetaFailureBody(marker), marker, + c => c.TrackOrderAsync("ORD-1")); + + error.Should().NotBeNull(); + error.Message.Should().Contain("Invalid requestorEmail " + MaskedEmail + " for field requestorEmail") + .And.NotContain(Email).And.NotContain("\r").And.NotContain("\n"); + + string errField = ErrorMessageField(lines); + errField.Should().Contain("Invalid requestorEmail " + MaskedEmail + " for field requestorEmail") + .And.NotContain(Email).And.NotContain("\r").And.NotContain("\n").And.Contain("\\r\\nforged"); + lines.Single(l => l.StartsWith("CERTInext API non-success")).Should().Contain("ErrorCode=EMS-100"); + } + + [Fact] + public async Task TrackOrder_MetaFailure_FlagOn_IsVerbatimInLogAndException() + { + string marker = "m-" + Guid.NewGuid().ToString("N"); + var (error, lines) = await RunAsync(true, "TrackOrder", 200, MetaFailureBody(marker), marker, + c => c.TrackOrderAsync("ORD-1")); + + error.Message.Should().Contain("Invalid requestorEmail " + Email + " for field requestorEmail"); + ErrorMessageField(lines).Should().Contain("Invalid requestorEmail " + Email + " for field requestorEmail"); + } + + [Fact] + public async Task TrackOrder_NotFound_FlagOff_MasksEmailInKeyNotFoundMessage() + { + string marker = "m-" + Guid.NewGuid().ToString("N"); + var (error, _) = await RunAsync(false, "TrackOrder", 200, MetaFailureBody(marker, "EMS-913"), marker, + c => c.TrackOrderAsync("ORD-1")); + + error.Should().BeOfType(); + error.Message.Should().Contain(MaskedEmail).And.NotContain(Email); + } + + [Fact] + public async Task GetProductDetails_Non2xxMetaBody_FlagOff_MasksEmailInLogAndException() + { + string marker = "m-" + Guid.NewGuid().ToString("N"); + var (error, lines) = await RunAsync(false, "GetProductDetails", 400, MetaFailureBody(marker), marker, + c => c.GetProductDetailsAsync()); + + error.Message.Should().Contain("(HTTP 400)").And.Contain("[EMS-100]") + .And.Contain("Invalid requestorEmail " + MaskedEmail + " for field requestorEmail") + .And.NotContain(Email); + ErrorMessageField(lines).Should().Contain(MaskedEmail).And.NotContain(Email); + } + + [Fact] + public async Task GetProductDetails_Non2xxMetaBody_FlagOn_IsVerbatimInLogAndException() + { + string marker = "m-" + Guid.NewGuid().ToString("N"); + var (error, lines) = await RunAsync(true, "GetProductDetails", 400, MetaFailureBody(marker), marker, + c => c.GetProductDetailsAsync()); + + error.Message.Should().Contain("Invalid requestorEmail " + Email + " for field requestorEmail"); + ErrorMessageField(lines).Should().Contain("Invalid requestorEmail " + Email + " for field requestorEmail"); + } + + [Fact] + public void IsRateLimitSurface_StillMatchesRawTextContainingEmail() + { + CERTInextClient.IsRateLimitSurface("Inactive Account User. contact " + Email).Should().BeTrue(); + // And the masked form keeps the phrase, so masking never hides a rate-limit diagnosis. + LogSanitizer.SanitizeCaText("Inactive Account User. contact " + Email, false) + .Should().Contain("Inactive Account User."); + } + } +} diff --git a/CERTInext.Tests/ClientPayloadLogRedactionTests.cs b/CERTInext.Tests/ClientPayloadLogRedactionTests.cs new file mode 100644 index 0000000..ff9a3a3 --- /dev/null +++ b/CERTInext.Tests/ClientPayloadLogRedactionTests.cs @@ -0,0 +1,293 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Linq; +using System.Text.Json; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Microsoft.Extensions.Logging; +using WireMock.RequestBuilders; +using WireMock.ResponseBuilders; +using WireMock.Server; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Issue 0040 regression coverage at the real log call sites in : + /// the PlaceOrderAsync Trace request dump (which used to write the replayable + /// meta.authKey digest and requestor PII verbatim), the TrackOrderAsync Trace + /// response dump, and the LogApiFailure response-body logger. Each test drives the client + /// against WireMock and captures what the client actually logged through + /// CERTInextClient.OverrideLoggerForTests. + /// + /// The client logger is process-wide, so other test classes running in parallel may log into + /// the capture while it is installed; every assertion is scoped to lines carrying this call's + /// unique marker. All data is synthetic. + /// + [Collection(LoggingStateCollection.Name)] + public class ClientPayloadLogRedactionTests : IDisposable + { + private const string RequestorName = "Jane Doe"; + private const string RequestorEmail = "jane.doe@example.com"; + private const string MaskedRequestorEmail = "j***@example.com"; + private const string RequestorMobile = "5551234567"; + private const string PocEmail = "tech.contact@example.com"; + private const string MaskedPocEmail = "t***@example.com"; + private const string PocFirstName = "Terry"; + private const string PocLastName = "Techcontact"; + private const string PocMobile = "5559876543"; + private const string SignerName = "John Signer"; + private const string EmailSan = "alice@example.com"; + private const string MaskedEmailSan = "a***@example.com"; + + private readonly WireMockServer _server; + + public ClientPayloadLogRedactionTests() + { + _server = WireMockServer.Start(); + } + + public void Dispose() => _server.Stop(); + + private sealed class CapturingLogger : ILogger + { + public ConcurrentQueue<(LogLevel Level, string Message)> Entries { get; } = new(); + public IDisposable BeginScope(TState state) => null; + public bool IsEnabled(LogLevel logLevel) => true; + public void Log(LogLevel logLevel, EventId eventId, TState state, Exception exception, + Func formatter) + => Entries.Enqueue((logLevel, formatter(state, exception))); + } + + private CERTInextClient BuildClient(bool logSensitiveRequestData) => new CERTInextClient(new CERTInextConfig + { + ApiUrl = _server.Urls[0], + AuthMode = "AccessKey", + ApiKey = "synthetic-access-key", + AccountNumber = "9988776655", + LogSensitiveRequestData = logSensitiveRequestData + }); + + private static GenerateOrderSslRequest BuildOrder(string primaryDomain) => new GenerateOrderSslRequest + { + // Meta left null so PlaceOrderAsync computes a real authKey via BuildMetaAsync. + OrderDetails = new SslOrderDetails + { + ProductCode = "842", + RequestorInformation = new RequestorInformation + { + RequestorName = RequestorName, + RequestorMobileNumber = RequestorMobile, + RequestorEmail = RequestorEmail, + RequestorDesignation = "IT Administrator" + }, + CertificateInformation = new CertificateInformation + { + DomainName = primaryDomain, + AdditionalDomains = new List { "www." + primaryDomain, EmailSan } + }, + AgreementDetails = new AgreementDetails { SignerName = SignerName, SignerPlace = "Austin", SignerIp = "203.0.113.10" }, + TechnicalPointOfContact = new TechnicalPointOfContact + { + PocFirstName = PocFirstName, PocLastName = PocLastName, PocEmail = PocEmail, + PocIsdCode = "44", PocMobileNumber = PocMobile + } + } + }; + + private void StubGenerateOrder(string body) => + _server.Given(Request.Create().WithPath("/GenerateOrderSSL").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json").WithBody(body)); + + /// Returns the meta.authKey the client actually sent on the wire. + private string SentAuthKey() + { + var entry = _server.LogEntries.Last(e => e.RequestMessage.Path == "/GenerateOrderSSL"); + using var doc = JsonDocument.Parse(entry.RequestMessage.Body ?? "{}"); + string authKey = doc.RootElement.GetProperty("meta").GetProperty("authKey").GetString(); + authKey.Should().NotBeNullOrEmpty("precondition: AccessKey mode sends a computed authKey"); + return authKey; + } + + private static async Task> CaptureAsync(string marker, Func act) + { + var logger = new CapturingLogger(); + using (CERTInextClient.OverrideLoggerForTests(logger)) + { + try { await act(); } + catch (Exception) { /* failure-path tests expect a throw; assertions are on the logs */ } + } + return logger.Entries.Where(e => e.Message != null && e.Message.Contains(marker)).ToList(); + } + + // --------------------------------------------------------------------------- + // PlaceOrderAsync Trace request dump + // --------------------------------------------------------------------------- + + [Fact] + public async Task PlaceOrder_TracePayload_FlagOff_OmitsAuthKeyAndPii() + { + string domain = "po-" + Guid.NewGuid().ToString("N") + ".example.com"; + StubGenerateOrder(MockCertificateData.GenerateOrderSuccessJson("ORD-REDACT-1")); + using var client = BuildClient(logSensitiveRequestData: false); + + var lines = await CaptureAsync(domain, () => client.PlaceOrderAsync(BuildOrder(domain))); + string authKey = SentAuthKey(); + + var dump = lines.Where(l => l.Message.StartsWith("PlaceOrderAsync request payload")).ToList(); + dump.Should().ContainSingle(); + dump[0].Level.Should().Be(LogLevel.Trace); + string payload = dump[0].Message; + + payload.Should().NotContain(authKey, "the replayable authKey digest must never be logged"); + payload.Should().Contain("\"authKey\":\"***REDACTED***\""); + payload.Should().NotContain(RequestorName).And.NotContain(RequestorEmail).And.NotContain(RequestorMobile) + .And.NotContain(PocEmail).And.NotContain(SignerName).And.NotContain(EmailSan) + .And.NotContain(PocFirstName).And.NotContain(PocLastName).And.NotContain(PocMobile) + .And.NotContain("\"pocIsdCode\":\"44\""); + payload.Should().Contain(MaskedPocEmail).And.Contain("\"pocFirstName\":\"***REDACTED***\"") + .And.Contain("\"pocLastName\":\"***REDACTED***\"").And.Contain("\"pocIsdCode\":\"***REDACTED***\"") + .And.Contain("\"pocMobileNumber\":\"***REDACTED***\""); + payload.Should().Contain(MaskedRequestorEmail).And.Contain(MaskedEmailSan).And.Contain("www." + domain); + + lines.Should().NotContain(l => l.Message.Contains(authKey) || l.Message.Contains(EmailSan) || l.Message.Contains(RequestorEmail), + "no client log line for this order may carry the authKey or unmasked email with the flag off"); + } + + [Fact] + public async Task PlaceOrder_TracePayload_FlagOn_IncludesPiiButStillRedactsAuthKey() + { + string domain = "po-" + Guid.NewGuid().ToString("N") + ".example.com"; + StubGenerateOrder(MockCertificateData.GenerateOrderSuccessJson("ORD-REDACT-2")); + using var client = BuildClient(logSensitiveRequestData: true); + + var lines = await CaptureAsync(domain, () => client.PlaceOrderAsync(BuildOrder(domain))); + string authKey = SentAuthKey(); + + string payload = lines.Single(l => l.Message.StartsWith("PlaceOrderAsync request payload")).Message; + + payload.Should().NotContain(authKey, "credentials are redacted regardless of LogSensitiveRequestData"); + payload.Should().Contain("\"authKey\":\"***REDACTED***\""); + payload.Should().Contain(RequestorName).And.Contain(RequestorEmail).And.Contain(RequestorMobile) + .And.Contain(PocEmail).And.Contain(SignerName).And.Contain(EmailSan) + .And.Contain(PocFirstName).And.Contain(PocLastName).And.Contain(PocMobile) + .And.Contain("\"pocIsdCode\":\"44\""); + + lines.Should().NotContain(l => l.Message.Contains(authKey)); + } + + [Fact] + public async Task PlaceOrder_SubmittingOrderLine_MasksEmailSanUnlessFlagOn() + { + string domain = "po-" + Guid.NewGuid().ToString("N") + ".example.com"; + StubGenerateOrder(MockCertificateData.GenerateOrderSuccessJson("ORD-REDACT-3")); + + using (var off = BuildClient(logSensitiveRequestData: false)) + { + var lines = await CaptureAsync(domain, () => off.PlaceOrderAsync(BuildOrder(domain))); + lines.Single(l => l.Message.StartsWith("Submitting order to CERTInext")).Message + .Should().Contain(MaskedEmailSan).And.NotContain(EmailSan); + } + + using (var on = BuildClient(logSensitiveRequestData: true)) + { + var lines = await CaptureAsync(domain, () => on.PlaceOrderAsync(BuildOrder(domain))); + lines.Single(l => l.Message.StartsWith("Submitting order to CERTInext")).Message + .Should().Contain(EmailSan); + } + } + + // --------------------------------------------------------------------------- + // LogApiFailure — CA error body echoing request fields + // --------------------------------------------------------------------------- + + private static string FailureBodyEchoingRequest(string domain) => + "{\"meta\":{\"status\":\"0\",\"errorCode\":\"EMS-100\",\"errorMessage\":\"Validation failed\"," + + "\"authKey\":\"0f1e2d3c4b5a6978synthetic\"}," + + "\"orderDetails\":{\"requestorInformation\":{\"requestorName\":\"" + RequestorName + "\",\"requestorEmail\":\"" + RequestorEmail + "\"}," + + "\"certificateInformation\":{\"domainName\":\"" + domain + "\",\"additionalDomains\":[\"" + EmailSan + "\"]}}}"; + + [Fact] + public async Task PlaceOrder_ApiFailureBody_FlagOff_RedactsCredentialsAndPii() + { + string domain = "fail-" + Guid.NewGuid().ToString("N") + ".example.com"; + StubGenerateOrder(FailureBodyEchoingRequest(domain)); + using var client = BuildClient(logSensitiveRequestData: false); + + var lines = await CaptureAsync(domain, () => client.PlaceOrderAsync(BuildOrder(domain))); + + string failure = lines.Single(l => l.Message.StartsWith("CERTInext API non-success")).Message; + failure.Should().NotContain("0f1e2d3c4b5a6978synthetic") + .And.NotContain(RequestorName).And.NotContain(RequestorEmail).And.NotContain(EmailSan); + failure.Should().Contain(MaskedRequestorEmail).And.Contain(MaskedEmailSan).And.Contain("EMS-100"); + } + + [Fact] + public async Task PlaceOrder_ApiFailureBody_FlagOn_KeepsPiiButRedactsCredentials() + { + string domain = "fail-" + Guid.NewGuid().ToString("N") + ".example.com"; + StubGenerateOrder(FailureBodyEchoingRequest(domain)); + using var client = BuildClient(logSensitiveRequestData: true); + + var lines = await CaptureAsync(domain, () => client.PlaceOrderAsync(BuildOrder(domain))); + + string failure = lines.Single(l => l.Message.StartsWith("CERTInext API non-success")).Message; + failure.Should().NotContain("0f1e2d3c4b5a6978synthetic"); + failure.Should().Contain(RequestorName).And.Contain(RequestorEmail).And.Contain(EmailSan); + } + + // --------------------------------------------------------------------------- + // TrackOrderAsync Trace response dump + // --------------------------------------------------------------------------- + + private void StubTrackOrder(string orderNumber) => + _server.Given(Request.Create().WithPath("/TrackOrder").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody( + "{\"meta\":{\"status\":\"1\"},\"orderDetails\":{\"orderNumber\":\"" + orderNumber + "\"," + + "\"orderStatusId\":\"1\",\"certificateStatusId\":\"1\"," + + "\"requestorInformation\":{\"requestorName\":\"" + RequestorName + "\",\"requestorEmail\":\"" + RequestorEmail + "\"}," + + "\"domainVerification\":{\"example.com\":{\"dcvStatus\":\"1\"},\"" + EmailSan + "\":{\"dcvStatus\":\"0\"},\"status\":\"0\"}}}")); + + [Fact] + public async Task TrackOrder_TracePayload_FlagOff_OmitsPii() + { + string order = "ORD-" + Guid.NewGuid().ToString("N"); + StubTrackOrder(order); + using var client = BuildClient(logSensitiveRequestData: false); + + var lines = await CaptureAsync(order, () => client.TrackOrderAsync(order)); + + var dump = lines.Where(l => l.Message.StartsWith("TrackOrderAsync response payload")).ToList(); + dump.Should().ContainSingle(); + dump[0].Level.Should().Be(LogLevel.Trace); + dump[0].Message.Should().NotContain(RequestorName).And.NotContain(RequestorEmail).And.NotContain(EmailSan); + dump[0].Message.Should().Contain(MaskedRequestorEmail).And.Contain(MaskedEmailSan); + } + + [Fact] + public async Task TrackOrder_TracePayload_FlagOn_IncludesPii() + { + string order = "ORD-" + Guid.NewGuid().ToString("N"); + StubTrackOrder(order); + using var client = BuildClient(logSensitiveRequestData: true); + + var lines = await CaptureAsync(order, () => client.TrackOrderAsync(order)); + + lines.Single(l => l.Message.StartsWith("TrackOrderAsync response payload")).Message + .Should().Contain(RequestorName).And.Contain(RequestorEmail).And.Contain(EmailSan); + } + } +} diff --git a/CERTInext.Tests/EmailNotificationsEnrollmentTests.cs b/CERTInext.Tests/EmailNotificationsEnrollmentTests.cs new file mode 100644 index 0000000..b3f55e1 --- /dev/null +++ b/CERTInext.Tests/EmailNotificationsEnrollmentTests.cs @@ -0,0 +1,331 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Generic; +using System.Text.Json; +using System.Text.Json.Serialization; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Moq; +using Org.BouncyCastle.Asn1.X509; +using Org.BouncyCastle.Crypto; +using Org.BouncyCastle.Crypto.Generators; +using Org.BouncyCastle.Pkcs; +using Org.BouncyCastle.Security; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Tests that the V2 order body's emailNotifications field honors the connector's + /// EmailNotifications config rather than a hardcoded "all". These tests exercise + /// EnrollV2Async end-to-end (through ) against a + /// Strict mock, plus a direct DTO serialization check for + /// , following the pattern established + /// by V2SubscriptionEnrollmentTests.cs. + /// + /// Mapping under test: "1" -> "all", "0" -> "consent-only" (the V2 spec's enum is + /// `consent-only | all`; the old literal "0" is not a member), + /// blank/whitespace/unset -> null (omitted; CA defaults to "all"), any other value + /// (including the literal "all") fails the enrollment before any CA call. + /// + public class EmailNotificationsEnrollmentTests + { + private static Mock NewMock() => + new Mock(MockBehavior.Strict); + + // Default here intentionally matches CERTInextConfig's own property default ("0") — NOT + // a `?? "0"`-style fallback applied to the parameter, which would silently coerce an + // explicitly-passed null (a real Theory case below) back to "0" and defeat that test case. + private static CERTInextCAPlugin BuildV2Plugin( + ICERTInextClient client, + string emailNotifications = "0") => + new CERTInextCAPlugin(client, new CERTInextConfig + { + UseV2Api = true, + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + SignerIp = "1.2.3.4", + SignerPlace = "New York", + PickupRetries = 0, + EmailNotifications = emailNotifications + }); + + private static EnrollmentProductInfo MakeV2ProductInfo(string productCode, string productVariant) => + new EnrollmentProductInfo + { + ProductID = "DV SSL", + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = productCode, + ["ProductFamily"] = "ssl", + ["ProductVariant"] = productVariant, + ["DomainName"] = "example.com" + } + }; + + private static void StubCatalog(Mock mock, string productCode, string productTypeId) => + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = productCode, ProductTypeId = productTypeId, Active = true } + }); + + private static void StubHappyOrderPlacement(Mock mock, string orderId) + { + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), orderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), orderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = orderId, Status = "pending-dcv" }); + } + + private static string GenerateCsrPem(string cn) + { + var keyGen = new RsaKeyPairGenerator(); + keyGen.Init(new KeyGenerationParameters(new SecureRandom(), 2048)); + AsymmetricCipherKeyPair kp = keyGen.GenerateKeyPair(); + + var csr = new Pkcs10CertificationRequest( + "SHA256withRSA", new X509Name($"CN={cn}"), kp.Public, null, kp.Private); + + return "-----BEGIN CERTIFICATE REQUEST-----\n" + + Convert.ToBase64String(csr.GetEncoded(), Base64FormattingOptions.InsertLineBreaks) + + "\n-----END CERTIFICATE REQUEST-----"; + } + + private static async Task<(EnrollmentResult Result, V2CreateSslOrderRequest Captured)> RunEnrollAsync( + Mock mock, CERTInextCAPlugin plugin, string orderId = "ord_email_001") + { + V2CreateSslOrderRequest captured = null; + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .Callback((_, __, req, ___) => captured = req) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = orderId, Status = "pending-dcv" }); + + var result = await plugin.Enroll( + csr: GenerateCsrPem("example.com"), + subject: "CN=example.com", + san: null, + productInfo: MakeV2ProductInfo("842", "dv"), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + return (result, captured); + } + + // --------------------------------------------------------------------------- + // EnrollV2Async wiring — valid mapped values + // --------------------------------------------------------------------------- + + [Fact] + public async Task Enroll_V2_EmailNotifications_1_MapsToAll() + { + var mock = NewMock(); + StubCatalog(mock, "842", "13"); // DV SSL (non-UCC) + StubHappyOrderPlacement(mock, "ord_email_001"); + + var plugin = BuildV2Plugin(mock.Object, emailNotifications: "1"); + + var (result, captured) = await RunEnrollAsync(mock, plugin, "ord_email_001"); + + result.CARequestID.Should().Be("ord_email_001"); + captured.Should().NotBeNull(); + captured!.EmailNotifications.Should().Be("all", + "EmailNotifications=\"1\" must map to the CA's full notification set (\"all\")"); + } + + [Fact] + public async Task Enroll_V2_EmailNotifications_0_MapsToConsentOnly() + { + var mock = NewMock(); + StubCatalog(mock, "842", "13"); + StubHappyOrderPlacement(mock, "ord_email_002"); + + var plugin = BuildV2Plugin(mock.Object, emailNotifications: "0"); + + var (result, captured) = await RunEnrollAsync(mock, plugin, "ord_email_002"); + + result.CARequestID.Should().Be("ord_email_002"); + captured!.EmailNotifications.Should().Be("consent-only", + "EmailNotifications=\"0\" (silent) must be sent as the V2 spec's \"consent-only\"; the " + + "legacy literal \"0\" is not a member of the `consent-only | all` enum"); + captured.EmailNotifications.Should().NotBe("0"); + } + + [Fact] + public async Task Enroll_V2_PrivatePki_EmailNotifications_0_MapsToConsentOnly() + { + // The Private PKI create body shares the same connector mapping (the spec's enum is the + // same `consent-only | all` there). + var mock = NewMock(); + V2CreatePrivatePkiOrderRequest captured = null; + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), It.IsAny())) + .Callback((_, req, __) => captured = req) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = "ord_email_pki", Status = "pending-csr" }); + mock.Setup(c => c.SubmitCsrV2Async( + Constants.ApiV2.FamilyPrivatePki, "ord_email_pki", It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.TrackOrderV2Async(Constants.ApiV2.FamilyPrivatePki, "ord_email_pki", It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = "ord_email_pki", Status = "pending-approval" }); + + var plugin = BuildV2Plugin(mock.Object, emailNotifications: "0"); + await plugin.Enroll( + csr: GenerateCsrPem("intranet.example.com"), + subject: "CN=intranet.example.com", + san: null, + productInfo: new EnrollmentProductInfo + { + ProductID = "DV SSL", + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductFamily"] = "private-pki", + ["ProductVariant"] = "intranet-ssl", + ["DomainName"] = "intranet.example.com" + } + }, + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + captured.Should().NotBeNull(); + captured!.EmailNotifications.Should().Be("consent-only"); + } + + [Fact] + public async Task Enroll_V2_EmailNotifications_1_IsTrimmedBeforeMapping() + { + var mock = NewMock(); + StubCatalog(mock, "842", "13"); + StubHappyOrderPlacement(mock, "ord_email_003"); + + var plugin = BuildV2Plugin(mock.Object, emailNotifications: " 1 "); + + var (result, captured) = await RunEnrollAsync(mock, plugin, "ord_email_003"); + + result.CARequestID.Should().Be("ord_email_003"); + captured!.EmailNotifications.Should().Be("all", + "surrounding whitespace must be trimmed before comparing against \"1\"/\"0\""); + } + + // --------------------------------------------------------------------------- + // EnrollV2Async wiring — blank/unset omits the field entirely + // --------------------------------------------------------------------------- + + [Theory] + [InlineData(null)] + [InlineData("")] + [InlineData(" ")] + public async Task Enroll_V2_EmailNotifications_Blank_OmitsField(string configValue) + { + var mock = NewMock(); + StubCatalog(mock, "842", "13"); + StubHappyOrderPlacement(mock, "ord_email_004"); + + var plugin = BuildV2Plugin(mock.Object, emailNotifications: configValue); + + var (result, captured) = await RunEnrollAsync(mock, plugin, "ord_email_004"); + + result.CARequestID.Should().Be("ord_email_004"); + captured!.EmailNotifications.Should().BeNull( + "a blank/unset EmailNotifications must leave the field null so it is omitted on the " + + "wire and the CA's own default (\"all\") applies"); + } + + [Fact] + public void V2CreateSslOrderRequest_Serialization_OmitsEmailNotifications_WhenNull() + { + var request = new V2CreateSslOrderRequest + { + ProductVariant = "dv", + EmailNotifications = null, + Certificate = new V2CertificateParams { Domain = "example.com" } + }; + + string json = JsonSerializer.Serialize(request, ClientEquivalentJsonOptions()); + + json.Should().NotContain("emailNotifications", + "the emailNotifications key itself must be absent when unset, not present-but-null, " + + "under the client's actual serializer options"); + } + + [Fact] + public void V2CreateSslOrderRequest_Serialization_IncludesEmailNotifications_WhenSet() + { + var request = new V2CreateSslOrderRequest + { + ProductVariant = "dv", + EmailNotifications = "consent-only", + Certificate = new V2CertificateParams { Domain = "example.com" } + }; + + string json = JsonSerializer.Serialize(request, ClientEquivalentJsonOptions()); + + json.Should().Contain("\"emailNotifications\":\"consent-only\""); + } + + // Mirrors the client's actual GetJsonOptions() (private) — see + // V2SubscriptionEnrollmentTests.ClientEquivalentJsonOptions for the same rationale: plain + // JsonSerializer.Serialize(req) without these options would show "emailNotifications":null + // instead of omitting the key. + private static JsonSerializerOptions ClientEquivalentJsonOptions() => new JsonSerializerOptions + { + PropertyNameCaseInsensitive = true, + DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull + }; + + // --------------------------------------------------------------------------- + // EnrollV2Async — invalid EmailNotifications fails fast, before any CA call + // --------------------------------------------------------------------------- + + [Theory] + [InlineData("all")] // deliberately invalid: the user's mapping only accepts "0"/"1"/blank, + // even though "all" is the CA's own wire value for "1" — an admin + // must not be able to bypass the mapping by writing the CA's literal. + [InlineData("yes")] + [InlineData("2")] + public async Task Enroll_V2_EmailNotifications_Invalid_FailsEnrollment_NoHttpCallMade(string configValue) + { + // Strict mock with NO setups at all: if EnrollV2Async made any client call before + // failing validation, Moq would throw a MockException for the unstubbed invocation + // and this test would fail — that, plus the explicit Verify(Times.Never) calls below, + // together confirm zero HTTP requests are sent for an invalid config value. + var mock = NewMock(); + + var plugin = BuildV2Plugin(mock.Object, emailNotifications: configValue); + + var result = await plugin.Enroll( + csr: GenerateCsrPem("example.com"), + subject: "CN=example.com", + san: null, + productInfo: MakeV2ProductInfo("842", "dv"), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.Status.Should().Be((int)EndEntityStatus.FAILED); + result.StatusMessage.Should().Contain("EmailNotifications", + "the failure message must name the offending config field"); + + mock.Verify(c => c.GetProductDetailsV2Async(It.IsAny()), Times.Never); + mock.Verify(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny()), Times.Never); + } + } +} diff --git a/CERTInext.Tests/EnrollmentParamsTests.cs b/CERTInext.Tests/EnrollmentParamsTests.cs new file mode 100644 index 0000000..9fa52e9 --- /dev/null +++ b/CERTInext.Tests/EnrollmentParamsTests.cs @@ -0,0 +1,102 @@ +// Copyright 2026 Keyfactor +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System.Collections.Generic; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.Models; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Coverage for 's V1-only fallback + /// (): only V1 dispatch uses it; V2 + /// dispatch (EnrollV2Async / ValidateProductInfo) does not. These tests exercise directly (it is + /// internal; this project has InternalsVisibleTo access) so the V1-unaffected + /// claim is pinned at the unit that both V1 and V2 share, not just re-derived from other + /// tests continuing to pass. + /// + public class EnrollmentParamsTests + { + private static EnrollmentProductInfo MakeProductInfo(string productId, Dictionary parameters = null) => + new EnrollmentProductInfo + { + ProductID = productId, + ProductParameters = parameters ?? new Dictionary() + }; + + [Fact] + public void ProductCode_NoOverride_FallsBackToV1DefaultProductCodesTable_Unchanged() + { + // This is the V1 path's fallback: V1 dispatch + // (EnrollNewAsync/RenewOrReissueAsync) relies on this exact value. + var ep = new EnrollmentParams(MakeProductInfo(Constants.Products.OvSsl)); + + ep.HasExplicitProductCode.Should().BeFalse(); + ep.ProductCode.Should().Be(Constants.Products.DefaultProductCodes[Constants.Products.OvSsl]); + ep.ProductCode.Should().Be("842", "the V1-era table value must not change as part of the V2 fix"); + ep.ProfileId.Should().Be(ep.ProductCode, "ProfileId remains a pure alias for ProductCode"); + } + + [Theory] + [InlineData(Constants.EnrollmentParam.ProductCode)] + [InlineData(Constants.EnrollmentParam.ProfileId)] + public void ProductCode_ExplicitOverride_TakesPrecedenceOverDefaultTable(string parameterKey) + { + var ep = new EnrollmentParams(MakeProductInfo( + Constants.Products.OvSsl, + new Dictionary { [parameterKey] = "999" })); + + ep.HasExplicitProductCode.Should().BeTrue(); + ep.ProductCode.Should().Be("999"); + } + + [Fact] + public void HasExplicitProductCode_False_ForEveryDefaultProductCodesEntry_MatchesV1FallbackBehavior() + { + // Sanity sweep across all 10 V1 product names: with no override, every one of them + // must report HasExplicitProductCode=false and resolve to the exact + // DefaultProductCodes value — proving the shared getter's V1 behavior is bit-for-bit + // unchanged by the V2 fix. + foreach (var kvp in Constants.Products.DefaultProductCodes) + { + var ep = new EnrollmentParams(MakeProductInfo(kvp.Key)); + + ep.HasExplicitProductCode.Should().BeFalse($"ProductId '{kvp.Key}' has no override configured"); + ep.ProductCode.Should().Be(kvp.Value, $"ProductId '{kvp.Key}' must still resolve via the V1 table"); + } + } + + // Private-pki validation must tell "ProductVariant not set" apart from an + // explicit value, because the getter's SSL-only "dv" default masks the difference. + [Theory] + [InlineData(null, false, "dv")] + [InlineData("", false, "dv")] + [InlineData(" ", false, "dv")] + [InlineData("dv", true, "dv")] + [InlineData(" intranet-ssl ", true, "intranet-ssl")] + public void HasExplicitProductVariant_DistinguishesUnsetFromExplicit(string configured, bool expectedExplicit, string expectedVariant) + { + var parameters = new Dictionary(); + if (configured != null) + parameters[Constants.EnrollmentParam.ProductVariant] = configured; + + var ep = new EnrollmentParams(MakeProductInfo(Constants.Products.DvSsl, parameters)); + + ep.HasExplicitProductVariant.Should().Be(expectedExplicit); + ep.ProductVariant.Should().Be(expectedVariant, "the ProductVariant getter's own default is unchanged"); + } + } +} diff --git a/CERTInext.Tests/ExtractErrorMessageTests.cs b/CERTInext.Tests/ExtractErrorMessageTests.cs new file mode 100644 index 0000000..5b9daac --- /dev/null +++ b/CERTInext.Tests/ExtractErrorMessageTests.cs @@ -0,0 +1,81 @@ +// Copyright 2026 Keyfactor +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using FluentAssertions; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Parser-level coverage for CERTInextClient.ExtractErrorMessage, which + /// builds the V1 non-success exception message. + /// + public class ExtractErrorMessageTests + { + private const string Op = "list orders page 1"; + + [Fact] + public void LiveSpringNotFoundBody_WithStatus_ReturnsGenericMessageWithHttpStatus() + { + CERTInextClient.ExtractErrorMessage(V1NonSuccessResponseTests.LiveSpringNotFoundBody, Op, 404) + .Should().Be("CERTInext returned an unrecognised error body (HTTP 404) for operation 'list orders page 1'. " + + "See gateway logs for details."); + } + + [Fact] + public void LiveSpringNotFoundBody_WithoutStatus_KeepsPreviousMessage() + { + // RevokeOrderAsync still calls the two-argument form; its message must not change. + CERTInextClient.ExtractErrorMessage(V1NonSuccessResponseTests.LiveSpringNotFoundBody, Op) + .Should().Be("CERTInext returned an unrecognised error body for operation 'list orders page 1'. " + + "See gateway logs for details."); + } + + [Theory] + [InlineData("Bad Gateway")] + [InlineData("[]")] + public void NonEnvelopeBody_WithStatus_ReturnsGenericMessageWithHttpStatus(string body) + { + CERTInextClient.ExtractErrorMessage(body, Op, 502) + .Should().StartWith("CERTInext returned an unrecognised error body (HTTP 502) for operation"); + } + + [Fact] + public void MetaEnvelope_WithStatus_IncludesStatusAndCaError() + { + const string body = "{\"meta\":{\"status\":\"0\",\"errorCode\":\"EMS-913\",\"errorMessage\":\"Invalid Account Number\"}}"; + + CERTInextClient.ExtractErrorMessage(body, Op, 500) + .Should().Be("CERTInext error during 'list orders page 1' (HTTP 500): Invalid Account Number [EMS-913]"); + } + + [Fact] + public void LegacyMessageBody_WithStatus_IncludesStatusAndMessage() + { + CERTInextClient.ExtractErrorMessage("{\"message\":\"Service Unavailable\"}", Op, 503) + .Should().Be("CERTInext error during 'list orders page 1' (HTTP 503): Service Unavailable"); + } + + [Theory] + [InlineData(null)] + [InlineData("")] + [InlineData(" ")] + public void EmptyBody_WithStatus_IncludesStatus(string body) + { + CERTInextClient.ExtractErrorMessage(body, Op, 404) + .Should().Be("CERTInext returned no body (HTTP 404) for operation 'list orders page 1'."); + } + } +} diff --git a/CERTInext.Tests/ExtractSerialFromPemTests.cs b/CERTInext.Tests/ExtractSerialFromPemTests.cs index f8064dd..d5daa8b 100644 --- a/CERTInext.Tests/ExtractSerialFromPemTests.cs +++ b/CERTInext.Tests/ExtractSerialFromPemTests.cs @@ -127,5 +127,59 @@ public void ExtractSerialFromPem_EmptyBody_ReturnsEmptyPem() InvokeExtractSerialFromPem("-----BEGIN CERTIFICATE-----\n-----END CERTIFICATE-----") .Should().Be("(empty-pem)"); } + + /// + /// Functional coverage for the minimal chain-PEM shape (acceptance criterion: "leaf + + /// intermediate chain PEM -> the leaf's serial"), built the same way V2 enroll/sync + /// assemble it (AssembleV2CertChain: leaf PEM, then each intermediate PEM + /// appended after a newline, each block keeping its own BEGIN/END markers and base64 + /// padding). Whether a specific 2-block combination exercises the base64 + /// padding path depends on the leaf's DER byte length modulo 3 (whether its base64 + /// body needs '=' padding) — see + /// + /// for the three-block (ChainPemCount=2) chain. Both must return the leaf's serial, + /// never the intermediate's. + /// + [Fact] + public void ExtractSerialFromPem_LeafPlusIntermediateChainPem_ReturnsLeafSerial() + { + var leafSerial = new BigInteger("7994334872", 10); + var intermediateSerial = new BigInteger("00E0353B0E133906D77D5137E5E5D6A1", 16); + + string leafPem = GeneratePemWithSerial(leafSerial); + string intermediatePem = GeneratePemWithSerial(intermediateSerial); + + // Mirrors CERTInextCAPlugin.AssembleV2CertChain: leaf.TrimEnd() + "\n" + intermediate.TrimEnd(). + string chainPem = leafPem.TrimEnd() + "\n" + intermediatePem.TrimEnd(); + + string result = InvokeExtractSerialFromPem(chainPem); + + result.Should().Be(Convert.ToHexString(leafSerial.ToByteArrayUnsigned()).ToUpperInvariant(), + "the audit log must report the leaf certificate's serial, matching what Command records"); + result.Should().NotBe(Convert.ToHexString(intermediateSerial.ToByteArrayUnsigned()).ToUpperInvariant(), + "the intermediate's serial must never be mistaken for the leaf's"); + } + + /// + /// Leaf + two intermediates (three PEM blocks total, ChainPemCount=2): the leaf's + /// serial must be extracted rather than "(parse-error)", and never an intermediate's. + /// + [Fact] + public void ExtractSerialFromPem_LeafPlusTwoIntermediatesChainPem_ReturnsLeafSerial() + { + var leafSerial = new BigInteger("9817499991", 10); + var intermediateSerial1 = new BigInteger("00FEABDFF1B29657D9AF75ABC6CDCAAE", 16); + var intermediateSerial2 = new BigInteger("DEADBEEF", 16); + + string leafPem = GeneratePemWithSerial(leafSerial); + string intermediatePem1 = GeneratePemWithSerial(intermediateSerial1); + string intermediatePem2 = GeneratePemWithSerial(intermediateSerial2); + + string chainPem = leafPem.TrimEnd() + "\n" + intermediatePem1.TrimEnd() + "\n" + intermediatePem2.TrimEnd(); + + string result = InvokeExtractSerialFromPem(chainPem); + + result.Should().Be(Convert.ToHexString(leafSerial.ToByteArrayUnsigned()).ToUpperInvariant()); + } } } diff --git a/CERTInext.Tests/FakeDomainValidator.cs b/CERTInext.Tests/FakeDomainValidator.cs index 6b42475..73aaef4 100644 --- a/CERTInext.Tests/FakeDomainValidator.cs +++ b/CERTInext.Tests/FakeDomainValidator.cs @@ -2,6 +2,7 @@ // Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. // At http://www.apache.org/licenses/LICENSE-2.0 +using System; using System.Collections.Generic; using System.Threading; using System.Threading.Tasks; @@ -21,10 +22,20 @@ internal sealed class FakeDomainValidator : IDomainValidator /// All keys passed to . public List CleanedUpKeys { get; } = new(); + /// All CancellationTokens passed to . + public List CleanupTokens { get; } = new(); + /// When false, returns a failure result. public bool StageSucceeds { get; init; } = true; - /// Error message returned when is false. + /// + /// When set, overrides on a per-key basis — e.g. + /// key => key.Contains("bad", StringComparison.OrdinalIgnoreCase) to fail only a + /// specific hostname in a multi-domain test while the others still stage successfully. + /// + public Func ShouldFail { get; init; } + + /// Error message returned when a StageValidation call fails. public string StageError { get; init; } = "Stage failed (test stub)"; public void Initialize(IDomainValidatorConfigProvider configProvider) { } @@ -32,18 +43,67 @@ public void Initialize(IDomainValidatorConfigProvider configProvider) { } public Task StageValidation(string key, string value, CancellationToken cancellationToken) { cancellationToken.ThrowIfCancellationRequested(); - StagedRecords.Add((key, value)); + bool fail = ShouldFail?.Invoke(key) ?? !StageSucceeds; + if (!fail) + StagedRecords.Add((key, value)); + return Task.FromResult(new DomainValidationResult { - Success = StageSucceeds, - ErrorMessage = StageSucceeds ? null : StageError + Success = !fail, + ErrorMessage = fail ? StageError : null }); } - public Task CleanupValidation(string key, CancellationToken cancellationToken) + /// + /// Artificial delay applied inside before completing — lets + /// tests distinguish "cleanup calls run concurrently" (wall time ~= one delay) from + /// "cleanup calls run sequentially" (wall time ~= N x delay). + /// + public TimeSpan CleanupDelay { get; init; } = TimeSpan.Zero; + + // Cleanup calls can genuinely run concurrently (that's what CleanupDelay exists to prove), + // so the two List fields below need a lock — unlike StagedRecords above, which only ever + // sees synchronously-completing calls in practice. + private readonly object _cleanupLock = new(); + + // Tracks how many CleanupValidation calls were in flight (past the increment below, + // still inside CleanupDelay) at the same time. This is the direct, wall-clock-independent + // proof that cleanup ran concurrently rather than sequentially — see + // Dcv_CleanupOfMultipleDomains_RunsConcurrently_NotSequentially, which asserts on this + // instead of total elapsed time (elapsed time also includes fixed overhead from the + // surrounding DCV flow — propagation delay + verification poll interval — unrelated to + // cleanup concurrency, which made a wall-clock threshold an unreliable proxy). + private int _inFlightCleanups; + + /// + /// The maximum number of calls observed executing + /// concurrently (i.e. inside the artificial ) at once. + /// + public int PeakConcurrentCleanups { get; private set; } + + public async Task CleanupValidation(string key, CancellationToken cancellationToken) { - CleanedUpKeys.Add(key); - return Task.FromResult(new DomainValidationResult { Success = true }); + int inFlight = Interlocked.Increment(ref _inFlightCleanups); + lock (_cleanupLock) + { + if (inFlight > PeakConcurrentCleanups) + PeakConcurrentCleanups = inFlight; + } + try + { + if (CleanupDelay > TimeSpan.Zero) + await Task.Delay(CleanupDelay, cancellationToken); + } + finally + { + Interlocked.Decrement(ref _inFlightCleanups); + } + lock (_cleanupLock) + { + CleanedUpKeys.Add(key); + CleanupTokens.Add(cancellationToken); + } + return new DomainValidationResult { Success = true }; } public Task ValidateConfiguration(Dictionary configuration) => Task.CompletedTask; @@ -53,15 +113,24 @@ public Task CleanupValidation(string key, CancellationTo /// /// Factory that returns a single pre-configured for every - /// domain. Pass null as the validator to simulate "no DNS provider configured". + /// domain, or only for if set. Pass null as the + /// validator to simulate "no DNS provider configured". /// internal sealed class FakeDomainValidatorFactory : IDomainValidatorFactory { private readonly IDomainValidator _validator; + private readonly string _resolvableDomain; - public FakeDomainValidatorFactory(IDomainValidator validator = null) => _validator = validator; + public FakeDomainValidatorFactory(IDomainValidator validator = null, string resolvableDomain = null) + { + _validator = validator; + _resolvableDomain = resolvableDomain; + } - public IDomainValidator ResolveDomainValidator(string domain, string validationType) => _validator; + public IDomainValidator ResolveDomainValidator(string domain, string validationType) => + (_resolvableDomain == null || string.Equals(domain, _resolvableDomain, StringComparison.OrdinalIgnoreCase)) + ? _validator + : null; /// The validator this factory returns; exposed for assertions in tests. public IDomainValidator PrimaryValidator => _validator; diff --git a/CERTInext.Tests/IncrementalSyncUnchangedTests.cs b/CERTInext.Tests/IncrementalSyncUnchangedTests.cs new file mode 100644 index 0000000..6f4f3e5 --- /dev/null +++ b/CERTInext.Tests/IncrementalSyncUnchangedTests.cs @@ -0,0 +1,214 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Linq; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Moq; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Issue 0093: the V1 order listing filters by calendar day, so every incremental pass + /// re-lists every order placed that day. An issued or revoked order the gateway already holds + /// with the same status and a stored body must not be refetched (TrackOrder + + /// DownloadCertificate) or re-emitted on an incremental pass. Anything new, changed, body-less + /// or unverifiable is processed as before, and full sync is unaffected. + /// + public class IncrementalSyncUnchangedTests + { + private const string Id = MockCertificateData.CertId1; + private static readonly DateTime LastSync = new DateTime(2026, 11, 10, 10, 20, 0, DateTimeKind.Utc); + + /// An order as the listing returns it: status and metadata, never a body. + private static LegacyGetCertificateResponse Listed(string status) => + new LegacyGetCertificateResponse + { + Id = Id, + Status = status, + Certificate = null, + Subject = "test.example.com", + ProfileId = MockCertificateData.ProfileIdTls + }; + + private static async IAsyncEnumerable AsyncEnum( + IEnumerable items) + { + foreach (var item in items) + { + yield return item; + await Task.Yield(); + } + } + + private static Mock Client(LegacyGetCertificateResponse listed, + LegacyGetCertificateResponse refetched) + { + var mock = new Mock(MockBehavior.Loose); + mock.Setup(c => c.ListCertificatesAsync( + It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(AsyncEnum(new[] { listed })); + mock.Setup(c => c.GetCertificateAsync(Id, It.IsAny())) + .ReturnsAsync(refetched); + return mock; + } + + private static async Task> RunSync( + ICERTInextClient client, ICertificateDataReader reader, bool fullSync = false) + { + var plugin = new CERTInextCAPlugin(client, reader, new CERTInextConfig()); + var buffer = new BlockingCollection(10); + await plugin.Synchronize(buffer, lastSync: fullSync ? (DateTime?)null : LastSync, + fullSync: fullSync, cancelToken: CancellationToken.None); + return buffer.ToList(); + } + + private static Mock Reader(int dbStatus, DateTime? storedExpiry) + { + var reader = new Mock(MockBehavior.Strict); + reader.Setup(r => r.GetStatusByRequestID(Id)).ReturnsAsync(dbStatus); + reader.Setup(r => r.GetExpirationDateByRequestId(Id)).Returns(storedExpiry); + return reader; + } + + [Fact] + public async Task Incremental_IssuedAndHeldUnchanged_IsNotRefetchedOrEmitted() + { + var client = Client(Listed("issued"), MockCertificateData.IssuedCertRecord(Id)); + var reader = Reader((int)EndEntityStatus.GENERATED, new DateTime(2027, 1, 1)); + + var results = await RunSync(client.Object, reader.Object); + + results.Should().BeEmpty("the gateway already holds this certificate as-is"); + client.Verify(c => c.GetCertificateAsync(It.IsAny(), It.IsAny()), Times.Never); + } + + [Fact] + public async Task Incremental_RevokedAndHeldAsRevoked_IsNotRefetchedOrEmitted() + { + var client = Client(Listed("revoked"), MockCertificateData.RevokedCertRecord(Id)); + var reader = Reader((int)EndEntityStatus.REVOKED, new DateTime(2027, 1, 1)); + + var results = await RunSync(client.Object, reader.Object); + + results.Should().BeEmpty(); + client.Verify(c => c.GetCertificateAsync(It.IsAny(), It.IsAny()), Times.Never); + } + + [Fact] + public async Task Incremental_NewOrder_IsRefetchedAndEmitted() + { + var client = Client(Listed("issued"), MockCertificateData.IssuedCertRecord(Id)); + var reader = new Mock(MockBehavior.Strict); + reader.Setup(r => r.GetStatusByRequestID(Id)).ThrowsAsync(new ArgumentException("no row")); + + var results = await RunSync(client.Object, reader.Object); + + results.Should().ContainSingle(); + results[0].Status.Should().Be((int)EndEntityStatus.GENERATED); + results[0].Certificate.Should().NotBeNullOrWhiteSpace(); + } + + [Fact] + public async Task Incremental_StatusChangedIssuedToRevoked_IsRefetchedAndEmitted() + { + var client = Client(Listed("revoked"), MockCertificateData.RevokedCertRecord(Id)); + var reader = Reader((int)EndEntityStatus.GENERATED, new DateTime(2027, 1, 1)); + + var results = await RunSync(client.Object, reader.Object); + + results.Should().ContainSingle("an out-of-band revoke must still propagate"); + results[0].Status.Should().Be((int)EndEntityStatus.REVOKED); + client.Verify(c => c.GetCertificateAsync(Id, It.IsAny()), Times.Once); + } + + [Fact] + public async Task Incremental_StatusChangedPendingToIssued_IsRefetchedAndEmitted() + { + var client = Client(Listed("issued"), MockCertificateData.IssuedCertRecord(Id)); + var reader = Reader((int)EndEntityStatus.EXTERNALVALIDATION, null); + + var results = await RunSync(client.Object, reader.Object); + + results.Should().ContainSingle("a DV order that issued after its first pass must be imported"); + results[0].Status.Should().Be((int)EndEntityStatus.GENERATED); + results[0].Certificate.Should().NotBeNullOrWhiteSpace(); + } + + [Fact] + public async Task Incremental_HeldWithoutBody_IsRefetchedAndEmitted() + { + var client = Client(Listed("issued"), MockCertificateData.IssuedCertRecord(Id)); + var reader = Reader((int)EndEntityStatus.GENERATED, null); + + var results = await RunSync(client.Object, reader.Object); + + results.Should().ContainSingle("a row whose earlier refetch failed must get its body"); + results[0].Certificate.Should().NotBeNullOrWhiteSpace(); + } + + [Fact] + public async Task Incremental_ReaderFails_IsProcessedAsBefore() + { + var client = Client(Listed("issued"), MockCertificateData.IssuedCertRecord(Id)); + var reader = new Mock(MockBehavior.Strict); + reader.Setup(r => r.GetStatusByRequestID(Id)).ThrowsAsync(new InvalidOperationException("db down")); + + var results = await RunSync(client.Object, reader.Object); + + results.Should().ContainSingle(); + results[0].Status.Should().Be((int)EndEntityStatus.GENERATED); + } + + [Fact] + public async Task Incremental_NoReaderInjected_IsProcessedAsBefore() + { + var client = Client(Listed("issued"), MockCertificateData.IssuedCertRecord(Id)); + + var results = await RunSync(client.Object, reader: null); + + results.Should().ContainSingle(); + results[0].Status.Should().Be((int)EndEntityStatus.GENERATED); + } + + [Fact] + public async Task Incremental_PendingOrder_DoesNotConsultReader() + { + // Strict mock with no setups: any reader call fails the test. + var client = Client(MockCertificateData.PendingCertRecord(Id), MockCertificateData.PendingCertRecord(Id)); + var reader = new Mock(MockBehavior.Strict); + + var results = await RunSync(client.Object, reader.Object); + + results.Should().ContainSingle(); + results[0].Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + } + + [Fact] + public async Task FullSync_HeldUnchanged_IsStillRefetchedAndEmitted() + { + // Strict mock with no setups: full sync must not consult the reader for issued orders. + var client = Client(Listed("issued"), MockCertificateData.IssuedCertRecord(Id)); + var reader = new Mock(MockBehavior.Strict); + + var results = await RunSync(client.Object, reader.Object, fullSync: true); + + results.Should().ContainSingle(); + results[0].Certificate.Should().NotBeNullOrWhiteSpace(); + client.Verify(c => c.GetCertificateAsync(Id, It.IsAny()), Times.Once); + } + } +} diff --git a/CERTInext.Tests/LoggingStateCollection.cs b/CERTInext.Tests/LoggingStateCollection.cs new file mode 100644 index 0000000..9f14c32 --- /dev/null +++ b/CERTInext.Tests/LoggingStateCollection.cs @@ -0,0 +1,30 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// The single xUnit collection for every test that mutates or asserts on process-global logger + /// state: the static CERTInextClient.OverrideLoggerForTests logger and + /// LogHandler.Factory (finding #15). + /// + /// DisableParallelization = true makes xUnit run this collection by itself, after the + /// parallel collections have finished, so no other test (in this collection or outside it) can + /// log into a swapped logger while a capture is active. Without it, captured-log assertions + /// (must-not-contain, exact counts) could pick up entries from unrelated tests and flake. + /// + /// Any new test class that swaps either logger, or asserts on captured log lines, MUST carry + /// [Collection(LoggingStateCollection.Name)]. + /// + [CollectionDefinition(Name, DisableParallelization = true)] + public sealed class LoggingStateCollection + { + public const string Name = "GlobalLoggerState-NoParallel"; + } +} diff --git a/CERTInext.Tests/MaskEmailTests.cs b/CERTInext.Tests/MaskEmailTests.cs new file mode 100644 index 0000000..7a14d48 --- /dev/null +++ b/CERTInext.Tests/MaskEmailTests.cs @@ -0,0 +1,54 @@ +// Copyright 2026 Keyfactor +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using FluentAssertions; +using Keyfactor.Extensions.CAPlugin.CERTInext.Models; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// is the shared email-masking helper used + /// by both CERTInextCAPlugin (the enrollment-attempt Information log line) and + /// Client.CERTInextClient (RedactPersonalData) when LogSensitiveRequestData + /// is off. + /// + public class MaskEmailTests + { + [Theory] + [InlineData("jane.doe@example.com", "j***@example.com")] + [InlineData("a@b.co", "a***@b.co")] + [InlineData("Jane.Doe@Example.COM", "J***@Example.COM")] + public void MaskEmail_KeepsFirstCharacterAndDomain(string input, string expected) + { + LogSanitizer.MaskEmail(input).Should().Be(expected); + } + + [Theory] + [InlineData(null)] + [InlineData("")] + public void MaskEmail_HandlesNullAndEmpty(string input) + { + LogSanitizer.MaskEmail(input).Should().Be(input); + } + + [Theory] + [InlineData("not-an-email")] + [InlineData("@example.com")] + public void MaskEmail_NoUsableLocalPart_FallsBackToFullRedaction(string input) + { + LogSanitizer.MaskEmail(input).Should().Be("***REDACTED***"); + } + } +} diff --git a/CERTInext.Tests/MockCertificateData.cs b/CERTInext.Tests/MockCertificateData.cs index ee6644b..dcd5fc4 100644 --- a/CERTInext.Tests/MockCertificateData.cs +++ b/CERTInext.Tests/MockCertificateData.cs @@ -1,4 +1,4 @@ -// Copyright 2024 Keyfactor +// Copyright 2026 Keyfactor // Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. // You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 // Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, @@ -232,6 +232,45 @@ public static string GetProductDetailsJson() => public static string GetProductDetailsEmptyJson() => $@"{{""meta"":{SuccessMetaJson()},""productDetails"":[]}}"; + // GET /api/certinext/v2/catalog/products — nested category envelope, the shape + // returned by the sandbox account. Same structure as the V1 GetProductDetails + // category envelope, just under a + // top-level "products" key instead of "productDetails". + public static string GetCatalogProductsV2NestedJson() => + $@"{{ + ""products"":[ + {{ + ""currencyType"":""USD"", + ""categoryName"":""SSL/TLS Certificates"", + ""categoryID"":""3"", + ""products"":[ + {{""productCode"":""{ProfileIdTls}"",""productName"":""TLS Server"",""productTypeID"":""13""}}, + {{""productCode"":""{ProfileIdClient}"",""productName"":""Client Authentication"",""productTypeID"":""14""}} + ] + }} + ] +}}"; + + // Flat shape from the spec's "List Products" example response — kept as a + // fallback branch in the parser even though the live account returns the nested shape. + public static string GetCatalogProductsV2FlatJson() => + $@"{{ + ""products"":[ + {{""productId"":""{ProfileIdTls}"",""productName"":""TLS Server"",""masterProductName"":""TLS Server""}}, + {{""productId"":""{ProfileIdClient}"",""productName"":""Client Authentication"",""masterProductName"":""Client Authentication""}} + ] +}}"; + + // Bare-array shape (no wrapper object) — legacy branch already handled by + // ParseProductDetailsV2Response. + public static string GetCatalogProductsV2BareArrayJson() => + $@"[ + {{""productCode"":""{ProfileIdTls}"",""productName"":""TLS Server"",""productType"":""SSL/TLS Certificates"",""active"":true}} +]"; + + public static string GetCatalogProductsV2EmptyJson() => + $@"{{""products"":[]}}"; + // Generic API failure body (meta.status = "0") public static string ApiFailureJson(string errorCode = "EMS-100", string errorMessage = "An error occurred") => $@"{{""meta"":{FailureMetaJson(errorCode, errorMessage)}}}"; @@ -294,6 +333,20 @@ public static EnrollCertificateResponse PendingEnrollResponse(string id = null) Message = "Awaiting approval." }; + // Reproduces the CERTInext "auto-approved" race: TrackOrder reports a + // certificateStatusId the client legacy-maps to "issued", but the immediate + // GetCertificate download failed (cert bytes not generated yet), so no PEM + // ever arrived. + public static EnrollCertificateResponse AutoApprovedNoBodyEnrollResponse(string id = null) => + new EnrollCertificateResponse + { + Id = id ?? CertId1, + Status = "issued", + Certificate = null, + ProfileId = ProfileIdTls, + Message = "Order auto-approved." + }; + // ----------------------------------------------------------------------- // GetCertificate response (object helpers — used by Moq-based plugin tests) // These use the legacy inferred type (LegacyGetCertificateResponse). @@ -478,6 +531,104 @@ public static string ServerErrorJson() => public static string UnauthorizedJson() => @"{""error"":""UNAUTHORIZED"",""message"":""Invalid API key."",""statusCode"":401}"; + // ----------------------------------------------------------------------- + // V2 API JSON factories + // ----------------------------------------------------------------------- + + // V2 well-known order IDs + public const string V2OrderId1 = "ord_abc001"; + public const string V2OrderId2 = "ord_abc002"; + + /// Standard OAuth2 client_credentials token response. + public static string V2TokenResponseJson(int expiresIn = 3600) => + $@"{{""access_token"":""eyJhbGciOiJSUzI1NiJ9.test-token"",""token_type"":""Bearer"",""expires_in"":{expiresIn},""refresh_token"":""refresh-opaque-token""}}"; + + /// V2 create order response (status = pending-dcv). + public static string V2CreateOrderPendingJson(string orderId = "ord_abc001") => + $@"{{""orderId"":""{orderId}"",""requestId"":""req_xyz001"",""status"":""pending-dcv"",""_links"":{{""self"":{{""href"":""/api/certinext/v2/ssl-certificates/{orderId}""}}}}}}"; + + /// V2 create order response (status = issued — unlikely on fresh order but usable for testing). + public static string V2CreateOrderIssuedJson(string orderId = "ord_abc001") => + $@"{{""orderId"":""{orderId}"",""requestId"":""req_xyz001"",""status"":""issued"",""_links"":{{""self"":{{""href"":""/api/certinext/v2/ssl-certificates/{orderId}""}}}}}}"; + + /// V2 track order response — pending DCV. + public static string V2TrackOrderPendingJson(string orderId = "ord_abc001") => + $@"{{""orderId"":""{orderId}"",""requestId"":""req_xyz001"",""status"":""pending-dcv"",""productVariant"":""dv"",""domain"":""example.com"",""_links"":{{""self"":{{""href"":""/api/certinext/v2/ssl-certificates/{orderId}""}}}}}}"; + + /// V2 track order response — issued. + public static string V2TrackOrderIssuedJson(string orderId = "ord_abc001") => + $@"{{""orderId"":""{orderId}"",""requestId"":""req_xyz001"",""status"":""issued"",""productVariant"":""dv"",""domain"":""example.com"",""_links"":{{""certificate"":{{""href"":""/api/certinext/v2/ssl-certificates/{orderId}/certificate""}}}}}}"; + + /// + /// V2 track order response — revoked. Nested revocation object shape, as seen + /// against a real revoked order — NOT the flat + /// revocationReason/revocationDate shape. + /// + public static string V2TrackOrderRevokedJson( + string orderId = "ord_abc001", + string reason = "cessation-of-operation", + string processedAt = "2026-09-24T20:44:41Z") => + $@"{{""orderId"":""{orderId}"",""requestId"":""req_xyz001"",""status"":""revoked"",""productVariant"":""dv"",""domain"":""example.com"",""revocation"":{{""status"":""Certificate Revoked"",""reason"":""{reason}"",""processedAt"":""{processedAt}""}},""_links"":{{}}}}"; + + /// V2 certificate download response (leaf PEM only). + public static string V2CertificateDownloadJson(string orderId = "ord_abc001") => + $@"{{""orderId"":""{orderId}"",""serialNumber"":""0A1B2C3D4E5F"",""subject"":""CN=example.com"",""issuer"":""CN=CERTInext TLS Intermediate"",""notBefore"":""2026-01-01T00:00:00Z"",""notAfter"":""2027-01-01T00:00:00Z"",""certificatePem"":""{EscapeForJson(FakePemCertificate)}""}}"; + + /// V2 auth/me response. + public static string V2AuthMeJson(string accountNumber = "99887766") => + $@"{{""accountNumber"":""{accountNumber}"",""authType"":""oauth2""}}"; + + /// RFC 7807 problem+json error response. + public static string V2ProblemDetailsJson(int status = 403, string title = "Forbidden", string detail = "OAuth2 not enabled", string type = "EMS-2022") => + $@"{{""type"":""{type}"",""title"":""{title}"",""status"":{status},""detail"":""{detail}"",""instance"":null}}"; + + /// + /// V2 DCV challenge response. Matches the real wire shape: exactly token and + /// tokenExpiryDate — no + /// orderNumber/domainName/dcvMethod/fileNameContent. + /// + public static string V2DcvChallengeJson(string token = "emudhra-dcv-abc123", string tokenExpiryDate = "2026-12-31 23:59:59") => + $@"{{""tokenExpiryDate"":""{tokenExpiryDate}"",""token"":""{token}""}}"; + + /// V2 DCV verify response (success). + public static string V2DcvVerifySuccessJson(string domain = "example.com") => + $@"{{""overallStatus"":""VERIFIED"",""method"":""dns-txt"",""verifiedAt"":""2026-09-21T10:00:00Z""}}"; + + /// V2 DCV verify response (failure). + public static string V2DcvVerifyFailedJson() => + $@"{{""overallStatus"":""FAILED"",""method"":""dns-txt"",""verifiedAt"":null}}"; + + /// V2 certificate download response with chain PEM. + public static string V2CertificateDownloadWithChainJson(string orderId = "ord_abc001") => + $@"{{""orderId"":""{orderId}"",""serialNumber"":""0A1B2C3D4E5F"",""subject"":""CN=example.com"",""issuer"":""CN=CERTInext TLS Intermediate"",""notBefore"":""2026-01-01T00:00:00Z"",""notAfter"":""2027-01-01T00:00:00Z"",""certificatePem"":""{EscapeForJson(FakePemCertificate)}"",""chainPem"":[""{EscapeForJson(FakeIntermediatePemCertificate)}""]}}"; + + public static readonly string FakeIntermediatePemCertificate = + "-----BEGIN CERTIFICATE-----\nMIIBfakeBASE64INTERMEDIATE==\n-----END CERTIFICATE-----"; + + /// + /// V2 /reports/orders page envelope. Rows default to a + /// pending-DCV-shaped display-string pair ("Order Accepted" / "Pending for Approver") — + /// override / for other + /// scenarios. Field names match the live field table. + /// + public static string V2OrdersReportJson( + int page, int totalPages, string[] orderNumbers, + int size = 50, long? totalElements = null, + string orderStatus = "Order Accepted", string certificateStatus = "Pending for Approver") + { + var rows = new List(); + foreach (string id in orderNumbers) + { + rows.Add( + $@"{{""orderNumber"":""{id}"",""requestNumber"":""{id}-req"",""orderStatus"":""{orderStatus}""," + + $@"""certificateStatus"":""{certificateStatus}"",""domainName"":""example.com""," + + $@"""productCode"":""842"",""orderDate"":""2026-01-01T00:00:00Z""}}"); + } + long total = totalElements ?? orderNumbers.Length; + return $@"{{""content"":[{string.Join(",", rows)}],""page"":{page},""size"":{size}," + + $@"""totalElements"":{total},""totalPages"":{totalPages}}}"; + } + // ----------------------------------------------------------------------- // Helpers // ----------------------------------------------------------------------- diff --git a/CERTInext.Tests/PluginLogCapture.cs b/CERTInext.Tests/PluginLogCapture.cs new file mode 100644 index 0000000..ad5068e --- /dev/null +++ b/CERTInext.Tests/PluginLogCapture.cs @@ -0,0 +1,66 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Concurrent; +using System.Linq; +using Keyfactor.Logging; +using Microsoft.Extensions.Logging; +using Microsoft.Extensions.Logging.Abstractions; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Captures every log line (level + rendered message) written by a CERTInextCAPlugin + /// constructed while the capture is active, by swapping . + /// The plugin resolves its class logger at construction time, so BUILD THE PLUGIN INSIDE the + /// capture scope. Process-global state: every test class that uses it must carry + /// [Collection(LoggingStateCollection.Name)]. + /// + internal sealed class PluginLogCapture : IDisposable + { + private sealed class Provider : ILoggerProvider + { + public ConcurrentQueue<(LogLevel Level, string Message)> Entries { get; } = new(); + public ILogger CreateLogger(string categoryName) => new Capturing(Entries); + public void Dispose() { } + + private sealed class Capturing : ILogger + { + private readonly ConcurrentQueue<(LogLevel, string)> _entries; + public Capturing(ConcurrentQueue<(LogLevel, string)> entries) => _entries = entries; + public IDisposable BeginScope(TState state) => null; + public bool IsEnabled(LogLevel logLevel) => true; + public void Log(LogLevel logLevel, EventId eventId, TState state, Exception exception, + Func formatter) + => _entries.Enqueue((logLevel, formatter(state, exception))); + } + } + + private readonly Provider _provider = new(); + private readonly ILoggerFactory _factory; + + public PluginLogCapture() + { + _factory = LoggerFactory.Create(b => b.AddProvider(_provider).SetMinimumLevel(LogLevel.Trace)); + LogHandler.Factory = _factory; + } + + public (LogLevel Level, string Message)[] Entries => _provider.Entries.ToArray(); + + /// Lines at exactly whose message contains . + public string[] Lines(LogLevel level, string marker) => Entries + .Where(e => e.Level == level && e.Message.Contains(marker)) + .Select(e => e.Message).ToArray(); + + public void Dispose() + { + LogHandler.Factory = NullLoggerFactory.Instance; + _factory.Dispose(); + } + } +} diff --git a/CERTInext.Tests/PostPlacementDcvFailureTests.cs b/CERTInext.Tests/PostPlacementDcvFailureTests.cs new file mode 100644 index 0000000..72a8cba --- /dev/null +++ b/CERTInext.Tests/PostPlacementDcvFailureTests.cs @@ -0,0 +1,171 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Linq; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.Logging; +using Keyfactor.PKI.Enums.EJBCA; +using Microsoft.Extensions.Logging; +using Moq; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Issue 0077 (DCV build): the in-call DCV / issuance wait in EnrollNewAsync runs after + /// the order has been placed. A failure in it (TrackOrder or VerifyDcv error, or the internal + /// DcvTimeoutMinutes cancellation) used to escape Enroll, failing the enrollment while a paid + /// order existed at CERTInext. It must now log a Warning naming the order and return the pending + /// result carrying the order number so the sync-DCV retry path finishes the order. + /// Only compiled on the -p:DcvSupport=true build (see CERTInext.Tests.csproj). + /// + [Collection(LoggingStateCollection.Name)] + public class PostPlacementDcvFailureTests + { + private const string Order = MockCertificateData.DcvOrderId; + private const string Domain = MockCertificateData.DcvDomain; + + private sealed class CapturingLoggerProvider : ILoggerProvider + { + public ConcurrentQueue<(LogLevel Level, string Message)> Entries { get; } = new(); + public ILogger CreateLogger(string categoryName) => new CapturingLogger(Entries); + public void Dispose() { } + + private sealed class CapturingLogger : ILogger + { + private readonly ConcurrentQueue<(LogLevel, string)> _entries; + public CapturingLogger(ConcurrentQueue<(LogLevel, string)> entries) => _entries = entries; + public IDisposable BeginScope(TState state) => null; + public bool IsEnabled(LogLevel logLevel) => true; + public void Log(LogLevel logLevel, EventId eventId, TState state, Exception exception, + Func formatter) => _entries.Enqueue((logLevel, formatter(state, exception))); + } + } + + private static CERTInextConfig DcvConfig() => new CERTInextConfig + { + DcvEnabled = true, + DcvPropagationDelaySeconds = 1, + DcvTimeoutMinutes = 1, + DcvWaitForChallengeSeconds = 0, + DcvWaitForIssuanceSeconds = 0, + PickupRetries = 0 + }; + + private static Mock PlacedOrderMock() + { + var mock = new Mock(MockBehavior.Strict); + mock.Setup(c => c.EnrollCertificateAsync(It.IsAny(), It.IsAny())) + .ReturnsAsync(MockCertificateData.PendingEnrollResponse(Order)); + return mock; + } + + private static async Task<(EnrollmentResult Result, IReadOnlyList<(LogLevel Level, string Message)> Logs)> EnrollAsync( + Mock mock, FakeDomainValidator validator) + { + var provider = new CapturingLoggerProvider(); + var factory = LoggerFactory.Create(b => b.AddProvider(provider).SetMinimumLevel(LogLevel.Trace)); + try + { + LogHandler.Factory = factory; + // Constructed after the swap so the plugin's per-instance logger resolves through it. + var plugin = new CERTInextCAPlugin(mock.Object, new FakeDomainValidatorFactory(validator), DcvConfig()); + + var result = await plugin.Enroll( + MockCertificateData.FakeCsrPem, $"CN={Domain}", + new Dictionary { ["dns"] = new[] { Domain } }, + new EnrollmentProductInfo + { + ProductID = MockCertificateData.ProfileIdTls, + ProductParameters = new Dictionary { ["ProfileId"] = MockCertificateData.ProfileIdTls } + }, + RequestFormat.PKCS10, EnrollmentType.New); + return (result, provider.Entries.ToList()); + } + finally + { + LogHandler.Factory = Microsoft.Extensions.Logging.Abstractions.NullLoggerFactory.Instance; + factory.Dispose(); + } + } + + private static void AssertPendingWithOrder(EnrollmentResult result, IReadOnlyList<(LogLevel Level, string Message)> logs) + { + result.CARequestID.Should().Be(Order); + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + result.Certificate.Should().BeNull(); + logs.Should().Contain(l => l.Level == LogLevel.Warning && l.Message.Contains(Order) && l.Message.Contains("after order"), + "the swallowed DCV failure must be logged as a Warning naming the order"); + } + + [Fact] + public async Task Enroll_DcvTrackOrderThrows_ReturnsPendingWithOrderNumber() + { + var mock = PlacedOrderMock(); + mock.Setup(c => c.TrackOrderAsync(Order, It.IsAny())) + .ThrowsAsync(new Exception("CERTInext error during 'track order' (HTTP 500)")); + + var (result, logs) = await EnrollAsync(mock, new FakeDomainValidator()); + + AssertPendingWithOrder(result, logs); + } + + [Fact] + public async Task Enroll_DcvTrackOrderNotFound_ReturnsPendingWithOrderNumber() + { + var mock = PlacedOrderMock(); + mock.Setup(c => c.TrackOrderAsync(Order, It.IsAny())) + .ThrowsAsync(new KeyNotFoundException($"Order '{Order}' was not found in CERTInext.")); + + var (result, logs) = await EnrollAsync(mock, new FakeDomainValidator()); + + AssertPendingWithOrder(result, logs); + } + + [Fact] + public async Task Enroll_DcvVerifyThrows_ReturnsPendingWithOrderNumber_AndCleansUpStagedRecord() + { + var mock = PlacedOrderMock(); + mock.Setup(c => c.TrackOrderAsync(Order, It.IsAny())) + .ReturnsAsync(MockCertificateData.DcvPendingTrackResponse(Order, Domain)); + mock.Setup(c => c.GetDcvAsync(Order, Domain, Constants.Dcv.MethodDnsTxt, It.IsAny())) + .ReturnsAsync(MockCertificateData.DcvTokenResponse()); + mock.Setup(c => c.VerifyDcvAsync(Order, Domain, Constants.Dcv.MethodDnsTxt, It.IsAny())) + .ThrowsAsync(new Exception("VerifyDcv HTTP 503")); + var validator = new FakeDomainValidator(); + + var (result, logs) = await EnrollAsync(mock, validator); + + AssertPendingWithOrder(result, logs); + validator.StagedRecords.Should().ContainSingle(); + validator.CleanedUpKeys.Should().ContainSingle("the staged TXT record is still removed on failure"); + } + + [Fact] + public async Task Enroll_DcvTimeoutCancellation_ReturnsPendingWithOrderNumber() + { + // Enroll has no caller token: an OperationCanceledException out of the DCV block is the + // internal DcvTimeoutMinutes token (or a spurious HTTP-timeout TaskCanceledException) and + // must not fail an enrollment whose order already exists. + var mock = PlacedOrderMock(); + mock.Setup(c => c.TrackOrderAsync(Order, It.IsAny())) + .ThrowsAsync(new TaskCanceledException("The request was canceled due to the configured HttpClient.Timeout")); + + var (result, logs) = await EnrollAsync(mock, new FakeDomainValidator()); + + AssertPendingWithOrder(result, logs); + } + } +} diff --git a/CERTInext.Tests/PostPlacementTrackOrderFailureTests.cs b/CERTInext.Tests/PostPlacementTrackOrderFailureTests.cs new file mode 100644 index 0000000..1921dba --- /dev/null +++ b/CERTInext.Tests/PostPlacementTrackOrderFailureTests.cs @@ -0,0 +1,309 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Linq; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.Extensions.CAPlugin.CERTInext.Models; +using Keyfactor.PKI.Enums.EJBCA; +using Microsoft.Extensions.Logging; +using Moq; +using WireMock; +using WireMock.Matchers; +using WireMock.RequestBuilders; +using WireMock.ResponseBuilders; +using WireMock.Server; +using WireMock.Types; +using WireMock.Util; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Issue 0077: once GenerateOrderSSL has returned an order number, a failure of the + /// follow-up TrackOrder (transient 5xx, a timeout, or an EMS-9xx "not found" during + /// propagation lag that surfaces as ) must not fail Enroll or + /// Renewal. A paid order already exists at CERTInext; failing here would hide its order number + /// from Command and invite an operator retry that places a duplicate paid order. The client + /// logs a Warning naming the order and returns a pending result carrying the order number, so + /// sync and pickup finish the order later. + /// + /// Driven against WireMock with the real . All data is synthetic. + /// + [Collection(LoggingStateCollection.Name)] + public class PostPlacementTrackOrderFailureTests : IDisposable + { + private const string PriorOrder = MockCertificateData.OrderNumber1; + private const string NewOrder = MockCertificateData.OrderNumber2; + + private readonly WireMockServer _server; + + public PostPlacementTrackOrderFailureTests() + { + _server = WireMockServer.Start(); + } + + public void Dispose() => _server.Stop(); + + private sealed class CapturingLogger : ILogger + { + public ConcurrentQueue<(LogLevel Level, string Message, Exception Exception)> Entries { get; } = new(); + public IDisposable BeginScope(TState state) => null; + public bool IsEnabled(LogLevel logLevel) => true; + public void Log(LogLevel logLevel, EventId eventId, TState state, Exception exception, + Func formatter) => Entries.Enqueue((logLevel, formatter(state, exception), exception)); + } + + private CERTInextConfig Config() => new CERTInextConfig + { + ApiUrl = _server.Urls[0], + AuthMode = "AccessKey", + ApiKey = "test-key", + AccountNumber = "12345", + RequestorName = "Default Requestor", + RequestorEmail = "default@example.com", + RequestorIsdCode = "1", + RequestorMobileNumber = "5550000000", + SignerPlace = "Austin", + SignerIp = "203.0.113.10", + PageSize = 100, + // Plugin-level tests: keep the synchronous pickup poll out of the way. + PickupRetries = 0 + }; + + private CERTInextClient BuildClient() => new CERTInextClient(Config()); + + private static EnrollCertificateRequest EnrollReq() => new EnrollCertificateRequest + { + ProfileId = "842", + Csr = MockCertificateData.FakeCsrPem, + Subject = "CN=test.example.com", + Comment = "Unit test" + }; + + private static RenewCertificateRequest RenewReq() => new RenewCertificateRequest + { + Csr = MockCertificateData.FakeCsrPem, + Subject = "CN=test.example.com", + ProfileId = "842", + Comment = "Unit test" + }; + + private void StubPlacement(string orderNumber) => + _server.Given(Request.Create().WithPath("/GenerateOrderSSL").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.GenerateOrderSuccessJson(orderNumber))); + + private void StubTrackOrderOk(string orderNumber, string body) => + _server.Given(Request.Create().WithPath("/TrackOrder").UsingPost() + .WithBody(new WildcardMatcher($"*{orderNumber}*"))) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json").WithBody(body)); + + /// + /// Makes TrackOrder for fail the way the issue describes. + /// http500 = transient server error, ems100 = CA-reported failure, + /// http404 / ems913 = "not found" (propagation lag) -> KeyNotFoundException. + /// + private void StubTrackOrderFailure(string orderNumber, string scenario) + { + var response = Response.Create().WithHeader("Content-Type", "application/json"); + switch (scenario) + { + case "http500": + response = response.WithStatusCode(500).WithBody(MockCertificateData.ServerErrorJson()); + break; + case "http404": + response = response.WithStatusCode(404).WithBody(MockCertificateData.ApiFailureJson("EMS-913", "Order not found")); + break; + case "ems913": + response = response.WithStatusCode(200).WithBody(MockCertificateData.ApiFailureJson("EMS-913", "Order not found")); + break; + case "ems100": + response = response.WithStatusCode(200).WithBody(MockCertificateData.ApiFailureJson("EMS-100", "An error occurred")); + break; + default: + throw new ArgumentOutOfRangeException(nameof(scenario)); + } + + _server.Given(Request.Create().WithPath("/TrackOrder").UsingPost() + .WithBody(new WildcardMatcher($"*{orderNumber}*"))) + .RespondWith(response); + } + + private int CallsTo(string path) => _server.LogEntries.Count(e => e.RequestMessage.Path == path); + + private static void AssertWarningNamesOrder(CapturingLogger logger, string orderNumber, bool expectKeyNotFound) + { + var warnings = logger.Entries + .Where(e => e.Level == LogLevel.Warning && e.Message.Contains(orderNumber) && e.Exception != null) + .ToList(); + warnings.Should().NotBeEmpty("the swallowed TrackOrder failure must be logged as a Warning naming the order"); + if (expectKeyNotFound) + warnings.Should().Contain(w => w.Exception is KeyNotFoundException); + else + warnings.Should().Contain(w => !(w.Exception is KeyNotFoundException)); + } + + // --------------------------------------------------------------------------- + // Client: enroll + // --------------------------------------------------------------------------- + + [Theory] + [InlineData("http500", false)] + [InlineData("ems100", false)] + [InlineData("http404", true)] + [InlineData("ems913", true)] + public async Task Enroll_TrackOrderFailsAfterPlacement_ReturnsPendingWithOrderNumber(string scenario, bool expectKeyNotFound) + { + StubPlacement(NewOrder); + StubTrackOrderFailure(NewOrder, scenario); + + var logger = new CapturingLogger(); + EnrollCertificateResponse resp; + using (CERTInextClient.OverrideLoggerForTests(logger)) + resp = await BuildClient().EnrollCertificateAsync(EnrollReq()); + + resp.Id.Should().Be(NewOrder); + resp.Certificate.Should().BeNull(); + StatusMapper.ToRequestDisposition(resp.Status).Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + CallsTo("/GenerateOrderSSL").Should().Be(1, "the order must not be placed twice"); + CallsTo("/GetCertificate").Should().Be(0, "no download is attempted when the status is unknown"); + AssertWarningNamesOrder(logger, NewOrder, expectKeyNotFound); + } + + // --------------------------------------------------------------------------- + // Client: renewal + // --------------------------------------------------------------------------- + + [Theory] + [InlineData("http500", false)] + [InlineData("ems100", false)] + [InlineData("http404", true)] + [InlineData("ems913", true)] + public async Task Renewal_TrackOrderFailsAfterPlacement_ReturnsPendingWithOrderNumber(string scenario, bool expectKeyNotFound) + { + // The prior-order TrackOrder (pre-placement) succeeds; only the new order's fails. + StubTrackOrderOk(PriorOrder, MockCertificateData.TrackOrderIssuedJson(PriorOrder)); + StubPlacement(NewOrder); + StubTrackOrderFailure(NewOrder, scenario); + + var logger = new CapturingLogger(); + EnrollCertificateResponse resp; + using (CERTInextClient.OverrideLoggerForTests(logger)) + resp = await BuildClient().RenewCertificateAsync(PriorOrder, RenewReq()); + + resp.Id.Should().Be(NewOrder); + resp.Certificate.Should().BeNull(); + StatusMapper.ToRequestDisposition(resp.Status).Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + CallsTo("/GenerateOrderSSL").Should().Be(1, "the renewal order must not be placed twice"); + CallsTo("/GetCertificate").Should().Be(0); + AssertWarningNamesOrder(logger, NewOrder, expectKeyNotFound); + } + + // --------------------------------------------------------------------------- + // Plugin: result carries CARequestID and nothing downstream throws on the missing status + // --------------------------------------------------------------------------- + + private static EnrollmentProductInfo ProductInfo(string priorSerial = null) + { + var parameters = new Dictionary(StringComparer.OrdinalIgnoreCase) { ["ProfileId"] = "842" }; + if (priorSerial != null) + { + parameters["PriorCertSN"] = priorSerial; + parameters["RenewalWindowDays"] = "90"; + } + return new EnrollmentProductInfo { ProductID = "842", ProductParameters = parameters }; + } + + [Theory] + [InlineData("http500")] + [InlineData("ems913")] + public async Task Plugin_Enroll_New_TrackOrderFailsAfterPlacement_ReturnsPendingWithCARequestID(string scenario) + { + StubPlacement(NewOrder); + StubTrackOrderFailure(NewOrder, scenario); + var plugin = new CERTInextCAPlugin(BuildClient(), Config()); + + var result = await plugin.Enroll( + MockCertificateData.FakeCsrPem, "CN=test.example.com", + new Dictionary { ["dns"] = new[] { "test.example.com" } }, + ProductInfo(), RequestFormat.PKCS10, EnrollmentType.New); + + result.CARequestID.Should().Be(NewOrder); + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + result.Certificate.Should().BeNull(); + CallsTo("/GenerateOrderSSL").Should().Be(1); + } + + [Theory] + [InlineData("http500")] + [InlineData("ems913")] + public async Task Plugin_Enroll_RenewalApi_TrackOrderFailsAfterPlacement_ReturnsPendingWithCARequestID(string scenario) + { + StubTrackOrderOk(PriorOrder, MockCertificateData.TrackOrderIssuedJson(PriorOrder)); + StubPlacement(NewOrder); + StubTrackOrderFailure(NewOrder, scenario); + + var reader = new Mock(); + reader.Setup(r => r.GetRequestIDBySerialNumber(It.IsAny())).ReturnsAsync(PriorOrder); + reader.Setup(r => r.GetExpirationDateByRequestId(PriorOrder)).Returns(DateTime.UtcNow.AddDays(30)); + var plugin = new CERTInextCAPlugin(BuildClient(), reader.Object, Config()); + + var result = await plugin.Enroll( + MockCertificateData.FakeCsrPem, "CN=test.example.com", + new Dictionary { ["dns"] = new[] { "test.example.com" } }, + ProductInfo("AABB"), RequestFormat.PKCS10, EnrollmentType.RenewOrReissue); + + // Guard: the renewal API path (not the new-enroll fallback) produced the order. + reader.Verify(r => r.GetExpirationDateByRequestId(PriorOrder), Times.Once); + result.CARequestID.Should().Be(NewOrder); + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + result.Certificate.Should().BeNull(); + CallsTo("/GenerateOrderSSL").Should().Be(1); + } + + // --------------------------------------------------------------------------- + // A real cancellation may still propagate + // --------------------------------------------------------------------------- + + [Fact] + public async Task Enroll_RealCancellationAfterPlacement_StillPropagates() + { + using var cts = new CancellationTokenSource(); + // Cancel the caller's token as the placement response is produced, so the follow-up + // TrackOrder runs with a genuinely cancelled token. + _server.Given(Request.Create().WithPath("/GenerateOrderSSL").UsingPost()) + .RespondWith(Response.Create().WithCallback(_ => + { + cts.Cancel(); + return new ResponseMessage + { + StatusCode = 200, + BodyData = new BodyData + { + DetectedBodyType = BodyType.String, + BodyAsString = MockCertificateData.GenerateOrderSuccessJson(NewOrder) + } + }; + })); + StubTrackOrderOk(NewOrder, MockCertificateData.TrackOrderPendingJson(NewOrder)); + + Func act = () => BuildClient().EnrollCertificateAsync(EnrollReq(), cts.Token); + + await act.Should().ThrowAsync(); + } + } +} diff --git a/CERTInext.Tests/RedactCredentialsTests.cs b/CERTInext.Tests/RedactCredentialsTests.cs index fad3e46..e689656 100644 --- a/CERTInext.Tests/RedactCredentialsTests.cs +++ b/CERTInext.Tests/RedactCredentialsTests.cs @@ -54,6 +54,52 @@ public void RedactCredentials_ScrubsFormUrlEncodedCredentialFields(string input, CERTInextClient.RedactCredentials(input).Should().Be(expected); } + // JSON string values can contain escaped quotes and backslashes. A scrubber that stops at the + // first '"' it sees leaks everything after the escape into the log. Values below are synthetic. + [Theory] + [InlineData( + "{\"authKey\":\"ab\\\"cd\"}", + "{\"authKey\":\"***REDACTED***\"}")] + [InlineData( + "{\"meta\":{\"authKey\":\"ab\\\"cd\\\"ef\",\"ts\":\"2026\"}}", + "{\"meta\":{\"authKey\":\"***REDACTED***\",\"ts\":\"2026\"}}")] + [InlineData( + "{\"password\":\"p\\\\q\",\"other\":\"keep\"}", + "{\"password\":\"***REDACTED***\",\"other\":\"keep\"}")] + [InlineData( + "{\"client_secret\":\"ends-with-backslash\\\\\",\"other\":\"keep\"}", + "{\"client_secret\":\"***REDACTED***\",\"other\":\"keep\"}")] + [InlineData( + "{\"apiKey\":\"a\\\"b\",\"accessKey\":\"c\\\\d\\\"e\"}", + "{\"apiKey\":\"***REDACTED***\",\"accessKey\":\"***REDACTED***\"}")] + public void RedactCredentials_ScrubsJsonValuesContainingEscapes(string input, string expected) + { + CERTInextClient.RedactCredentials(input).Should().Be(expected); + } + + [Fact] + public void RedactCredentials_EscapedQuoteInJsonValue_DoesNotLeakTail() + { + string actual = CERTInextClient.RedactCredentials("{\"authKey\":\"head\\\"TAILSECRET\"}"); + actual.Should().NotContain("TAILSECRET").And.NotContain("head"); + } + + [Fact] + public void RedactCredentials_EmptyJsonValue_IsStillRedactedAsBefore() + { + // Pre-existing behavior (unlike PII fields, credential fields are not skipped when empty). + CERTInextClient.RedactCredentials("{\"authKey\":\"\"}") + .Should().Be("{\"authKey\":\"***REDACTED***\"}"); + } + + [Theory] + [InlineData("authKey=ab\\\"TAILSECRET", "authKey=***REDACTED***")] + [InlineData("x=1&password=a\\\\b\\\"TAILSECRET&y=2", "x=1&password=***REDACTED***&y=2")] + public void RedactCredentials_FormValueWithEscapedQuote_DoesNotLeakTail(string input, string expected) + { + CERTInextClient.RedactCredentials(input).Should().Be(expected); + } + [Fact] public void RedactCredentials_ScrubsAuthorizationHeaderLines() { diff --git a/CERTInext.Tests/RedactPersonalDataTests.cs b/CERTInext.Tests/RedactPersonalDataTests.cs new file mode 100644 index 0000000..1b92658 --- /dev/null +++ b/CERTInext.Tests/RedactPersonalDataTests.cs @@ -0,0 +1,893 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System.Text.Json; +using System.Text.Json.Serialization; +using FluentAssertions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.Extensions.CAPlugin.CERTInext.Models; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Requestor personal data (name, email, phone, org contact fields) must not + /// appear in gateway logs unless the connector's LogSensitiveRequestData setting is + /// explicitly turned on. These tests pin and + /// against realistic V1 and V2 order + /// payload JSON, produced by serializing the real request/response models rather than + /// hand-written strings — so a future rename of a JSON property name (which would silently + /// stop the redactor from matching it) fails these tests immediately. + /// + public class RedactPersonalDataTests + { + // Mirrors CERTInextClient.GetJsonOptions() (private), so serialized payloads in these + // tests match the real wire shape (case-insensitive property names, nulls omitted). + private static JsonSerializerOptions ClientEquivalentJsonOptions() => new JsonSerializerOptions + { + PropertyNameCaseInsensitive = true, + DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull + }; + + private const string SyntheticAuthKey = "0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0"; + + // --------------------------------------------------------------------------- + // V1 GenerateOrderSSL request — requestorInformation / technicalPointOfContact / + // agreementDetails all carry personal data; certificateInformation/orderDetails don't. + // --------------------------------------------------------------------------- + + private static string BuildV1OrderRequestJson() + { + var request = new GenerateOrderSslRequest + { + Meta = new RequestMeta + { + Ver = "1.0", Ts = "2026-05-22T10:00:00+00:00", Txn = "1234567890", + AccountNumber = "9988776655", AuthKey = SyntheticAuthKey + }, + OrderDetails = new SslOrderDetails + { + ProductCode = "842", + AccountingModel = "2", + SaveAndHold = "0", + EmailNotifications = "0", + RequestorInformation = new RequestorInformation + { + RequestorName = "Jane Doe", + RequestorIsdCode = "1", + RequestorMobileNumber = "5551234567", + RequestorEmail = "jane.doe@example.com", + RequestorDesignation = "IT Administrator" + }, + SubscriptionDetails = new SubscriptionDetails { Validity = "1", AutoRenew = "0", RenewCriteria = "30" }, + CertificateInformation = new CertificateInformation + { + DomainName = "example.com", + AdditionalDomains = new System.Collections.Generic.List { "alt.example.com", "www.example.com" } + }, + AgreementDetails = new AgreementDetails + { + AcceptAgreement = "1", + SignerName = "John Signer", + SignerPlace = "Austin", + SignerIp = "203.0.113.10" + }, + TechnicalPointOfContact = new TechnicalPointOfContact + { + PocFirstName = "Terry", + PocLastName = "Techcontact", + PocEmail = "tech.contact@example.com", + PocIsdCode = "44", + PocMobileNumber = "5559876543" + } + } + }; + + return JsonSerializer.Serialize(request, ClientEquivalentJsonOptions()); + } + + [Fact] + public void RedactPersonalData_V1OrderRequest_RemovesAllPersonFields() + { + string input = BuildV1OrderRequestJson(); + string output = CERTInextClient.RedactPersonalData(input); + + output.Should().NotContain("Jane Doe"); + output.Should().NotContain("jane.doe@example.com"); + output.Should().NotContain("5551234567"); + output.Should().NotContain("IT Administrator"); + output.Should().NotContain("John Signer"); + output.Should().NotContain("Austin"); + output.Should().NotContain("203.0.113.10"); + output.Should().NotContain("Terry"); + output.Should().NotContain("Techcontact"); + output.Should().NotContain("tech.contact@example.com"); + output.Should().NotContain("5559876543"); + output.Should().NotContain("\"pocIsdCode\":\"44\""); + } + + [Fact] + public void RedactPersonalData_V1OrderRequest_MasksEmailsKeepingDomain() + { + string output = CERTInextClient.RedactPersonalData(BuildV1OrderRequestJson()); + + output.Should().Contain("\"requestorEmail\":\"j***@example.com\""); + output.Should().Contain("\"pocEmail\":\"t***@example.com\""); + } + + [Fact] + public void RedactPersonalData_V1OrderRequest_PreservesNonPersonalFields() + { + string output = CERTInextClient.RedactPersonalData(BuildV1OrderRequestJson()); + + output.Should().Contain("\"productCode\":\"842\""); + output.Should().Contain("\"domainName\":\"example.com\""); + output.Should().Contain("alt.example.com"); + output.Should().Contain("www.example.com"); + output.Should().Contain("\"accountNumber\":\"9988776655\""); + output.Should().Contain("\"validity\":\"1\""); + } + + [Fact] + public void RedactPersonalData_V1OrderRequest_RedactsRequestorNameToPlaceholder() + { + string output = CERTInextClient.RedactPersonalData(BuildV1OrderRequestJson()); + + output.Should().Contain("\"requestorName\":\"***REDACTED***\""); + output.Should().Contain("\"requestorMobileNumber\":\"***REDACTED***\""); + output.Should().Contain("\"requestorDesignation\":\"***REDACTED***\""); + output.Should().Contain("\"signerName\":\"***REDACTED***\""); + output.Should().Contain("\"signerPlace\":\"***REDACTED***\""); + output.Should().Contain("\"signerIP\":\"***REDACTED***\""); + output.Should().Contain("\"pocFirstName\":\"***REDACTED***\""); + output.Should().Contain("\"pocLastName\":\"***REDACTED***\""); + output.Should().Contain("\"pocIsdCode\":\"***REDACTED***\""); + output.Should().Contain("\"pocMobileNumber\":\"***REDACTED***\""); + } + + // --------------------------------------------------------------------------- + // The V1 order body's meta.authKey is a replayable credential — always redacted by + // ApplyLoggingRedaction, whatever LogSensitiveRequestData says. + // --------------------------------------------------------------------------- + + [Theory] + [InlineData(false)] + [InlineData(true)] + public void ApplyLoggingRedaction_V1OrderRequest_AuthKeyAlwaysRedacted(bool logSensitiveRequestData) + { + string input = BuildV1OrderRequestJson(); + input.Should().Contain(SyntheticAuthKey, "precondition: the serialized body carries meta.authKey"); + + string output = CERTInextClient.ApplyLoggingRedaction(input, logSensitiveRequestData); + + output.Should().NotContain(SyntheticAuthKey); + output.Should().Contain("\"authKey\":\"***REDACTED***\""); + } + + [Fact] + public void ApplyLoggingRedaction_V1OrderRequest_FlagOn_KeepsPersonalDataInFull() + { + string output = CERTInextClient.ApplyLoggingRedaction(BuildV1OrderRequestJson(), logSensitiveRequestData: true); + + output.Should().Contain("Jane Doe"); + output.Should().Contain("jane.doe@example.com"); + output.Should().Contain("5551234567"); + output.Should().Contain("tech.contact@example.com"); + output.Should().Contain("\"pocFirstName\":\"Terry\""); + output.Should().Contain("\"pocLastName\":\"Techcontact\""); + output.Should().Contain("\"pocIsdCode\":\"44\""); + output.Should().Contain("\"pocMobileNumber\":\"5559876543\""); + output.Should().Contain("\"authKey\":\"***REDACTED***\"", "credentials stay redacted with the flag on"); + output.Should().NotContain(SyntheticAuthKey); + } + + [Fact] + public void ApplyLoggingRedaction_V1OrderRequest_FlagOff_RedactsEveryPocField() + { + string output = CERTInextClient.ApplyLoggingRedaction(BuildV1OrderRequestJson(), logSensitiveRequestData: false); + + output.Should().Contain("\"pocFirstName\":\"***REDACTED***\""); + output.Should().Contain("\"pocLastName\":\"***REDACTED***\""); + output.Should().Contain("\"pocEmail\":\"t***@example.com\""); + output.Should().Contain("\"pocIsdCode\":\"***REDACTED***\""); + output.Should().Contain("\"pocMobileNumber\":\"***REDACTED***\""); + output.Should().NotContain("tech.contact@example.com"); + output.Should().NotContain(SyntheticAuthKey); + } + + [Fact] + public void RedactPersonalData_PrettyPrintedNestedPocBlock_IsRedacted() + { + string input = "{\n \"technicalPointOfContact\" : {\n \"pocFirstName\" : \"Terry\",\n \"pocEmail\" : \"tech.contact@example.com\",\n \"pocMobileNumber\":\"5559876543\"\n }\n}"; + + string output = CERTInextClient.RedactPersonalData(input); + + output.Should().NotContain("Terry").And.NotContain("tech.contact@example.com").And.NotContain("5559876543"); + output.Should().Contain("t***@example.com"); + } + + [Fact] + public void RedactPersonalData_LegacyTpcKeysInResponseBody_AreRedacted_DefenceInDepth() + { + // The V1 request no longer emits tpc* (renamed to poc*), but a CA error body may echo + // the old names, so they stay on the redaction lists. + string input = "{\"tpcName\":\"Tech Contact\",\"tpcEmail\":\"tech.contact@example.com\",\"tpcIsdCode\":\"1\",\"tpcMobileNumber\":\"5559876543\"}"; + + string output = CERTInextClient.RedactPersonalData(input); + + output.Should().Be("{\"tpcName\":\"***REDACTED***\",\"tpcEmail\":\"t***@example.com\",\"tpcIsdCode\":\"***REDACTED***\",\"tpcMobileNumber\":\"***REDACTED***\"}"); + } + + // --------------------------------------------------------------------------- + // V2 order create request — requestor / technicalPointOfContact / agreement all carry + // bare name/email/phone/designation/signerName keys; certificate/subscription don't. + // --------------------------------------------------------------------------- + + private static string BuildV2OrderRequestJson() + { + var request = new V2CreateSslOrderRequest + { + ProductVariant = "ov", + EmailNotifications = "0", + Requestor = new V2Requestor + { + Name = "Jane Doe", + Email = "jane.doe@example.com", + Phone = "+15551234567", + Designation = "IT Administrator" + }, + Organization = new V2OrganizationParams { OrganizationNumber = "1234567", PreVetted = true }, + Certificate = new V2CertificateParams + { + Domain = "example.com", + AdditionalDomains = new System.Collections.Generic.List { "alt.example.com" } + }, + Subscription = new V2SubscriptionParams { ValidityYears = 1, AutoRenew = false }, + Agreement = new V2AgreementParams + { + SignerName = "John Signer", + SignerPlace = "Austin" + }, + TechnicalPointOfContact = new V2TechnicalPointOfContact + { + Name = "Tech Contact", + Email = "tech.contact@example.com", + Phone = "+15559876543", + Designation = "PKI Manager" + }, + GroupNumber = "2345678901" + }; + + return JsonSerializer.Serialize(request, ClientEquivalentJsonOptions()); + } + + [Fact] + public void RedactPersonalData_V2OrderRequest_RemovesAllPersonFields() + { + string output = CERTInextClient.RedactPersonalData(BuildV2OrderRequestJson()); + + output.Should().NotContain("Jane Doe"); + output.Should().NotContain("jane.doe@example.com"); + output.Should().NotContain("+15551234567"); + output.Should().NotContain("IT Administrator"); + output.Should().NotContain("John Signer"); + output.Should().NotContain("Austin"); + output.Should().NotContain("Tech Contact"); + output.Should().NotContain("tech.contact@example.com"); + output.Should().NotContain("+15559876543"); + output.Should().NotContain("PKI Manager"); + } + + [Fact] + public void RedactPersonalData_V2OrderRequest_MasksEmailsKeepingDomain() + { + string output = CERTInextClient.RedactPersonalData(BuildV2OrderRequestJson()); + + // requestor.email ("jane.doe@example.com") and technicalPointOfContact.email + // ("tech.contact@example.com") both use the same bare "email" key but have distinct + // local parts — both must be masked independently (domain kept in each). + output.Should().Contain("\"email\":\"j***@example.com\""); + output.Should().Contain("\"email\":\"t***@example.com\""); + } + + [Fact] + public void RedactPersonalData_V2OrderRequest_PreservesNonPersonalFields() + { + string output = CERTInextClient.RedactPersonalData(BuildV2OrderRequestJson()); + + output.Should().Contain("\"productVariant\":\"ov\""); + output.Should().Contain("\"domain\":\"example.com\""); + output.Should().Contain("alt.example.com"); + output.Should().Contain("\"organizationNumber\":\"1234567\""); + output.Should().Contain("\"groupNumber\":\"2345678901\""); + output.Should().Contain("\"validityYears\":1"); + } + + [Fact] + public void RedactPersonalData_V2OrderRequest_NestedNameFieldsRedactedToPlaceholder() + { + string output = CERTInextClient.RedactPersonalData(BuildV2OrderRequestJson()); + + // Both requestor.name and technicalPointOfContact.name must be caught even though + // they are nested inside different objects using the same bare "name" key. + var nameMatches = System.Text.RegularExpressions.Regex.Matches(output, "\"name\":\"\\*\\*\\*REDACTED\\*\\*\\*\""); + nameMatches.Count.Should().Be(2, "both requestor.name and technicalPointOfContact.name must be redacted"); + + output.Should().Contain("\"phone\":\"***REDACTED***\""); + output.Should().Contain("\"designation\":\"***REDACTED***\""); + output.Should().Contain("\"signerName\":\"***REDACTED***\""); + output.Should().Contain("\"signerPlace\":\"***REDACTED***\""); + } + + // V2 place-order response echoes the agreement as subscriberAgreement with the key + // "signedPlace" (not the request's "signerPlace"), plus an orderedBy contact. Shape taken + // from a sandbox response; values here are fictitious. + private const string V2OrderResponseJson = + "{\"orderId\":\"4898663698\",\"status\":\"pending-approval\",\"productVariant\":\"dv\"," + + "\"domain\":\"example.com\",\"resolvedProductCode\":\"842\"," + + "\"requestor\":{\"name\":\"Jane Doe\",\"email\":\"jane.doe@example.com\"}," + + "\"orderedBy\":{\"name\":\"Account Owner\",\"email\":\"owner@example.com\"}," + + "\"subscriberAgreement\":{\"signed\":true,\"signerName\":\"John Signer\"," + + "\"signedAt\":\"2026-09-26T15:58:51Z\",\"signedPlace\":\"Austin\"}}"; + + [Fact] + public void RedactPersonalData_V2OrderResponse_RedactsSubscriberAgreementAndOrderedBy() + { + string output = CERTInextClient.RedactPersonalData(V2OrderResponseJson); + + output.Should().NotContain("Austin"); + output.Should().Contain("\"signedPlace\":\"***REDACTED***\""); + output.Should().NotContain("John Signer"); + output.Should().NotContain("Jane Doe"); + output.Should().NotContain("Account Owner"); + output.Should().Contain("\"email\":\"o***@example.com\""); + output.Should().Contain("\"orderId\":\"4898663698\""); + output.Should().Contain("\"domain\":\"example.com\""); + output.Should().Contain("\"signedAt\":\"2026-09-26T15:58:51Z\""); + } + + // --------------------------------------------------------------------------- + // Whitespace tolerance — a pretty-printed body must redact identically to a compact one. + // --------------------------------------------------------------------------- + + [Fact] + public void RedactPersonalData_TolerantOfWhitespaceAroundKeyValueSeparator() + { + string input = "{\n \"requestor\" : {\n \"name\" : \"Jane Doe\",\n \"email\":\"jane.doe@example.com\"\n }\n}"; + + string output = CERTInextClient.RedactPersonalData(input); + + output.Should().NotContain("Jane Doe"); + output.Should().Contain("j***@example.com"); + } + + // --------------------------------------------------------------------------- + // Edge cases + // --------------------------------------------------------------------------- + + [Theory] + [InlineData(null)] + [InlineData("")] + public void RedactPersonalData_HandlesNullAndEmpty(string input) + { + CERTInextClient.RedactPersonalData(input).Should().Be(input); + } + + [Fact] + public void RedactPersonalData_LeavesAlreadyBlankFieldsUntouched() + { + string input = "{\"requestorName\":\"\",\"requestorEmail\":\"\"}"; + CERTInextClient.RedactPersonalData(input).Should().Be(input, + "there is nothing to redact in an already-blank field"); + } + + [Fact] + public void RedactPersonalData_MalformedEmailValue_FallsBackToFullRedaction() + { + string input = "{\"requestorEmail\":\"not-an-email\"}"; + string output = CERTInextClient.RedactPersonalData(input); + output.Should().Be("{\"requestorEmail\":\"***REDACTED***\"}"); + } + + [Fact] + public void RedactPersonalData_DoesNotTouchUnrelatedNameLikeKeys() + { + // domainName / organizationName end in "Name" but are not the exact key "name" — + // the anchored quote-delimited match must not treat them as substrings of "name". + string input = "{\"domainName\":\"example.com\",\"organizationName\":\"Acme Corp\"}"; + CERTInextClient.RedactPersonalData(input).Should().Be(input); + } + + // --------------------------------------------------------------------------- + // Credentials are always redacted, regardless of RedactPersonalData + // --------------------------------------------------------------------------- + + [Fact] + public void RedactPersonalData_DoesNotRedactCredentials_ThatIsRedactCredentialsJob() + { + // RedactPersonalData is deliberately scoped to person/contact fields only; credential + // scrubbing is RedactCredentials's job and is applied unconditionally by + // ApplyLoggingRedaction regardless of this method. + string input = "{\"authKey\":\"deadbeef\",\"requestorName\":\"Jane Doe\"}"; + string output = CERTInextClient.RedactPersonalData(input); + + output.Should().Contain("deadbeef", "RedactPersonalData alone does not scrub credentials"); + output.Should().NotContain("Jane Doe"); + } + + // --------------------------------------------------------------------------- + // ApplyLoggingRedaction — the flag-gated composition used at every log site + // --------------------------------------------------------------------------- + + [Fact] + public void ApplyLoggingRedaction_FlagOff_RedactsBothCredentialsAndPersonalData() + { + string input = "{\"authKey\":\"deadbeef\",\"requestorName\":\"Jane Doe\",\"requestorEmail\":\"jane.doe@example.com\",\"domainName\":\"example.com\"}"; + + string output = CERTInextClient.ApplyLoggingRedaction(input, logSensitiveRequestData: false); + + output.Should().NotContain("deadbeef"); + output.Should().NotContain("Jane Doe"); + output.Should().Contain("j***@example.com"); + output.Should().Contain("\"domainName\":\"example.com\""); + } + + [Fact] + public void ApplyLoggingRedaction_V2SslCreateBody_InlineCsr_RedactedWhenFlagOff_KeptWhenFlagOn() + { + // The V2 SSL create body carries the PKCS#10 CSR inline ("csr"); its subject is requester data. + string csrBody = MockCertificateData.FakeCsrPem.Split('\n')[1]; + var ssl = new V2CreateSslOrderRequest + { + Requestor = new V2Requestor { Name = "Jane Doe", Email = "jane.doe@example.com" }, + Certificate = new V2CertificateParams { Domain = "example.com" }, + Csr = MockCertificateData.FakeCsrPem + }; + + foreach (object body in new object[] { ssl }) + { + string json = JsonSerializer.Serialize(body, body.GetType(), ClientEquivalentJsonOptions()); + json.Should().Contain(csrBody, "precondition: the serialized create body carries the CSR"); + + CERTInextClient.ApplyLoggingRedaction(json, logSensitiveRequestData: false) + .Should().NotContain(csrBody, "the inline CSR must not reach logs unless sensitive logging is on") + .And.Contain("\"csr\":\"***REDACTED***\""); + CERTInextClient.ApplyLoggingRedaction(json, logSensitiveRequestData: true) + .Should().Contain(csrBody); + } + } + + [Fact] + public void ApplyLoggingRedaction_FlagOn_RedactsCredentialsOnly_LeavesPersonalDataInFull() + { + string input = "{\"authKey\":\"deadbeef\",\"requestorName\":\"Jane Doe\",\"requestorEmail\":\"jane.doe@example.com\",\"domainName\":\"example.com\"}"; + + string output = CERTInextClient.ApplyLoggingRedaction(input, logSensitiveRequestData: true); + + output.Should().NotContain("deadbeef", "credentials must always be redacted, even with the flag on"); + output.Should().Contain("Jane Doe", "personal data is left in full when the flag is on"); + output.Should().Contain("jane.doe@example.com", "personal data is left in full when the flag is on"); + output.Should().Contain("\"domainName\":\"example.com\""); + } + + [Theory] + [InlineData(null)] + [InlineData("")] + public void ApplyLoggingRedaction_HandlesNullAndEmpty(string input) + { + CERTInextClient.ApplyLoggingRedaction(input, logSensitiveRequestData: false).Should().Be(input); + CERTInextClient.ApplyLoggingRedaction(input, logSensitiveRequestData: true).Should().Be(input); + } + + // --------------------------------------------------------------------------- + // V2 Private PKI and Document Signer (signature) order bodies. Built from the + // real DTOs so a JSON property rename that would silently defeat the redactor fails here. + // --------------------------------------------------------------------------- + + // Values mirror the spec's "Create - Natural Person" example body. + private static string BuildV2SignatureOrderRequestJson() + { + var request = new V2CreateSignatureOrderRequest + { + SubjectType = "natural-person", + EmailNotifications = "all", + Requestor = new V2Requestor { Name = "Sarah Johnson", Email = "sarah.johnson@example.com", Phone = "+12025551234", Designation = "Document Signer" }, + Subject = new V2SignatureSubject + { + FirstName = "Sarah", + LastName = "Johnson", + Email = "sarah.johnson@example.com", + Phone = "+12025551234", + IdentityDocumentType = "passport", + IdentificationNumber = "X12345678", + StreetAddress1 = "1600 Pennsylvania Avenue NW", + StreetAddress2 = "Apt 7", + Locality = "Washington", + State = "DC", + PostalCode = "20500", + CountryCode = "US" + }, + Subscription = new V2SubscriptionParams { ValidityYears = 1, AutoRenew = false }, + Agreement = new V2AgreementParams { SignerName = "Sarah Johnson", SignerPlace = "Washington, DC", Accepted = true }, + Remarks = "Document Signer - Natural Person, US" + }; + return JsonSerializer.Serialize(request, ClientEquivalentJsonOptions()); + } + + [Fact] + public void RedactPersonalData_V2SignatureOrderRequest_RemovesSubjectPersonFields() + { + string output = CERTInextClient.RedactPersonalData(BuildV2SignatureOrderRequestJson()); + + // Name, identity-document and street-address values must all be gone. + foreach (var raw in new[] + { + "Sarah", "Johnson", "+12025551234", "Document Signer\"", "passport", "X12345678", + "1600 Pennsylvania Avenue NW", "Apt 7", "\"Washington\"", "20500", "Washington, DC" + }) + { + output.Should().NotContain(raw, $"'{raw}' is subject/requestor personal data"); + } + + // subject.email and requestor.email are masked to their domain, not dropped. + output.Should().NotContain("sarah.johnson@"); + output.Should().Contain("s***@example.com"); + } + + [Fact] + public void RedactPersonalData_V2SignatureOrderRequest_PreservesNonPersonalFields() + { + string output = CERTInextClient.RedactPersonalData(BuildV2SignatureOrderRequestJson()); + + // Deliberately-not-redacted keys: the discriminator, coarse location, and the + // agreement flag carry no personal identity on their own. + output.Should().Contain("\"subjectType\":\"natural-person\""); + output.Should().Contain("\"state\":\"DC\""); + output.Should().Contain("\"countryCode\":\"US\""); + output.Should().Contain("\"accepted\":true"); + } + + [Fact] + public void RedactPersonalData_V2SignatureCreateResponse_RedactsSubjectDisplayName() + { + // Spec "Create - Natural Person" response: subjectDisplayName is the full name for a + // natural / legal person. PlaceOrderV2Async logs this response body at Trace. + string input = "{\"orderId\":\"ord_sig_1\",\"status\":\"pending-documents\",\"subjectType\":\"natural-person\"," + + "\"subjectDisplayName\":\"Sarah Johnson\",\"resolvedProductCode\":\"819\"}"; + + string output = CERTInextClient.RedactPersonalData(input); + + output.Should().NotContain("Sarah Johnson"); + output.Should().Contain("\"subjectDisplayName\":\"***REDACTED***\""); + output.Should().Contain("\"orderId\":\"ord_sig_1\""); + output.Should().Contain("\"resolvedProductCode\":\"819\""); + } + + [Fact] + public void RedactPersonalData_LegalEntitySubject_KeepsOrganizationFields() + { + // Organization identity is not personal data, and "organizationName" is also a V1 + // order/report key for an OV organization — deliberately excluded from the key set. + var request = new V2CreateSignatureOrderRequest + { + SubjectType = "legal-entity", + Requestor = new V2Requestor { Name = "Acme Corporation Compliance", Email = "pki-ops@acme.com" }, + Subject = new V2SignatureSubject + { + OrganizationName = "Acme Corporation", + OrganizationUnit = "Compliance", + BusinessCategory = "Business Entity", + OrganizationIdentificationNumber = "EIN-12-3456789", + Email = "pki-ops@acme.com" + } + }; + string json = JsonSerializer.Serialize(request, ClientEquivalentJsonOptions()); + + string output = CERTInextClient.RedactPersonalData(json); + + output.Should().Contain("\"organizationName\":\"Acme Corporation\""); + output.Should().Contain("\"organizationIdentificationNumber\":\"EIN-12-3456789\""); + output.Should().NotContain("Acme Corporation Compliance", "requestor.name is still personal/contact data"); + output.Should().NotContain("pki-ops@"); + } + + [Fact] + public void ApplyLoggingRedaction_V2SignatureOrderRequest_FlagOn_LeavesSubjectInFull() + { + string output = CERTInextClient.ApplyLoggingRedaction(BuildV2SignatureOrderRequestJson(), logSensitiveRequestData: true); + + output.Should().Contain("\"firstName\":\"Sarah\""); + output.Should().Contain("\"identificationNumber\":\"X12345678\""); + output.Should().Contain("sarah.johnson@example.com"); + } + + [Fact] + public void ApplyLoggingRedaction_V2PrivatePkiOrderRequest_FlagOff_RedactsRequestorAndContact_KeepsHosts() + { + // Private PKI adds no new personal keys (requestor / technicalPointOfContact reuse the + // bare name/email/phone/designation keys); hostname / additionalHosts are diagnostic + // host data and must survive redaction. + var request = new V2CreatePrivatePkiOrderRequest + { + Variant = "intranet-ssl", + Hostname = "intranet.acme.local", + AdditionalHosts = new System.Collections.Generic.List { "portal.acme.local", "10.0.0.50" }, + Requestor = new V2Requestor { Name = "DevOps Team", Email = "devops@acme.com", Phone = "+14155551234", Designation = "Platform Engineering" }, + TechnicalPointOfContact = new V2TechnicalPointOfContact { Name = "Tech Person", Email = "tech@acme.com", Phone = "+14155550000", Designation = "Technical Contact" }, + Subscription = new V2SubscriptionParams { ValidityYears = 1 } + }; + string json = JsonSerializer.Serialize(request, ClientEquivalentJsonOptions()); + + string output = CERTInextClient.ApplyLoggingRedaction(json, logSensitiveRequestData: false); + + foreach (var raw in new[] { "DevOps Team", "devops@", "+14155551234", "Platform Engineering", "Tech Person", "tech@", "+14155550000" }) + output.Should().NotContain(raw); + output.Should().Contain("\"hostname\":\"intranet.acme.local\""); + output.Should().Contain("portal.acme.local"); + output.Should().Contain("10.0.0.50"); + output.Should().Contain("\"variant\":\"intranet-ssl\""); + } + + // --------------------------------------------------------------------------- + // Email SANs inside SAN arrays (V1 additionalDomains carries every + // SAN type) and V1 TrackOrder domainVerification keys, which the key/value regex can't reach. + // --------------------------------------------------------------------------- + + private static string BuildV1OrderRequestJsonWithMixedSans(bool indented) + { + var request = new GenerateOrderSslRequest + { + Meta = new RequestMeta { Ver = "1.0", Ts = "2026-05-22T10:00:00+00:00", Txn = "1234567890", AccountNumber = "9988776655" }, + OrderDetails = new SslOrderDetails + { + ProductCode = "844", + RequestorInformation = new RequestorInformation { RequestorName = "Jane Doe", RequestorEmail = "jane.doe@example.com" }, + CertificateInformation = new CertificateInformation + { + DomainName = "example.com", + AdditionalDomains = new System.Collections.Generic.List { "a.example.com", "alice@example.com", "10.0.0.1" } + } + } + }; + var options = ClientEquivalentJsonOptions(); + options.WriteIndented = indented; + return JsonSerializer.Serialize(request, options); + } + + [Fact] + public void ApplyLoggingRedaction_V1AdditionalDomains_FlagOff_MasksOnlyEmailElement() + { + string output = CERTInextClient.ApplyLoggingRedaction(BuildV1OrderRequestJsonWithMixedSans(indented: false), logSensitiveRequestData: false); + + output.Should().NotContain("alice@"); + output.Should().Contain("\"additionalDomains\":[\"a.example.com\",\"a***@example.com\",\"10.0.0.1\"]"); + output.Should().Contain("\"domainName\":\"example.com\""); + output.Should().Contain("j***@example.com", "the existing key/value redaction still runs"); + } + + [Fact] + public void ApplyLoggingRedaction_V1AdditionalDomains_PrettyPrinted_FlagOff_MasksOnlyEmailElement() + { + string input = BuildV1OrderRequestJsonWithMixedSans(indented: true); + input.Should().Contain("\n", "precondition: the body is pretty-printed"); + + string output = CERTInextClient.ApplyLoggingRedaction(input, logSensitiveRequestData: false); + + output.Should().NotContain("alice@"); + output.Should().Contain("\"a***@example.com\""); + output.Should().Contain("\"a.example.com\""); + output.Should().Contain("\"10.0.0.1\""); + // Only the email token changes; the layout of the array is preserved. + string expectedArray = System.Text.RegularExpressions.Regex.Match(input, @"""additionalDomains"":\s*\[[^\]]*\]").Value + .Replace("\"alice@example.com\"", "\"a***@example.com\""); + expectedArray.Should().NotBeEmpty(); + output.Should().Contain(expectedArray); + } + + [Fact] + public void ApplyLoggingRedaction_V1AdditionalDomains_FlagOn_LeavesArrayVerbatim() + { + string input = BuildV1OrderRequestJsonWithMixedSans(indented: false); + + string output = CERTInextClient.ApplyLoggingRedaction(input, logSensitiveRequestData: true); + + output.Should().Be(CERTInextClient.RedactCredentials(input)); + output.Should().Contain("\"additionalDomains\":[\"a.example.com\",\"alice@example.com\",\"10.0.0.1\"]"); + } + + [Fact] + public void RedactPersonalData_HandWrittenWhitespaceInSanArray_MasksEmailAndKeepsLayout() + { + string input = "{ \"additionalDomains\" :\n [ \"a.example.com\" ,\n \"alice@example.com\",\"10.0.0.1\" ] }"; + + string output = CERTInextClient.RedactPersonalData(input); + + output.Should().Be("{ \"additionalDomains\" :\n [ \"a.example.com\" ,\n \"a***@example.com\",\"10.0.0.1\" ] }"); + } + + [Fact] + public void RedactPersonalData_SanArrayKeyMatch_IsCaseInsensitive() + { + CERTInextClient.RedactPersonalData("{\"AdditionalDomains\":[\"alice@example.com\"]}") + .Should().Be("{\"AdditionalDomains\":[\"a***@example.com\"]}"); + } + + [Fact] + public void RedactPersonalData_EscapedEmailElement_IsMasked() + { + // Elements using JSON unicode escapes (backslash-u0040 for '@', backslash-u0069 for 'i') + // must still be detected and masked. + CERTInextClient.RedactPersonalData("{\"additionalDomains\":[\"alice\\u0040example.com\",\"al\\u0069ce@example.com\"]}") + .Should().Be("{\"additionalDomains\":[\"a***@example.com\",\"a***@example.com\"]}"); + } + + [Fact] + public void RedactPersonalData_V2SanArrays_MaskEmailElements_DefenceInDepth() + { + // V2 filters these to DNS/IP before submission; a mis-typed email must still be masked, + // and DNS/IP values must be untouched. + CERTInextClient.RedactPersonalData("{\"certificate\":{\"domain\":\"example.com\",\"additionalDomains\":[\"www.example.com\",\"bob@example.com\"]}}") + .Should().Be("{\"certificate\":{\"domain\":\"example.com\",\"additionalDomains\":[\"www.example.com\",\"b***@example.com\"]}}"); + CERTInextClient.RedactPersonalData("{\"hostname\":\"h.acme.local\",\"additionalHosts\":[\"10.0.0.50\",\"bob@acme.local\",\"::1\"]}") + .Should().Be("{\"hostname\":\"h.acme.local\",\"additionalHosts\":[\"10.0.0.50\",\"b***@acme.local\",\"::1\"]}"); + } + + [Fact] + public void RedactPersonalData_UnrelatedArraysAndValuesWithAt_AreUntouched() + { + // Only the named SAN containers are touched. An '@' in any other array, object key or + // string value is left as it is. + string input = "{\"notifyList\":[\"alice@example.com\"],\"tags\":[\"x@y\"],\"note\":\"ping bob@example.com\"," + + "\"customFields\":{\"owner@example.com\":\"v\"},\"additionalDomains\":[\"a.example.com\"]}"; + + CERTInextClient.RedactPersonalData(input).Should().Be(input); + } + + [Fact] + public void RedactPersonalData_NestedContainersInsideSanArray_AreNotDescendedInto() + { + // Only direct string elements of the array are candidates. + string input = "{\"additionalDomains\":[[\"alice@example.com\"],{\"k\":\"bob@example.com\"},\"carol@example.com\"]}"; + + CERTInextClient.RedactPersonalData(input) + .Should().Be("{\"additionalDomains\":[[\"alice@example.com\"],{\"k\":\"bob@example.com\"},\"c***@example.com\"]}"); + } + + // V1 TrackOrder wire shape per the spec: domainVerification is keyed by domain name, with a + // block-level "status". An email SAN submitted in additionalDomains comes back as one of + // these keys. + private const string V1TrackOrderResponseWithEmailDomainKey = + "{\"meta\":{\"status\":\"1\"},\"orderDetails\":{\"orderStatus\":\"Pending\"," + + "\"domainVerification\":{" + + "\"example.com\":{\"dcvMethod\":\"DNS\",\"dcvStatus\":\"1\",\"status\":\"1\",\"verifiedDate\":\"2026-09-01\",\"caaStatus\":\"1\"}," + + "\"san-probe@example.com\":{\"dcvMethod\":\"\",\"dcvStatus\":\"0\",\"status\":\"1\",\"verifiedDate\":\"\",\"caaStatus\":\"1\"}," + + "\"192.0.2.10\":{\"dcvMethod\":\"\",\"dcvStatus\":\"0\",\"status\":\"1\",\"verifiedDate\":\"\",\"caaStatus\":\"1\"}," + + "\"status\":\"0\"}," + + "\"customFields\":{\"owner@example.com\":\"kept\"}}}"; + + [Fact] + public void ApplyLoggingRedaction_V1TrackOrderDomainVerification_FlagOff_MasksEmailKeyOnly() + { + string output = CERTInextClient.ApplyLoggingRedaction(V1TrackOrderResponseWithEmailDomainKey, logSensitiveRequestData: false); + + output.Should().Be(V1TrackOrderResponseWithEmailDomainKey.Replace("\"san-probe@example.com\":", "\"s***@example.com\":")); + + // The masked body still deserializes into the real DTO and keeps the DNS/IP entries. + var parsed = JsonSerializer.Deserialize(output, ClientEquivalentJsonOptions()); + var domainVerification = parsed?.OrderDetails?.DomainVerification; + domainVerification.Should().NotBeNull(); + domainVerification!.GetDomainEntries().Keys.Should().BeEquivalentTo(new[] { "example.com", "s***@example.com", "192.0.2.10" }); + domainVerification.Status.Should().Be("0"); + } + + [Fact] + public void ApplyLoggingRedaction_V1TrackOrderDomainVerification_FlagOn_Verbatim() + { + CERTInextClient.ApplyLoggingRedaction(V1TrackOrderResponseWithEmailDomainKey, logSensitiveRequestData: true) + .Should().Be(V1TrackOrderResponseWithEmailDomainKey); + } + + [Fact] + public void RedactPersonalData_DomainVerificationPrettyPrinted_MasksEmailKey() + { + string input = "{\n \"domainVerification\" : {\n \"alice@example.com\" : { \"dcvStatus\" : \"0\" },\n \"status\" : \"0\"\n }\n}"; + + CERTInextClient.RedactPersonalData(input) + .Should().Be("{\n \"domainVerification\" : {\n \"a***@example.com\" : { \"dcvStatus\" : \"0\" },\n \"status\" : \"0\"\n }\n}"); + } + + [Theory] + [InlineData("{\"additionalDomains\":[\"a.example.com\",\"alice@example.com\",\"bob@ex")] + [InlineData("{\"additionalDomains\":[")] + [InlineData("{\"additionalDomains\":[\"alice@example.com\"")] + [InlineData("{\"domainVerification\":{\"alice@example.com\":{\"dcvStatus\":")] + [InlineData("{\"additionalDomains\":[\"alice@example.com\",,]} trailing @ garbage")] + [InlineData("{not json at all @ }")] + [InlineData("[\"@\"")] + [InlineData("contact admin@example.com")] + [InlineData("additionalDomains=alice@example.com&x=1")] + [InlineData(" ")] + public void RedactPersonalData_MalformedOrTruncatedBody_DoesNotThrow(string input) + { + System.Func act = () => CERTInextClient.RedactPersonalData(input); + act.Should().NotThrow(); + System.Func act2 = () => CERTInextClient.ApplyLoggingRedaction(input, logSensitiveRequestData: false); + act2.Should().NotThrow(); + } + + // JSON string values can contain escaped quotes and backslashes. A scrubber that stops at the + // first '"' it sees leaks everything after the escape into the log. Values below are synthetic. + [Theory] + [InlineData( + "{\"requestorName\":\"Jane \\\"JD\\\" Doe\"}", + "{\"requestorName\":\"***REDACTED***\"}")] + [InlineData( + "{\"requestorName\":\"Jane \\\"JD\\\" Doe\",\"requestorDesignation\":\"Eng\"}", + "{\"requestorName\":\"***REDACTED***\",\"requestorDesignation\":\"***REDACTED***\"}")] + [InlineData( + "{\"signerPlace\":\"C:\\\\Users\\\\jdoe\",\"other\":\"keep\"}", + "{\"signerPlace\":\"***REDACTED***\",\"other\":\"keep\"}")] + [InlineData( + "{\"pocLastName\":\"Doe\\\\\",\"other\":\"keep\"}", + "{\"pocLastName\":\"***REDACTED***\",\"other\":\"keep\"}")] + [InlineData( + "{\"pocFirstName\":\"\\\"\",\"other\":\"keep\"}", + "{\"pocFirstName\":\"***REDACTED***\",\"other\":\"keep\"}")] + public void RedactPersonalData_RedactsOtherFieldValuesContainingEscapes(string input, string expected) + { + CERTInextClient.RedactPersonalData(input).Should().Be(expected); + } + + [Fact] + public void RedactPersonalData_EmailValueContainingEscapedQuote_IsMaskedWithoutLeakingTail() + { + string actual = CERTInextClient.RedactPersonalData( + "{\"requestorEmail\":\"jane\\\"TAILSECRET\\\"@example.com\",\"other\":\"keep\"}"); + actual.Should().NotContain("TAILSECRET"); + actual.Should().Contain("\"other\":\"keep\""); + } + + [Fact] + public void RedactPersonalData_EmptyValues_AreLeftUntouchedByEscapeAwareMatching() + { + string input = "{\"requestorName\":\"\",\"requestorEmail\":\"\"}"; + CERTInextClient.RedactPersonalData(input).Should().Be(input); + } + + [Fact] + public void ApplyLoggingRedaction_EscapedQuotesInCredentialAndPii_NeitherLeaks() + { + string input = "{\"authKey\":\"ab\\\"AUTHTAIL\",\"requestorName\":\"Jane \\\"JD\\\" PIITAIL\"}"; + + CERTInextClient.ApplyLoggingRedaction(input, logSensitiveRequestData: false) + .Should().Be("{\"authKey\":\"***REDACTED***\",\"requestorName\":\"***REDACTED***\"}"); + + // Credentials are scrubbed even when PII logging is opted in; the PII is left as sent. + string credsOnly = CERTInextClient.ApplyLoggingRedaction(input, logSensitiveRequestData: true); + credsOnly.Should().NotContain("AUTHTAIL"); + credsOnly.Should().Contain("PIITAIL"); + } + + [Fact] + public void RedactPersonalData_TruncatedBody_MasksElementsSeenBeforeTheFault() + { + // A body cut off mid-array keeps the masks for the complete elements before the cut. + // The partial last element is not a complete token, so it is left as it was. + CERTInextClient.RedactPersonalData("{\"additionalDomains\":[\"a.example.com\",\"alice@example.com\",\"bob@ex") + .Should().Be("{\"additionalDomains\":[\"a.example.com\",\"a***@example.com\",\"bob@ex"); + } + + [Fact] + public void RedactPersonalData_NonJsonBody_IsReturnedUnchanged() + { + string input = "additionalDomains=alice@example.com&x=1"; + CERTInextClient.RedactPersonalData(input).Should().Be(input); + } + } +} diff --git a/CERTInext.Tests/RenewalPickupDcvTests.cs b/CERTInext.Tests/RenewalPickupDcvTests.cs new file mode 100644 index 0000000..8f37b30 --- /dev/null +++ b/CERTInext.Tests/RenewalPickupDcvTests.cs @@ -0,0 +1,282 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Linq; +using System.Reflection; +using System.Text.Json; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.Logging; +using Keyfactor.PKI.Enums.EJBCA; +using Microsoft.Extensions.Logging; +using Moq; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Finding 5: on a DCV-enabled deployment a renewal that is waiting on DNS-01 validation cannot + /// reach GENERATED inside the synchronous pickup window — the renew path never runs DCV in the + /// call, only sync-driven DCV does. Pickup (~55s by default) must therefore be skipped for such + /// a renewal (pending result carrying the new order number), while every renewal that can still + /// issue promptly keeps the pickup benefit. A failure of the DCV-state check must never fail the + /// renewal (the order is already placed — issue 0077). + /// + [Collection(LoggingStateCollection.Name)] + public class RenewalPickupDcvTests + { + private const string PriorOrder = "ORD-PRIOR-001"; + private const string NewOrder = "ORD-RENEW-002"; + private const string Domain = "renew.example.com"; + + private sealed class CapturingLoggerProvider : ILoggerProvider + { + public ConcurrentQueue<(LogLevel Level, string Message)> Entries { get; } = new(); + public ILogger CreateLogger(string categoryName) => new CapturingLogger(Entries); + public void Dispose() { } + + private sealed class CapturingLogger : ILogger + { + private readonly ConcurrentQueue<(LogLevel, string)> _entries; + public CapturingLogger(ConcurrentQueue<(LogLevel, string)> entries) => _entries = entries; + public IDisposable BeginScope(TState state) => null; + public bool IsEnabled(LogLevel logLevel) => true; + public void Log(LogLevel logLevel, EventId eventId, TState state, Exception exception, + Func formatter) => _entries.Enqueue((logLevel, formatter(state, exception))); + } + } + + // One pickup poll, 1s apart: the smallest real pickup window (InitialDelaySeconds is a + // fixed 5s), so the "pickup still runs" cases cost ~6s each. + private static CERTInextConfig Config(bool dcvEnabled = false) => new CERTInextConfig + { + PickupRetries = 1, + PickupDelayInSeconds = 1, + DcvEnabled = dcvEnabled, + DcvPropagationDelaySeconds = 1, + DcvTimeoutMinutes = 1, + DcvWaitForChallengeSeconds = 0, + DcvWaitForIssuanceSeconds = 0 + }; + + private static Mock Reader() + { + var reader = new Mock(); + reader.Setup(r => r.GetRequestIDBySerialNumber(It.IsAny())).ReturnsAsync(PriorOrder); + reader.Setup(r => r.GetExpirationDateByRequestId(PriorOrder)).Returns(DateTime.UtcNow.AddDays(30)); + return reader; + } + + private static Mock RenewedOrderMock() + { + var mock = new Mock(MockBehavior.Strict); + mock.Setup(c => c.RenewCertificateAsync(PriorOrder, It.IsAny(), It.IsAny())) + .ReturnsAsync(MockCertificateData.PendingEnrollResponse(NewOrder)); + return mock; + } + + private static void SetupPickupIssues(Mock mock) => + mock.Setup(c => c.GetCertificateAsync(NewOrder, It.IsAny())) + .ReturnsAsync(MockCertificateData.IssuedCertRecord(NewOrder)); + + private static EnrollmentProductInfo ProductInfo() => new EnrollmentProductInfo + { + ProductID = MockCertificateData.ProfileIdTls, + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProfileId"] = MockCertificateData.ProfileIdTls, + ["PriorCertSN"] = "AABB", + ["RenewalWindowDays"] = "90" + } + }; + + private static async Task<(EnrollmentResult Result, IReadOnlyList<(LogLevel Level, string Message)> Logs)> RenewAsync( + Mock mock, Mock reader, CERTInextConfig config, bool withDcvFactory) + { + var provider = new CapturingLoggerProvider(); + var factory = LoggerFactory.Create(b => b.AddProvider(provider).SetMinimumLevel(LogLevel.Trace)); + try + { + LogHandler.Factory = factory; + // Constructed after the swap so the plugin's per-instance logger resolves through it. + CERTInextCAPlugin plugin; +#if SUPPORTS_DCV + if (withDcvFactory) + { + plugin = new CERTInextCAPlugin(mock.Object, new FakeDomainValidatorFactory(new FakeDomainValidator()), config); + // The DCV test constructor takes no certificate-data reader; inject it directly. + typeof(CERTInextCAPlugin) + .GetField("_certificateDataReader", BindingFlags.Instance | BindingFlags.NonPublic)! + .SetValue(plugin, reader.Object); + } + else +#endif + { + plugin = new CERTInextCAPlugin(mock.Object, reader.Object, config); + } + + var result = await plugin.Enroll( + MockCertificateData.FakeCsrPem, $"CN={Domain}", + new Dictionary { ["dns"] = new[] { Domain } }, + ProductInfo(), RequestFormat.PKCS10, EnrollmentType.RenewOrReissue); + + // Guard: the renewal API path (not the new-enroll fallback) produced the order. + reader.Verify(r => r.GetExpirationDateByRequestId(PriorOrder), Times.Once); + return (result, provider.Entries.ToList()); + } + finally + { + LogHandler.Factory = Microsoft.Extensions.Logging.Abstractions.NullLoggerFactory.Instance; + factory.Dispose(); + } + } + + [Fact] + public async Task Renewal_DcvDisabled_PickupStillRuns_AndNeverChecksDcvState() + { + var mock = RenewedOrderMock(); + SetupPickupIssues(mock); + + var (result, _) = await RenewAsync(mock, Reader(), Config(dcvEnabled: false), withDcvFactory: false); + + result.CARequestID.Should().Be(NewOrder); + result.Status.Should().Be((int)EndEntityStatus.GENERATED); + result.Certificate.Should().NotBeNullOrEmpty(); + mock.Verify(c => c.GetCertificateAsync(NewOrder, It.IsAny()), Times.Once); + mock.Verify(c => c.TrackOrderAsync(It.IsAny(), It.IsAny()), Times.Never); + } + +#if SUPPORTS_DCV + [Fact] + public async Task Renewal_PendingDnsDcvDomain_SkipsPickup_ReturnsPendingWithNewOrderNumber() + { + var mock = RenewedOrderMock(); + mock.Setup(c => c.TrackOrderAsync(NewOrder, It.IsAny())) + .ReturnsAsync(MockCertificateData.DcvPendingTrackResponse(NewOrder, Domain)); + + var (result, logs) = await RenewAsync(mock, Reader(), Config(dcvEnabled: true), withDcvFactory: true); + + result.CARequestID.Should().Be(NewOrder); + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + result.Certificate.Should().BeNull(); + mock.Verify(c => c.GetCertificateAsync(It.IsAny(), It.IsAny()), Times.Never, + "an order waiting on DNS-01 cannot issue inside the pickup window"); + logs.Should().Contain(l => l.Level == LogLevel.Information + && l.Message.Contains(NewOrder) && l.Message.Contains("pickup skipped"), + "the skip must be explained at Information"); + } + + [Fact] + public async Task Renewal_DcvEnabled_NoPendingDcv_PickupStillRuns() + { + // Domain validation reused from the prior order: every domain already validated. + var mock = RenewedOrderMock(); + mock.Setup(c => c.TrackOrderAsync(NewOrder, It.IsAny())) + .ReturnsAsync(MockCertificateData.DcvVerifiedTrackResponse(NewOrder, Domain)); + SetupPickupIssues(mock); + + var (result, _) = await RenewAsync(mock, Reader(), Config(dcvEnabled: true), withDcvFactory: true); + + result.CARequestID.Should().Be(NewOrder); + result.Status.Should().Be((int)EndEntityStatus.GENERATED); + result.Certificate.Should().NotBeNullOrEmpty(); + mock.Verify(c => c.GetCertificateAsync(NewOrder, It.IsAny()), Times.Once); + } + + [Fact] + public async Task Renewal_DcvEnabled_NoDomainVerificationBlock_PickupStillRuns() + { + // CERTInext has not exposed domainVerification (e.g. OV/EV or not yet materialized): + // nothing is known to be pending DNS-01, so keep the pickup benefit. + var track = MockCertificateData.DcvPendingTrackResponse(NewOrder, Domain); + track.OrderDetails.DomainVerification = null; + var mock = RenewedOrderMock(); + mock.Setup(c => c.TrackOrderAsync(NewOrder, It.IsAny())).ReturnsAsync(track); + SetupPickupIssues(mock); + + var (result, _) = await RenewAsync(mock, Reader(), Config(dcvEnabled: true), withDcvFactory: true); + + result.Status.Should().Be((int)EndEntityStatus.GENERATED); + mock.Verify(c => c.GetCertificateAsync(NewOrder, It.IsAny()), Times.Once); + } + + [Fact] + public async Task Renewal_DcvEnabled_PendingDomainOnNonDnsMethod_PickupStillRuns() + { + // Only DNS-01 is something the sync-DCV path can complete; a domain assigned to HTTP or + // e-mail validation is out of this check's scope. + var track = MockCertificateData.DcvPendingTrackResponse(NewOrder, Domain); + track.OrderDetails.DomainVerification.RawDomainEntries[Domain] = JsonSerializer.SerializeToElement( + new DomainVerificationDetail + { + DcvMethod = Constants.Dcv.MethodHttpFile, + DcvStatus = Constants.Dcv.StatusPending, + Status = "1" + }); + var mock = RenewedOrderMock(); + mock.Setup(c => c.TrackOrderAsync(NewOrder, It.IsAny())).ReturnsAsync(track); + SetupPickupIssues(mock); + + var (result, _) = await RenewAsync(mock, Reader(), Config(dcvEnabled: true), withDcvFactory: true); + + result.Status.Should().Be((int)EndEntityStatus.GENERATED); + mock.Verify(c => c.GetCertificateAsync(NewOrder, It.IsAny()), Times.Once); + } + + [Fact] + public async Task Renewal_DcvEnabled_TerminalOrderWithStalePendingDomain_PickupStillRuns() + { + // A cancelled/rejected order can keep a stale dcvStatus="0"; pickup surfaces FAILED + // quickly, so it must not be skipped (mirrors the terminal guard in PerformDcvIfNeededAsync). + var track = MockCertificateData.DcvPendingTrackResponse(NewOrder, Domain); + track.OrderDetails.OrderStatusId = "5"; + var mock = RenewedOrderMock(); + mock.Setup(c => c.TrackOrderAsync(NewOrder, It.IsAny())).ReturnsAsync(track); + mock.Setup(c => c.GetCertificateAsync(NewOrder, It.IsAny())) + .ReturnsAsync(new LegacyGetCertificateResponse { Id = NewOrder, Status = "rejected" }); + + var (result, _) = await RenewAsync(mock, Reader(), Config(dcvEnabled: true), withDcvFactory: true); + + result.CARequestID.Should().Be(NewOrder); + mock.Verify(c => c.GetCertificateAsync(NewOrder, It.IsAny()), Times.Once); + } + + [Theory] + [InlineData("exception")] + [InlineData("notfound")] + [InlineData("canceled")] + public async Task Renewal_DcvStateCheckThrows_DoesNotThrow_FallsBackToPickup(string kind) + { + Exception ex = kind switch + { + "notfound" => new KeyNotFoundException($"Order '{NewOrder}' was not found in CERTInext."), + "canceled" => new TaskCanceledException("The request was canceled due to the configured HttpClient.Timeout"), + _ => new Exception("CERTInext error during 'track order' (HTTP 500)") + }; + var mock = RenewedOrderMock(); + mock.Setup(c => c.TrackOrderAsync(NewOrder, It.IsAny())).ThrowsAsync(ex); + SetupPickupIssues(mock); + + var (result, logs) = await RenewAsync(mock, Reader(), Config(dcvEnabled: true), withDcvFactory: true); + + // Falls back to today's behavior: pickup runs and the order is returned, never a throw. + result.CARequestID.Should().Be(NewOrder); + result.Status.Should().Be((int)EndEntityStatus.GENERATED); + mock.Verify(c => c.GetCertificateAsync(NewOrder, It.IsAny()), Times.Once); + logs.Should().Contain(l => l.Level == LogLevel.Warning && l.Message.Contains(NewOrder), + "the swallowed DCV-state check failure must be logged as a Warning naming the order"); + } +#endif + } +} diff --git a/CERTInext.Tests/RequestorDesignationEnrollmentTests.cs b/CERTInext.Tests/RequestorDesignationEnrollmentTests.cs new file mode 100644 index 0000000..efca48e --- /dev/null +++ b/CERTInext.Tests/RequestorDesignationEnrollmentTests.cs @@ -0,0 +1,390 @@ +// Copyright 2026 Keyfactor +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; +using System.Collections.Generic; +using System.Linq; +using System.Text.Json; +using System.Text.Json.Serialization; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Moq; +using Org.BouncyCastle.Asn1.X509; +using Org.BouncyCastle.Crypto; +using Org.BouncyCastle.Crypto.Generators; +using Org.BouncyCastle.Pkcs; +using Org.BouncyCastle.Security; +using WireMock.RequestBuilders; +using WireMock.ResponseBuilders; +using WireMock.Server; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Tests that the V2 order body's requestor.designation field is sourced from a + /// connector config field rather than hardcoded (the V2 spec's own example value for this + /// Optional free-text field is "IT Administrator"). V1 does not send + /// requestorDesignation unless configured — the DTO carries the property. + /// + /// Covers both paths: + /// - V2 ( → EnrollV2Async): exercised end-to-end + /// against a Strict mock, mirroring + /// V2SubscriptionEnrollmentTests / V2TechnicalContactEnrollmentTests. + /// - V1 ( / + /// ): exercised against a WireMock HTTP + /// stub, mirroring CERTInextClientRequestShapeTests, since the V1 wire shape is built + /// by the concrete client rather than behind . + /// + public class RequestorDesignationEnrollmentTests : IDisposable + { + // --------------------------------------------------------------------------- + // V2 — EnrollV2Async wiring: RequestorDesignation config -> Requestor.Designation + // --------------------------------------------------------------------------- + + private static Mock NewMock() => + new Mock(MockBehavior.Strict); + + private static CERTInextConfig BaseV2Config() => new CERTInextConfig + { + UseV2Api = true, + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + RequestorIsdCode = "1", + RequestorMobileNumber = "5550000000", + SignerIp = "1.2.3.4", + SignerPlace = "New York", + PickupRetries = 0 + }; + + private static CERTInextCAPlugin BuildV2Plugin(ICERTInextClient client, CERTInextConfig config) => + new CERTInextCAPlugin(client, config); + + private static EnrollmentProductInfo MakeV2ProductInfo(string productCode, string productVariant) => + new EnrollmentProductInfo + { + ProductID = "DV SSL", + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = productCode, + ["ProductFamily"] = "ssl", + ["ProductVariant"] = productVariant, + ["DomainName"] = "example.com" + } + }; + + private static void StubCatalog(Mock mock, string productCode, string productTypeId) => + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = productCode, ProductTypeId = productTypeId, Active = true } + }); + + private static void StubHappyOrderPlacement(Mock mock, string orderId) + { + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), orderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), orderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = orderId, Status = "pending-dcv" }); + } + + private static string GenerateCsrPem(string cn) + { + var keyGen = new RsaKeyPairGenerator(); + keyGen.Init(new KeyGenerationParameters(new SecureRandom(), 2048)); + AsymmetricCipherKeyPair kp = keyGen.GenerateKeyPair(); + + var csr = new Pkcs10CertificationRequest( + "SHA256withRSA", new X509Name($"CN={cn}"), kp.Public, null, kp.Private); + + return "-----BEGIN CERTIFICATE REQUEST-----\n" + + Convert.ToBase64String(csr.GetEncoded(), Base64FormattingOptions.InsertLineBreaks) + + "\n-----END CERTIFICATE REQUEST-----"; + } + + private static async Task RunV2EnrollAndCaptureOrderAsync( + CERTInextConfig config, string orderId = "ord_desig_001") + { + var mock = NewMock(); + StubCatalog(mock, "842", "13"); // DV SSL (non-UCC) + StubHappyOrderPlacement(mock, orderId); + + V2CreateSslOrderRequest captured = null; + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .Callback((_, __, req, ___) => captured = req) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = orderId, Status = "pending-dcv" }); + + var plugin = BuildV2Plugin(mock.Object, config); + + var result = await plugin.Enroll( + csr: GenerateCsrPem("example.com"), + subject: "CN=example.com", + san: null, + productInfo: MakeV2ProductInfo("842", "dv"), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.CARequestID.Should().Be(orderId); + captured.Should().NotBeNull(); + return captured; + } + + [Theory] + [InlineData(null)] + [InlineData("")] + [InlineData(" ")] + public async Task Enroll_V2_RequestorDesignationBlank_SetsDesignationNull(string configValue) + { + var config = BaseV2Config(); + config.RequestorDesignation = configValue; + + var captured = await RunV2EnrollAndCaptureOrderAsync(config, orderId: "ord_desig_002"); + + captured.Requestor.Should().NotBeNull(); + captured.Requestor.Designation.Should().BeNull( + "a blank/unset RequestorDesignation must leave Requestor.Designation null so the " + + "key is omitted from the wire JSON, instead of sending any default designation value"); + } + + [Fact] + public async Task Enroll_V2_RequestorDesignationSet_SendsTrimmedValue() + { + var config = BaseV2Config(); + config.RequestorDesignation = " PKI Manager "; + + var captured = await RunV2EnrollAndCaptureOrderAsync(config, orderId: "ord_desig_003"); + + captured.Requestor.Designation.Should().Be("PKI Manager", + "a configured RequestorDesignation must be forwarded trimmed of surrounding whitespace"); + } + + // --------------------------------------------------------------------------- + // V2 — DTO serialization: requestor.designation key present/absent on the wire + // + // V2Requestor.Designation carries no per-property [JsonIgnore(WhenWritingNull)] of its + // own; it relies solely on the client's global serializer options + // (CERTInextClient.GetJsonOptions, DefaultIgnoreCondition = WhenWritingNull) to omit it + // when null. GetJsonOptions() is private, so this test builds an equivalent + // JsonSerializerOptions inline to verify that global-option omission actually applies to + // this property, rather than relying on plain JsonSerializer.Serialize (whose default + // options do NOT ignore nulls and would show "designation":null instead of omitting it). + // --------------------------------------------------------------------------- + + private static JsonSerializerOptions ClientEquivalentJsonOptions() => new JsonSerializerOptions + { + PropertyNameCaseInsensitive = true, + DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull + }; + + [Fact] + public void V2Requestor_Serialization_OmitsDesignation_WhenNull() + { + var requestor = new V2Requestor + { + Name = "Jane Doe", + Email = "jane@example.com", + Phone = "+15550000000", + Designation = null + }; + + string json = JsonSerializer.Serialize(requestor, ClientEquivalentJsonOptions()); + + json.Should().NotContain("designation", + "the designation key itself must be absent when unset, not present-but-null, " + + "under the client's actual serializer options"); + } + + [Fact] + public void V2Requestor_Serialization_IncludesDesignation_WhenSet() + { + var requestor = new V2Requestor + { + Name = "Jane Doe", + Email = "jane@example.com", + Phone = "+15550000000", + Designation = "PKI Manager" + }; + + string json = JsonSerializer.Serialize(requestor, ClientEquivalentJsonOptions()); + + json.Should().Contain("\"designation\":\"PKI Manager\""); + } + + // --------------------------------------------------------------------------- + // V1 — BuildOrderRequestFromLegacyEnrollRequest / RenewCertificateAsync wiring: + // RequestorDesignation config -> requestorInformation.requestorDesignation + // + // Uses a WireMock HTTP stub (mirroring CERTInextClientRequestShapeTests) because the V1 + // wire shape is built inside the concrete CERTInextClient, not behind ICERTInextClient. + // RequestorInformation.RequestorDesignation already carries its own + // [JsonIgnore(Condition = WhenWritingNull)] (API/CertificateRequest.cs), so a blank config + // value is expected to omit the key without needing any client-level options change. + // --------------------------------------------------------------------------- + + private readonly WireMockServer _server = WireMockServer.Start(); + + public void Dispose() => _server.Stop(); + + private CERTInextClient BuildV1Client(CERTInextConfig config) + { + config.ApiUrl = _server.Urls[0]; + return new CERTInextClient(config); + } + + private static CERTInextConfig MinimalV1Config() => new CERTInextConfig + { + AuthMode = "AccessKey", + ApiKey = "test-key", + AccountNumber = "12345", + RequestorName = "Default Requestor", + RequestorEmail = "default@example.com", + RequestorIsdCode = "1", + RequestorMobileNumber = "5550000000", + SignerPlace = "Austin", + SignerIp = "203.0.113.10", + PageSize = 100 + }; + + private void StubHappyEnroll() + { + _server.Given(Request.Create().WithPath("/GenerateOrderSSL").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.GenerateOrderSuccessJson(MockCertificateData.OrderNumber1))); + + _server.Given(Request.Create().WithPath("/TrackOrder").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.TrackOrderIssuedJson(MockCertificateData.OrderNumber1))); + + _server.Given(Request.Create().WithPath("/GetCertificate").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.GetCertificateSuccessJson())); + } + + private JsonElement CapturedGenerateOrderSslBody() + { + var generateOrderRequests = _server.LogEntries + .Where(e => e.RequestMessage.Path == "/GenerateOrderSSL") + .ToList(); + generateOrderRequests.Should().HaveCount(1, + "exactly one GenerateOrderSSL POST should have been emitted"); + string body = generateOrderRequests[0].RequestMessage.Body; + body.Should().NotBeNullOrEmpty(); + return JsonDocument.Parse(body!).RootElement.GetProperty("orderDetails"); + } + + private static EnrollCertificateRequest BasicEnrollRequest() => new EnrollCertificateRequest + { + ProfileId = "842", + Csr = MockCertificateData.FakeCsrPem, + Subject = "CN=test.example.com", + Comment = "Unit test" + }; + + [Theory] + [InlineData(null)] + [InlineData("")] + [InlineData(" ")] + public async Task EnrollCertificateAsync_RequestorDesignationBlank_OmitsFieldFromRequestorInformation(string configValue) + { + StubHappyEnroll(); + var cfg = MinimalV1Config(); + cfg.RequestorDesignation = configValue; + + await BuildV1Client(cfg).EnrollCertificateAsync(BasicEnrollRequest()); + + var requestorInfo = CapturedGenerateOrderSslBody().GetProperty("requestorInformation"); + requestorInfo.TryGetProperty("requestorDesignation", out _).Should().BeFalse( + "a blank/unset RequestorDesignation must omit requestorDesignation from the wire " + + "JSON entirely (V1 does not send this field unless configured)"); + } + + [Fact] + public async Task EnrollCertificateAsync_RequestorDesignationSet_SendsTrimmedValue() + { + StubHappyEnroll(); + var cfg = MinimalV1Config(); + cfg.RequestorDesignation = " IT Administrator "; + + await BuildV1Client(cfg).EnrollCertificateAsync(BasicEnrollRequest()); + + var requestorInfo = CapturedGenerateOrderSslBody().GetProperty("requestorInformation"); + requestorInfo.GetProperty("requestorDesignation").GetString().Should().Be("IT Administrator", + "a configured RequestorDesignation must be forwarded trimmed of surrounding whitespace"); + } + + [Theory] + [InlineData(null)] + [InlineData("")] + [InlineData(" ")] + public async Task RenewCertificateAsync_RequestorDesignationBlank_OmitsFieldFromRequestorInformation(string configValue) + { + StubHappyEnroll(); + var cfg = MinimalV1Config(); + cfg.RequestorDesignation = configValue; + + var renewReq = new RenewCertificateRequest + { + Csr = MockCertificateData.FakeCsrPem, + ProfileId = "842", + ValidityDays = 365, + Comment = "Renewal test" + }; + + await BuildV1Client(cfg).RenewCertificateAsync(MockCertificateData.OrderNumber1, renewReq); + + var requestorInfo = CapturedGenerateOrderSslBody().GetProperty("requestorInformation"); + requestorInfo.TryGetProperty("requestorDesignation", out _).Should().BeFalse( + "a blank/unset RequestorDesignation must omit requestorDesignation from renewal " + + "orders too, mirroring the new-enrollment path"); + } + + [Fact] + public async Task RenewCertificateAsync_RequestorDesignationSet_SendsTrimmedValue() + { + StubHappyEnroll(); + var cfg = MinimalV1Config(); + cfg.RequestorDesignation = " PKI Manager "; + + var renewReq = new RenewCertificateRequest + { + Csr = MockCertificateData.FakeCsrPem, + ProfileId = "842", + ValidityDays = 365, + Comment = "Renewal test" + }; + + await BuildV1Client(cfg).RenewCertificateAsync(MockCertificateData.OrderNumber1, renewReq); + + var requestorInfo = CapturedGenerateOrderSslBody().GetProperty("requestorInformation"); + requestorInfo.GetProperty("requestorDesignation").GetString().Should().Be("PKI Manager", + "a configured RequestorDesignation must be forwarded trimmed of surrounding whitespace " + + "on renewal orders too"); + } + } +} diff --git a/CERTInext.Tests/SanLogMaskingTests.cs b/CERTInext.Tests/SanLogMaskingTests.cs new file mode 100644 index 0000000..8d26e20 --- /dev/null +++ b/CERTInext.Tests/SanLogMaskingTests.cs @@ -0,0 +1,319 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Linq; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.Extensions.CAPlugin.CERTInext.Models; +using Keyfactor.Logging; +using Microsoft.Extensions.Logging; +using Moq; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// With LogSensitiveRequestData off, email-type SAN values are + /// masked in log lines (); DNS, IP and URI values stay + /// verbatim. With the flag on, everything is logged in full. + /// + public class LogSanitizerFormatSansTests + { + [Theory] + [InlineData("rfc822name")] + [InlineData("RFC822Name")] + [InlineData("rfc822")] + [InlineData("email")] + public void FormatSanValue_FlagOff_EmailType_IsMasked(string type) + => LogSanitizer.FormatSanValue(type, "alice@example.com", false).Should().Be("a***@example.com"); + + [Theory] + [InlineData("rfc822name")] + [InlineData("email")] + [InlineData("otherName")] + [InlineData(null)] + public void FormatSanValue_FlagOn_IsVerbatim(string type) + => LogSanitizer.FormatSanValue(type, "alice@example.com", true).Should().Be("alice@example.com"); + + [Theory] + [InlineData("dnsname", "www.example.com")] + [InlineData("dns", "www.example.com")] + [InlineData("ipaddress", "192.0.2.10")] + [InlineData("ip", "2001:db8::1")] + [InlineData("uri", "https://example.com/path")] + [InlineData("uri", "https://host.example.com:8443/a/b?q=1#frag")] + [InlineData("uniformresourceidentifier", "urn:example:thing")] + [InlineData("uri", "https://example.com/path/@handle")] + [InlineData("uri", "https://example.com/?contact=a@b.example")] + public void FormatSanValue_DnsIpUri_VerbatimEitherWay(string type, string value) + { + LogSanitizer.FormatSanValue(type, value, false).Should().Be(value); + LogSanitizer.FormatSanValue(type, value, true).Should().Be(value); + } + + [Theory] + [InlineData("uri", "mailto:jane.doe@example.com", "mailto:j***@example.com")] + [InlineData("URI", "MAILTO:jane.doe@example.com", "MAILTO:j***@example.com")] + [InlineData("uniformresourceidentifier", "sip:jane.doe@example.com", "sip:j***@example.com")] + [InlineData("uri", "https://user:pw@host.example.com/", "https://***@host.example.com/")] + [InlineData("uri", "https://user@host.example.com/", "https://***@host.example.com/")] + [InlineData("uri", "ldaps://cn=a:p@ss@host.example.com:636/dc=x?q", "ldaps://***@host.example.com:636/dc=x?q")] + [InlineData("uri", "https://user:pw@host.example.com", "https://***@host.example.com")] + public void FormatSanValue_FlagOff_UriWithAt_IsMasked(string type, string value, string expected) + { + string masked = LogSanitizer.FormatSanValue(type, value, false); + masked.Should().Be(expected); + masked.Should().NotContain("jane.doe").And.NotContain("pw@").And.NotContain("user"); + } + + [Theory] + [InlineData("uri", "mailto:jane.doe@example.com")] + [InlineData("uri", "https://user:pw@host.example.com/")] + [InlineData("uniformresourceidentifier", "https://user@host.example.com/")] + public void FormatSanValue_FlagOn_UriIsVerbatim(string type, string value) + => LogSanitizer.FormatSanValue(type, value, true).Should().Be(value); + + [Fact] + public void FormatSans_Dictionary_FlagOff_MasksUriUserinfoAndMailto() + { + var san = new Dictionary + { + ["uri"] = new[] { "mailto:jane.doe@example.com", "https://user:pw@host.example.com/", "https://example.com" } + }; + + string off = LogSanitizer.FormatSans(san, false); + off.Should().Be("uri:mailto:j***@example.com; uri:https://***@host.example.com/; uri:https://example.com"); + off.Should().NotContain("jane.doe").And.NotContain("pw"); + LogSanitizer.FormatSans(san, true).Should().Contain("uri:mailto:jane.doe@example.com") + .And.Contain("uri:https://user:pw@host.example.com/"); + } + + [Fact] + public void FormatUntypedSans_FlagOff_UriWithAt_LeaksNoLocalPartOrUserinfo() + { + string line = LogSanitizer.FormatUntypedSans( + new[] { "mailto:jane.doe@example.com", "https://user:pw@host.example.com/", "https://example.com/x" }, false); + line.Should().NotContain("jane.doe").And.NotContain("user").And.NotContain("pw@") + .And.Contain("https://example.com/x"); + } + + [Theory] + [InlineData("upn")] + [InlineData(null)] + public void FormatSanValue_FlagOff_UnknownTypeWithAt_IsMasked(string type) + => LogSanitizer.FormatSanValue(type, "bob@corp.example.com", false).Should().Be("b***@corp.example.com"); + + [Fact] + public void FormatSanValue_FlagOff_UnknownTypeWithoutAt_IsVerbatim() + => LogSanitizer.FormatSanValue("upn", "host.example.com", false).Should().Be("host.example.com"); + + [Theory] + [InlineData(null)] + [InlineData("")] + public void FormatSanValue_NullOrEmptyValue_ReturnedAsIs(string value) + { + LogSanitizer.FormatSanValue("rfc822name", value, false).Should().Be(value); + LogSanitizer.FormatSanValue(null, value, false).Should().Be(value); + } + + [Fact] + public void FormatSans_Dictionary_FlagOff_MasksOnlyEmail() + { + var san = new Dictionary + { + ["dnsname"] = new[] { "a.example.com", "b.example.com" }, + ["ipaddress"] = new[] { "192.0.2.10" }, + ["rfc822name"] = new[] { "alice@example.com" }, + ["uri"] = new[] { "https://example.com" } + }; + + LogSanitizer.FormatSans(san, false).Should().Be( + "dnsname:a.example.com; dnsname:b.example.com; ipaddress:192.0.2.10; " + + "rfc822name:a***@example.com; uri:https://example.com"); + LogSanitizer.FormatSans(san, true).Should().Contain("rfc822name:alice@example.com"); + } + + [Fact] + public void FormatSans_Dictionary_NullOrEmpty_ReturnsNone() + { + LogSanitizer.FormatSans((Dictionary)null, false).Should().Be("(none)"); + LogSanitizer.FormatSans(new Dictionary(), false).Should().Be("(none)"); + LogSanitizer.FormatSans(new Dictionary { ["dnsname"] = null }, false).Should().Be("(none)"); + } + + [Fact] + public void FormatSans_SanEntries_FlagOff_MasksEmail_SkipsNullEntries() + { + var sans = new List + { + new SanEntry { Type = "dns", Value = "a.example.com" }, + null, + new SanEntry { Type = "email", Value = "alice@example.com" } + }; + + LogSanitizer.FormatSans(sans, false).Should().Be("dns:a.example.com; email:a***@example.com"); + LogSanitizer.FormatSans(sans, true).Should().Be("dns:a.example.com; email:alice@example.com"); + LogSanitizer.FormatSans((IEnumerable)null, false).Should().Be("(none)"); + } + + [Fact] + public void FormatSans_StillStripsControlCharacters() + => LogSanitizer.FormatSans(new Dictionary { ["dnsname"] = new[] { "a.example.com\nforged" } }, false) + .Should().Be("dnsname:a.example.com\\nforged"); + + [Fact] + public void FormatUntypedSans_FlagOff_MasksAtValuesOnly() + { + var values = new[] { "a.example.com", "alice@example.com", "192.0.2.10" }; + LogSanitizer.FormatUntypedSans(values, false).Should().Be("a.example.com; a***@example.com; 192.0.2.10"); + LogSanitizer.FormatUntypedSans(values, true).Should().Be("a.example.com; alice@example.com; 192.0.2.10"); + LogSanitizer.FormatUntypedSans(values, false, ", ").Should().Be("a.example.com, a***@example.com, 192.0.2.10"); + } + + [Fact] + public void FormatUntypedSans_NullOrEmpty_ReturnsNone() + { + LogSanitizer.FormatUntypedSans(null, false).Should().Be("(none)"); + LogSanitizer.FormatUntypedSans(Array.Empty(), false).Should().Be("(none)"); + } + } + + /// + /// Plugin-level log capture for SAN log masking: the "Enrollment attempt started" + /// line and BuildSanList's "Resolved N SAN(s)" / "submitted rather than dropped" lines + /// must mask an email SAN with LogSensitiveRequestData off and log it in full with it + /// on. Same swap seam and non-parallel collection as + /// ; only lines carrying this call's unique + /// subject marker are considered. + /// + [Collection(LoggingStateCollection.Name)] + public class SanLogMaskingPluginTests + { + private const string EmailSan = "alice@example.com"; + private const string MaskedEmailSan = "a***@example.com"; + private const string IpSan = "192.0.2.10"; + + private sealed class CapturingLoggerProvider : ILoggerProvider + { + public ConcurrentQueue Messages { get; } = new(); + public ILogger CreateLogger(string categoryName) => new CapturingLogger(Messages); + public void Dispose() { } + + private sealed class CapturingLogger : ILogger + { + private readonly ConcurrentQueue _messages; + public CapturingLogger(ConcurrentQueue messages) => _messages = messages; + public IDisposable BeginScope(TState state) => null; + public bool IsEnabled(LogLevel logLevel) => true; + public void Log(LogLevel logLevel, EventId eventId, TState state, Exception exception, + Func formatter) + => _messages.Enqueue(formatter(state, exception)); + } + } + + private static async Task<(List Messages, string Primary, EnrollCertificateRequest Captured)> EnrollV1Async( + bool logSensitiveRequestData) + { + string marker = "sanmask-" + Guid.NewGuid().ToString("N"); + string primary = marker + ".example.com"; + + EnrollCertificateRequest captured = null; + var mock = new Mock(MockBehavior.Loose); + mock.Setup(c => c.EnrollCertificateAsync(It.IsAny(), It.IsAny())) + .Callback((req, _) => captured = req) + .ReturnsAsync(new EnrollCertificateResponse + { + Id = "ORD-SANMASK", Status = "issued", Certificate = MockCertificateData.FakePemCertificate + }); + + var productInfo = new EnrollmentProductInfo + { + ProductID = "DV SSL", + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = "842" + } + }; + var san = new Dictionary + { + ["dnsname"] = new[] { primary }, + ["ipaddress"] = new[] { IpSan }, + ["rfc822name"] = new[] { EmailSan } + }; + + var provider = new CapturingLoggerProvider(); + var factory = LoggerFactory.Create(b => b.AddProvider(provider).SetMinimumLevel(LogLevel.Trace)); + try + { + LogHandler.Factory = factory; + // Constructed AFTER the swap so _logger resolves through the capturing factory. + var plugin = new CERTInextCAPlugin(mock.Object, new CERTInextConfig + { + PickupRetries = 0, + LogSensitiveRequestData = logSensitiveRequestData + }); + await plugin.Enroll(MockCertificateData.FakeCsrPem, $"CN={primary}", san, productInfo, + RequestFormat.PKCS10, EnrollmentType.New); + } + finally + { + LogHandler.Factory = Microsoft.Extensions.Logging.Abstractions.NullLoggerFactory.Instance; + factory.Dispose(); + } + + return (provider.Messages.Where(m => m != null && m.Contains(marker)).ToList(), primary, captured); + } + + [Fact] + public async Task Enroll_FlagOff_MasksEmailSan_KeepsDnsAndIpVerbatim_WireUnchanged() + { + var (messages, primary, captured) = await EnrollV1Async(logSensitiveRequestData: false); + + var start = messages.Where(m => m.StartsWith("Enrollment attempt started")).ToList(); + start.Should().ContainSingle(); + start[0].Should().Contain($"dnsname:{primary}") + .And.Contain($"ipaddress:{IpSan}") + .And.Contain($"rfc822name:{MaskedEmailSan}") + .And.NotContain(EmailSan); + + var resolved = messages.Where(m => m.StartsWith("Resolved ")).ToList(); + resolved.Should().ContainSingle(); + resolved[0].Should().Contain($"dns:{primary}") + .And.Contain($"ip:{IpSan}") + .And.Contain($"email:{MaskedEmailSan}") + .And.NotContain(EmailSan); + + messages.Should().NotContain(m => m.Contains(EmailSan), + "no plugin log line for this enrollment may carry the unmasked email SAN with the flag off"); + + captured.Should().NotBeNull(); + captured!.Sans.Select(s => s.Value).Should().Contain(EmailSan, + "masking is log-only; the SAN still goes to CERTInext unchanged"); + } + + [Fact] + public async Task Enroll_FlagOn_LogsEmailSanInFull() + { + var (messages, _, captured) = await EnrollV1Async(logSensitiveRequestData: true); + + messages.Where(m => m.StartsWith("Enrollment attempt started")).Should().ContainSingle() + .Which.Should().Contain($"rfc822name:{EmailSan}"); + messages.Where(m => m.StartsWith("Resolved ")).Should().ContainSingle() + .Which.Should().Contain($"email:{EmailSan}"); + messages.Should().NotContain(m => m.Contains(MaskedEmailSan)); + + captured!.Sans.Select(s => s.Value).Should().Contain(EmailSan); + } + } +} diff --git a/CERTInext.Tests/SanSubmissionTests.cs b/CERTInext.Tests/SanSubmissionTests.cs new file mode 100644 index 0000000..83c18eb --- /dev/null +++ b/CERTInext.Tests/SanSubmissionTests.cs @@ -0,0 +1,699 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Generic; +using System.Linq; +using System.Reflection; +using System.Text.Json; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Moq; +using Org.BouncyCastle.Asn1; +using Org.BouncyCastle.Asn1.Pkcs; +using Org.BouncyCastle.Asn1.X509; +using Org.BouncyCastle.Crypto; +using Org.BouncyCastle.Crypto.Generators; +using Org.BouncyCastle.Pkcs; +using Org.BouncyCastle.Security; +using WireMock.RequestBuilders; +using WireMock.ResponseBuilders; +using WireMock.Server; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Tests for UCC SAN submission. + /// + /// The AnyCA REST Gateway keys its SAN dictionary dnsname, so MapSanType + /// must recognize it (as well as dns): otherwise every DNS SAN would be filtered out + /// by the DNS-only test when building certificateInformation.additionalDomains, and + /// the order would reach CERTInext with no additional domains at all — yielding a + /// certificate holding only the CN. Because CERTInext ignores the CSR's subjectAltName + /// extension entirely, SANs present on the CSR do not + /// compensate. + /// + /// The end-to-end tests below drive a real against WireMock + /// so they assert on the JSON actually put on the wire, not on an intermediate object. + /// A test that only checked the mapping function would miss problems in the + /// interaction with the downstream filter that could lose the names. + /// + public class SanSubmissionTests : IDisposable + { + private readonly WireMockServer _server; + + public SanSubmissionTests() + { + _server = WireMockServer.Start(); + StubHappyEnroll(); + } + + public void Dispose() => _server.Stop(); + + // ----------------------------------------------------------------------- + // Harness + // ----------------------------------------------------------------------- + + private void StubHappyEnroll() + { + _server.Given(Request.Create().WithPath("/GenerateOrderSSL").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.GenerateOrderSuccessJson(MockCertificateData.OrderNumber1))); + + _server.Given(Request.Create().WithPath("/TrackOrder").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.TrackOrderIssuedJson(MockCertificateData.OrderNumber1))); + + _server.Given(Request.Create().WithPath("/GetCertificate").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.GetCertificateSuccessJson())); + } + + private CERTInextClient BuildRealClient() => new CERTInextClient(new CERTInextConfig + { + ApiUrl = _server.Urls[0], + AuthMode = "AccessKey", + ApiKey = "test-key", + AccountNumber = "12345", + RequestorName = "Default Requestor", + RequestorEmail = "default@example.com", + RequestorIsdCode = "1", + RequestorMobileNumber = "5550000000", + SignerPlace = "Austin", + SignerIp = "203.0.113.10", + PageSize = 100 + }); + + /// + /// Plugin wired to a real client pointed at WireMock. PickupRetries = 0 is set on + /// the plugin's own config (not the client's) — that is where the synchronous-pickup + /// budget is read, and leaving it at the default would make every test here sit in a + /// polling loop. + /// + private CERTInextCAPlugin BuildPlugin() => + new CERTInextCAPlugin(BuildRealClient(), new CERTInextConfig { PickupRetries = 0 }); + + private static EnrollmentProductInfo MakeProductInfo(string profileId = "842") => + new EnrollmentProductInfo + { + ProductID = profileId, + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProfileId"] = profileId + } + }; + + /// The orderDetails.certificateInformation block actually POSTed. + private JsonElement CapturedCertificateInformation() + { + var posts = _server.LogEntries + .Where(e => e.RequestMessage.Path == "/GenerateOrderSSL") + .ToList(); + posts.Should().HaveCount(1, "exactly one GenerateOrderSSL POST should have been emitted"); + + string body = posts[0].RequestMessage.Body; + body.Should().NotBeNullOrEmpty(); + + return JsonDocument.Parse(body!).RootElement + .GetProperty("orderDetails") + .GetProperty("certificateInformation"); + } + + private static List AdditionalDomains(JsonElement certificateInformation) => + certificateInformation.TryGetProperty("additionalDomains", out var el) + ? el.EnumerateArray().Select(x => x.GetString()).ToList() + : null; + + // ----------------------------------------------------------------------- + // CSR generation (BouncyCastle — project crypto policy) + // ----------------------------------------------------------------------- + + /// + /// Builds a real PKCS#10 CSR for carrying arbitrary + /// in its subjectAltName extension — used to exercise + /// GeneralName types that have no domain-name rendering. + /// + private static string GenerateCsrPemWithGeneralNames(string cn, params GeneralName[] names) + { + var keyGen = new RsaKeyPairGenerator(); + keyGen.Init(new KeyGenerationParameters(new SecureRandom(), 2048)); + AsymmetricCipherKeyPair kp = keyGen.GenerateKeyPair(); + + Asn1Set attributes = null; + if (names != null && names.Length > 0) + { + var extGen = new X509ExtensionsGenerator(); + extGen.AddExtension(X509Extensions.SubjectAlternativeName, critical: false, + extValue: new GeneralNames(names)); + + attributes = new DerSet(new AttributePkcs( + PkcsObjectIdentifiers.Pkcs9AtExtensionRequest, + new DerSet(extGen.Generate()))); + } + + var csr = new Pkcs10CertificationRequest( + "SHA256withRSA", new X509Name($"CN={cn}"), kp.Public, attributes, kp.Private); + + return "-----BEGIN CERTIFICATE REQUEST-----\n" + + Convert.ToBase64String(csr.GetEncoded(), Base64FormattingOptions.InsertLineBreaks) + + "\n-----END CERTIFICATE REQUEST-----"; + } + + /// + /// Builds a real PKCS#10 CSR for , optionally carrying a + /// subjectAltName extension holding . + /// + private static string GenerateCsrPem(string cn, params string[] dnsSans) => + GenerateCsrPemWithGeneralNames( + cn, (dnsSans ?? Array.Empty()).Select(d => new GeneralName(GeneralName.DnsName, d)).ToArray()); + + // ======================================================================= + // End-to-end: Command's SAN dictionary → the JSON on the wire + // ======================================================================= + + /// + /// "dnsname" is the key the real gateway sends (e.g. + /// SANs=dnsname:host.example.com; dnsname:host.ad.example.com); both names must + /// reach additionalDomains. + /// + [Fact] + public async Task GatewayDnsNameKey_ReachesAdditionalDomains() + { + var plugin = BuildPlugin(); + + await plugin.Enroll( + csr: GenerateCsrPem("host.example.com"), + subject: "CN=host.example.com", + san: new Dictionary + { + ["dnsname"] = new[] { "host.example.com", "alt.example.com" } + }, + productInfo: MakeProductInfo(), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + var certInfo = CapturedCertificateInformation(); + certInfo.GetProperty("domainName").GetString().Should().Be("host.example.com"); + + AdditionalDomains(certInfo).Should().BeEquivalentTo(new[] { "alt.example.com" }, + "the extra SAN must reach additionalDomains, and the CN must not be repeated there"); + } + + /// + /// The short "dns" spelling must keep working — some callers and older hosts use it. + /// + [Fact] + public async Task ShortDnsKey_StillReachesAdditionalDomains() + { + var plugin = BuildPlugin(); + + await plugin.Enroll( + csr: GenerateCsrPem("host.example.com"), + subject: "CN=host.example.com", + san: new Dictionary + { + ["dns"] = new[] { "alt.example.com" } + }, + productInfo: MakeProductInfo(), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + AdditionalDomains(CapturedCertificateInformation()) + .Should().BeEquivalentTo(new[] { "alt.example.com" }); + } + + /// + /// SANs present only on the CSR must still reach additionalDomains. CERTInext does not + /// read the CSR's SAN extension, so if we don't forward these the names never appear + /// on the certificate. + /// + [Fact] + public async Task CsrSans_ReachAdditionalDomains_WhenGatewaySuppliesNone() + { + var plugin = BuildPlugin(); + + await plugin.Enroll( + csr: GenerateCsrPem("host.example.com", "host.example.com", "fromcsr.example.com"), + subject: "CN=host.example.com", + san: null, + productInfo: MakeProductInfo(), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + AdditionalDomains(CapturedCertificateInformation()) + .Should().BeEquivalentTo(new[] { "fromcsr.example.com" }); + } + + /// + /// Union, not either/or: names unique to each source survive and the overlap collapses. + /// + [Fact] + public async Task CsrOnlySans_AreIgnored_WhenGatewaySuppliesAnyEntries() + { + // The CSR is not unioned in on top of whatever the gateway supplied: Command's SAN + // dictionary is how an enrollment pattern's SAN policy is expressed, and a signed CSR — + // usually generated by the subscriber's own tooling, not by Command — can legitimately + // carry more names than that policy allows. Unioning them in would re-introduce a name + // the policy excluded. The CSR is consulted only as a fallback when the gateway + // supplies nothing at all (see CsrSans_ReachAdditionalDomains_WhenGatewaySuppliesNone). + var plugin = BuildPlugin(); + + await plugin.Enroll( + csr: GenerateCsrPem("host.example.com", "host.example.com", "csronly.example.com"), + subject: "CN=host.example.com", + san: new Dictionary + { + ["dnsname"] = new[] { "gatewayonly.example.com" } + }, + productInfo: MakeProductInfo(), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + var domains = AdditionalDomains(CapturedCertificateInformation()); + + domains.Should().BeEquivalentTo(new[] { "gatewayonly.example.com" }, + "the gateway supplied a (non-empty) SAN set, so the CSR's own SAN extension must be " + + "ignored entirely, not merged in on top of it"); + } + + /// + /// The CSR-fallback trigger must not be "the gateway dictionary computed to zero + /// added entries", which cannot distinguish "Command never populated SAN data" (the case the + /// fallback exists for) from "Command's enrollment pattern ran and deliberately computed + /// zero SANs for this request" (an explicit policy decision this plugin must respect). A + /// non-null dictionary whose only key maps to an empty array is the latter — the fallback + /// must not engage, even though it computes to the same "0 SANs added" outcome as a null + /// dictionary would. + /// + [Fact] + public async Task CsrSans_AreIgnored_WhenGatewaySuppliesNonNullDictWithOnlyEmptyValues() + { + var plugin = BuildPlugin(); + + await plugin.Enroll( + csr: GenerateCsrPem("host.example.com", "host.example.com", "csronly.example.com"), + subject: "CN=host.example.com", + san: new Dictionary + { + // Non-null dictionary, but the key maps to no values — computes to zero added + // SANs, same as san == null would, but it must NOT be treated the same way. + ["dnsname"] = Array.Empty() + }, + productInfo: MakeProductInfo(), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + AdditionalDomains(CapturedCertificateInformation()).Should().BeNull( + "a non-null gateway SAN dictionary that computes to zero entries must be respected " + + "as Command's own decision, not treated as 'Command supplied nothing' and " + + "backfilled from the CSR"); + } + + /// + /// The CN is already submitted as domainName; repeating it in additionalDomains is + /// suppressed. CERTInext collapses it anyway (measured), so this keeps the body matching + /// what we log rather than relying on undocumented CA-side behaviour. + /// + [Fact] + public async Task Cn_IsNotRepeatedInAdditionalDomains() + { + var plugin = BuildPlugin(); + + await plugin.Enroll( + csr: GenerateCsrPem("host.example.com", "host.example.com"), + subject: "CN=host.example.com", + san: new Dictionary + { + ["dnsname"] = new[] { "host.example.com" } + }, + productInfo: MakeProductInfo(), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + var certInfo = CapturedCertificateInformation(); + certInfo.GetProperty("domainName").GetString().Should().Be("host.example.com"); + AdditionalDomains(certInfo).Should().BeNull( + "with the CN as the only SAN there is nothing left to send, so the field is omitted"); + } + + /// + /// Non-DNS SANs are submitted rather than silently discarded. CERTInext accepts them + /// verbatim (measured) and the resulting order cannot pass validation — a visible + /// failure, deliberately preferred over issuing a certificate that quietly lacks names + /// the subscriber requested. + /// + [Fact] + public async Task NonDnsSans_AreSubmitted_NotDropped() + { + var plugin = BuildPlugin(); + + await plugin.Enroll( + csr: GenerateCsrPem("host.example.com"), + subject: "CN=host.example.com", + san: new Dictionary + { + ["dnsname"] = new[] { "alt.example.com" }, + ["ipaddress"] = new[] { "192.0.2.10" }, + ["rfc822name"] = new[] { "admin@example.com" } + }, + productInfo: MakeProductInfo(), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + AdditionalDomains(CapturedCertificateInformation()) + .Should().BeEquivalentTo(new[] { "alt.example.com", "192.0.2.10", "admin@example.com" }); + } + + /// + /// BuildSanList's audit log must report post-filter counts: with a mixed + /// DNS/non-DNS gateway SAN dictionary and SubmitNonDnsSans=false, the "Resolved N SAN(s)" + /// log line must not report the pre-filter gateway count (3) alongside the post-filter + /// total (1). This pins the payload-level data the log line is computed from: with the + /// non-DNS entries filtered out, exactly the one DNS name must reach additionalDomains — + /// proving the surviving gateway-sourced count is 1, not the pre-filter 3. + /// + [Fact] + public async Task MixedGatewaySans_SubmitNonDnsSansFalse_OnlyDnsNameSurvivesFiltering() + { + var plugin = new CERTInextCAPlugin( + BuildRealClient(), + new CERTInextConfig { PickupRetries = 0, SubmitNonDnsSans = false }); + + await plugin.Enroll( + csr: GenerateCsrPem("host.example.com"), + subject: "CN=host.example.com", + san: new Dictionary + { + ["dnsname"] = new[] { "alt.example.com" }, + ["ipaddress"] = new[] { "192.0.2.10" }, + ["rfc822name"] = new[] { "admin@example.com" } + }, + productInfo: MakeProductInfo(), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + AdditionalDomains(CapturedCertificateInformation()) + .Should().BeEquivalentTo(new[] { "alt.example.com" }, + "only the DNS entry should survive the SubmitNonDnsSans=false filter, out of " + + "3 the gateway supplied"); + } + + /// + /// A CSR we cannot parse must not break enrollment — the gateway-supplied SANs still go. + /// FakeCsrPem is deliberately truncated, so this also guards the many existing + /// tests that pass it. + /// + [Fact] + public async Task UnparseableCsr_DoesNotBlockGatewaySuppliedSans() + { + var plugin = BuildPlugin(); + + await plugin.Enroll( + csr: MockCertificateData.FakeCsrPem, + subject: "CN=host.example.com", + san: new Dictionary + { + ["dnsname"] = new[] { "alt.example.com" } + }, + productInfo: MakeProductInfo(), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + AdditionalDomains(CapturedCertificateInformation()) + .Should().BeEquivalentTo(new[] { "alt.example.com" }); + } + + /// + /// No SANs from either source → the field is omitted rather than emitted as null/empty. + /// + [Fact] + public async Task NoSansAnywhere_OmitsAdditionalDomains() + { + var plugin = BuildPlugin(); + + await plugin.Enroll( + csr: GenerateCsrPem("host.example.com"), + subject: "CN=host.example.com", + san: null, + productInfo: MakeProductInfo(), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + AdditionalDomains(CapturedCertificateInformation()).Should().BeNull(); + } + + // ======================================================================= + // GeneralName types with no domain-name rendering + // ======================================================================= + + /// + /// A UPN otherName and a directoryName must NOT be submitted. + /// + /// GeneralNameToValue must not fall back to BouncyCastle's ASN.1 stringification: a + /// Windows-generated CSR carrying a UPN otherName would otherwise put + /// "[1.3.6.1.4.1.311.20.2.3, [CONTEXT 0]svc@corp.example.com]" into additionalDomains as if + /// it were a domain name. These types cannot become a certificate SAN via a domain-name + /// field at all, which is why they are skipped (with a Warning) rather than submitted the way + /// well-formed IP/email/URI SANs are. + /// + [Fact] + public async Task CsrOtherNameAndDirectoryName_AreNotSubmittedAsDomains() + { + // UPN otherName, as emitted by Windows/AD certificate tooling. + var upn = new GeneralName(GeneralName.OtherName, new DerSequence( + new DerObjectIdentifier("1.3.6.1.4.1.311.20.2.3"), + new DerTaggedObject(true, 0, new DerUtf8String("svc@corp.example.com")))); + + var directoryName = new GeneralName( + GeneralName.DirectoryName, new X509Name("CN=host.example.com,O=Acme")); + + var plugin = BuildPlugin(); + + await plugin.Enroll( + csr: GenerateCsrPemWithGeneralNames( + "host.example.com", + new GeneralName(GeneralName.DnsName, "alt.example.com"), + upn, + directoryName), + subject: "CN=host.example.com", + san: null, + productInfo: MakeProductInfo(), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + var domains = AdditionalDomains(CapturedCertificateInformation()); + + domains.Should().BeEquivalentTo(new[] { "alt.example.com" }, + "only the renderable DNS name may be submitted"); + domains.Should().NotContain(d => d.Contains("1.3.6.1.4.1.311.20.2.3"), + "an otherName must never be submitted as an ASN.1 dump"); + domains.Should().NotContain(d => d.Contains("CONTEXT"), + "BouncyCastle ASN.1 debris must never reach the wire"); + domains.Should().NotContain(d => d.StartsWith("CN=", StringComparison.OrdinalIgnoreCase), + "a directoryName must never be submitted as a domain"); + } + + // ======================================================================= + // Log-injection hardening (CWE-117) + // ======================================================================= + + /// + /// SAN values reach the log from the CSR and from Command's SAN dictionary — i.e. from the + /// requester. Structured message templates stop format-string abuse but not embedded + /// newlines, so a value carrying CRLF could forge audit records in the very log lines added + /// to make the submitted SAN set auditable. LogSanitizer is internal (not private) and + /// shared between the plugin and the client, so this is a direct call, not reflection. + /// + [Theory] + [InlineData("evil.example.com\r\nINFO forged record", "evil.example.com\\r\\nINFO forged record")] + [InlineData("a\nb", "a\\nb")] + [InlineData("a\tb", "a\\tb")] + [InlineData("plain.example.com", "plain.example.com")] + [InlineData("", "")] + [InlineData(null, null)] + public void SanitizeForLog_NeutralizesControlCharacters(string input, string expected) + { + var actual = Keyfactor.Extensions.CAPlugin.CERTInext.Models.LogSanitizer.Strip(input); + + actual.Should().Be(expected); + } + + /// + /// A CRLF-bearing SAN must not break enrollment, and the value is still submitted verbatim — + /// the scrub is a logging concern and deliberately does not mutate the payload sent to the CA. + /// + [Fact] + public async Task SanValueWithCrLf_DoesNotBreakEnrollment() + { + var plugin = BuildPlugin(); + + await plugin.Enroll( + csr: GenerateCsrPem("host.example.com"), + subject: "CN=host.example.com", + san: new Dictionary + { + ["dnsname"] = new[] { "alt.example.com\r\nforged log line" } + }, + productInfo: MakeProductInfo(), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + AdditionalDomains(CapturedCertificateInformation()) + .Should().ContainSingle().Which.Should().Contain("alt.example.com"); + } + + // ======================================================================= + // SubmitNonDnsSans escape hatch + // ======================================================================= + + /// + /// Submitting non-DNS SANs flips affected enrollments from "issues, silently missing the + /// name" to "parks pending". SubmitNonDnsSans=false restores the pre-1.0.1 behaviour so an + /// upgraded host has a way back that isn't a plugin downgrade. + /// + [Fact] + public async Task SubmitNonDnsSansFalse_SubmitsDnsNamesOnly() + { + var plugin = new CERTInextCAPlugin( + BuildRealClient(), + new CERTInextConfig { PickupRetries = 0, SubmitNonDnsSans = false }); + + await plugin.Enroll( + csr: GenerateCsrPem("host.example.com"), + subject: "CN=host.example.com", + san: new Dictionary + { + ["dnsname"] = new[] { "alt.example.com" }, + ["ipaddress"] = new[] { "192.0.2.10" }, + ["rfc822name"] = new[] { "admin@example.com" } + }, + productInfo: MakeProductInfo(), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + AdditionalDomains(CapturedCertificateInformation()) + .Should().BeEquivalentTo(new[] { "alt.example.com" }, + "with the switch off, only DNS names are submitted"); + } + + /// + /// The switch defaults to true, so the documented default behaviour is pinned independently + /// of any test that sets it explicitly. + /// + [Fact] + public void SubmitNonDnsSans_DefaultsToTrue() + { + new CERTInextConfig().SubmitNonDnsSans.Should().BeTrue(); + } + + /// + /// BuildSanList must not log "N SAN(s) ... have been added to the order" for CSR-fallback + /// entries and then filter exactly those entries back out when SubmitNonDnsSans is false — + /// a self-contradicting claim in the same call. The method filters first and logs the + /// final result, which this test exercises functionally: with the gateway supplying nothing (so the CSR fallback + /// engages) and a non-DNS CSR SAN present, SubmitNonDnsSans=false must still result in that + /// name being genuinely absent from the wire, not merely mis-described in the log. + /// + [Fact] + public async Task CsrFallbackNonDnsSan_IsExcluded_WhenSubmitNonDnsSansFalse() + { + var plugin = new CERTInextCAPlugin( + BuildRealClient(), + new CERTInextConfig { PickupRetries = 0, SubmitNonDnsSans = false }); + + await plugin.Enroll( + csr: GenerateCsrPemWithGeneralNames( + "host.example.com", + new GeneralName(GeneralName.DnsName, "host.example.com"), + new GeneralName(GeneralName.DnsName, "alt.example.com"), + new GeneralName(GeneralName.Rfc822Name, "admin@example.com")), + subject: "CN=host.example.com", + san: null, + productInfo: MakeProductInfo(), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + AdditionalDomains(CapturedCertificateInformation()) + .Should().BeEquivalentTo(new[] { "alt.example.com" }, + "the CSR-fallback email SAN must be genuinely absent from the order, not just " + + "misreported as present"); + } + + // ======================================================================= + // Renew path — SANs are carried onto the renewal order + // ======================================================================= + + /// + /// A renewal that goes through the CERTInext renew API must carry the same domain set + /// as a new enrollment, and must take its primary domain from the subject's CN rather + /// than from the prior order's requestor name. + /// + [Fact] + public async Task RenewalRequest_CarriesSubjectAndSans() + { + var clientMock = new Mock(MockBehavior.Loose); + RenewCertificateRequest captured = null; + + clientMock + .Setup(c => c.RenewCertificateAsync( + It.IsAny(), + It.IsAny(), + It.IsAny())) + .Callback((_, req, __) => captured = req) + .ReturnsAsync(MockCertificateData.IssuedEnrollResponse()); + + var readerMock = new Mock(MockBehavior.Loose); + readerMock + .Setup(r => r.GetRequestIDBySerialNumber(It.IsAny())) + .ReturnsAsync("PRIOR-ORDER-1"); + + // The renewal-window decision reads expiry from the data reader, not from the CA. + // Put the prior cert 10 days out so it lands inside the 30-day window below and the + // renew API path is actually taken. + readerMock + .Setup(r => r.GetExpirationDateByRequestId(It.IsAny())) + .Returns(DateTime.UtcNow.AddDays(10)); + + var plugin = new CERTInextCAPlugin(clientMock.Object, readerMock.Object); + + var productInfo = MakeProductInfo(); + productInfo.ProductParameters["PriorCertSN"] = "AABBCCDDEEFF"; + productInfo.ProductParameters["RenewalWindowDays"] = "30"; + + await plugin.Enroll( + csr: GenerateCsrPem("host.example.com", "host.example.com", "alt.example.com"), + subject: "CN=host.example.com", + san: new Dictionary + { + ["dnsname"] = new[] { "host.example.com", "alt.example.com" } + }, + productInfo: productInfo, + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.Renew); + + captured.Should().NotBeNull("the renew API path should have been taken"); + + // Bind to a local so the compiler's null-flow analysis is satisfied — a + // FluentAssertions NotBeNull() does not narrow the nullable reference. + RenewCertificateRequest renewReq = captured!; + + renewReq.Subject.Should().Be("CN=host.example.com", + "without the subject the renewal order has no usable primary domain"); + renewReq.Sans.Should().NotBeNull("renewals must carry the SANs onto the renewal order"); + renewReq.Sans.Select(s => s.Value) + .Should().BeEquivalentTo(new[] { "host.example.com", "alt.example.com" }); + } + } +} diff --git a/CERTInext.Tests/SensitiveRequestDataConfigTests.cs b/CERTInext.Tests/SensitiveRequestDataConfigTests.cs new file mode 100644 index 0000000..25dac06 --- /dev/null +++ b/CERTInext.Tests/SensitiveRequestDataConfigTests.cs @@ -0,0 +1,78 @@ +// Copyright 2026 Keyfactor +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using FluentAssertions; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// LogSensitiveRequestData is an opt-in CA connector setting, off by + /// default, that gates whether requestor personal data and full CA request/response bodies + /// are written to gateway logs. + /// + public class SensitiveRequestDataConfigTests + { + [Fact] + public void CERTInextConfig_DefaultsToFalse() + { + new CERTInextConfig().LogSensitiveRequestData.Should().BeFalse( + "sensitive-data logging must be opt-in, not opt-out"); + } + + [Fact] + public void GetCAConnectorAnnotations_ContainsLogSensitiveRequestData() + { + var annotations = CERTInextCAPluginConfig.GetCAConnectorAnnotations(); + + annotations.Should().ContainKey(Constants.Config.LogSensitiveRequestData); + + var annotation = annotations[Constants.Config.LogSensitiveRequestData]; + annotation.Type.Should().Be("Boolean"); + annotation.DefaultValue.Should().Be(false); + annotation.Comments.Should().ContainAll("name", "email", "phone", + "temporary", "Credentials"); + } + + [Fact] + public void Constants_LogSensitiveRequestData_MatchesJsonPropertyName() + { + // The Dictionary key used by the Command UI/connector config must match the + // [JsonPropertyName] on CERTInextConfig for the round-trip through + // JsonSerializer.Serialize(configProvider.CAConnectionData) / + // JsonSerializer.Deserialize in Initialize() to work. + Constants.Config.LogSensitiveRequestData.Should().Be("LogSensitiveRequestData"); + } + + [Fact] + public void CERTInextConfig_DeserializesLogSensitiveRequestData_WhenTrue() + { + string json = "{\"LogSensitiveRequestData\": true}"; + var config = System.Text.Json.JsonSerializer.Deserialize(json); + + config.Should().NotBeNull(); + config!.LogSensitiveRequestData.Should().BeTrue(); + } + + [Fact] + public void CERTInextConfig_DeserializesLogSensitiveRequestData_OmittedField_DefaultsFalse() + { + string json = "{\"ApiUrl\": \"https://ca.example.com\"}"; + var config = System.Text.Json.JsonSerializer.Deserialize(json); + + config.Should().NotBeNull(); + config!.LogSensitiveRequestData.Should().BeFalse(); + } + } +} diff --git a/CERTInext.Tests/SignerFallbackWarningTests.cs b/CERTInext.Tests/SignerFallbackWarningTests.cs new file mode 100644 index 0000000..69d3fd2 --- /dev/null +++ b/CERTInext.Tests/SignerFallbackWarningTests.cs @@ -0,0 +1,169 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Linq; +using System.Text.Json; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Microsoft.Extensions.Logging; +using WireMock.RequestBuilders; +using WireMock.ResponseBuilders; +using WireMock.Server; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// SOC1 accuracy-of-processing: when SignerName / SignerPlace fall back to the built-in + /// placeholders ("Keyfactor Gateway" / "Gateway") the client must log a Warning naming what to + /// configure, without changing the values sent in agreementDetails. + /// + [Collection(LoggingStateCollection.Name)] + public class SignerFallbackWarningTests : IDisposable + { + private readonly WireMockServer _server; + + public SignerFallbackWarningTests() + { + _server = WireMockServer.Start(); + _server.Given(Request.Create().WithPath("/GenerateOrderSSL").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.GenerateOrderSuccessJson(MockCertificateData.OrderNumber1))); + _server.Given(Request.Create().WithPath("/TrackOrder").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.TrackOrderIssuedJson(MockCertificateData.OrderNumber1))); + _server.Given(Request.Create().WithPath("/GetCertificate").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.GetCertificateSuccessJson())); + } + + public void Dispose() => _server.Stop(); + + private sealed class CapturingLogger : ILogger + { + public ConcurrentQueue<(LogLevel Level, string Message)> Entries { get; } = new(); + public IDisposable BeginScope(TState state) => null; + public bool IsEnabled(LogLevel logLevel) => true; + + public void Log(LogLevel logLevel, EventId eventId, TState state, Exception exception, + Func formatter) + => Entries.Enqueue((logLevel, formatter(state, exception))); + + public List Warnings(string contains) => Entries + .Where(e => e.Level == LogLevel.Warning && e.Message.Contains(contains, StringComparison.Ordinal)) + .Select(e => e.Message).ToList(); + } + + private CERTInextClient BuildClient(string requestorName, string signerPlace) => new CERTInextClient(new CERTInextConfig + { + ApiUrl = _server.Urls[0], + AuthMode = "AccessKey", + ApiKey = "test-key", + AccountNumber = "12345", + RequestorName = requestorName, + RequestorEmail = "requestor@example.com", + RequestorIsdCode = "1", + RequestorMobileNumber = "5550000000", + SignerPlace = signerPlace, + SignerIp = "203.0.113.10", + PageSize = 100 + }); + + private async Task<(CapturingLogger Logger, JsonElement Agreement)> EnrollAsync( + CERTInextClient client, Dictionary templateParams = null) + { + var parameters = new Dictionary(StringComparer.OrdinalIgnoreCase) { ["ProfileId"] = "842" }; + if (templateParams != null) + foreach (var kv in templateParams) parameters[kv.Key] = kv.Value; + + var plugin = new CERTInextCAPlugin(client, new CERTInextConfig { PickupRetries = 0 }); + var logger = new CapturingLogger(); + using (CERTInextClient.OverrideLoggerForTests(logger)) + { + await plugin.Enroll( + MockCertificateData.FakeCsrPem, "CN=test.example.com", + new Dictionary { ["dns"] = new[] { "test.example.com" } }, + new EnrollmentProductInfo { ProductID = "842", ProductParameters = parameters }, + RequestFormat.PKCS10, EnrollmentType.New); + } + + var post = _server.LogEntries.Single(e => e.RequestMessage.Path == "/GenerateOrderSSL"); + var agreement = JsonDocument.Parse(post.RequestMessage.Body!).RootElement + .GetProperty("orderDetails").GetProperty("agreementDetails").Clone(); + return (logger, agreement); + } + + [Fact] + public async Task SignerName_Unset_WarnsAndSendsPlaceholder() + { + var (logger, agreement) = await EnrollAsync(BuildClient(requestorName: "", signerPlace: "Austin")); + + var warnings = logger.Warnings("SignerName"); + warnings.Should().ContainSingle(); + warnings[0].Should().Contain("RequestorName").And.Contain("template"); + logger.Warnings("SignerPlace").Should().BeEmpty(); + agreement.GetProperty("signerName").GetString().Should().Be("Keyfactor Gateway"); + agreement.GetProperty("signerPlace").GetString().Should().Be("Austin"); + } + + [Fact] + public async Task SignerPlace_Unset_WarnsAndSendsPlaceholder() + { + var (logger, agreement) = await EnrollAsync(BuildClient(requestorName: "Jane Doe", signerPlace: "")); + + var warnings = logger.Warnings("SignerPlace"); + warnings.Should().ContainSingle(); + warnings[0].Should().Contain("template").And.Contain("connector"); + logger.Warnings("SignerName").Should().BeEmpty(); + agreement.GetProperty("signerName").GetString().Should().Be("Jane Doe"); + agreement.GetProperty("signerPlace").GetString().Should().Be("Gateway"); + } + + [Fact] + public async Task SignerFields_SetOnConnector_NoWarning_ValuesUnchanged() + { + var (logger, agreement) = await EnrollAsync(BuildClient(requestorName: "Jane Doe", signerPlace: "Austin")); + + logger.Warnings("SignerName").Should().BeEmpty(); + logger.Warnings("SignerPlace").Should().BeEmpty(); + agreement.GetProperty("signerName").GetString().Should().Be("Jane Doe"); + agreement.GetProperty("signerPlace").GetString().Should().Be("Austin"); + } + + [Fact] + public async Task SignerFields_SetOnTemplate_NoWarning_TemplateWins() + { + var (logger, agreement) = await EnrollAsync( + BuildClient(requestorName: "", signerPlace: ""), + new Dictionary { ["SignerName"] = "Template Signer", ["SignerPlace"] = "Denver" }); + + logger.Warnings("SignerName").Should().BeEmpty(); + logger.Warnings("SignerPlace").Should().BeEmpty(); + agreement.GetProperty("signerName").GetString().Should().Be("Template Signer"); + agreement.GetProperty("signerPlace").GetString().Should().Be("Denver"); + } + + [Fact] + public async Task SignerFields_BothUnset_WarnsForEach_AndSendsBothPlaceholders() + { + var (logger, agreement) = await EnrollAsync(BuildClient(requestorName: null, signerPlace: null)); + + logger.Warnings("SignerName").Should().ContainSingle(); + logger.Warnings("SignerPlace").Should().ContainSingle(); + agreement.GetProperty("signerName").GetString().Should().Be("Keyfactor Gateway"); + agreement.GetProperty("signerPlace").GetString().Should().Be("Gateway"); + } + } +} diff --git a/CERTInext.Tests/SignerIpWarningTests.cs b/CERTInext.Tests/SignerIpWarningTests.cs new file mode 100644 index 0000000..ad8909c --- /dev/null +++ b/CERTInext.Tests/SignerIpWarningTests.cs @@ -0,0 +1,209 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Concurrent; +using System.Linq; +using System.Text.Json; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Microsoft.Extensions.Logging; +using WireMock.RequestBuilders; +using WireMock.ResponseBuilders; +using WireMock.Server; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// A resolved SignerIp that is not an IP literal (for example a host name) is sent unchanged as + /// agreementDetails.signerIP but logs a Warning naming the source (template or connector). + /// Enroll and renewal share BuildSslOrderDetails -> BuildAgreementDetails, so both + /// paths are covered. All values are synthetic (RFC 5737 / RFC 3849 documentation addresses). + /// + [Collection(LoggingStateCollection.Name)] + public class SignerIpWarningTests : IDisposable + { + private readonly WireMockServer _server; + + public SignerIpWarningTests() + { + _server = WireMockServer.Start(); + _server.Given(Request.Create().WithPath("/GenerateOrderSSL").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.GenerateOrderSuccessJson(MockCertificateData.OrderNumber1))); + _server.Given(Request.Create().WithPath("/TrackOrder").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.TrackOrderIssuedJson(MockCertificateData.OrderNumber1))); + _server.Given(Request.Create().WithPath("/GetCertificate").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.GetCertificateSuccessJson())); + } + + public void Dispose() => _server.Stop(); + + private sealed class CapturingLogger : ILogger + { + public ConcurrentQueue<(LogLevel Level, string Message)> Entries { get; } = new(); + public IDisposable BeginScope(TState state) => null; + public bool IsEnabled(LogLevel logLevel) => true; + public void Log(LogLevel logLevel, EventId eventId, TState state, Exception exception, + Func formatter) => Entries.Enqueue((logLevel, formatter(state, exception))); + + public string[] SignerIpWarnings => Entries + .Where(e => e.Level == LogLevel.Warning && e.Message.Contains("SignerIp value")) + .Select(e => e.Message).ToArray(); + } + + private CERTInextClient BuildClient(string connectorSignerIp) => new CERTInextClient(new CERTInextConfig + { + ApiUrl = _server.Urls[0], + AuthMode = "AccessKey", + ApiKey = "test-key", + AccountNumber = "12345", + RequestorName = "Default Requestor", + RequestorEmail = "default@example.com", + RequestorIsdCode = "1", + RequestorMobileNumber = "5550000000", + SignerPlace = "Austin", + SignerIp = connectorSignerIp, + PageSize = 100 + }); + + private string CapturedSignerIp() + { + var posts = _server.LogEntries.Where(e => e.RequestMessage.Path == "/GenerateOrderSSL").ToList(); + posts.Should().HaveCount(1); + return JsonDocument.Parse(posts[0].RequestMessage.Body!).RootElement + .GetProperty("orderDetails").GetProperty("agreementDetails").GetProperty("signerIP").GetString(); + } + + private static EnrollCertificateRequest EnrollReq(string templateSignerIp) => new EnrollCertificateRequest + { + ProfileId = "842", + Csr = MockCertificateData.FakeCsrPem, + Subject = "CN=test.example.com", + Comment = "Unit test", + SignerIp = templateSignerIp + }; + + private static RenewCertificateRequest RenewReq(string templateSignerIp) => new RenewCertificateRequest + { + Csr = MockCertificateData.FakeCsrPem, + ProfileId = "842", + Comment = "Unit test", + SignerIp = templateSignerIp + }; + + [Fact] + public async Task Enroll_InvalidTemplateSignerIp_WarnsNamingTemplate_AndSendsValueUnchanged() + { + var logger = new CapturingLogger(); + using (CERTInextClient.OverrideLoggerForTests(logger)) + await BuildClient("203.0.113.10").EnrollCertificateAsync(EnrollReq("gateway-host")); + + var warnings = logger.SignerIpWarnings; + warnings.Should().ContainSingle(); + warnings[0].Should().Contain("template").And.Contain("gateway-host"); + CapturedSignerIp().Should().Be("gateway-host"); + } + + [Fact] + public async Task Enroll_InvalidConnectorSignerIp_WarnsNamingConnector_AndSendsValueUnchanged() + { + var logger = new CapturingLogger(); + using (CERTInextClient.OverrideLoggerForTests(logger)) + await BuildClient("gateway-host").EnrollCertificateAsync(EnrollReq(null)); + + var warnings = logger.SignerIpWarnings; + warnings.Should().ContainSingle(); + warnings[0].Should().Contain("connector").And.Contain("gateway-host"); + CapturedSignerIp().Should().Be("gateway-host"); + } + + [Fact] + public async Task Renewal_InvalidTemplateSignerIp_WarnsNamingTemplate_AndSendsValueUnchanged() + { + var logger = new CapturingLogger(); + using (CERTInextClient.OverrideLoggerForTests(logger)) + await BuildClient("203.0.113.10").RenewCertificateAsync(MockCertificateData.OrderNumber1, RenewReq("gateway-host")); + + var warnings = logger.SignerIpWarnings; + warnings.Should().ContainSingle(); + warnings[0].Should().Contain("template").And.Contain("gateway-host"); + CapturedSignerIp().Should().Be("gateway-host"); + } + + [Fact] + public async Task Enroll_InvalidSignerIpWithControlChars_LogLineHasNoRawCrLf() + { + var logger = new CapturingLogger(); + using (CERTInextClient.OverrideLoggerForTests(logger)) + await BuildClient("203.0.113.10").EnrollCertificateAsync(EnrollReq("bad\r\nhost")); + + var warnings = logger.SignerIpWarnings; + warnings.Should().ContainSingle(); + warnings[0].Should().NotContain("\r").And.NotContain("\n").And.Contain("bad\\r\\nhost"); + CapturedSignerIp().Should().Be("bad\r\nhost"); + } + + [Theory] + [InlineData("203.0.113.10")] + [InlineData("2001:db8::1")] + public async Task Enroll_ValidSignerIp_LogsNoSignerIpWarning(string ip) + { + var logger = new CapturingLogger(); + using (CERTInextClient.OverrideLoggerForTests(logger)) + await BuildClient("198.51.100.7").EnrollCertificateAsync(EnrollReq(ip)); + + logger.SignerIpWarnings.Should().BeEmpty(); + CapturedSignerIp().Should().Be(ip); + } + + [Theory] + [InlineData("203.0.113.10")] + [InlineData("2001:db8::1")] + public async Task Enroll_ValidConnectorSignerIp_LogsNoSignerIpWarning(string ip) + { + var logger = new CapturingLogger(); + using (CERTInextClient.OverrideLoggerForTests(logger)) + await BuildClient(ip).EnrollCertificateAsync(EnrollReq(null)); + + logger.SignerIpWarnings.Should().BeEmpty(); + CapturedSignerIp().Should().Be(ip); + } + + [Theory] + [InlineData("203.0.113.10")] + [InlineData("2001:db8::1")] + public async Task Renewal_ValidSignerIp_LogsNoSignerIpWarning(string ip) + { + var logger = new CapturingLogger(); + using (CERTInextClient.OverrideLoggerForTests(logger)) + await BuildClient("198.51.100.7").RenewCertificateAsync(MockCertificateData.OrderNumber1, RenewReq(ip)); + + logger.SignerIpWarnings.Should().BeEmpty(); + CapturedSignerIp().Should().Be(ip); + } + + [Fact] + public async Task Enroll_BlankSignerIpEverywhere_FallsBackWithoutInvalidIpWarning() + { + var logger = new CapturingLogger(); + using (CERTInextClient.OverrideLoggerForTests(logger)) + await BuildClient("").EnrollCertificateAsync(EnrollReq(null)); + + logger.SignerIpWarnings.Should().BeEmpty("the existing missing-SignerIp warning is a different message"); + CapturedSignerIp().Should().Be("127.0.0.1"); + } + } +} diff --git a/CERTInext.Tests/StatusMapperV2Tests.cs b/CERTInext.Tests/StatusMapperV2Tests.cs new file mode 100644 index 0000000..00765a3 --- /dev/null +++ b/CERTInext.Tests/StatusMapperV2Tests.cs @@ -0,0 +1,205 @@ +// Copyright 2026 Keyfactor +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System.Collections.Generic; +using FluentAssertions; +using Keyfactor.Extensions.CAPlugin.CERTInext.Models; +using Keyfactor.PKI.Enums.EJBCA; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Unit tests for the V2-specific mapping methods on . + /// + public class StatusMapperV2Tests + { + // --------------------------------------------------------------------------- + // V2StatusToRequestDisposition + // --------------------------------------------------------------------------- + + // All 11 status values documented by the V2 spec's `/reports/orders` `status` + // filter — every one must map explicitly, not fall through the + // "unmapped" default arm, even where the resulting disposition (FAILED) is the + // same as the default's. `unknown-future`/empty/null exercise the true default + // arm below. `expired` is a deliberate GENERATED mapping (see test below), not a + // default-arm case. + [Theory] + [InlineData("issued", (int)EndEntityStatus.GENERATED)] + [InlineData("ISSUED", (int)EndEntityStatus.GENERATED)] // case-insensitive + [InlineData("pending-dcv", (int)EndEntityStatus.EXTERNALVALIDATION)] + [InlineData("pending-csr", (int)EndEntityStatus.EXTERNALVALIDATION)] + [InlineData("pending-agreement", (int)EndEntityStatus.EXTERNALVALIDATION)] + [InlineData("pending-organization-verification", (int)EndEntityStatus.EXTERNALVALIDATION)] + [InlineData("pending-documents", (int)EndEntityStatus.EXTERNALVALIDATION)] + [InlineData("pending-approval", (int)EndEntityStatus.EXTERNALVALIDATION)] + [InlineData("revoked", (int)EndEntityStatus.REVOKED)] + [InlineData("cancelled", (int)EndEntityStatus.FAILED)] + [InlineData("rejected", (int)EndEntityStatus.FAILED)] + // Expired-but-not-revoked certs remain issued inventory — mirrors V1's + // ToRequestDisposition convention and the sync/report path's own "expired" case. + [InlineData("expired", (int)EndEntityStatus.GENERATED)] + // The spec-documented `unknown` means "may still be live" — pending, not FAILED. + [InlineData("unknown", (int)EndEntityStatus.EXTERNALVALIDATION)] + [InlineData("UNKNOWN", (int)EndEntityStatus.EXTERNALVALIDATION)] // case-insensitive + [InlineData("Unknown", (int)EndEntityStatus.EXTERNALVALIDATION)] + public void V2StatusToRequestDisposition_MapsCorrectly(string v2Status, int expectedDisposition) + { + StatusMapper.V2StatusToRequestDisposition(v2Status).Should().Be(expectedDisposition); + } + + // --------------------------------------------------------------------------- + // A status string that is NOT one of the 11 spec + // values must still degrade gracefully to FAILED via the default arm, rather + // than throwing or being silently treated as "still pending". This is the + // "truly unrecognized" case, distinct from the deliberate FAILED mappings + // (cancelled/rejected) tested above. + // --------------------------------------------------------------------------- + + [Theory] + [InlineData("unknown-future")] + [InlineData("not-a-real-status")] // garbage still defaults to FAILED, unlike `unknown` + [InlineData("")] + [InlineData(null)] + public void V2StatusToRequestDisposition_UnrecognizedStatus_DefaultsToFailed(string v2Status) + { + StatusMapper.V2StatusToRequestDisposition(v2Status).Should().Be((int)EndEntityStatus.FAILED); + } + + // --------------------------------------------------------------------------- + // ToV2RevocationReason + // --------------------------------------------------------------------------- + + [Theory] + [InlineData(0u, Constants.RevocationReasonV2.Unspecified)] + [InlineData(1u, Constants.RevocationReasonV2.KeyCompromise)] + [InlineData(2u, Constants.RevocationReasonV2.CACompromise)] + [InlineData(3u, Constants.RevocationReasonV2.AffiliationChanged)] + [InlineData(4u, Constants.RevocationReasonV2.Superseded)] + [InlineData(5u, Constants.RevocationReasonV2.CessationOfOperation)] + [InlineData(6u, Constants.RevocationReasonV2.CertificateHold)] + [InlineData(8u, Constants.RevocationReasonV2.Unspecified)] // removeFromCRL: CRL-only, not a valid revoke reason + [InlineData(9u, Constants.RevocationReasonV2.PrivilegeWithdrawn)] + [InlineData(10u, Constants.RevocationReasonV2.AACompromise)] + [InlineData(99u, Constants.RevocationReasonV2.Unspecified)] // unknown → unspecified + public void ToV2RevocationReason_MapsCorrectly(uint crlReason, string expectedV2Reason) + { + StatusMapper.ToV2RevocationReason(crlReason).Should().Be(expectedV2Reason); + } + + // --------------------------------------------------------------------------- + // Round-trip: ToV2RevocationReason never returns null or empty + // --------------------------------------------------------------------------- + + [Theory] + [InlineData(0u), InlineData(1u), InlineData(3u), InlineData(4u), InlineData(5u), InlineData(9u)] + public void ToV2RevocationReason_NeverReturnsNullOrEmpty(uint crlReason) + { + StatusMapper.ToV2RevocationReason(crlReason).Should().NotBeNullOrEmpty(); + } + + // --------------------------------------------------------------------------- + // Every CRL reason code Keyfactor Command can send + // to IAnyCAPlugin.Revoke must map to a value in the V2 spec's kebab-case + // `reason` enum ("Revoke Certificate" in the V2 spec), never to a camelCase string that would get HTTP 400. + // --------------------------------------------------------------------------- + + /// + /// The V2 spec's `reason` enum, hardcoded from the spec text rather than from + /// so this test still catches a + /// future accidental edit to that class drifting away from the spec. + /// + private static readonly HashSet SpecRevocationReasonEnum = new() + { + "unspecified", + "key-compromise", + "ca-compromise", + "affiliation-changed", + "superseded", + "cessation-of-operation", + "certificate-hold", + "privilege-withdrawn", + "aa-compromise", + }; + + // RFC 5280 CRLReason codes that Keyfactor Command can pass through to + // IAnyCAPlugin.Revoke's revocationReason parameter (0-10, minus the two + // codes RFC 5280 never assigns: 7 and, for a *request* reason, 8 + // (removeFromCRL is CRL-only) is still exercised here to prove it degrades + // safely to "unspecified" rather than to an invalid string). + [Theory] + [InlineData(0u)] + [InlineData(1u)] + [InlineData(2u)] + [InlineData(3u)] + [InlineData(4u)] + [InlineData(5u)] + [InlineData(6u)] + [InlineData(8u)] + [InlineData(9u)] + [InlineData(10u)] + public void ToV2RevocationReason_EveryCrlCode_MapsToASpecEnumValue(uint crlReason) + { + string v2Reason = StatusMapper.ToV2RevocationReason(crlReason); + + SpecRevocationReasonEnum.Should().Contain(v2Reason, + $"CRL reason code {crlReason} mapped to '{v2Reason}', which is not one of the V2 spec's " + + "kebab-case reason values — sending it would get HTTP 400."); + } + + // --------------------------------------------------------------------------- + // V2RevocationReasonToCrlCode — the inverse of ToV2RevocationReason, + // used to populate AnyCAPluginCertificate.RevocationReason from a Track Order + // response's nested revocation.reason string. + // --------------------------------------------------------------------------- + + [Theory] + [InlineData(Constants.RevocationReasonV2.Unspecified, 0)] + [InlineData(Constants.RevocationReasonV2.KeyCompromise, 1)] + [InlineData(Constants.RevocationReasonV2.CACompromise, 2)] + [InlineData(Constants.RevocationReasonV2.AffiliationChanged, 3)] + [InlineData(Constants.RevocationReasonV2.Superseded, 4)] + [InlineData(Constants.RevocationReasonV2.CessationOfOperation, 5)] + [InlineData(Constants.RevocationReasonV2.CertificateHold, 6)] + [InlineData(Constants.RevocationReasonV2.PrivilegeWithdrawn, 9)] + [InlineData(Constants.RevocationReasonV2.AACompromise, 10)] + [InlineData("KEY-COMPROMISE", 1)] // case-insensitive + [InlineData("not-a-real-reason", 0)] // unrecognized → unspecified + [InlineData(null, 0)] // absent/null → unspecified + public void V2RevocationReasonToCrlCode_MapsCorrectly(string v2Reason, int expectedCrlCode) + { + StatusMapper.V2RevocationReasonToCrlCode(v2Reason).Should().Be(expectedCrlCode); + } + + // Round-trip: every CRL code ToV2RevocationReason can produce must map back to the + // same code through V2RevocationReasonToCrlCode (the codes ToV2RevocationReason never + // emits — 7, and CRL-only 8 — are out of scope, matching ToV2RevocationReason's own + // documented behavior of mapping "no V2 equivalent" codes to "unspecified"). + [Theory] + [InlineData(0u)] + [InlineData(1u)] + [InlineData(2u)] + [InlineData(3u)] + [InlineData(4u)] + [InlineData(5u)] + [InlineData(6u)] + [InlineData(9u)] + [InlineData(10u)] + public void V2RevocationReasonToCrlCode_RoundTripsWithToV2RevocationReason(uint crlReason) + { + string v2Reason = StatusMapper.ToV2RevocationReason(crlReason); + StatusMapper.V2RevocationReasonToCrlCode(v2Reason).Should().Be((int)crlReason); + } + } +} diff --git a/CERTInext.Tests/TESTING.md b/CERTInext.Tests/TESTING.md index e56c35a..e3bb590 100644 --- a/CERTInext.Tests/TESTING.md +++ b/CERTInext.Tests/TESTING.md @@ -6,19 +6,34 @@ The `CERTInext.Tests` project contains unit and contract tests for the CERTInext REST plugin. No external services are required — all HTTP I/O is handled in-process by WireMock.Net or replaced by Moq strict mocks. -The project is split into several focused test classes: +The project is split into focused test classes: | Class | Layer under test | Isolation technique | |---|---|---| -| `CERTInextClientTests` | `CERTInextClient` HTTP transport | WireMock.Net (real loopback HTTP) | -| `CERTInextClientRequestShapeTests` | `CERTInextClient` request body construction | WireMock.Net | -| `CERTInextCAPluginTests` | `CERTInextCAPlugin` IAnyCAPlugin logic | Moq strict mock of `ICERTInextClient` | -| `CERTInextCAPluginCoverageTests` | Additional plugin logic paths | Moq strict mock | -| `CERTInextCAPluginPublicSurfaceTests` | Binary-compat / no-DCV surface contract | Reflection only | -| `BoundedDcvSyncTests` | DCV sync age/cap filter logic | Pure unit (no I/O) | -| `RateLimitRetryTests` | Rate-limit back-off helpers | Pure unit (no I/O) | -| `ExtractSerialFromPemTests` | PEM serial-number extraction | Pure unit (no I/O) | -| `RedactCredentialsTests` | Log credential-redaction helper | Pure unit (no I/O) | +| `CERTInextClientTests`, `CERTInextClientCoverageTests` | `CERTInextClient` V1 HTTP transport, auth, and error branches | WireMock.Net (real loopback HTTP) | +| `CERTInextClientRequestShapeTests` | V1 `GenerateOrderSSL` request body construction | WireMock.Net | +| `CERTInextClientV2Tests` | `CERTInextClient` V2 transport: token caching, order create/track/CSR/revoke/cancel, DCV, catalog, orders report | WireMock.Net | +| `CERTInextCAPluginTests`, `CERTInextCAPluginCoverageTests` | `CERTInextCAPlugin` V1 logic: enroll, renew, revoke, sync, validation | Moq strict mock of `ICERTInextClient` | +| `CERTInextCAPluginV2Tests` | V2 dispatch in the plugin: ping, enroll, revoke, single record, sync, validation | Moq strict mock | +| `CERTInextCAPluginDcvTests`, `CERTInextCAPluginV2DcvTests` | V1 and V2 DNS-01 DCV orchestration | Moq strict mock + `FakeDomainValidator` | +| `CERTInextCAPluginV2PickupTests`, `CERTInextCAPluginV2EnrollRevokedTests` | V2 synchronous pickup poll; a revoked order observed during enrollment | Moq strict mock | +| `V2UccEnrollmentTests`, `V2WildcardEnrollmentTests`, `V2UccNonDnsSanLoggingTests` | V2 multi-domain and wildcard handling, SAN guard, non-DNS SAN logging | Moq strict mock | +| `V2ProductCodeResolutionTests` | `X-Product-Code` is an optional override: no header and no catalog call without a template `ProductCode`, connector `DefaultProductCode` ignored on V2, wildcard and UCC detected from the request shape, explicit code keeps catalog-based detection, `resolvedProductCode` logged | Moq strict mock; captured logger | +| `V2CertificateNotGeneratedTests` | Download Certificate 422 `EMS-1165` on an order reported `issued` is "certificate not generated yet": pickup keeps polling and returns pending with Debug per attempt and one Info summary, `GetSingleRecord` and Synchronize log it quietly, and other download errors still warn | Moq strict mock; captured logger | +| `V2AgreementAcceptTests`, `V2AgreementSignerIpTests` | The `pending-agreement` accept-agreement fallback (wire shape, once per order per enroll call or sync pass, audit log, failures only warn, SSL/TLS only) and `agreement.signerIp` never reaching a V2 body | WireMock.Net; Moq strict mock; captured logger | +| `V2SslComValidationTests` | SSL.com organization validation for V2 OV/EV orders: the tolerant response model and its defensive per-level "validated" logic, the three client calls, the advisory plugin pre-check (read, one refresh, optional submission with audit log; every failure or not-validated outcome only warns and the order is placed), and the two new settings | WireMock.Net; Moq strict mock; captured logger | +| `V2PrivatePkiEnrollmentTests`, `V2FamilyOrderRequestSerializationTests` | V2 Private PKI enrollment and the Private PKI / Document Signer request bodies | Moq strict mock; DTO serialization | +| `V2ProductVariantDerivationTests`, `V2SignerPlaceRequiredTests`, `V2OrganizationEnrollmentTests`, `V2GroupNumberEnrollmentTests`, `V2SubscriptionEnrollmentTests`, `V2TechnicalContactEnrollmentTests`, `EmailNotificationsEnrollmentTests`, `RequestorDesignationEnrollmentTests` | How each connector and template setting reaches the V2 order body, and the checks that run before an order is placed | Moq strict mock; DTO serialization | +| `V2SslOrderBodyGoldenTests` | The V2 SSL create-order body is byte-for-byte stable | Moq strict mock; golden JSON | +| `V2CsrTransportFailureTests`, `V2OrphanedOrderCancelTests` | What happens when CSR submission fails: cancel the orphaned order, or track it first after a transport error | Moq strict mock | +| `V2SingleCallCreateTests` | The default single-call V2 create (`V2InlineCsr=true`) end to end through the real client: CSR inline and `X-Product-Code` sent on the create body only for an explicit template `ProductCode`, no `PUT .../csr`, issued / pending-approval / EMS-1165 outcomes, 5xx and dropped-connection create failures (no retry, do-not-resubmit message), blank CSR rejected before any call; plus the two-call SSL flow with `V2InlineCsr=false` (exactly one PUT, orphan cancel) and Private PKI (one PUT with the flag on) | WireMock.Net | +| `V2InlineCsrConfigTests` | The `V2InlineCsr` setting: default `true`, JSON parsing, connector annotation, and `ValidateCAConnectionInfo` rejecting a non-boolean value | Moq strict mock | +| `V2UnknownStatusTests`, `StatusMapperV2Tests`, `V2OrderStatusResponseTests` | V2 status mapping, the `unknown` status, revocation reason mapping, status-response parsing | Pure unit | +| `CERTInextCAPluginPublicSurfaceTests` | The plugin's gateway-visible public surface | Reflection only | +| `CERTInextCAPluginAuditLoggingTests`, `CERTInextCAPluginRevokeV2AuditLoggingTests` | Audit log lines for enrollment and V2 revocation | Captured logger | +| `RedactPersonalDataTests`, `RedactCredentialsTests`, `MaskEmailTests`, `SanLogMaskingTests`, `SensitiveRequestDataConfigTests` | Log redaction and `LogSensitiveRequestData` | Pure unit | +| `SanSubmissionTests` | UCC SAN submission: gateway SAN keys, CSR fallback, non-DNS SANs | WireMock.Net and pure unit | +| `EnrollmentParamsTests`, `ExtractErrorMessageTests`, `V1NonSuccessResponseTests`, `ExtractSerialFromPemTests`, `BoundedDcvSyncTests`, `RateLimitRetryTests` | Template parameter parsing, error-message extraction, PEM serial extraction, DCV sync bounds, rate-limit back-off | Pure unit (no I/O) | If a test fails in `CERTInextClientTests` or `CERTInextClientRequestShapeTests`, the bug is in HTTP transport or request serialisation. If it fails in `CERTInextCAPluginTests` or @@ -29,7 +44,7 @@ HTTP transport or request serialisation. If it fails in `CERTInextCAPluginTests` ## Running the Tests **Prerequisites:** -- .NET 8 or .NET 10 SDK +- .NET 10 SDK (the test project targets `net8.0` and references the plugin, which also builds `net10.0`) - NuGet packages restored (`dotnet restore`) - No external services required @@ -56,19 +71,22 @@ stops it in `Dispose()`, so tests are isolated and can run in parallel without p ## Authentication model -The real CERTInext API uses HTTP POST for **all** endpoints. There is no Authorization header +The CERTInext V1 API uses HTTP POST for **all** endpoints. There is no Authorization header for AccessKey mode. Instead, every request body includes a `meta` block containing: - `authKey` — `SHA256(accessKey + requestTs + requestTxnId)` (lowercase hex) - `ts` — ISO 8601 timestamp -- `txn` — unique transaction UUID +- `txn` — random numeric transaction ID The raw access key is never transmitted — only the derived hash is sent. `AuthMode` accepted values: -- `AccessKey` (primary) — HMAC signed body -- `OAuth` (alternative) — bearer token via client credentials flow -- `ApiKey`, `AccessKeyLegacy`, `OAuthLegacy` — legacy aliases accepted for backward compatibility +- `AccessKey` (primary) — `authKey` in the request body +- `OAuth` (alternative) — bearer token via client credentials flow, sent in an `Authorization` header with an empty `authKey` +- `ApiKey` and `OAuth2` — legacy aliases accepted for backward compatibility + +The V2 API (`CERTInextClientV2Tests`) authenticates with an OAuth2 `client_credentials` bearer token +requested from `{ApiUrl}/oauth/token`. --- @@ -158,6 +176,34 @@ CERTInext has no dedicated renewal endpoint. `RenewCertificateAsync` submits a n | `GetProfilesAsync_ReturnsProfiles_WhenServerResponds` | `POST /GetProductDetails` → two products in nested category envelope | Result has 2 items; `ProfileIdTls` and `ProfileIdClient` present; all `Active == true` | | `GetProfilesAsync_ReturnsEmptyList_WhenNoProductsReturned` | `POST /GetProductDetails` → empty `productDetails` array | Result is empty | +### GetProductDetailsV2Async — GET /api/certinext/v2/catalog/products (`CERTInextClientV2Tests`) + +The V2 catalog returns the same nested category envelope as V1's `GetProductDetails`, under a +top-level `"products"` key. `ParseProductDetailsV2Response` flattens each shape into +`ProductDetail`; the flat `productId` and bare-array shapes are kept as fallback branches for other +accounts and API versions. + +| Test | Stub | Assertion | +|------|------|-----------| +| `GetProductDetailsV2Async_NestedCategoryEnvelope_FlattensProducts` | `GET catalog/products` → nested category envelope | 2 products; `ProductCode`/`ProductName`/`ProductType` populated, `Active == true` | +| `GetProductDetailsV2Async_FlatProductIdRows_MapsToProductCode` | `GET catalog/products` → flat `productId` rows | `productId` mapped to `ProductCode` | +| `GetProductDetailsV2Async_BareArray_Parses` | `GET catalog/products` → bare JSON array | Parses without a wrapper object | +| `GetProductDetailsV2Async_EmptyCatalog_ReturnsEmptyList` | `GET catalog/products` → `{"products":[]}` | Returns an empty list (no throw) | + +### ValidateProductInfo — `CERTInextCAPluginTests` (V1) / `CERTInextCAPluginV2Tests` (V2) + +`ValidateProductInfo` builds its own `CERTInextClient` from `connectionInfo` (ignoring the +Moq-injected client), so these tests use a real WireMock server as `ApiUrl`. + +| Test | Mode | Stub | Assertion | +|------|------|------|-----------| +| `ValidateProductInfo_V1_Succeeds_WhenProductCodePresent` | V1 | `POST /GetProductDetails` → nested envelope containing the code | Does not throw | +| `ValidateProductInfo_V1_Throws_WhenProductCodeAbsent` | V1 | Same stub, unknown code | Throws `AnyCAValidationException` `*not found*` | +| `ValidateProductInfo_V2_Succeeds_WhenProductCodeInCatalog` | V2 | `GET catalog/products` → nested envelope containing the code | Does not throw; no request ever hits `/GetProductDetails` | +| `ValidateProductInfo_V2_Throws_WhenProductCodeNotInCatalog` | V2 | Same stub, unknown code | Throws `AnyCAValidationException` `*not found*` | +| `ValidateProductInfo_V2_Throws_WhenCatalogEmpty` | V2 | `GET catalog/products` → `{"products":[]}` | Throws `*not found*` — no soft-accept, matches V1 | +| `ValidateProductInfo_V2_Throws_WhenCatalogReturnsError` | V2 | `GET catalog/products` → HTTP 500 | Throws `*Unable to validate*`; message excludes the response body | + ### DCV endpoints | Test | Stub | Assertion | @@ -181,13 +227,26 @@ blocks depending on connector configuration. |------|-----------| | `OrganizationNumber_Set_EmitsPreVettedOrganizationDetails` | Body includes `organizationDetails.preVetting="1"` and the configured `organizationNumber` | | `OrganizationNumber_Blank_OmitsOrganizationDetailsBlock` | Body omits `organizationDetails` entirely | -| `GroupNumber_Set_EmitsDelegationInformation` | Body includes `delegationInformation.groupNumber` | -| `GroupNumber_Blank_OmitsDelegationInformation` | Body omits `delegationInformation` | -| `TechnicalContact_AllSet_EmitsExplicitValues` | Body includes `technicalPointOfContact` with the configured values | -| `TechnicalContact_AllBlank_FallsBackToRequestorDefaults` | Body includes `technicalPointOfContact` fields derived from `RequestorName`/`RequestorEmail` | -| `SslBodyDefaults_AreEmitted_FromCustomConnectorValues` | Custom connector-level defaults appear in the order body | -| `SslBodyDefaults_AreSafeFallbacks_WhenConfigUntouched` | Default values are emitted without throwing when optional config fields are omitted | +| `GroupNumber_Set_EmitsOrderDetailsGroupNumber` | Body includes `orderDetails.groupNumber`; no `delegationInformation` | +| `GroupNumber_Blank_OmitsGroupNumber` | Body omits `orderDetails.groupNumber` (null/empty/whitespace) | +| `TechnicalContact_AllSet_EmitsPocFields` | `technicalPointOfContact` carries `pocFirstName`/`pocLastName` (split from `TechnicalContactName`), `pocEmail`, `pocIsdCode`, `pocMobileNumber`; no `tpc*` fields | +| `TechnicalContact_AllBlank_FallsBackToRequestorDefaults` | Each `poc*` field falls back to the matching `Requestor*` value | +| `TechnicalContact_SingleTokenName_FillsFirstAndLast` | A single-token name goes into both `pocFirstName` and `pocLastName` | +| `TechnicalContact_PerFieldFallback_MixesOverridesAndRequestorValues` | Fallback is per field, not all-or-nothing | +| `TechnicalContact_NoEmailResolved_OmitsBlock` | `technicalPointOfContact` is omitted (with a Warning) when no email resolves | +| `SslBodyDefaults_AreEmitted_FromCustomConnectorValues` | Custom connector-level defaults appear in the order body, incl. `orderDetails.autoSecureWWW` | +| `SslBodyDefaults_AreSafeFallbacks_WhenConfigUntouched` | Default values are emitted when optional config fields are untouched; `orderDetails.autoSecureWWW="0"` is sent | +| `AutoSecureWww_Blank_SendsZero` | Blank `AutoSecureWww` still sends `orderDetails.autoSecureWWW="0"` | | `ValidityDays_OnRequest_OverridesConnectorDefault` | `ValidityDays` template parameter overrides the connector `SubscriptionValidityYears` | +| `RenewCertificateAsync_ProfileIdSet_UsesTemplateProductCode` | Renewal uses the template product code over the connector default | +| `RenewCertificateAsync_ProfileIdBlank_FallsBackToConnectorDefault` | Blank renewal `ProfileId` falls back to `DefaultProductCode` | +| `RenewCertificateAsync_SendsFullOrderDetails_FromConnectorConfig` | Renewal body carries every field a new order does (groupNumber, autoSecureWWW, organizationDetails, requestor, subscription, SANs, `poc*`, CSR, agreement, remarks) | +| `RenewCertificateAsync_NoValidityOnRequest_UsesConnectorValidity` | Renewal validity comes from `SubscriptionValidityYears`, not a hard-coded `1` | +| `RenewCertificateAsync_ValidityDays_ConvertsToYears` | Renewal `ValidityDays` is rounded up to whole years | +| `RenewCertificateAsync_ConfigUntouched_UsesConnectorDefaultsNotDtoDefaults` | Renewal uses connector defaults (`autoRenew="0"`, `emailNotifications="0"`), not DTO defaults | +| `SplitContactName_SplitsOnFirstWhitespaceRun` | Name split: trim, first whitespace run separates first/last; single token fills both; blank → empty | + +Every enroll and renewal shape test also asserts the legacy (ignored-by-CERTInext) placements are absent: no `delegationInformation`, no `certificateInformation.autoSecureWWW`, no `tpc*` property anywhere in `orderDetails`. --- @@ -277,9 +336,10 @@ already called it throws `InvalidOperationException`. ## CERTInextCAPluginPublicSurfaceTests -Reflection-based contract tests that verify the no-DCV build does not expose any public types, -fields, methods, or constructors that reference `IDomainValidatorFactory` or other IAnyCAPlugin -3.3-only types. These tests ensure the default build loads cleanly on AnyCA Gateway 25.5.x hosts. +Reflection-based contract tests that pin the plugin's gateway-visible public surface: no public +constructor, field, method, or nested type references `IDomainValidatorFactory` or another +IAnyCAPlugin 3.3-only type, so the plugin class loads even when the host doesn't supply the factory +type, and DCV is then simply inactive. | Test | What it checks | |------|---------------| @@ -359,6 +419,10 @@ block with `status: "1"` (success) or `status: "0"` (failure). | `OrderReportEmptyJson()` | `POST /GetOrderReport` | Empty `ordersArray`, `noOfPages=0` | | `GetProductDetailsJson()` | `POST /GetProductDetails` | Nested category envelope with two products | | `GetProductDetailsEmptyJson()` | `POST /GetProductDetails` | Empty `productDetails` array | +| `GetCatalogProductsV2NestedJson()` | `GET catalog/products` | Nested category envelope (the live sandbox shape) | +| `GetCatalogProductsV2FlatJson()` | `GET catalog/products` | Flat `productId` rows (alternate shape, fallback branch) | +| `GetCatalogProductsV2BareArrayJson()` | `GET catalog/products` | Bare JSON array, no wrapper object | +| `GetCatalogProductsV2EmptyJson()` | `GET catalog/products` | `{"products":[]}` | | `ApiFailureJson(code, msg)` | Any endpoint | Generic `meta.status="0"` failure | | `GetDcvSuccessJson(token)` | `POST /GetDcv` | `dcvDetails.token` | | `GetDcvFailureJson(code, msg)` | `POST /GetDcv` | Failure meta | diff --git a/CERTInext.Tests/TracePayloadGuardTests.cs b/CERTInext.Tests/TracePayloadGuardTests.cs new file mode 100644 index 0000000..853e3c7 --- /dev/null +++ b/CERTInext.Tests/TracePayloadGuardTests.cs @@ -0,0 +1,265 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Linq; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Microsoft.Extensions.Logging; +using WireMock.RequestBuilders; +using WireMock.ResponseBuilders; +using WireMock.Server; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Finding #6 (perf): the PlaceOrder request dump and TrackOrder response dump are Trace logs + /// whose argument is ApplyLoggingRedaction(...) (dozens of regex passes plus a JSON parse). + /// C# evaluates that argument eagerly, and the LogTrace extension does not itself consult + /// IsEnabled before calling ILogger.Log, so unguarded the cost was paid, and the + /// payload handed to the logger, on every call even with Trace off. These tests use a logger + /// that reports Trace disabled yet still records any Log call it receives: the payload + /// line must never reach it when Trace is off, and must be byte-identical to + /// ApplyLoggingRedaction output when Trace is on. All data is synthetic. + /// + [Collection(LoggingStateCollection.Name)] + public class TracePayloadGuardTests : IDisposable + { + private const string RequestorName = "Jane Doe"; + private const string RequestorEmail = "jane.doe@example.com"; + + private readonly WireMockServer _server; + + public TracePayloadGuardTests() + { + _server = WireMockServer.Start(); + } + + public void Dispose() => _server.Stop(); + + private sealed class LevelGatedLogger : ILogger + { + private readonly LogLevel _min; + public LevelGatedLogger(LogLevel min) => _min = min; + public ConcurrentQueue<(LogLevel Level, string Message)> Entries { get; } = new(); + public IDisposable BeginScope(TState state) => null; + public bool IsEnabled(LogLevel logLevel) => logLevel >= _min; + // Deliberately records without re-checking IsEnabled, as the LogTrace extension would + // reach it: any payload line seen here means the call site did not guard. + public void Log(LogLevel logLevel, EventId eventId, TState state, Exception exception, + Func formatter) + => Entries.Enqueue((logLevel, formatter(state, exception))); + } + + private CERTInextClient BuildClient(bool logSensitiveRequestData) => new CERTInextClient(new CERTInextConfig + { + ApiUrl = _server.Urls[0], + AuthMode = "AccessKey", + ApiKey = "synthetic-access-key", + AccountNumber = "9988776655", + LogSensitiveRequestData = logSensitiveRequestData + }); + + private static GenerateOrderSslRequest BuildOrder(string primaryDomain) => new GenerateOrderSslRequest + { + OrderDetails = new SslOrderDetails + { + ProductCode = "842", + RequestorInformation = new RequestorInformation + { + RequestorName = RequestorName, + RequestorMobileNumber = "5551234567", + RequestorEmail = RequestorEmail, + RequestorDesignation = "IT Administrator" + }, + CertificateInformation = new CertificateInformation + { + DomainName = primaryDomain, + AdditionalDomains = new List { "www." + primaryDomain } + }, + AgreementDetails = new AgreementDetails { SignerName = "John Signer", SignerPlace = "Austin", SignerIp = "203.0.113.10" } + } + }; + + private void StubGenerateOrder() => + _server.Given(Request.Create().WithPath("/GenerateOrderSSL").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.GenerateOrderSuccessJson("ORD-GUARD-1"))); + + private string StubTrackOrder(string orderNumber) + { + string body = + "{\"meta\":{\"status\":\"1\"},\"orderDetails\":{\"orderNumber\":\"" + orderNumber + "\"," + + "\"orderStatusId\":\"1\",\"certificateStatusId\":\"1\"," + + "\"requestorInformation\":{\"requestorName\":\"" + RequestorName + "\",\"requestorEmail\":\"" + RequestorEmail + "\"}}}"; + _server.Given(Request.Create().WithPath("/TrackOrder").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json").WithBody(body)); + return body; + } + + private static async Task> CaptureAsync( + LogLevel minLevel, string marker, Func act) + { + var logger = new LevelGatedLogger(minLevel); + using (CERTInextClient.OverrideLoggerForTests(logger)) + await act(); + // The client logger is process-wide; scope to lines carrying this call's marker. + return logger.Entries.Where(e => e.Message != null && e.Message.Contains(marker)).ToList(); + } + + [Theory] + [InlineData(false)] + [InlineData(true)] + public async Task TrackOrder_TraceDisabled_PayloadLogNotEmitted(bool logSensitiveRequestData) + { + string order = "ORD-" + Guid.NewGuid().ToString("N"); + StubTrackOrder(order); + using var client = BuildClient(logSensitiveRequestData); + + var lines = await CaptureAsync(LogLevel.Debug, order, () => client.TrackOrderAsync(order)); + + lines.Should().NotContain(l => l.Message.StartsWith("TrackOrderAsync response payload"), + "redaction and the payload log must be skipped when Trace is disabled"); + } + + [Theory] + [InlineData(false)] + [InlineData(true)] + public async Task TrackOrder_TraceEnabled_PayloadMatchesApplyLoggingRedaction(bool logSensitiveRequestData) + { + string order = "ORD-" + Guid.NewGuid().ToString("N"); + string body = StubTrackOrder(order); + using var client = BuildClient(logSensitiveRequestData); + + var lines = await CaptureAsync(LogLevel.Trace, order, () => client.TrackOrderAsync(order)); + + var dump = lines.Single(l => l.Message.StartsWith("TrackOrderAsync response payload")); + dump.Level.Should().Be(LogLevel.Trace); + dump.Message.Should().Be( + $"TrackOrderAsync response payload (Order={order}): " + + CERTInextClient.ApplyLoggingRedaction(body, logSensitiveRequestData)); + } + + [Theory] + [InlineData(false)] + [InlineData(true)] + public async Task PlaceOrder_TraceDisabled_PayloadLogNotEmitted(bool logSensitiveRequestData) + { + string domain = "po-" + Guid.NewGuid().ToString("N") + ".example.com"; + StubGenerateOrder(); + using var client = BuildClient(logSensitiveRequestData); + + var lines = await CaptureAsync(LogLevel.Debug, domain, () => client.PlaceOrderAsync(BuildOrder(domain))); + + lines.Should().Contain(l => l.Message.StartsWith("Submitting order to CERTInext"), + "precondition: the client logged this call, so the absence below is meaningful"); + lines.Should().NotContain(l => l.Message.StartsWith("PlaceOrderAsync request payload"), + "redaction and the payload log must be skipped when Trace is disabled"); + } + + [Theory] + [InlineData(false)] + [InlineData(true)] + public async Task PlaceOrder_TraceEnabled_PayloadMatchesApplyLoggingRedaction(bool logSensitiveRequestData) + { + string domain = "po-" + Guid.NewGuid().ToString("N") + ".example.com"; + StubGenerateOrder(); + using var client = BuildClient(logSensitiveRequestData); + + var lines = await CaptureAsync(LogLevel.Trace, domain, () => client.PlaceOrderAsync(BuildOrder(domain))); + + var dump = lines.Single(l => l.Message.StartsWith("PlaceOrderAsync request payload")); + dump.Level.Should().Be(LogLevel.Trace); + string sentBody = _server.LogEntries.Last(e => e.RequestMessage.Path == "/GenerateOrderSSL").RequestMessage.Body; + dump.Message.Should().Be( + "PlaceOrderAsync request payload: " + + CERTInextClient.ApplyLoggingRedaction(sentBody, logSensitiveRequestData)); + } + + // --------------------------------------------------------------------------- + // V2 PlaceOrder: same guard on the shared create-order transport. + // --------------------------------------------------------------------------- + + private CERTInextClient BuildV2Client(bool logSensitiveRequestData) => new CERTInextClient(new CERTInextConfig + { + ApiUrl = _server.Urls[0], + AuthMode = "AccessKey", + ApiKey = "synthetic-access-key", + AccountNumber = "9988776655", + UseV2Api = true, + OAuthClientId = "my-v2-client", + OAuthClientSecret = "my-v2-secret", + LogSensitiveRequestData = logSensitiveRequestData + }); + + private static V2CreateSslOrderRequest BuildV2Order(string domain) => new V2CreateSslOrderRequest + { + ProductVariant = "dv", + Requestor = new V2Requestor { Name = RequestorName, Email = RequestorEmail, Phone = "555", Designation = "IT" }, + Certificate = new V2CertificateParams { Domain = domain }, + Subscription = new V2SubscriptionParams { ValidityYears = 1 }, + Agreement = new V2AgreementParams { SignerName = "Test", SignerPlace = "NY", Accepted = true } + }; + + private void StubV2PlaceOrder() + { + _server.Given(Request.Create().WithPath("/oauth/token").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2TokenResponseJson(3600))); + _server.Given(Request.Create().WithPath("/api/certinext/v2/ssl-certificates").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(201) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2CreateOrderPendingJson(MockCertificateData.V2OrderId1))); + } + + [Theory] + [InlineData(false)] + [InlineData(true)] + public async Task PlaceOrderV2_TraceDisabled_PayloadLogsNotEmitted(bool logSensitiveRequestData) + { + string domain = "v2-" + Guid.NewGuid().ToString("N") + ".example.com"; + StubV2PlaceOrder(); + using var client = BuildV2Client(logSensitiveRequestData); + + var lines = await CaptureAsync(LogLevel.Debug, domain, () => + client.PlaceOrderV2Async(Constants.ApiV2.FamilySsl, "842", BuildV2Order(domain))); + + // The request body carries the domain, so a leaked request dump would carry the marker. + lines.Should().NotContain(l => l.Message.StartsWith("PlaceOrderV2Async request payload"), + "redaction and the payload log must be skipped when Trace is disabled"); + } + + [Theory] + [InlineData(false)] + [InlineData(true)] + public async Task PlaceOrderV2_TraceEnabled_RequestPayloadMatchesApplyLoggingRedaction(bool logSensitiveRequestData) + { + string domain = "v2-" + Guid.NewGuid().ToString("N") + ".example.com"; + StubV2PlaceOrder(); + using var client = BuildV2Client(logSensitiveRequestData); + + var lines = await CaptureAsync(LogLevel.Trace, domain, () => + client.PlaceOrderV2Async(Constants.ApiV2.FamilySsl, "842", BuildV2Order(domain))); + + var dump = lines.Single(l => l.Message.StartsWith("PlaceOrderV2Async request payload")); + dump.Level.Should().Be(LogLevel.Trace); + string sentBody = _server.LogEntries.Last(e => e.RequestMessage.Path == "/api/certinext/v2/ssl-certificates").RequestMessage.Body; + dump.Message.Should().Be( + "PlaceOrderV2Async request payload: " + + CERTInextClient.ApplyLoggingRedaction(sentBody, logSensitiveRequestData)); + } + } +} diff --git a/CERTInext.Tests/V1NonSuccessLogRedactionTests.cs b/CERTInext.Tests/V1NonSuccessLogRedactionTests.cs new file mode 100644 index 0000000..88c2744 --- /dev/null +++ b/CERTInext.Tests/V1NonSuccessLogRedactionTests.cs @@ -0,0 +1,151 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Linq; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Microsoft.Extensions.Logging; +using WireMock.RequestBuilders; +using WireMock.ResponseBuilders; +using WireMock.Server; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Issue 0073 (port of 0044): an unrecognised V1 non-2xx error body is logged so it can be + /// diagnosed, but only after ApplyLoggingRedaction: the authKey is always scrubbed and + /// personal data is scrubbed unless LogSensitiveRequestData is on. Drives the real + /// DeserializeOrThrow call site through WireMock and captures what the client logged via + /// CERTInextClient.OverrideLoggerForTests. All data is synthetic. + /// + [Collection(LoggingStateCollection.Name)] + public class V1NonSuccessLogRedactionTests : IDisposable + { + private const string AuthKey = "SYNTHETIC-AUTHKEY-0073"; + private const string Email = "jane.doe@example.com"; + private const string Name = "Jane Doe"; + + private readonly WireMockServer _server; + + public V1NonSuccessLogRedactionTests() + { + _server = WireMockServer.Start(); + } + + public void Dispose() => _server.Stop(); + + private sealed class CapturingLogger : ILogger + { + public ConcurrentQueue<(LogLevel Level, string Message)> Entries { get; } = new(); + public IDisposable BeginScope(TState state) => null; + public bool IsEnabled(LogLevel logLevel) => true; + public void Log(LogLevel logLevel, EventId eventId, TState state, Exception exception, + Func formatter) + => Entries.Enqueue((logLevel, formatter(state, exception))); + } + + private CERTInextClient BuildClient(bool logSensitiveRequestData) => new CERTInextClient(new CERTInextConfig + { + ApiUrl = _server.Urls[0], + AuthMode = "AccessKey", + ApiKey = "synthetic-access-key", + AccountNumber = "9988776655", + LogSensitiveRequestData = logSensitiveRequestData + }); + + // Unrecognised shape (no meta.errorMessage/errorCode, no top-level message) that nevertheless + // echoes a credential and personal data, which is the case redaction must cover. + private static string BuildBody(string marker) => + "{\"timestamp\":\"2026-10-02T00:00:00.000+00:00\",\"status\":502,\"error\":\"Bad Gateway\"," + + $"\"trace\":\"{marker}\",\"meta\":{{\"authKey\":\"{AuthKey}\"}}," + + $"\"requestorEmail\":\"{Email}\",\"requestorName\":\"{Name}\"}}"; + + private async Task<(Exception Error, List<(LogLevel Level, string Message)> Lines)> RunAsync( + bool logSensitiveRequestData, int status, string body, string marker) + { + _server.Reset(); + _server.Given(Request.Create().WithPath("/GetProductDetails").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(status) + .WithHeader("Content-Type", "application/json").WithBody(body)); + + var client = BuildClient(logSensitiveRequestData); + var logger = new CapturingLogger(); + Exception error = null; + using (CERTInextClient.OverrideLoggerForTests(logger)) + { + try { await client.GetProductDetailsAsync(); } + catch (Exception ex) { error = ex; } + } + + // The client logger is process-wide; scope to lines carrying this call's marker. + var lines = logger.Entries.Where(e => e.Message != null && e.Message.Contains(marker)).ToList(); + return (error, lines); + } + + [Fact] + public async Task UnrecognisedErrorBody_FlagOff_LogsBodyWithAuthKeyAndPiiRedacted() + { + string marker = "m-" + Guid.NewGuid().ToString("N"); + var (error, lines) = await RunAsync(false, 502, BuildBody(marker), marker); + + error.Should().NotBeNull(); + error.Message.Should().Contain("unrecognised error body (HTTP 502)"); + + var failure = lines.Where(l => l.Message.StartsWith("CERTInext API non-success")).ToList(); + failure.Should().ContainSingle("the unrecognised body must be logged exactly once"); + failure[0].Level.Should().Be(LogLevel.Error); + string msg = failure[0].Message; + msg.Should().Contain("HttpStatus=502").And.Contain("Bad Gateway", "the diagnosable part of the body is kept"); + msg.Should().Contain("\"authKey\":\"***REDACTED***\""); + msg.Should().NotContain(AuthKey).And.NotContain(Email).And.NotContain(Name); + + lines.Should().NotContain(l => l.Message.Contains(AuthKey) || l.Message.Contains(Email) || l.Message.Contains(Name)); + } + + [Fact] + public async Task UnrecognisedErrorBody_FlagOn_KeepsPiiButStillRedactsAuthKey() + { + string marker = "m-" + Guid.NewGuid().ToString("N"); + var (_, lines) = await RunAsync(true, 502, BuildBody(marker), marker); + + var failure = lines.Where(l => l.Message.StartsWith("CERTInext API non-success")).ToList(); + failure.Should().ContainSingle(); + string msg = failure[0].Message; + msg.Should().Contain(Email).And.Contain(Name); + msg.Should().Contain("\"authKey\":\"***REDACTED***\"").And.NotContain(AuthKey); + lines.Should().NotContain(l => l.Message.Contains(AuthKey)); + } + + [Fact] + public async Task NonJsonErrorBody_FormEncodedAuthKey_IsRedactedInLog() + { + string marker = "m-" + Guid.NewGuid().ToString("N"); + string body = $"Bad Gateway {marker} authKey={AuthKey}"; + var (error, lines) = await RunAsync(false, 502, body, marker); + + error.Message.Should().Contain("unrecognised error body (HTTP 502)"); + var failure = lines.Where(l => l.Message.StartsWith("CERTInext API non-success")).ToList(); + failure.Should().ContainSingle(); + failure[0].Message.Should().Contain("Bad Gateway").And.Contain("authKey=***REDACTED***").And.NotContain(AuthKey); + } + + [Fact] + public async Task UnrecognisedErrorBody_ExceptionMessageDoesNotEmbedBody() + { + string marker = "m-" + Guid.NewGuid().ToString("N"); + var (error, _) = await RunAsync(false, 502, BuildBody(marker), marker); + + error.Message.Should().NotContain(AuthKey).And.NotContain(Email).And.NotContain(marker, + "the raw body goes to the (redacted) log only, never into the exception surfaced to Command"); + } + } +} diff --git a/CERTInext.Tests/V1NonSuccessResponseTests.cs b/CERTInext.Tests/V1NonSuccessResponseTests.cs new file mode 100644 index 0000000..4940129 --- /dev/null +++ b/CERTInext.Tests/V1NonSuccessResponseTests.cs @@ -0,0 +1,101 @@ +// Copyright 2026 Keyfactor +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using WireMock.RequestBuilders; +using WireMock.ResponseBuilders; +using WireMock.Server; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// A V1 call that gets a non-2xx response whose body is not a CERTInext envelope + /// must surface the HTTP status in the exception, not just "unrecognised error body". + /// + /// The body below is the one returned when the V1 GetOrderReport + /// call is sent to the V2 base URL (ApiUrl without /emSignHub-API/): the host's default + /// Spring Boot 404 body, with no meta and no message. + /// + public class V1NonSuccessResponseTests : IDisposable + { + internal const string LiveSpringNotFoundBody = + "{\"timestamp\":\"2026-09-29T16:05:05.736+00:00\",\"status\":404,\"error\":\"Not Found\",\"path\":\"/GetOrderReport\"}"; + + private readonly WireMockServer _server; + + public V1NonSuccessResponseTests() + { + _server = WireMockServer.Start(); + } + + public void Dispose() + { + _server.Stop(); + } + + private CERTInextClient BuildClient() => + new CERTInextClient(new CERTInextConfig + { + ApiUrl = _server.Urls[0], + AuthMode = "AccessKey", + ApiKey = "test-key", + AccountNumber = "12345", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + PageSize = 100 + }); + + private void StubNotFound(string path) => + _server + .Given(Request.Create().WithPath(path).UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(404) + .WithHeader("Content-Type", "application/json") + .WithBody(LiveSpringNotFoundBody)); + + [Fact] + public async Task ListOrdersAsync_SpringNotFoundBody_ThrowsWithHttpStatus() + { + StubNotFound("/GetOrderReport"); + var client = BuildClient(); + + Func act = async () => + { + await foreach (var _ in client.ListOrdersAsync(pageSize: 5)) + { + } + }; + + await act.Should().ThrowAsync() + .WithMessage("CERTInext returned an unrecognised error body (HTTP 404) for operation 'list orders page 1'. See gateway logs for details."); + } + + [Fact] + public async Task GetProductDetailsAsync_SpringNotFoundBody_ThrowsWithHttpStatus() + { + // Same shared DeserializeOrThrow path, different caller. + StubNotFound("/GetProductDetails"); + var client = BuildClient(); + + Func act = () => client.GetProductDetailsAsync(); + + await act.Should().ThrowAsync() + .WithMessage("*unrecognised error body (HTTP 404) for operation 'get product details'*"); + } + } +} diff --git a/CERTInext.Tests/V2AgreementAcceptTests.cs b/CERTInext.Tests/V2AgreementAcceptTests.cs new file mode 100644 index 0000000..a310cdb --- /dev/null +++ b/CERTInext.Tests/V2AgreementAcceptTests.cs @@ -0,0 +1,360 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Linq; +using System.Text.Json; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Microsoft.Extensions.Logging; +using Moq; +using WireMock.RequestBuilders; +using WireMock.ResponseBuilders; +using WireMock.Server; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// An SSL/TLS order that Track Order shows at pending-agreement is waiting for the + /// Subscriber Agreement ("the CA will not release the certificate until this is done"). The plugin + /// calls POST /ssl-certificates/{orderId}/agreement once per order per enroll call or sync + /// pass, with the same resolved signer values as create, audit-logs the intent first, and never + /// fails the enrollment or sync when the call fails. + /// + [Collection(LoggingStateCollection.Name)] + public class V2AgreementAcceptTests : IDisposable + { + private const string OrderId = "ord_agr_001"; + private const string SignerNameValue = "Jordan Signer-Placeholder"; + private const string SignerPlaceValue = "Springfield"; + + private readonly WireMockServer _server = WireMockServer.Start(); + public void Dispose() => _server.Stop(); + + // --------------------------------------------------------------------------- + // Client (WireMock): wire shape + // --------------------------------------------------------------------------- + + private CERTInextClient BuildClient() => new CERTInextClient(new CERTInextConfig + { + ApiUrl = _server.Urls[0], + UseV2Api = true, + OAuthClientId = "my-v2-client", + OAuthClientSecret = "my-v2-secret", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + PageSize = 100 + }); + + private void StubToken() => + _server.Given(Request.Create().WithPath("/oauth/token").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2TokenResponseJson(3600))); + + [Fact] + public async Task AcceptAgreementV2Async_PostsTheSpecBodyToTheSslAgreementPath() + { + StubToken(); + _server.Given(Request.Create().WithPath($"/api/certinext/v2/ssl-certificates/{OrderId}/agreement").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json").WithBody("{}")); + + using var client = BuildClient(); + await client.AcceptAgreementV2Async(Constants.ApiV2.FamilySsl, OrderId, + new V2AgreementParams { SignerName = SignerNameValue, SignerPlace = SignerPlaceValue, Accepted = true }); + + var entry = _server.LogEntries.Single(e => e.RequestMessage.Path.EndsWith("/agreement")); + entry.RequestMessage.Method.Should().Be("POST"); + using var doc = JsonDocument.Parse(entry.RequestMessage.Body!); + var root = doc.RootElement; + root.EnumerateObject().Select(p => p.Name).Should().Equal("agreement"); + var agreement = root.GetProperty("agreement"); + agreement.GetProperty("signerName").GetString().Should().Be(SignerNameValue); + agreement.GetProperty("signerPlace").GetString().Should().Be(SignerPlaceValue); + agreement.GetProperty("accepted").GetBoolean().Should().BeTrue(); + agreement.EnumerateObject().Select(p => p.Name).Should().BeEquivalentTo( + new[] { "signerName", "signerPlace", "accepted" }, "the AgreementAcceptRequest schema has exactly these members (no signerIp)"); + } + + [Theory] + [InlineData(Constants.ApiV2.FamilyPrivatePki)] + [InlineData(Constants.ApiV2.FamilySignature)] + public async Task AcceptAgreementV2Async_NonSslFamily_ThrowsBeforeAnyRequest(string family) + { + using var client = BuildClient(); + Func act = () => client.AcceptAgreementV2Async(family, OrderId, + new V2AgreementParams { SignerName = "A", SignerPlace = "B", Accepted = true }); + + await act.Should().ThrowAsync(); + _server.LogEntries.Should().BeEmpty(); + } + + [Fact] + public async Task AcceptAgreementV2Async_CaRejection_Throws() + { + StubToken(); + _server.Given(Request.Create().WithPath($"/api/certinext/v2/ssl-certificates/{OrderId}/agreement").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(422) + .WithHeader("Content-Type", "application/problem+json") + .WithBody("{\"title\":\"Unprocessable Entity\",\"status\":422,\"detail\":\"not in a state to accept\"}")); + + using var client = BuildClient(); + Func act = () => client.AcceptAgreementV2Async(Constants.ApiV2.FamilySsl, OrderId, + new V2AgreementParams { SignerName = "A", SignerPlace = "B", Accepted = true }); + + await act.Should().ThrowAsync().WithMessage("*HTTP 422*"); + } + + // --------------------------------------------------------------------------- + // Enroll + // --------------------------------------------------------------------------- + + private static CERTInextConfig Config(int pickupRetries = 0, string signerPlace = SignerPlaceValue, + string requestorName = "Connector Requestor") => new CERTInextConfig + { + UseV2Api = true, + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + RequestorName = requestorName, + RequestorEmail = "test@example.com", + SignerPlace = signerPlace, + PickupRetries = pickupRetries, + PickupDelayInSeconds = 1 + }; + + private static Mock NewOrderMock(string family, string trackStatus) + { + var mock = new Mock(MockBehavior.Strict); + if (family == Constants.ApiV2.FamilySsl) + { + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = OrderId, Status = "pending-csr" }); + } + else + { + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = OrderId, Status = "pending-csr" }); + } + mock.Setup(c => c.SubmitCsrV2Async(family, OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.TrackOrderV2Async(family, OrderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = trackStatus }); + return mock; + } + + private static Task EnrollAsync( + CERTInextCAPlugin plugin, string family = Constants.ApiV2.FamilySsl, string signerName = null) + { + var p = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductFamily"] = family == Constants.ApiV2.FamilySsl ? "ssl" : "private-pki", + ["DomainName"] = "example.com" + }; + if (family != Constants.ApiV2.FamilySsl) p["ProductVariant"] = "intranet-ssl"; + if (signerName != null) p["SignerName"] = signerName; + return plugin.Enroll(MockCertificateData.FakeCsrPem, "CN=example.com", + new Dictionary { ["dnsname"] = new[] { "example.com" } }, + new EnrollmentProductInfo { ProductID = Constants.Products.DvSsl, ProductParameters = p }, + RequestFormat.PKCS10, EnrollmentType.New); + } + + [Fact] + public async Task Enroll_PendingAgreement_AcceptsOncePerCall_WithTheCreateSignerValues_AndAuditsFirst() + { + using var capture = new PluginLogCapture(); + var mock = NewOrderMock(Constants.ApiV2.FamilySsl, "pending-agreement"); + V2AgreementParams sent = null; + int calls = 0; + mock.Setup(c => c.AcceptAgreementV2Async(Constants.ApiV2.FamilySsl, OrderId, It.IsAny(), It.IsAny())) + .Callback((_, __, a, ___) => { sent = a; calls++; }) + .Returns(Task.CompletedTask); + // Two pickup polls also observe pending-agreement: still only ONE accept call for the order. + var plugin = new CERTInextCAPlugin(mock.Object, Config(pickupRetries: 2)); + + var result = await EnrollAsync(plugin, signerName: SignerNameValue); + + calls.Should().Be(1, "the acceptance is attempted at most once per order per enroll call"); + sent.Should().NotBeNull(); + sent!.SignerName.Should().Be(SignerNameValue, "a template SignerName overrides the requestor default, as on create"); + sent.SignerPlace.Should().Be(SignerPlaceValue); + sent.Accepted.Should().BeTrue(); + result.CARequestID.Should().Be(OrderId); + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + + var all = capture.Entries.Select(e => e.Message).ToList(); + int started = all.FindIndex(m => m.Contains("Subscriber Agreement acceptance attempt started")); + int accepted = all.FindIndex(m => m.Contains("Subscriber Agreement accepted.")); + started.Should().BeGreaterOrEqualTo(0); + accepted.Should().BeGreaterThan(started, "the intent is audit-logged before the call"); + all[started].Should().Contain(OrderId).And.Contain("pending-agreement"); + all.Should().NotContain(m => m.Contains(SignerNameValue) || m.Contains(SignerPlaceValue), + "the signer's name and place are personal data, withheld unless LogSensitiveRequestData is on"); + } + + [Fact] + public async Task Enroll_PendingAgreement_AcceptFailure_WarnsAndStillReturnsThePendingOrder() + { + using var capture = new PluginLogCapture(); + var mock = NewOrderMock(Constants.ApiV2.FamilySsl, "pending-agreement"); + mock.Setup(c => c.AcceptAgreementV2Async(Constants.ApiV2.FamilySsl, OrderId, It.IsAny(), It.IsAny())) + .ThrowsAsync(new Exception("CERTInext V2 API error during 'V2 accept agreement'. HTTP 500. boom")); + var plugin = new CERTInextCAPlugin(mock.Object, Config()); + + var result = await EnrollAsync(plugin); + + result.CARequestID.Should().Be(OrderId); + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + capture.Lines(LogLevel.Warning, "Subscriber Agreement acceptance failed").Should().ContainSingle() + .Which.Should().Contain(OrderId); + } + + [Theory] + [InlineData("pending-dcv")] + [InlineData("pending-approval")] + [InlineData("issued")] + public async Task Enroll_OtherStatuses_NeverCallAcceptAgreement(string status) + { + var mock = NewOrderMock(Constants.ApiV2.FamilySsl, status); + if (status == "issued") + mock.Setup(c => c.DownloadCertificateV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(new V2CertificateDownloadResponse { OrderId = OrderId, CertificatePem = MockCertificateData.FakePemCertificate }); + var plugin = new CERTInextCAPlugin(mock.Object, Config()); + + await EnrollAsync(plugin); + + mock.Verify(c => c.AcceptAgreementV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny()), Times.Never); + } + + [Fact] + public async Task Enroll_PrivatePki_PendingAgreement_NeverCallsAcceptAgreement() + { + var mock = NewOrderMock(Constants.ApiV2.FamilyPrivatePki, "pending-agreement"); + var plugin = new CERTInextCAPlugin(mock.Object, Config()); + + await EnrollAsync(plugin, Constants.ApiV2.FamilyPrivatePki); + + mock.Verify(c => c.AcceptAgreementV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny()), Times.Never); + } + + // --------------------------------------------------------------------------- + // Synchronize + // --------------------------------------------------------------------------- + + private static async IAsyncEnumerable Rows(params OrderReportEntryV2[] rows) + { + foreach (var r in rows) yield return r; + await Task.CompletedTask; + } + + private static OrderReportEntryV2 PendingRow(string id, string domain = "example.com") => new OrderReportEntryV2 + { + OrderNumber = id, + OrderStatus = "Order Accepted", + CertificateStatus = "Pending for Approver", + DomainName = domain, + OrderDate = DateTime.UtcNow.AddHours(-1).ToString("o") + }; + + [Fact] + public async Task Synchronize_PendingAgreementOrder_AcceptedOncePerPass_WithConnectorSignerValues() + { + using var capture = new PluginLogCapture(); + var mock = new Mock(MockBehavior.Strict); + // The same order listed twice in one pass: still a single acceptance. + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(Rows(PendingRow(OrderId), PendingRow(OrderId))); + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync(OrderId, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse { OrderId = OrderId, Status = "pending-agreement" })); + V2AgreementParams sent = null; + mock.Setup(c => c.AcceptAgreementV2Async(Constants.ApiV2.FamilySsl, OrderId, It.IsAny(), It.IsAny())) + .Callback((_, __, a, ___) => sent = a) + .Returns(Task.CompletedTask); + var plugin = new CERTInextCAPlugin(mock.Object, Config()); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + mock.Verify(c => c.AcceptAgreementV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny()), Times.Once); + sent.Should().NotBeNull(); + sent!.SignerName.Should().Be("Connector Requestor"); + sent.SignerPlace.Should().Be(SignerPlaceValue); + capture.Lines(LogLevel.Information, "acceptance attempt started").Should().ContainSingle(); + buffer.Count.Should().Be(2, "the rows are still emitted as pending; acceptance only nudges the CA"); + } + + [Fact] + public async Task Synchronize_AcceptFailure_DoesNotFailTheSync() + { + using var capture = new PluginLogCapture(); + var mock = new Mock(MockBehavior.Strict); + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(Rows(PendingRow(OrderId))); + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync(OrderId, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse { OrderId = OrderId, Status = "pending-agreement" })); + mock.Setup(c => c.AcceptAgreementV2Async(Constants.ApiV2.FamilySsl, OrderId, It.IsAny(), It.IsAny())) + .ThrowsAsync(new Exception("HTTP 500")); + var plugin = new CERTInextCAPlugin(mock.Object, Config()); + var buffer = new BlockingCollection(100); + + Func act = () => plugin.Synchronize(buffer, null, true, CancellationToken.None); + + await act.Should().NotThrowAsync(); + buffer.Should().ContainSingle().Which.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + capture.Lines(LogLevel.Warning, "Subscriber Agreement acceptance failed").Should().ContainSingle(); + } + + [Fact] + public async Task Synchronize_NoSignerConfigured_MakesNoExtraCalls() + { + var mock = new Mock(MockBehavior.Strict); + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(Rows(PendingRow(OrderId))); + var plugin = new CERTInextCAPlugin(mock.Object, Config(signerPlace: "")); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + buffer.Count.Should().Be(1); + mock.Verify(c => c.ResolveAndTrackOrderV2WithFamilyAsync(It.IsAny(), It.IsAny()), Times.Never); + } + + [Fact] + public async Task Synchronize_PendingRowWithoutDomain_NonSslFamily_IsNotTracked() + { + var mock = new Mock(MockBehavior.Strict); + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(Rows(PendingRow(OrderId, domain: ""))); + var plugin = new CERTInextCAPlugin(mock.Object, Config()); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + buffer.Count.Should().Be(1); + mock.Verify(c => c.ResolveAndTrackOrderV2WithFamilyAsync(It.IsAny(), It.IsAny()), Times.Never); + } + } +} diff --git a/CERTInext.Tests/V2AgreementSignerIpTests.cs b/CERTInext.Tests/V2AgreementSignerIpTests.cs new file mode 100644 index 0000000..95cf026 --- /dev/null +++ b/CERTInext.Tests/V2AgreementSignerIpTests.cs @@ -0,0 +1,97 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Generic; +using System.Linq; +using System.Text.Json; +using System.Text.Json.Serialization; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Moq; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// The V2 spec's Agreement schema (SSL create and signature create alike) is exactly + /// signerName / signerPlace / accepted: there is no signerIp, so the + /// connector and template SignerIp settings are V1-only and must never reach a V2 body. + /// + public class V2AgreementSignerIpTests + { + private const string OrderId = "ord_sip_001"; + + [Fact] + public void V2AgreementParams_HasNoSignerIpMember_AndSerializesToTheSpecShape() + { + typeof(V2AgreementParams).GetProperties().Select(p => p.Name) + .Should().NotContain("SignerIp"); + + var json = JsonSerializer.Serialize( + new V2AgreementParams { SignerName = "A", SignerPlace = "B", Accepted = true }, + new JsonSerializerOptions { DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull }); + + json.Should().NotContain("signerIp"); + json.Should().Be("{\"signerName\":\"A\",\"signerPlace\":\"B\",\"accepted\":true}"); + } + + [Fact] + public async Task EnrollV2_WithConnectorAndTemplateSignerIp_NeverPutsSignerIpOnTheWire() + { + var mock = new Mock(MockBehavior.Strict); + V2CreateSslOrderRequest captured = null; + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .Callback((_, __, req, ___) => captured = req) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = OrderId, Status = "pending-dcv" }); + mock.Setup(c => c.SubmitCsrV2Async(It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "pending-dcv" }); + + var plugin = new CERTInextCAPlugin(mock.Object, new CERTInextConfig + { + UseV2Api = true, + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + SignerPlace = "New York", + SignerIp = "203.0.113.10", + PickupRetries = 0 + }); + var productInfo = new EnrollmentProductInfo + { + ProductID = Constants.Products.DvSsl, + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductFamily"] = "ssl", + ["DomainName"] = "example.com", + ["SignerIp"] = "198.51.100.7" + } + }; + + await plugin.Enroll(MockCertificateData.FakeCsrPem, "CN=example.com", + new Dictionary(), productInfo, RequestFormat.PKCS10, + EnrollmentType.New); + + captured.Should().NotBeNull(); + string body = JsonSerializer.Serialize(captured, + new JsonSerializerOptions { DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull }); + body.Should().Contain("\"agreement\":{\"signerName\":\"Test User\",\"signerPlace\":\"New York\",\"accepted\":true}"); + body.ToLowerInvariant().Should().NotContain("signerip"); + body.Should().NotContain("203.0.113.10").And.NotContain("198.51.100.7"); + } + } +} diff --git a/CERTInext.Tests/V2CertificateNotGeneratedTests.cs b/CERTInext.Tests/V2CertificateNotGeneratedTests.cs new file mode 100644 index 0000000..ff28910 --- /dev/null +++ b/CERTInext.Tests/V2CertificateNotGeneratedTests.cs @@ -0,0 +1,283 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Linq; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Microsoft.Extensions.Logging; +using Moq; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Download Certificate answers 422 EMS-1165 for a while after Track Order already reports + /// issued (the certificate is not generated yet; ~20 s normally). That is expected, so it + /// must not log a Warning per attempt: Debug per attempt plus one Info summary, the order stays + /// pending, and any other download error keeps its Warning. Covers the enroll immediate + /// download, the pickup poll, GetSingleRecord and Synchronize. + /// + [Collection(LoggingStateCollection.Name)] + public class V2CertificateNotGeneratedTests + { + private const string OrderId = "ord_ng_001"; + + private static readonly V2CertificateNotGeneratedException NotGenerated = new( + "CERTInext V2 API error during 'V2 download certificate'. HTTP 422. Unprocessable Entity: EMS-1165 Invalid request status."); + + private static CERTInextConfig Config(int pickupRetries = 0, ICertificateDataReader _ = null) => new CERTInextConfig + { + UseV2Api = true, + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + SignerPlace = "New York", + PickupRetries = pickupRetries, + PickupDelayInSeconds = 1 + }; + + private static V2OrderStatusResponse IssuedButNotGenerated() => new V2OrderStatusResponse + { + OrderId = OrderId, Status = "issued", OrderState = "Order Accepted", CertificateState = "Approved by System" + }; + + private static Mock NewIssuedOrderMock() + { + var mock = new Mock(MockBehavior.Strict); + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = OrderId, Status = "pending-csr" }); + mock.Setup(c => c.SubmitCsrV2Async(It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(IssuedButNotGenerated()); + return mock; + } + + private static Task EnrollAsync(CERTInextCAPlugin plugin) => + plugin.Enroll(MockCertificateData.FakeCsrPem, "CN=example.com", + new Dictionary { ["dnsname"] = new[] { "example.com" } }, + new EnrollmentProductInfo + { + ProductID = Constants.Products.DvSsl, + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductFamily"] = "ssl", ["DomainName"] = "example.com" + } + }, + RequestFormat.PKCS10, EnrollmentType.New); + + // --------------------------------------------------------------------------- + // Classifier + // --------------------------------------------------------------------------- + + [Fact] + public void IsCertificateNotGeneratedYet_RecognisesTheTypedExceptionAndTheEquivalentPlainMessage() + { + CERTInextCAPlugin.IsCertificateNotGeneratedYet(NotGenerated).Should().BeTrue(); + CERTInextCAPlugin.IsCertificateNotGeneratedYet(new Exception( + "CERTInext V2 API error during 'V2 download certificate'. HTTP 422. EMS-1165 Invalid request status.")).Should().BeTrue(); + } + + [Theory] + [InlineData("CERTInext V2 API error during 'V2 download certificate'. HTTP 422. EMS-1164 Domain Name is not matching.")] + [InlineData("CERTInext V2 API error during 'V2 download certificate'. HTTP 500. EMS-1165 something")] + [InlineData("HTTP 422 with no code")] + public void IsCertificateNotGeneratedYet_OtherFailures_AreNotClassifiedAsNotGenerated(string message) + { + CERTInextCAPlugin.IsCertificateNotGeneratedYet(new Exception(message)).Should().BeFalse(); + CERTInextCAPlugin.IsCertificateNotGeneratedYet(null).Should().BeFalse(); + } + + // --------------------------------------------------------------------------- + // Enroll: immediate download + pickup poll + // --------------------------------------------------------------------------- + + [Fact] + public async Task Enroll_IssuedButNotGeneratedForTheWholePickup_ReturnsPending_NoWarnings_OneInfoSummary() + { + using var capture = new PluginLogCapture(); + var mock = NewIssuedOrderMock(); + mock.Setup(c => c.DownloadCertificateV2Async(It.IsAny(), OrderId, It.IsAny())) + .ThrowsAsync(NotGenerated); + var plugin = new CERTInextCAPlugin(mock.Object, Config(pickupRetries: 2)); + + var result = await EnrollAsync(plugin); + + result.CARequestID.Should().Be(OrderId); + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + result.Certificate.Should().BeNull(); + result.StatusMessage.Should().Contain("not generated yet"); + + capture.Entries.Where(e => e.Level >= LogLevel.Warning).Should().BeEmpty( + "an expected 422 EMS-1165 on an issued order must not log a Warning or Error per attempt"); + var summary = capture.Lines(LogLevel.Information, "not generated yet after"); + summary.Should().ContainSingle(); + summary[0].Should().Contain("2 of 2").And.Contain("EMS-1165") + .And.Contain("CertificateState='Approved by System'").And.Contain("OrderState='Order Accepted'"); + // Debug per attempt: the immediate download plus both pickup attempts. + capture.Entries.Count(e => e.Level == LogLevel.Debug && e.Message.Contains("not generated yet")).Should().Be(3); + mock.Verify(c => c.DownloadCertificateV2Async(It.IsAny(), OrderId, It.IsAny()), Times.Exactly(3)); + } + + [Fact] + public async Task Enroll_CertificateBecomesDownloadableDuringPickup_ReturnsIssued_WithoutWarnings() + { + using var capture = new PluginLogCapture(); + var mock = NewIssuedOrderMock(); + mock.SetupSequence(c => c.DownloadCertificateV2Async(It.IsAny(), OrderId, It.IsAny())) + .ThrowsAsync(NotGenerated) // immediate attempt + .ThrowsAsync(NotGenerated) // pickup attempt 1 + .ReturnsAsync(new V2CertificateDownloadResponse + { + OrderId = OrderId, SerialNumber = "0A1B", CertificatePem = MockCertificateData.FakePemCertificate + }); + var plugin = new CERTInextCAPlugin(mock.Object, Config(pickupRetries: 3)); + + var result = await EnrollAsync(plugin); + + result.Status.Should().Be((int)EndEntityStatus.GENERATED); + result.Certificate.Should().StartWith("-----BEGIN CERTIFICATE-----"); + capture.Entries.Where(e => e.Level >= LogLevel.Warning).Should().BeEmpty(); + capture.Lines(LogLevel.Information, "not generated yet after").Should().BeEmpty( + "the summary is only for a poll that ended without the certificate"); + } + + [Fact] + public async Task Enroll_OtherDownloadErrors_StillWarnPerAttempt() + { + using var capture = new PluginLogCapture(); + var mock = NewIssuedOrderMock(); + mock.Setup(c => c.DownloadCertificateV2Async(It.IsAny(), OrderId, It.IsAny())) + .ThrowsAsync(new Exception("CERTInext V2 API error during 'V2 download certificate'. HTTP 500. boom")); + var plugin = new CERTInextCAPlugin(mock.Object, Config(pickupRetries: 2)); + + var result = await EnrollAsync(plugin); + + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + capture.Lines(LogLevel.Warning, "certificate download failed").Length.Should().Be(3, + "the immediate download and both pickup attempts keep their Warning"); + capture.Lines(LogLevel.Information, "not generated yet after").Should().BeEmpty(); + } + + // --------------------------------------------------------------------------- + // GetSingleRecord + // --------------------------------------------------------------------------- + + [Fact] + public async Task GetSingleRecord_IssuedButNotGenerated_LogsInfoNotWarning_AndReturnsTheRecordWithoutABody() + { + using var capture = new PluginLogCapture(); + var mock = new Mock(MockBehavior.Strict); + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync(OrderId, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, IssuedButNotGenerated())); + mock.Setup(c => c.ResolveAndDownloadCertificateV2Async(OrderId, It.IsAny())) + .ThrowsAsync(NotGenerated); + var plugin = new CERTInextCAPlugin(mock.Object, Config()); + + var record = await plugin.GetSingleRecord(OrderId); + + record.CARequestID.Should().Be(OrderId); + record.Certificate.Should().BeNull(); + capture.Entries.Where(e => e.Level >= LogLevel.Warning).Should().BeEmpty(); + var lines = capture.Lines(LogLevel.Information, "not generated yet"); + lines.Should().ContainSingle(); + lines[0].Should().Contain("CertificateState='Approved by System'"); + } + + [Fact] + public async Task GetSingleRecord_OtherDownloadError_StillWarns() + { + using var capture = new PluginLogCapture(); + var mock = new Mock(MockBehavior.Strict); + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync(OrderId, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, IssuedButNotGenerated())); + mock.Setup(c => c.ResolveAndDownloadCertificateV2Async(OrderId, It.IsAny())) + .ThrowsAsync(new Exception("CERTInext V2 API error during 'V2 download certificate'. HTTP 500. boom")); + var plugin = new CERTInextCAPlugin(mock.Object, Config()); + + await plugin.GetSingleRecord(OrderId); + + capture.Lines(LogLevel.Warning, "certificate download failed").Should().ContainSingle(); + } + + // --------------------------------------------------------------------------- + // Synchronize + // --------------------------------------------------------------------------- + + private static async IAsyncEnumerable Rows(params OrderReportEntryV2[] rows) + { + foreach (var r in rows) yield return r; + await Task.CompletedTask; + } + + private static OrderReportEntryV2 IssuedRow() => new OrderReportEntryV2 + { + OrderNumber = OrderId, + OrderStatus = "Order Fulfilled", + CertificateStatus = "Certificate Downloaded", + DomainName = "example.com", + ProductCode = "842", + OrderDate = DateTime.UtcNow.AddHours(-1).ToString("o") + }; + + [Fact] + public async Task Synchronize_IssuedButNotGenerated_NoWarning_CountedInTheSummary_RecordEmittedWithoutBody() + { + using var capture = new PluginLogCapture(); + var mock = new Mock(MockBehavior.Strict); + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(Rows(IssuedRow())); + mock.Setup(c => c.ResolveAndDownloadCertificateV2Async(OrderId, It.IsAny())) + .ThrowsAsync(NotGenerated); + var plugin = new CERTInextCAPlugin(mock.Object, Config()); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + var record = buffer.ToArray().Should().ContainSingle().Which; + record.CARequestID.Should().Be(OrderId); + record.Certificate.Should().BeNullOrEmpty(); + capture.Entries.Where(e => e.Level >= LogLevel.Warning).Should().BeEmpty(); + capture.Lines(LogLevel.Debug, "not generated yet").Should().ContainSingle(); + capture.Lines(LogLevel.Information, "synchronization complete").Should().ContainSingle() + .Which.Should().Contain("IssuedNotGeneratedYet=1"); + } + + [Fact] + public async Task Synchronize_OtherDownloadError_StillWarns_AndIsNotCountedAsNotGenerated() + { + using var capture = new PluginLogCapture(); + var mock = new Mock(MockBehavior.Strict); + mock.Setup(c => c.ListOrdersV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Returns(Rows(IssuedRow())); + mock.Setup(c => c.ResolveAndDownloadCertificateV2Async(OrderId, It.IsAny())) + .ThrowsAsync(new Exception("CERTInext V2 API error during 'V2 download certificate'. HTTP 500. boom")); + var plugin = new CERTInextCAPlugin(mock.Object, Config()); + var buffer = new BlockingCollection(100); + + await plugin.Synchronize(buffer, null, true, CancellationToken.None); + + capture.Lines(LogLevel.Warning, "certificate download failed").Should().ContainSingle(); + capture.Lines(LogLevel.Information, "synchronization complete").Should().ContainSingle() + .Which.Should().Contain("IssuedNotGeneratedYet=0"); + } + } +} diff --git a/CERTInext.Tests/V2CsrTransportFailureTests.cs b/CERTInext.Tests/V2CsrTransportFailureTests.cs new file mode 100644 index 0000000..3e9f767 --- /dev/null +++ b/CERTInext.Tests/V2CsrTransportFailureTests.cs @@ -0,0 +1,207 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Generic; +using System.Net.Http; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Moq; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// A transport-level failure or timeout from SubmitCsrV2Async does + /// not tell whether CERTInext actually received + /// the CSR — only that no successful response was seen. Cancelling unconditionally (as is done for a *definitive* CA rejection, covered in + /// V2OrphanedOrderCancelTests) can orphan an order the CA genuinely accepted. + /// + /// Covers the three ambiguous-failure branches: still pending-csr after tracking (cancel), progressed past pending-csr (continue the normal flow, no cancel), and tracking + /// itself failing (return pending without cancelling). Also pins the pure classification logic + /// in . + /// + public class V2CsrTransportFailureTests + { + private const string OrderId = "ord_transport_001"; + private const string Family = Constants.ApiV2.FamilySsl; + + // Mirrors ThrowOnV2Failure's generic fallback shape for a response that never arrived + // (RestSharp's ThrowOnAnyError=false swallows the transport failure into a non-successful + // response with the default HttpStatusCode, which is 0). + private const string TransportFailureText = + "CERTInext V2 API error during 'V2 submit CSR'. HTTP 0. See gateway logs for raw response."; + + private static CERTInextConfig BaseConfig() => new CERTInextConfig + { + UseV2Api = true, + V2InlineCsr = false, // these tests cover the two-call Submit CSR failure paths + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + RequestorName = "DevOps Team", + RequestorEmail = "devops@acme.com", + RequestorIsdCode = "1", + RequestorMobileNumber = "4155551234", + SignerIp = "1.2.3.4", + SignerPlace = "New York", + PickupRetries = 0 + }; + + private static EnrollmentProductInfo SslProductInfo() => new EnrollmentProductInfo + { + ProductID = "DV SSL", + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = "842", + ["ProductFamily"] = "ssl", + ["ProductVariant"] = "dv", + ["DomainName"] = "example.com" + } + }; + + private static Mock MockPlacingOrder() + { + var mock = new Mock(MockBehavior.Strict); + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = "842", ProductTypeId = "13", Active = true } + }); + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = OrderId, Status = "pending-csr" }); + return mock; + } + + private static Task EnrollAsync(ICERTInextClient client) => + new CERTInextCAPlugin(client, BaseConfig()).Enroll( + csr: MockCertificateData.FakeCsrPem, + subject: "CN=example.com", + san: new Dictionary(), + productInfo: SslProductInfo(), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + // --------------------------------------------------------------------------- + // Still pending-csr after tracking -> cancel (same outcome as a definitive rejection). + // --------------------------------------------------------------------------- + + [Fact] + public async Task TransportFailure_StillPendingCsrAfterTracking_Cancels_ReturnsFailed() + { + var mock = MockPlacingOrder(); + mock.Setup(c => c.SubmitCsrV2Async(Family, OrderId, It.IsAny(), It.IsAny())) + .ThrowsAsync(new Exception(TransportFailureText)); + mock.Setup(c => c.TrackOrderV2Async(Family, OrderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = Constants.ApiV2.StatusPendingCsr }); + mock.Setup(c => c.CancelOrderV2Async(Family, OrderId, It.IsAny(), It.IsAny())) + .ReturnsAsync(V2CancelOrderOutcome.Cancelled); + + var result = await EnrollAsync(mock.Object); + + result.Status.Should().Be((int)EndEntityStatus.FAILED); + result.CARequestID.Should().Be(OrderId); + result.StatusMessage.Should().Contain("The orphaned order was cancelled."); + mock.Verify(c => c.TrackOrderV2Async(Family, OrderId, It.IsAny()), Times.Once); + mock.Verify(c => c.CancelOrderV2Async( + Family, OrderId, CERTInextCAPlugin.OrphanedOrderCancelReason, It.IsAny()), Times.Once); + mock.Verify(c => c.SubmitCsrV2Async(Family, OrderId, It.IsAny(), It.IsAny()), + Times.Once, "the CSR submit is never retried"); + } + + // --------------------------------------------------------------------------- + // Progressed past pending-csr -> continue the normal flow, do not cancel a valid order. + // --------------------------------------------------------------------------- + + [Fact] + public async Task TransportFailure_ProgressedPastPendingCsr_DoesNotCancel_ContinuesNormalFlow() + { + var mock = MockPlacingOrder(); + mock.Setup(c => c.SubmitCsrV2Async(Family, OrderId, It.IsAny(), It.IsAny())) + .ThrowsAsync(new Exception(TransportFailureText)); + // CERTInext actually received the CSR despite the transport error on our side — the + // order has already moved on to pending-approval. + mock.Setup(c => c.TrackOrderV2Async(Family, OrderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = Constants.ApiV2.StatusPendingApproval }); + + var result = await EnrollAsync(mock.Object); + + result.Status.Should().NotBe((int)EndEntityStatus.FAILED, + "the CSR was actually accepted — this must not be reported as a failed enrollment"); + result.CARequestID.Should().Be(OrderId); + mock.Verify(c => c.CancelOrderV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny()), Times.Never); + mock.Verify(c => c.TrackOrderV2Async(Family, OrderId, It.IsAny()), Times.Once); + mock.Verify(c => c.SubmitCsrV2Async(Family, OrderId, It.IsAny(), It.IsAny()), + Times.Once, "the CSR submit is never retried"); + } + + // --------------------------------------------------------------------------- + // Tracking itself fails -> don't cancel; return pending with the known orderId. + // --------------------------------------------------------------------------- + + [Fact] + public async Task TransportFailure_TrackingAlsoFails_DoesNotCancel_ReturnsPendingWithOrderId() + { + var mock = MockPlacingOrder(); + mock.Setup(c => c.SubmitCsrV2Async(Family, OrderId, It.IsAny(), It.IsAny())) + .ThrowsAsync(new Exception(TransportFailureText)); + mock.Setup(c => c.TrackOrderV2Async(Family, OrderId, It.IsAny())) + .ThrowsAsync(new Exception("CERTInext V2 API error during 'V2 track order'. HTTP 0. See gateway logs for raw response.")); + + var result = await EnrollAsync(mock.Object); + + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + result.CARequestID.Should().Be(OrderId); + result.Certificate.Should().BeNull(); + result.StatusMessage.Should().Contain("sync will resolve"); + mock.Verify(c => c.CancelOrderV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny()), Times.Never); + } + + // --------------------------------------------------------------------------- + // Pure classification logic. + // --------------------------------------------------------------------------- + + [Theory] + [InlineData("CERTInext V2 API error during 'V2 submit CSR'. HTTP 0. See gateway logs for raw response.", true)] + [InlineData("CERTInext V2 API error during 'V2 submit CSR'. HTTP 503. Service unavailable.", true)] + [InlineData("Some unrecognized failure shape with no HTTP status at all.", true)] + [InlineData("CERTInext V2 API error during 'V2 submit CSR'. HTTP 400. CSR rejected.", false)] + [InlineData("CERTInext V2 API error during 'V2 submit CSR'. HTTP 404. Order not found.", false)] + [InlineData("CERTInext V2 API error during 'V2 submit CSR'. HTTP 499. Client closed request.", false)] + public void IsTransportLevelCsrFailure_ClassifiesByParsedHttpStatus(string message, bool expectedTransportLevel) + { + CERTInextCAPlugin.IsTransportLevelCsrFailure(new Exception(message)).Should().Be(expectedTransportLevel); + } + + [Fact] + public void IsTransportLevelCsrFailure_OperationCanceledException_IsTransportLevel() + { + CERTInextCAPlugin.IsTransportLevelCsrFailure(new OperationCanceledException()).Should().BeTrue(); + } + + [Fact] + public void IsTransportLevelCsrFailure_HttpRequestException_IsTransportLevel() + { + CERTInextCAPlugin.IsTransportLevelCsrFailure(new HttpRequestException("connection refused")).Should().BeTrue(); + } + + [Fact] + public void IsTransportLevelCsrFailure_TimeoutException_IsTransportLevel() + { + CERTInextCAPlugin.IsTransportLevelCsrFailure(new TimeoutException()).Should().BeTrue(); + } + } +} diff --git a/CERTInext.Tests/V2ErrorTextMaskingTests.cs b/CERTInext.Tests/V2ErrorTextMaskingTests.cs new file mode 100644 index 0000000..739f349 --- /dev/null +++ b/CERTInext.Tests/V2ErrorTextMaskingTests.cs @@ -0,0 +1,131 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using WireMock.RequestBuilders; +using WireMock.ResponseBuilders; +using WireMock.Server; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// V2 problem+json title/detail/errors[] can echo a submitted value such as an + /// email address, and ExtractV2ErrorMessage folds that text into the exception message Command + /// stores. With LogSensitiveRequestData off, email-shaped tokens are masked (via + /// MaskEmail) and the rest of the text is preserved; with the flag on the text is verbatim. + /// Mirrors the V1 coverage in . All data is synthetic. + /// + public class V2ErrorTextMaskingTests : IDisposable + { + private const string Email = "jane.doe@example.com"; + private const string MaskedEmail = "j***@example.com"; + private const string OrderId = "ord_mask_001"; + + private readonly WireMockServer _server = WireMockServer.Start(); + + public V2ErrorTextMaskingTests() + { + _server + .Given(Request.Create().WithPath("/oauth/token").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2TokenResponseJson(3600))); + } + + public void Dispose() => _server.Stop(); + + private CERTInextClient BuildClient(bool logSensitiveRequestData) => new CERTInextClient(new CERTInextConfig + { + ApiUrl = _server.Urls[0], + AuthMode = "AccessKey", + ApiKey = "test-v1-key", + AccountNumber = "12345", + UseV2Api = true, + OAuthClientId = "my-v2-client", + OAuthClientSecret = "my-v2-secret", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + PageSize = 100, + GroupNumber = string.Empty, + LogSensitiveRequestData = logSensitiveRequestData + }); + + private void StubRevoke(int status, string body) => + _server + .Given(Request.Create() + .WithPath($"/api/certinext/v2/ssl-certificates/{OrderId}/revoke").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(status) + .WithHeader("Content-Type", "application/problem+json") + .WithBody(body)); + + private static Task RevokeAsync(CERTInextClient client) => + client.RevokeOrderV2Async(Constants.ApiV2.FamilySsl, OrderId, new V2RevokeRequest { Reason = "superseded" }); + + [Fact] + public async Task V2Revoke422_Detail_FlagOff_MasksEmailKeepsRestOfText() + { + StubRevoke(422, MockCertificateData.V2ProblemDetailsJson( + 422, "Unprocessable Entity", $"Contact {Email} is not allowed for this order")); + + using var client = BuildClient(logSensitiveRequestData: false); + var ex = await Assert.ThrowsAsync(() => RevokeAsync(client)); + + ex.Message.Should().Contain(MaskedEmail) + .And.Contain("is not allowed for this order") + .And.NotContain(Email); + } + + [Fact] + public async Task V2Revoke422_Detail_FlagOn_IsVerbatim() + { + StubRevoke(422, MockCertificateData.V2ProblemDetailsJson( + 422, "Unprocessable Entity", $"Contact {Email} is not allowed for this order")); + + using var client = BuildClient(logSensitiveRequestData: true); + var ex = await Assert.ThrowsAsync(() => RevokeAsync(client)); + + ex.Message.Should().Contain(Email); + } + + [Fact] + public async Task V2Failure_PerFieldErrors_FlagOff_MasksEmailInFieldMessage() + { + string body = "{\"type\":\"EMS-400\",\"title\":\"Bad Request\",\"status\":400,\"detail\":\"Validation failed\"," + + $"\"errors\":[{{\"field\":\"requestor.email\",\"message\":\"{Email} is not a registered user\"}}]}}"; + StubRevoke(400, body); + + using var client = BuildClient(logSensitiveRequestData: false); + var ex = await Assert.ThrowsAsync(() => RevokeAsync(client)); + + ex.Message.Should().Contain("requestor.email") + .And.Contain(MaskedEmail) + .And.Contain("is not a registered user") + .And.NotContain(Email); + } + + [Fact] + public async Task V2Failure_Forbidden_FlagOff_MasksEmailInHint() + { + StubRevoke(403, MockCertificateData.V2ProblemDetailsJson( + 403, "Forbidden", $"User {Email} cannot revoke")); + + using var client = BuildClient(logSensitiveRequestData: false); + var ex = await Assert.ThrowsAsync(() => RevokeAsync(client)); + + ex.Message.Should().Contain("HTTP 403") + .And.Contain(MaskedEmail) + .And.NotContain(Email); + } + } +} diff --git a/CERTInext.Tests/V2FamilyOrderRequestSerializationTests.cs b/CERTInext.Tests/V2FamilyOrderRequestSerializationTests.cs new file mode 100644 index 0000000..ac3c7a2 --- /dev/null +++ b/CERTInext.Tests/V2FamilyOrderRequestSerializationTests.cs @@ -0,0 +1,376 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System.Collections.Generic; +using System.Linq; +using System.Text; +using System.Text.Json; +using System.Text.Json.Serialization; +using FluentAssertions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Wire-shape tests for the Private PKI and Document Signer create-order DTOs, checked + /// against the example request bodies in the V2 API spec. Each spec + /// example body is copied verbatim below; the DTO is + /// populated with the same values, serialized with the client's serializer options, and + /// compared structurally (key names, nesting, values — not whitespace or key order). + /// + public class V2FamilyOrderRequestSerializationTests + { + // Mirrors CERTInextClient.GetJsonOptions() (private). + private static JsonSerializerOptions ClientEquivalentJsonOptions() => new JsonSerializerOptions + { + PropertyNameCaseInsensitive = true, + DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull + }; + + private static string Serialize(T value) => JsonSerializer.Serialize(value, ClientEquivalentJsonOptions()); + + /// Order-insensitive canonical form of a JSON document (object keys sorted). + private static string Canonical(string json) + { + using var doc = JsonDocument.Parse(json); + var sb = new StringBuilder(); + WriteCanonical(doc.RootElement, sb); + return sb.ToString(); + } + + private static void WriteCanonical(JsonElement e, StringBuilder sb) + { + switch (e.ValueKind) + { + case JsonValueKind.Object: + sb.Append('{'); + bool first = true; + foreach (var p in e.EnumerateObject().OrderBy(p => p.Name, System.StringComparer.Ordinal)) + { + if (!first) sb.Append(','); + first = false; + sb.Append(JsonSerializer.Serialize(p.Name)).Append(':'); + WriteCanonical(p.Value, sb); + } + sb.Append('}'); + break; + case JsonValueKind.Array: + sb.Append('['); + bool firstItem = true; + foreach (var item in e.EnumerateArray()) + { + if (!firstItem) sb.Append(','); + firstItem = false; + WriteCanonical(item, sb); + } + sb.Append(']'); + break; + case JsonValueKind.String: + sb.Append(JsonSerializer.Serialize(e.GetString())); + break; + default: + sb.Append(e.GetRawText()); + break; + } + } + + // --------------------------------------------------------------------------- + // Private PKI — spec "Private PKI Certificates" -> "Create - Intranet SSL" + // --------------------------------------------------------------------------- + + private const string SpecCreateIntranetSslBody = """ + { + "variant": "intranet-ssl", + "hostname": "intranet.acme.local", + "additionalHosts": [ + "portal.acme.local", + "reports.acme.local", + "10.0.0.50" + ], + "emailNotifications": "all", + "subscription": { "validityYears": 1 }, + "requestor": { + "name": "DevOps Team", + "email": "devops@acme.com", + "phone": "+14155551234", + "designation": "Platform Engineering" + } + } + """; + + [Fact] + public void PrivatePki_CreateIntranetSslSpecExample_SerializesToTheSpecBody() + { + var request = new V2CreatePrivatePkiOrderRequest + { + Variant = "intranet-ssl", + Hostname = "intranet.acme.local", + AdditionalHosts = new List { "portal.acme.local", "reports.acme.local", "10.0.0.50" }, + EmailNotifications = "all", + Subscription = new V2SubscriptionParams { ValidityYears = 1 }, + Requestor = new V2Requestor + { + Name = "DevOps Team", Email = "devops@acme.com", Phone = "+14155551234", Designation = "Platform Engineering" + } + }; + + // The only difference from the spec example is subscription.autoRenew, which the + // shared V2SubscriptionParams always writes (spec: "Optional (default ON)" — the plugin + // always sends the connector's explicit choice, exactly as for SSL). + string expected = SpecCreateIntranetSslBody.Replace( + "\"subscription\": { \"validityYears\": 1 }", + "\"subscription\": { \"validityYears\": 1, \"autoRenew\": false }"); + + Canonical(Serialize(request)).Should().Be(Canonical(expected)); + } + + [Fact] + public void PrivatePki_OptionalBlocks_AreOmittedWhenNull() + { + var request = new V2CreatePrivatePkiOrderRequest + { + Variant = "igtf-host", + Hostname = "compute01.hpc.example.edu", + Requestor = new V2Requestor { Name = "HPC Operations", Email = "hpc-ops@example.edu" } + }; + + using var doc = JsonDocument.Parse(Serialize(request)); + doc.RootElement.EnumerateObject().Select(p => p.Name).Should().BeEquivalentTo( + new[] { "variant", "requestor", "hostname" }, + "only the spec's strictly-mandatory fields remain when nothing optional is set"); + } + + // --------------------------------------------------------------------------- + // Document Signer — spec "Document Signer Certificates" create examples + // --------------------------------------------------------------------------- + + private const string SpecCreateNaturalPersonBody = """ + { + "subjectType": "natural-person", + "emailNotifications": "all", + "requestor": { + "name": "Sarah Johnson", + "email": "sarah.johnson@example.com", + "phone": "+12025551234", + "designation": "Document Signer" + }, + "subject": { + "firstName": "Sarah", + "lastName": "Johnson", + "email": "sarah.johnson@example.com", + "phone": "+12025551234", + "identityDocumentType": "passport", + "identificationNumber": "X12345678", + "streetAddress1": "1600 Pennsylvania Avenue NW", + "locality": "Washington", + "state": "DC", + "postalCode": "20500", + "countryCode": "US" + }, + "subscription": { "validityYears": 1, "autoRenew": false }, + "agreement": { + "signerName": "Sarah Johnson", + "signerPlace": "Washington, DC", + "accepted": true + }, + "remarks": "Document Signer - Natural Person, US" + } + """; + + [Fact] + public void Signature_CreateNaturalPersonSpecExample_SerializesToExactlyTheSpecBody() + { + var request = new V2CreateSignatureOrderRequest + { + SubjectType = "natural-person", + EmailNotifications = "all", + Requestor = new V2Requestor + { + Name = "Sarah Johnson", Email = "sarah.johnson@example.com", Phone = "+12025551234", Designation = "Document Signer" + }, + Subject = new V2SignatureSubject + { + FirstName = "Sarah", + LastName = "Johnson", + Email = "sarah.johnson@example.com", + Phone = "+12025551234", + IdentityDocumentType = "passport", + IdentificationNumber = "X12345678", + StreetAddress1 = "1600 Pennsylvania Avenue NW", + Locality = "Washington", + State = "DC", + PostalCode = "20500", + CountryCode = "US" + }, + Subscription = new V2SubscriptionParams { ValidityYears = 1, AutoRenew = false }, + // No signerIp: the spec's Agreement schema (shared by SSL and signature) has none. + Agreement = new V2AgreementParams { SignerName = "Sarah Johnson", SignerPlace = "Washington, DC", Accepted = true }, + Remarks = "Document Signer - Natural Person, US" + }; + + Canonical(Serialize(request)).Should().Be(Canonical(SpecCreateNaturalPersonBody)); + } + + private const string SpecCreateLegalPersonBody = """ + { + "subjectType": "legal-person", + "emailNotifications": "all", + "requestor": { + "name": "Michael Chen", + "email": "michael.chen@acme.com", + "phone": "+14155551234", + "designation": "VP Engineering" + }, + "subject": { + "firstName": "Michael", + "lastName": "Chen", + "email": "michael.chen@acme.com", + "phone": "+14155551234", + "designation": "VP Engineering", + "organizationName": "Acme Corporation", + "organizationUnit": "Engineering", + "organizationIdentificationNumber": "EIN-12-3456789", + "identityDocumentType": "passport", + "identificationNumber": "P98765432", + "streetAddress1": "500 Market Street", + "streetAddress2": "Suite 300", + "locality": "San Francisco", + "state": "CA", + "postalCode": "94105", + "countryCode": "US" + }, + "subscription": { "validityYears": 1, "autoRenew": false }, + "agreement": { + "signerName": "Michael Chen", + "signerPlace": "San Francisco, CA", + "accepted": true + }, + "remarks": "Document Signer - Legal Person, employee of Acme Corp" + } + """; + + [Fact] + public void Signature_CreateLegalPersonSpecExample_SerializesToExactlyTheSpecBody() + { + var request = new V2CreateSignatureOrderRequest + { + SubjectType = "legal-person", + EmailNotifications = "all", + Requestor = new V2Requestor + { + Name = "Michael Chen", Email = "michael.chen@acme.com", Phone = "+14155551234", Designation = "VP Engineering" + }, + Subject = new V2SignatureSubject + { + FirstName = "Michael", + LastName = "Chen", + Email = "michael.chen@acme.com", + Phone = "+14155551234", + Designation = "VP Engineering", + OrganizationName = "Acme Corporation", + OrganizationUnit = "Engineering", + OrganizationIdentificationNumber = "EIN-12-3456789", + IdentityDocumentType = "passport", + IdentificationNumber = "P98765432", + StreetAddress1 = "500 Market Street", + StreetAddress2 = "Suite 300", + Locality = "San Francisco", + State = "CA", + PostalCode = "94105", + CountryCode = "US" + }, + Subscription = new V2SubscriptionParams { ValidityYears = 1, AutoRenew = false }, + Agreement = new V2AgreementParams { SignerName = "Michael Chen", SignerPlace = "San Francisco, CA", Accepted = true }, + Remarks = "Document Signer - Legal Person, employee of Acme Corp" + }; + + Canonical(Serialize(request)).Should().Be(Canonical(SpecCreateLegalPersonBody)); + } + + private const string SpecCreateLegalEntityBody = """ + { + "subjectType": "legal-entity", + "emailNotifications": "all", + "requestor": { + "name": "Acme Corporation Compliance", + "email": "pki-ops@acme.com", + "phone": "+14155551234", + "designation": "PKI Operations" + }, + "subject": { + "organizationName": "Acme Corporation", + "organizationUnit": "Compliance", + "businessCategory": "Business Entity", + "organizationIdentificationNumber": "EIN-12-3456789", + "email": "pki-ops@acme.com", + "phone": "+14155551234", + "streetAddress1": "500 Market Street", + "streetAddress2": "Suite 300", + "locality": "San Francisco", + "state": "CA", + "postalCode": "94105", + "countryCode": "US" + }, + "subscription": { "validityYears": 1, "autoRenew": false }, + "agreement": { + "signerName": "Acme Corp PKI Operations", + "signerPlace": "San Francisco, CA", + "accepted": true + }, + "remarks": "Document Signer - Legal Entity (org-only subject)" + } + """; + + [Fact] + public void Signature_CreateLegalEntitySpecExample_SerializesToExactlyTheSpecBody_WithNoPersonNameKeys() + { + var request = new V2CreateSignatureOrderRequest + { + SubjectType = "legal-entity", + EmailNotifications = "all", + Requestor = new V2Requestor + { + Name = "Acme Corporation Compliance", Email = "pki-ops@acme.com", Phone = "+14155551234", Designation = "PKI Operations" + }, + Subject = new V2SignatureSubject + { + OrganizationName = "Acme Corporation", + OrganizationUnit = "Compliance", + BusinessCategory = "Business Entity", + OrganizationIdentificationNumber = "EIN-12-3456789", + Email = "pki-ops@acme.com", + Phone = "+14155551234", + StreetAddress1 = "500 Market Street", + StreetAddress2 = "Suite 300", + Locality = "San Francisco", + State = "CA", + PostalCode = "94105", + CountryCode = "US" + }, + Subscription = new V2SubscriptionParams { ValidityYears = 1, AutoRenew = false }, + Agreement = new V2AgreementParams { SignerName = "Acme Corp PKI Operations", SignerPlace = "San Francisco, CA", Accepted = true }, + Remarks = "Document Signer - Legal Entity (org-only subject)" + }; + + string json = Serialize(request); + + Canonical(json).Should().Be(Canonical(SpecCreateLegalEntityBody)); + json.Should().NotContain("firstName").And.NotContain("lastName", + "subject.firstName/lastName are conditional on natural-/legal-person and must be omitted, not sent null"); + } + + [Fact] + public void Signature_SubjectEmail_IsAlwaysWritten_EvenWhenOtherSubjectFieldsAreAbsent() + { + // subject.email is the one strictly-mandatory subject field ("400 if missing"). + var json = Serialize(new V2SignatureSubject { Email = "signer@example.com" }); + + Canonical(json).Should().Be(Canonical("{\"email\":\"signer@example.com\"}")); + } + } +} diff --git a/CERTInext.Tests/V2GroupNumberEnrollmentTests.cs b/CERTInext.Tests/V2GroupNumberEnrollmentTests.cs new file mode 100644 index 0000000..974fc0c --- /dev/null +++ b/CERTInext.Tests/V2GroupNumberEnrollmentTests.cs @@ -0,0 +1,210 @@ +// Copyright 2026 Keyfactor +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; +using System.Collections.Generic; +using System.Text.Json; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Moq; +using Org.BouncyCastle.Asn1.X509; +using Org.BouncyCastle.Crypto; +using Org.BouncyCastle.Crypto.Generators; +using Org.BouncyCastle.Pkcs; +using Org.BouncyCastle.Security; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Tests that the V2 order body carries the connector's configured GroupNumber + /// (V1's DelegationInformation.GroupNumber equivalent), so V2 orders bill to the + /// configured group rather than always the account's default group. These tests exercise + /// EnrollV2Async end-to-end (through ) against a Strict + /// mock, plus direct DTO serialization checks for the new + /// property. + /// + public class V2GroupNumberEnrollmentTests + { + private static Mock NewMock() => + new Mock(MockBehavior.Strict); + + private static CERTInextCAPlugin BuildV2Plugin(ICERTInextClient client, string groupNumber = "") => + new CERTInextCAPlugin(client, new CERTInextConfig + { + UseV2Api = true, + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + SignerIp = "1.2.3.4", + SignerPlace = "New York", + GroupNumber = groupNumber, + PickupRetries = 0 + }); + + private static EnrollmentProductInfo MakeV2ProductInfo(string productCode, string productVariant) => + new EnrollmentProductInfo + { + ProductID = "DV SSL", + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = productCode, + ["ProductFamily"] = "ssl", + ["ProductVariant"] = productVariant, + ["DomainName"] = "example.com" + } + }; + + private static void StubCatalog(Mock mock, string productCode, string productTypeId) => + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = productCode, ProductTypeId = productTypeId, Active = true } + }); + + private static void StubHappyOrderPlacement(Mock mock, string orderId) + { + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), orderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), orderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = orderId, Status = "pending-dcv" }); + } + + private static string GenerateCsrPem(string cn) + { + var keyGen = new RsaKeyPairGenerator(); + keyGen.Init(new KeyGenerationParameters(new SecureRandom(), 2048)); + AsymmetricCipherKeyPair kp = keyGen.GenerateKeyPair(); + + var csr = new Pkcs10CertificationRequest( + "SHA256withRSA", new X509Name($"CN={cn}"), kp.Public, null, kp.Private); + + return "-----BEGIN CERTIFICATE REQUEST-----\n" + + Convert.ToBase64String(csr.GetEncoded(), Base64FormattingOptions.InsertLineBreaks) + + "\n-----END CERTIFICATE REQUEST-----"; + } + + // --------------------------------------------------------------------------- + // EnrollV2Async wiring — GroupNumber populated / omitted on the order body + // --------------------------------------------------------------------------- + + [Fact] + public async Task Enroll_V2_GroupNumberConfigured_PopulatesGroupNumberOnOrderBody() + { + var mock = NewMock(); + StubCatalog(mock, "842", "13"); // DV SSL (non-UCC) + StubHappyOrderPlacement(mock, "ord_grp_001"); + + V2CreateSslOrderRequest captured = null; + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .Callback((_, __, req, ___) => captured = req) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = "ord_grp_001", Status = "pending-dcv" }); + + var plugin = BuildV2Plugin(mock.Object, groupNumber: "GRP-12345"); + + var result = await plugin.Enroll( + csr: GenerateCsrPem("example.com"), + subject: "CN=example.com", + san: null, + productInfo: MakeV2ProductInfo("842", "dv"), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.CARequestID.Should().Be("ord_grp_001"); + captured.Should().NotBeNull(); + captured!.GroupNumber.Should().Be("GRP-12345", + "a configured GroupNumber must be forwarded to the V2 order body, mirroring V1's " + + "DelegationInformation.GroupNumber"); + } + + [Fact] + public async Task Enroll_V2_GroupNumberBlank_OmitsGroupNumberFromOrderBody() + { + var mock = NewMock(); + StubCatalog(mock, "842", "13"); + StubHappyOrderPlacement(mock, "ord_grp_002"); + + V2CreateSslOrderRequest captured = null; + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .Callback((_, __, req, ___) => captured = req) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = "ord_grp_002", Status = "pending-dcv" }); + + var plugin = BuildV2Plugin(mock.Object, groupNumber: string.Empty); + + var result = await plugin.Enroll( + csr: GenerateCsrPem("example.com"), + subject: "CN=example.com", + san: null, + productInfo: MakeV2ProductInfo("842", "dv"), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.CARequestID.Should().Be("ord_grp_002"); + captured.Should().NotBeNull(); + captured!.GroupNumber.Should().BeNull( + "an unconfigured GroupNumber must be omitted (null), not sent as an empty string — " + + "the account's default billing group should apply, same as V1's fallback behavior"); + } + + // --------------------------------------------------------------------------- + // DTO serialization — groupNumber key present/absent on the wire + // --------------------------------------------------------------------------- + + [Fact] + public void V2CreateSslOrderRequest_Serialization_OmitsGroupNumber_WhenNull() + { + var req = new V2CreateSslOrderRequest + { + ProductVariant = "dv", + Requestor = new V2Requestor { Name = "Jane Doe", Email = "jane@example.com" }, + Certificate = new V2CertificateParams { Domain = "example.com" }, + GroupNumber = null + }; + + string json = JsonSerializer.Serialize(req); + + json.Should().NotContain("groupNumber", + "the groupNumber key itself must be absent when unset, not present-but-null"); + } + + [Fact] + public void V2CreateSslOrderRequest_Serialization_IncludesGroupNumber_WhenSet() + { + var req = new V2CreateSslOrderRequest + { + ProductVariant = "dv", + Requestor = new V2Requestor { Name = "Jane Doe", Email = "jane@example.com" }, + Certificate = new V2CertificateParams { Domain = "example.com" }, + GroupNumber = "GRP-999" + }; + + string json = JsonSerializer.Serialize(req); + + json.Should().Contain("\"groupNumber\":\"GRP-999\""); + } + } +} diff --git a/CERTInext.Tests/V2InlineCsrConfigTests.cs b/CERTInext.Tests/V2InlineCsrConfigTests.cs new file mode 100644 index 0000000..f811b4b --- /dev/null +++ b/CERTInext.Tests/V2InlineCsrConfigTests.cs @@ -0,0 +1,105 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Generic; +using System.Text.Json; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Moq; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// V2InlineCsr is a CA connector setting (V2 only, default true): when true, SSL/TLS + /// enrollment sends the CSR inline in the create call; false selects create + Submit CSR. + /// + public class V2InlineCsrConfigTests + { + [Fact] + public void CERTInextConfig_DefaultsToTrue_SingleCallIsTheDefault() + { + new CERTInextConfig().V2InlineCsr.Should().BeTrue( + "the two-call flow fails for an already-validated domain (CERTInext approves at create, then rejects the CSR)"); + } + + [Fact] + public void Constants_V2InlineCsr_MatchesJsonPropertyName() + { + Constants.Config.V2InlineCsr.Should().Be("V2InlineCsr"); + } + + [Theory] + [InlineData("true", true)] + [InlineData("false", false)] + public void CERTInextConfig_Deserializes(string json, bool expected) + { + var cfg = JsonSerializer.Deserialize($"{{\"V2InlineCsr\":{json}}}"); + cfg!.V2InlineCsr.Should().Be(expected); + } + + [Fact] + public void GetCAConnectorAnnotations_ContainsV2InlineCsr_BooleanDefaultTrue_WithClearDescription() + { + var annotations = CERTInextCAPluginConfig.GetCAConnectorAnnotations(); + + annotations.Should().ContainKey(Constants.Config.V2InlineCsr); + var a = annotations[Constants.Config.V2InlineCsr]; + a.Type.Should().Be("Boolean"); + a.DefaultValue.Should().Be(true); + a.Hidden.Should().BeFalse(); + a.Comments.Should().ContainAll("V2", "inline", "SSL/TLS", "Private PKI", "two-call", "do not resubmit", "Default: true"); + } + + private static CERTInextCAPlugin NewPlugin() => + new CERTInextCAPlugin(new Mock(MockBehavior.Strict).Object); + + private static Dictionary Info(object inlineCsr) => new Dictionary + { + ["UseV2Api"] = true, + ["ApiUrl"] = "not-a-url", // invalid on purpose: collected with the V2InlineCsr error + ["OAuthClientId"] = "id", + ["OAuthClientSecret"] = "secret", + ["SignerPlace"] = "NY", + ["V2InlineCsr"] = inlineCsr + }; + + [Theory] + [InlineData("yes")] + [InlineData("true")] // a string would fail config deserialization, so it is rejected up front + [InlineData(1)] + public async Task ValidateCAConnectionInfo_RejectsNonBooleanV2InlineCsr(object value) + { + Func act = () => NewPlugin().ValidateCAConnectionInfo(Info(value)); + + await act.Should().ThrowAsync().WithMessage("*V2InlineCsr*must be true or false*"); + } + + [Fact] + public async Task ValidateCAConnectionInfo_AcceptsBooleanV2InlineCsr_ErrorsAreOnlyTheOtherFields() + { + Func act = () => NewPlugin().ValidateCAConnectionInfo(Info(true)); + + // ApiUrl is deliberately invalid, so validation still throws, but not about V2InlineCsr. + var ex = await act.Should().ThrowAsync(); + ex.Which.Message.Should().NotContain("V2InlineCsr"); + } + + [Fact] + public async Task ValidateCAConnectionInfo_AcceptsJsonElementBoolean() + { + var el = JsonDocument.Parse("false").RootElement; + Func act = () => NewPlugin().ValidateCAConnectionInfo(Info(el)); + + var ex = await act.Should().ThrowAsync(); + ex.Which.Message.Should().NotContain("V2InlineCsr"); + } + } +} diff --git a/CERTInext.Tests/V2OrderStatusResponseTests.cs b/CERTInext.Tests/V2OrderStatusResponseTests.cs new file mode 100644 index 0000000..338f775 --- /dev/null +++ b/CERTInext.Tests/V2OrderStatusResponseTests.cs @@ -0,0 +1,77 @@ +// Copyright 2026 Keyfactor +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; +using System.Text.Json; +using FluentAssertions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Pure DTO deserialization tests for 's nested + /// revocation object. No HTTP layer involved — these assert directly + /// against , isolated from the client and plugin code that + /// consumes this type. + /// + public class V2OrderStatusResponseTests + { + /// + /// Raw Track Order response body, as returned against a real revoked SSL order + /// (family ssl-certificates). Verbatim except for whitespace; unmapped fields (requestor, orderedBy, + /// subscriberAgreement, subscription, verifications) are expected to be ignored by + /// System.Text.Json's default unmapped-member handling. + /// + private const string LiveRevokedTrackOrderJson = + @"{""orderId"":""6758681362"",""requestId"":""1279754567"",""status"":""revoked"",""orderState"":""Order Accepted"",""certificateState"":""Certificate Revoked"",""productVariant"":""dv"",""domain"":""nt2-20260924204408874594000.dcv-test.scrup.org"",""expiresAt"":""2026-12-23T20:44:23Z"",""requestor"":{""name"":""Keyfactor Plugin Test"",""email"":""plugin-test@keyfactor.com"",""phone"":""+0000000000"",""designation"":""Plugin Test""},""orderedBy"":{""name"":""Sean"",""email"":""sbailey@keyfactor.com""},""csrSubmitted"":true,""subscriberAgreement"":{""signed"":true,""signerName"":""Keyfactor Plugin Test"",""signedAt"":""2026-09-25T14:18:14Z"",""signedPlace"":""Gateway Lab""},""subscription"":{""validityYears"":1,""endDate"":""2027-09-24T20:44:27Z"",""status"":""active""},""revocation"":{""status"":""Certificate Revoked"",""reason"":""cessation-of-operation"",""processedAt"":""2026-09-24T20:44:41Z""},""verifications"":{""domain"":{""status"":""VERIFIED"",""domains"":[{""domain"":""nt2-20260924204408874594000.dcv-test.scrup.org"",""domainStatus"":""ACTIVE"",""dcvMethod"":""dns-txt"",""dcvStatus"":""VERIFIED"",""verifiedAt"":""2026-09-24T20:44:13Z"",""caaStatus"":""PASSED""}]},""empty"":false}}"; + + [Fact] + public void Deserialize_LiveRevokedOrderBody_PopulatesNestedRevocationObject() + { + var result = JsonSerializer.Deserialize(LiveRevokedTrackOrderJson); + + result.Should().NotBeNull(); + result!.OrderId.Should().Be("6758681362"); + result.Status.Should().Be("revoked"); + result.ProductVariant.Should().Be("dv"); + result.Domain.Should().Be("nt2-20260924204408874594000.dcv-test.scrup.org"); + + // `revocation` is a nested object — status/reason/processedAt — not + // flat top-level revocationReason/revocationDate properties. + result.Revocation.Should().NotBeNull(); + result.Revocation!.Status.Should().Be("Certificate Revoked"); + result.Revocation.Reason.Should().Be("cessation-of-operation", + "the wire reason is RFC 5280-style hyphenated, not V1's camelCase convention"); + result.Revocation.ProcessedAt.Should().Be( + new DateTime(2026, 9, 24, 20, 44, 41, DateTimeKind.Utc), + "processedAt is standard ISO 8601 UTC and should bind directly with no custom converter"); + } + + [Fact] + public void Deserialize_NotRevokedOrderBody_RevocationIsNull() + { + // The `revocation` key is absent entirely when an order has never been revoked — + // not present-but-null. + const string issuedJson = + @"{""orderId"":""ord_abc001"",""requestId"":""req_xyz001"",""status"":""issued"",""productVariant"":""dv"",""domain"":""example.com""}"; + + var result = JsonSerializer.Deserialize(issuedJson); + + result.Should().NotBeNull(); + result!.Status.Should().Be("issued"); + result.Revocation.Should().BeNull(); + } + } +} diff --git a/CERTInext.Tests/V2OrganizationEnrollmentTests.cs b/CERTInext.Tests/V2OrganizationEnrollmentTests.cs new file mode 100644 index 0000000..8e9a55f --- /dev/null +++ b/CERTInext.Tests/V2OrganizationEnrollmentTests.cs @@ -0,0 +1,259 @@ +// Copyright 2026 Keyfactor +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; +using System.Collections.Generic; +using System.Text.Json; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Moq; +using Org.BouncyCastle.Asn1.X509; +using Org.BouncyCastle.Crypto; +using Org.BouncyCastle.Crypto.Generators; +using Org.BouncyCastle.Pkcs; +using Org.BouncyCastle.Security; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Tests that the V2 organization block is populated for OV/EV product variants; + /// CERTInext hard-rejects an OV/EV order that omits it (HTTP 422 + /// [EMS-1180] Organization Name cannot be empty). These tests exercise + /// EnrollV2Async end-to-end (through ) against a + /// Strict mock, plus direct DTO serialization checks for the + /// new block on . + /// + public class V2OrganizationEnrollmentTests + { + private static Mock NewMock() => + new Mock(MockBehavior.Strict); + + private static CERTInextCAPlugin BuildV2Plugin(ICERTInextClient client, string organizationNumber = "") => + new CERTInextCAPlugin(client, new CERTInextConfig + { + UseV2Api = true, + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + SignerIp = "1.2.3.4", + SignerPlace = "New York", + OrganizationNumber = organizationNumber, + PickupRetries = 0 + }); + + // ProductVariant must agree with ProductId (the plugin derives/validates + // one from the other), so callers pass both explicitly rather than this helper hardcoding + // a single ProductID ("OV SSL") for every variant under test. + private static EnrollmentProductInfo MakeV2ProductInfo(string productId, string productCode, string productVariant) => + new EnrollmentProductInfo + { + ProductID = productId, + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = productCode, + ["ProductFamily"] = "ssl", + ["ProductVariant"] = productVariant, + ["DomainName"] = "example.com" + } + }; + + private static void StubCatalog(Mock mock, string productCode, string productTypeId) => + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = productCode, ProductTypeId = productTypeId, Active = true } + }); + + private static void StubHappyOrderPlacement(Mock mock, string orderId) + { + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), orderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), orderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = orderId, Status = "pending-organization-verification" }); + } + + private static string GenerateCsrPem(string cn) + { + var keyGen = new RsaKeyPairGenerator(); + keyGen.Init(new KeyGenerationParameters(new SecureRandom(), 2048)); + AsymmetricCipherKeyPair kp = keyGen.GenerateKeyPair(); + + var csr = new Pkcs10CertificationRequest( + "SHA256withRSA", new X509Name($"CN={cn}"), kp.Public, null, kp.Private); + + return "-----BEGIN CERTIFICATE REQUEST-----\n" + + Convert.ToBase64String(csr.GetEncoded(), Base64FormattingOptions.InsertLineBreaks) + + "\n-----END CERTIFICATE REQUEST-----"; + } + + // --------------------------------------------------------------------------- + // EnrollV2Async wiring — organization block populated / omitted per productVariant + // --------------------------------------------------------------------------- + + [Theory] + [InlineData("ov", Constants.Products.OvSsl, "846", "16")] + [InlineData("ev", Constants.Products.EvSsl, "847", "19")] + [InlineData("OV", Constants.Products.OvSsl, "846", "16")] + [InlineData("Ev", Constants.Products.EvSsl, "847", "19")] + public async Task Enroll_V2_OvOrEvProduct_PopulatesOrganizationBlockFromConfig( + string productVariant, string productId, string catalogCode, string catalogTypeId) + { + var mock = NewMock(); + StubCatalog(mock, catalogCode, catalogTypeId); + StubHappyOrderPlacement(mock, "ord_org_001"); + + V2CreateSslOrderRequest captured = null; + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .Callback((_, __, req, ___) => captured = req) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = "ord_org_001", Status = "pending-organization-verification" }); + + var plugin = BuildV2Plugin(mock.Object, organizationNumber: "ORG-12345"); + + var result = await plugin.Enroll( + csr: GenerateCsrPem("example.com"), + subject: "CN=example.com", + san: null, + productInfo: MakeV2ProductInfo(productId, catalogCode, productVariant), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.CARequestID.Should().Be("ord_org_001"); + captured.Should().NotBeNull(); + captured!.Organization.Should().NotBeNull( + "organization is mandatory for OV/EV orders per the V2 spec's field table"); + captured.Organization.OrganizationNumber.Should().Be("ORG-12345"); + captured.Organization.PreVetted.Should().BeTrue(); + } + + [Fact] + public async Task Enroll_V2_DvProduct_OmitsOrganizationBlock_EvenWhenOrganizationNumberConfigured() + { + var mock = NewMock(); + StubCatalog(mock, "842", "13"); // DV SSL (non-UCC) + StubHappyOrderPlacement(mock, "ord_dv_001"); + + V2CreateSslOrderRequest captured = null; + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .Callback((_, __, req, ___) => captured = req) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = "ord_dv_001", Status = "pending-dcv" }); + + // OrganizationNumber IS configured — a DV order must still omit the block per spec + // ("organization | Conditional - Mandatory for OV / EV", not DV). + var plugin = BuildV2Plugin(mock.Object, organizationNumber: "ORG-12345"); + + var result = await plugin.Enroll( + csr: GenerateCsrPem("example.com"), + subject: "CN=example.com", + san: null, + productInfo: MakeV2ProductInfo(Constants.Products.DvSsl, "842", "dv"), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.CARequestID.Should().Be("ord_dv_001"); + captured.Should().NotBeNull(); + captured!.Organization.Should().BeNull( + "DV orders must not send an organization block even when OrganizationNumber is configured"); + } + + [Theory] + [InlineData("ov", Constants.Products.OvSsl)] + [InlineData("ev", Constants.Products.EvSsl)] + public async Task Enroll_V2_OvOrEvProduct_MissingOrganizationNumber_FailsFastWithoutCallingCa( + string productVariant, string productId) + { + // Strict mock with NOTHING stubbed: proves the guard fires before any catalog lookup + // or order-placement call — mirrors the CSR-SAN-count guard's own Strict-mock test. + var mock = NewMock(); + var plugin = BuildV2Plugin(mock.Object, organizationNumber: string.Empty); + + var result = await plugin.Enroll( + csr: GenerateCsrPem("example.com"), + subject: "CN=example.com", + san: null, + productInfo: MakeV2ProductInfo(productId, "846", productVariant), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.Status.Should().Be((int)EndEntityStatus.FAILED); + result.StatusMessage.Should().Contain("OrganizationNumber"); + + mock.Verify(c => c.GetProductDetailsV2Async(It.IsAny()), Times.Never, + "the OrganizationNumber guard must reject before any catalog lookup is attempted"); + mock.Verify(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny()), Times.Never); + } + + // --------------------------------------------------------------------------- + // DTO serialization — organization block shape on the wire + // --------------------------------------------------------------------------- + + [Fact] + public void V2CreateSslOrderRequest_Serialization_IncludesOrganizationBlock_ForOvEv() + { + var req = new V2CreateSslOrderRequest + { + ProductVariant = "ov", + Requestor = new V2Requestor { Name = "Jane Doe", Email = "jane@example.com" }, + Organization = new V2OrganizationParams + { + OrganizationNumber = "ORG-999", + PreVetted = true + }, + Certificate = new V2CertificateParams { Domain = "example.com" } + }; + + string json = JsonSerializer.Serialize(req); + + json.Should().Contain("\"organization\""); + json.Should().Contain("\"organizationNumber\":\"ORG-999\""); + json.Should().Contain("\"preVetted\":true"); + // preVettingToken is optional and unset here — must be omitted, not sent as null. + json.Should().NotContain("preVettingToken"); + } + + [Fact] + public void V2CreateSslOrderRequest_Serialization_OmitsOrganizationBlock_ForDv() + { + var req = new V2CreateSslOrderRequest + { + ProductVariant = "dv", + Requestor = new V2Requestor { Name = "Jane Doe", Email = "jane@example.com" }, + Organization = null, + Certificate = new V2CertificateParams { Domain = "example.com" } + }; + + string json = JsonSerializer.Serialize(req); + + json.Should().NotContain("\"organization\"", + "the organization key itself (not just its sub-fields) must be absent for DV orders, " + + "not present-but-empty — an empty/placeholder block risks a different CA-side 422"); + } + } +} diff --git a/CERTInext.Tests/V2OrphanedOrderCancelTests.cs b/CERTInext.Tests/V2OrphanedOrderCancelTests.cs new file mode 100644 index 0000000..09f81c8 --- /dev/null +++ b/CERTInext.Tests/V2OrphanedOrderCancelTests.cs @@ -0,0 +1,326 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Generic; +using System.Linq; +using System.Text.Json; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Moq; +using WireMock.RequestBuilders; +using WireMock.ResponseBuilders; +using WireMock.Server; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// When SubmitCsrV2Async throws after the V2 order was placed, the order + /// sits at pending-csr and Command never learns its ID. EnrollV2Async must make + /// exactly one best-effort CancelOrderV2Async call for that order's family and return + /// FAILED with the orderId — never throwing, never retrying. + /// + public class V2OrphanedOrderCancelTests + { + private const string OrderId = "ord_orphan_001"; + private const string CsrFailureText = "CERTInext V2 API error during 'V2 submit CSR'. HTTP 400. CSR rejected."; + + private static CERTInextConfig BaseConfig() => new CERTInextConfig + { + UseV2Api = true, + V2InlineCsr = false, // these tests cover the two-call Submit CSR failure paths + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + RequestorName = "DevOps Team", + RequestorEmail = "devops@acme.com", + RequestorIsdCode = "1", + RequestorMobileNumber = "4155551234", + SignerIp = "1.2.3.4", + SignerPlace = "New York", + PickupRetries = 0 + }; + + private static EnrollmentProductInfo SslProductInfo() => new EnrollmentProductInfo + { + ProductID = "DV SSL", + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = "842", + ["ProductFamily"] = "ssl", + ["ProductVariant"] = "dv", + ["DomainName"] = "example.com" + } + }; + + private static EnrollmentProductInfo PrivatePkiProductInfo() => new EnrollmentProductInfo + { + ProductID = Constants.Products.DvSsl, + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductFamily"] = "private-pki", + ["ProductVariant"] = "intranet-ssl", + ["ProductCode"] = "149", + ["DomainName"] = "intranet.acme.local" + } + }; + + /// Strict mock that places an order in . + private static Mock MockPlacingOrder(string family) + { + var mock = new Mock(MockBehavior.Strict); + if (family == Constants.ApiV2.FamilyPrivatePki) + { + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = OrderId, Status = "pending-csr" }); + } + else + { + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = "842", ProductTypeId = "13", Active = true } + }); + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = OrderId, Status = "pending-csr" }); + } + return mock; + } + + private static void SubmitCsrThrows(Mock mock, string family) => + mock.Setup(c => c.SubmitCsrV2Async(family, OrderId, It.IsAny(), It.IsAny())) + .ThrowsAsync(new Exception(CsrFailureText)); + + private static Task EnrollAsync(ICERTInextClient client, EnrollmentProductInfo productInfo) => + new CERTInextCAPlugin(client, BaseConfig()).Enroll( + csr: MockCertificateData.FakeCsrPem, + subject: "CN=example.com", + san: new Dictionary(), + productInfo: productInfo, + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + // --------------------------------------------------------------------------- + // Plugin: EnrollV2Async + // --------------------------------------------------------------------------- + + public static IEnumerable Families() => new[] + { + new object[] { Constants.ApiV2.FamilySsl }, + new object[] { Constants.ApiV2.FamilyPrivatePki } + }; + + private static EnrollmentProductInfo ProductInfoFor(string family) => + family == Constants.ApiV2.FamilyPrivatePki ? PrivatePkiProductInfo() : SslProductInfo(); + + [Theory] + [MemberData(nameof(Families))] + public async Task Enroll_SubmitCsrThrows_CancelsOnceInSameFamily_ReturnsFailedWithOrderId(string family) + { + var mock = MockPlacingOrder(family); + SubmitCsrThrows(mock, family); + mock.Setup(c => c.CancelOrderV2Async(family, OrderId, It.IsAny(), It.IsAny())) + .ReturnsAsync(V2CancelOrderOutcome.Cancelled); + + var result = await EnrollAsync(mock.Object, ProductInfoFor(family)); + + result.Status.Should().Be((int)EndEntityStatus.FAILED); + result.CARequestID.Should().Be(OrderId); + result.Certificate.Should().BeNull(); + result.StatusMessage.Should().Contain("CSR submission failed") + .And.Contain("CSR rejected") + .And.Contain("The orphaned order was cancelled."); + + mock.Verify(c => c.CancelOrderV2Async( + family, OrderId, CERTInextCAPlugin.OrphanedOrderCancelReason, It.IsAny()), Times.Once); + mock.Verify(c => c.CancelOrderV2Async( + It.Is(f => f != family), It.IsAny(), It.IsAny(), It.IsAny()), Times.Never); + mock.Verify(c => c.SubmitCsrV2Async(family, OrderId, It.IsAny(), It.IsAny()), + Times.Once, "the CSR submit is never retried"); + // Strict mock: no TrackOrderV2Async / DownloadCertificateV2Async setup, so any + // post-CSR call would have thrown out of Enroll. + } + + [Fact] + public void OrphanedOrderCancelReason_IsNonEmpty_AndCarriesNoExceptionDetail() + { + CERTInextCAPlugin.OrphanedOrderCancelReason.Should().NotBeNullOrWhiteSpace("an empty reason is rejected with EMS-984"); + CERTInextCAPlugin.OrphanedOrderCancelReason.Should().NotContain("CSR rejected"); + } + + [Fact] + public async Task Enroll_SubmitCsrThrows_CancelReturns422_StillFailed_SaysNotCancelled() + { + var mock = MockPlacingOrder(Constants.ApiV2.FamilySsl); + SubmitCsrThrows(mock, Constants.ApiV2.FamilySsl); + mock.Setup(c => c.CancelOrderV2Async(Constants.ApiV2.FamilySsl, OrderId, It.IsAny(), It.IsAny())) + .ReturnsAsync(V2CancelOrderOutcome.AlreadyTerminal); + + var result = await EnrollAsync(mock.Object, SslProductInfo()); + + result.Status.Should().Be((int)EndEntityStatus.FAILED); + result.CARequestID.Should().Be(OrderId); + result.StatusMessage.Should().Contain("NOT cancelled").And.Contain("422"); + result.StatusMessage.Should().NotContain("The orphaned order was cancelled."); + mock.Verify(c => c.CancelOrderV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny()), Times.Once); + } + + [Theory] + [MemberData(nameof(Families))] + public async Task Enroll_SubmitCsrThrows_CancelThrows_StillFailed_DoesNotThrow_NoRetry(string family) + { + var mock = MockPlacingOrder(family); + SubmitCsrThrows(mock, family); + mock.Setup(c => c.CancelOrderV2Async(family, OrderId, It.IsAny(), It.IsAny())) + .ThrowsAsync(new Exception("CERTInext V2 API error during 'V2 cancel order'. HTTP 500.")); + + EnrollmentResult result = null; + Func act = async () => result = await EnrollAsync(mock.Object, ProductInfoFor(family)); + await act.Should().NotThrowAsync(); + + result.Should().NotBeNull(); + result!.Status.Should().Be((int)EndEntityStatus.FAILED); + result.CARequestID.Should().Be(OrderId); + result.StatusMessage.Should().Contain("CSR submission failed") + .And.Contain("NOT cancelled") + .And.Contain("Cancel it manually"); + mock.Verify(c => c.CancelOrderV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny()), + Times.Once, "the cancel is best-effort and never retried"); + } + + [Theory] + [MemberData(nameof(Families))] + public async Task Enroll_SubmitCsrSucceeds_NeverCancels(string family) + { + var mock = MockPlacingOrder(family); + mock.Setup(c => c.SubmitCsrV2Async(family, OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.TrackOrderV2Async(family, OrderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "pending-approval" }); + + var result = await EnrollAsync(mock.Object, ProductInfoFor(family)); + + result.CARequestID.Should().Be(OrderId); + result.Status.Should().NotBe((int)EndEntityStatus.FAILED); + mock.Verify(c => c.CancelOrderV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny()), Times.Never); + } + } + + /// + /// WireMock coverage for : spec + /// "Cancel Order" is POST /api/certinext/v2/{family}/:orderId/cancel with body + /// { "reason": ... }; 204 = cancelled, 422 = already in a terminal state. + /// + public class CERTInextClientCancelOrderV2Tests : IDisposable + { + private const string OrderId = "ord_cancel_001"; + private readonly WireMockServer _server; + + public CERTInextClientCancelOrderV2Tests() + { + _server = WireMockServer.Start(); + _server + .Given(Request.Create().WithPath("/oauth/token").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2TokenResponseJson(3600))); + } + + public void Dispose() => _server.Stop(); + + private CERTInextClient BuildClient() => new CERTInextClient(new CERTInextConfig + { + ApiUrl = _server.Urls[0], + AuthMode = "AccessKey", + ApiKey = "test-v1-key", + AccountNumber = "12345", + UseV2Api = true, + OAuthClientId = "my-v2-client", + OAuthClientSecret = "my-v2-secret", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + PageSize = 100, + GroupNumber = string.Empty + }); + + [Theory] + [InlineData(Constants.ApiV2.FamilySsl, Constants.ApiV2.SslCertificatesPath)] + [InlineData(Constants.ApiV2.FamilyPrivatePki, Constants.ApiV2.PrivatePkiCertificatesPath)] + [InlineData(Constants.ApiV2.FamilySignature, Constants.ApiV2.SignatureCertificatesPath)] + public async Task CancelOrderV2Async_204_PostsReasonToFamilyPath_ReturnsCancelled(string family, string familyPath) + { + string path = $"{familyPath}/{OrderId}/cancel"; + _server + .Given(Request.Create().WithPath(path).UsingPost()) + .RespondWith(Response.Create().WithStatusCode(204)); + + using var client = BuildClient(); + var outcome = await client.CancelOrderV2Async(family, OrderId, "Keyfactor test reason."); + + outcome.Should().Be(V2CancelOrderOutcome.Cancelled); + var entry = _server.LogEntries.Single(e => e.RequestMessage.Path == path); + entry.RequestMessage.Method.Should().Be("POST"); + using var body = JsonDocument.Parse(entry.RequestMessage.Body ?? "{}"); + body.RootElement.GetProperty("reason").GetString().Should().Be("Keyfactor test reason."); + entry.RequestMessage.Headers.Should().ContainKey("Idempotency-Key"); + } + + [Fact] + public async Task CancelOrderV2Async_422_ReturnsAlreadyTerminal_DoesNotThrow() + { + _server + .Given(Request.Create().WithPath($"{Constants.ApiV2.SslCertificatesPath}/{OrderId}/cancel").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(422) + .WithHeader("Content-Type", "application/problem+json") + .WithBody(MockCertificateData.V2ProblemDetailsJson( + 422, "Unprocessable Entity", "Order is already issued; use POST /{orderId}/revoke instead of /cancel."))); + + using var client = BuildClient(); + var outcome = await client.CancelOrderV2Async(Constants.ApiV2.FamilySsl, OrderId, "reason"); + + outcome.Should().Be(V2CancelOrderOutcome.AlreadyTerminal); + } + + [Fact] + public async Task CancelOrderV2Async_500_Throws() + { + _server + .Given(Request.Create().WithPath($"{Constants.ApiV2.SslCertificatesPath}/{OrderId}/cancel").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(500)); + + using var client = BuildClient(); + await Assert.ThrowsAsync( + () => client.CancelOrderV2Async(Constants.ApiV2.FamilySsl, OrderId, "reason")); + } + + [Theory] + [InlineData(null)] + [InlineData("")] + [InlineData(" ")] + public async Task CancelOrderV2Async_BlankReason_ThrowsBeforeAnyHttpCall(string reason) + { + using var client = BuildClient(); + await Assert.ThrowsAsync( + () => client.CancelOrderV2Async(Constants.ApiV2.FamilySsl, OrderId, reason)); + _server.LogEntries.Should().BeEmpty(); + } + } +} diff --git a/CERTInext.Tests/V2PrivatePkiEnrollmentTests.cs b/CERTInext.Tests/V2PrivatePkiEnrollmentTests.cs new file mode 100644 index 0000000..34bbf7b --- /dev/null +++ b/CERTInext.Tests/V2PrivatePkiEnrollmentTests.cs @@ -0,0 +1,631 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Generic; +using System.Linq; +using System.Text.Json; +using System.Text.Json.Serialization; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Moq; +using Org.BouncyCastle.Asn1.Pkcs; +using Org.BouncyCastle.Asn1.X509; +using Org.BouncyCastle.Crypto; +using Org.BouncyCastle.Crypto.Generators; +using Org.BouncyCastle.Pkcs; +using Org.BouncyCastle.Security; +using WireMock.RequestBuilders; +using WireMock.ResponseBuilders; +using WireMock.Server; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Tests that EnrollV2Async builds a family-specific create body rather than the + /// SSL/TLS one () for every product family. A + /// ProductFamily=private-pki template must place a + /// (spec: variant, hostname, + /// additionalHosts; no organization / certificate / agreement block) through the + /// Private PKI client overload, with IP SANs carried into additionalHosts; a + /// ProductFamily=signature template must fail fast with no CA call (open design + /// decision). Driven end-to-end through against a Strict + /// mock, plus WireMock-backed + /// coverage. + /// + public class V2PrivatePkiEnrollmentTests + { + private const string OrderId = "ord_pki_001"; + private const string Hostname = "intranet.acme.local"; + + // Spec "Private PKI Certificates" field table — every key the create body may carry. + private static readonly HashSet SpecPrivatePkiTopLevelKeys = new HashSet + { + "variant", "caProfileId", "masterProductId", "saveAsDraft", "requestId", "emailNotifications", + "groupNumber", "requestor", "hostname", "additionalHosts", "subscription", "csr", "remarks", + "tags", "customFields", "technicalPointOfContact" + }; + + private static Mock NewMock() => + new Mock(MockBehavior.Strict); + + private static CERTInextConfig BaseConfig() => new CERTInextConfig + { + UseV2Api = true, + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + RequestorName = "DevOps Team", + RequestorEmail = "devops@acme.com", + RequestorIsdCode = "1", + RequestorMobileNumber = "4155551234", + SignerIp = "1.2.3.4", + SignerPlace = "New York", + PickupRetries = 0 + }; + + private static CERTInextCAPlugin BuildV2Plugin(ICERTInextClient client, CERTInextConfig config = null) => + new CERTInextCAPlugin(client, config ?? BaseConfig()); + + private static EnrollmentProductInfo MakePrivatePkiProductInfo( + string variant = "intranet-ssl", string productCode = "149", string domainName = Hostname) + { + var parameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductFamily"] = "private-pki" + }; + if (variant != null) parameters["ProductVariant"] = variant; + if (productCode != null) parameters["ProductCode"] = productCode; + if (domainName != null) parameters["DomainName"] = domainName; + + // GetProductIds() only advertises SSL/TLS product names, so a real private-pki + // template is necessarily attached to one of them. + return new EnrollmentProductInfo { ProductID = Constants.Products.DvSsl, ProductParameters = parameters }; + } + + private static JsonSerializerOptions ClientEquivalentJsonOptions() => new JsonSerializerOptions + { + PropertyNameCaseInsensitive = true, + DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull + }; + + /// + /// Stubs the Private PKI placement + CSR submit + track (+ download when issued) and + /// returns an accessor for the captured create body. + /// + private static Func StubPrivatePkiOrder( + Mock mock, string trackStatus = "pending-approval") + { + V2CreatePrivatePkiOrderRequest captured = null; + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), It.IsAny())) + .Callback((_, req, __) => captured = req) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = OrderId, Status = "pending-csr" }); + + mock.Setup(c => c.SubmitCsrV2Async( + Constants.ApiV2.FamilyPrivatePki, OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + mock.Setup(c => c.TrackOrderV2Async(Constants.ApiV2.FamilyPrivatePki, OrderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = trackStatus }); + + if (trackStatus == "issued") + { + mock.Setup(c => c.DownloadCertificateV2Async(Constants.ApiV2.FamilyPrivatePki, OrderId, It.IsAny())) + .ReturnsAsync(new V2CertificateDownloadResponse + { + OrderId = OrderId, + SerialNumber = "0A1B2C", + CertificatePem = MockCertificateData.FakePemCertificate + }); + } + + return () => captured; + } + + private static Task EnrollAsync( + CERTInextCAPlugin plugin, + EnrollmentProductInfo productInfo, + Dictionary san, + string csr = null) => + plugin.Enroll( + csr: csr ?? MockCertificateData.FakeCsrPem, + subject: $"CN={Hostname}", + san: san, + productInfo: productInfo, + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + // BouncyCastle only (project crypto policy). DNS and IP SANs in the extensionRequest. + private static string GenerateCsrPem(string cn, string[] dnsSans, string[] ipSans) + { + var keyGen = new RsaKeyPairGenerator(); + keyGen.Init(new KeyGenerationParameters(new SecureRandom(), 2048)); + AsymmetricCipherKeyPair kp = keyGen.GenerateKeyPair(); + + var names = (dnsSans ?? Array.Empty()).Select(d => new GeneralName(GeneralName.DnsName, d)) + .Concat((ipSans ?? Array.Empty()).Select(ip => new GeneralName(GeneralName.IPAddress, ip))) + .ToArray(); + + Org.BouncyCastle.Asn1.Asn1Set attributes = null; + if (names.Length > 0) + { + var extGen = new X509ExtensionsGenerator(); + extGen.AddExtension(X509Extensions.SubjectAlternativeName, critical: false, + extValue: new GeneralNames(names)); + attributes = new Org.BouncyCastle.Asn1.DerSet(new AttributePkcs( + PkcsObjectIdentifiers.Pkcs9AtExtensionRequest, + new Org.BouncyCastle.Asn1.DerSet(extGen.Generate()))); + } + + var csr = new Pkcs10CertificationRequest( + "SHA256withRSA", new X509Name($"CN={cn}"), kp.Public, attributes, kp.Private); + + return "-----BEGIN CERTIFICATE REQUEST-----\n" + + Convert.ToBase64String(csr.GetEncoded(), Base64FormattingOptions.InsertLineBreaks) + + "\n-----END CERTIFICATE REQUEST-----"; + } + + // --------------------------------------------------------------------------- + // Body shape + routing + // --------------------------------------------------------------------------- + + [Fact] + public async Task Enroll_V2_PrivatePki_PlacesPrivatePkiBody_ThroughPrivatePkiOverload_NotTheSslBody() + { + var mock = NewMock(); + var captured = StubPrivatePkiOrder(mock, trackStatus: "issued"); + + var config = BaseConfig(); + config.GroupNumber = "GRP-9"; + config.EmailNotifications = "1"; + config.RequestorDesignation = "Platform Engineering"; + config.SubscriptionAutoRenew = "1"; + config.SubscriptionRenewCriteriaDays = "20"; + // OV/EV-only and agreement-only settings must have no effect on a Private PKI body. + config.OrganizationNumber = "ORG-001"; + config.AutoSecureWww = "1"; + + var result = await EnrollAsync(BuildV2Plugin(mock.Object, config), MakePrivatePkiProductInfo(), + new Dictionary { ["dnsname"] = new[] { Hostname, "portal.acme.local" } }); + + result.Status.Should().Be((int)EndEntityStatus.GENERATED); + result.CARequestID.Should().Be(OrderId); + + var req = captured(); + req.Should().NotBeNull("a private-pki enrollment must use the Private PKI PlaceOrderV2Async overload"); + req.Variant.Should().Be("intranet-ssl"); + req.Hostname.Should().Be(Hostname); + req.AdditionalHosts.Should().Equal("portal.acme.local"); + req.EmailNotifications.Should().Be("all"); + req.GroupNumber.Should().Be("GRP-9"); + req.Requestor.Name.Should().Be("DevOps Team"); + req.Requestor.Email.Should().Be("devops@acme.com"); + req.Requestor.Phone.Should().Be("+14155551234"); + req.Requestor.Designation.Should().Be("Platform Engineering"); + req.Subscription.ValidityYears.Should().Be(1); + req.Subscription.AutoRenew.Should().BeTrue(); + req.Subscription.RenewBeforeDays.Should().Be(20); + req.TechnicalPointOfContact.Name.Should().Be("DevOps Team", "blank TechnicalContact* falls back to Requestor*, same as SSL"); + req.TechnicalPointOfContact.Designation.Should().Be(Constants.ApiV2.DefaultTechnicalContactDesignation); + + // The SSL overload and the catalog lookup (SSL UCC detection only) are never touched. + mock.Verify(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny()), + Times.Never); + mock.Verify(c => c.GetProductDetailsV2Async(It.IsAny()), Times.Never); + mock.Verify(c => c.PlaceOrderV2Async("149", It.IsAny(), It.IsAny()), + Times.Once, "the explicit ProductCode is sent as X-Product-Code as-is"); + + // CSR submit / track / download all hit the private-pki family. + mock.Verify(c => c.SubmitCsrV2Async(Constants.ApiV2.FamilyPrivatePki, OrderId, It.IsAny(), It.IsAny()), Times.Once); + mock.Verify(c => c.DownloadCertificateV2Async(Constants.ApiV2.FamilyPrivatePki, OrderId, It.IsAny()), Times.Once); + } + + [Fact] + public async Task Enroll_V2_PrivatePki_SerializedBody_UsesOnlySpecFieldNames_AndNoSslBlocks() + { + var mock = NewMock(); + var captured = StubPrivatePkiOrder(mock); + var config = BaseConfig(); + config.GroupNumber = "GRP-9"; + config.EmailNotifications = "1"; + config.RequestorDesignation = "Platform Engineering"; + + await EnrollAsync(BuildV2Plugin(mock.Object, config), MakePrivatePkiProductInfo(), + new Dictionary + { + ["dnsname"] = new[] { Hostname, "portal.acme.local" }, + ["ipaddress"] = new[] { "10.0.0.50" } + }); + + string json = JsonSerializer.Serialize(captured(), ClientEquivalentJsonOptions()); + using var doc = JsonDocument.Parse(json); + var root = doc.RootElement; + var keys = root.EnumerateObject().Select(p => p.Name).ToList(); + + keys.Should().BeEquivalentTo(new[] + { + "variant", "emailNotifications", "groupNumber", "requestor", "hostname", "additionalHosts", + "subscription", "remarks", "technicalPointOfContact" + }); + keys.Should().OnlyContain(k => SpecPrivatePkiTopLevelKeys.Contains(k), + "every key must come from the spec's Private PKI field table"); + keys.Should().NotContain(new[] { "productVariant", "certificate", "organization", "agreement", "domain" }, + "Private PKI has no DCV, no organization block, and no Subscriber Agreement (spec)"); + + root.GetProperty("variant").GetString().Should().Be("intranet-ssl"); + root.GetProperty("hostname").GetString().Should().Be(Hostname); + root.GetProperty("additionalHosts").EnumerateArray().Select(e => e.GetString()) + .Should().Equal("portal.acme.local", "10.0.0.50"); + root.GetProperty("requestor").EnumerateObject().Select(p => p.Name) + .Should().BeEquivalentTo(new[] { "name", "email", "phone", "designation" }); + root.GetProperty("technicalPointOfContact").EnumerateObject().Select(p => p.Name) + .Should().BeEquivalentTo(new[] { "name", "email", "phone", "designation" }); + root.GetProperty("subscription").GetProperty("validityYears").GetInt32().Should().Be(1); + } + + [Fact] + public async Task Enroll_V2_PrivatePki_VariantMatchIsCaseInsensitive_AndSentInSpecCase() + { + var mock = NewMock(); + var captured = StubPrivatePkiOrder(mock); + + await EnrollAsync(BuildV2Plugin(mock.Object), MakePrivatePkiProductInfo(variant: " IGTF-Host "), + new Dictionary { ["dnsname"] = new[] { Hostname } }); + + captured().Variant.Should().Be(Constants.ApiV2.PrivatePkiVariantIgtfHost); + } + + [Fact] + public async Task Enroll_V2_PrivatePki_HostnameFallsBackToSubjectCn_WhenDomainNameUnset() + { + var mock = NewMock(); + var captured = StubPrivatePkiOrder(mock); + + await EnrollAsync(BuildV2Plugin(mock.Object), MakePrivatePkiProductInfo(domainName: null), + new Dictionary { ["dnsname"] = new[] { Hostname } }); + + captured().Hostname.Should().Be(Hostname, "spec: \"hostname - primary CN\""); + } + + [Fact] + public async Task Enroll_V2_PrivatePki_PendingApproval_ReturnsPendingWithOrderId() + { + var mock = NewMock(); + StubPrivatePkiOrder(mock, trackStatus: "pending-approval"); + + var result = await EnrollAsync(BuildV2Plugin(mock.Object), MakePrivatePkiProductInfo(), + new Dictionary { ["dnsname"] = new[] { Hostname } }); + + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + result.CARequestID.Should().Be(OrderId, "the order was placed; sync must be able to find it"); + } + + // --------------------------------------------------------------------------- + // SAN mapping -> additionalHosts + // --------------------------------------------------------------------------- + + [Fact] + public async Task Enroll_V2_PrivatePki_AdditionalHosts_CarriesDnsAndIpSans_ExcludesPrimaryDuplicatesAndNonHostTypes() + { + var mock = NewMock(); + var captured = StubPrivatePkiOrder(mock); + + await EnrollAsync(BuildV2Plugin(mock.Object), MakePrivatePkiProductInfo(), + new Dictionary + { + ["dnsname"] = new[] { Hostname, "portal.acme.local", "PORTAL.acme.local" }, + ["ipaddress"] = new[] { "10.0.0.50", "fd00::50" }, + ["rfc822name"] = new[] { "ops@acme.com" }, + ["uri"] = new[] { "https://intranet.acme.local/" } + }); + + captured().AdditionalHosts.Should().Equal( + new[] { "portal.acme.local", "10.0.0.50", "fd00::50" }, + "additionalHosts is a 'SAN list (DNS names or IPv4 / IPv6)' per the spec: IPs are kept, the " + + "primary hostname is not repeated, duplicates collapse, and email/URI SANs are excluded"); + } + + [Fact] + public async Task Enroll_V2_PrivatePki_CsrFallback_CarriesIpSansFromCsr_WhenGatewaySanDictionaryIsNull() + { + var mock = NewMock(); + var captured = StubPrivatePkiOrder(mock); + string csr = GenerateCsrPem(Hostname, + dnsSans: new[] { Hostname, "reports.acme.local" }, + ipSans: new[] { "10.0.0.60" }); + + await EnrollAsync(BuildV2Plugin(mock.Object), MakePrivatePkiProductInfo(), san: null, csr: csr); + + captured().AdditionalHosts.Should().Equal( + new[] { "reports.acme.local", "10.0.0.60" }, + "with no gateway SAN dictionary the CSR's SANs are used, IP SAN rendered as text"); + } + + [Fact] + public async Task Enroll_V2_PrivatePki_MultiSanCsr_IsNotRejectedBySslSingleDomainGuard() + { + // The same CSR on a non-UCC SSL product is rejected before any order is placed (multi-SAN + // guard). Private PKI's additionalHosts is multi-entry for every variant. + var mock = NewMock(); + var captured = StubPrivatePkiOrder(mock); + string csr = GenerateCsrPem(Hostname, + dnsSans: new[] { Hostname, "portal.acme.local", "reports.acme.local" }, + ipSans: null); + + var result = await EnrollAsync(BuildV2Plugin(mock.Object), MakePrivatePkiProductInfo(), + new Dictionary { ["dnsname"] = new[] { Hostname, "portal.acme.local", "reports.acme.local" } }, + csr); + + result.Status.Should().NotBe((int)EndEntityStatus.FAILED); + captured().AdditionalHosts.Should().Equal("portal.acme.local", "reports.acme.local"); + } + + [Fact] + public async Task Enroll_V2_PrivatePki_SubmitNonDnsSansFalse_StillSubmitsIpSans() + { + var mock = NewMock(); + var captured = StubPrivatePkiOrder(mock); + var config = BaseConfig(); + config.SubmitNonDnsSans = false; + + await EnrollAsync(BuildV2Plugin(mock.Object, config), MakePrivatePkiProductInfo(), + new Dictionary + { + ["dnsname"] = new[] { Hostname }, + ["ipaddress"] = new[] { "10.0.0.50" } + }); + + captured().AdditionalHosts.Should().Equal(new[] { "10.0.0.50" }, + "IP literals are native to additionalHosts, so the V1-era SubmitNonDnsSans switch is not consulted"); + } + + [Fact] + public async Task Enroll_V2_PrivatePki_NoAdditionalSans_OmitsAdditionalHostsFromWireBody() + { + var mock = NewMock(); + var captured = StubPrivatePkiOrder(mock); + + await EnrollAsync(BuildV2Plugin(mock.Object), MakePrivatePkiProductInfo(), + new Dictionary { ["dnsname"] = new[] { Hostname } }); + + captured().AdditionalHosts.Should().BeNull(); + JsonSerializer.Serialize(captured(), ClientEquivalentJsonOptions()) + .Should().NotContain("additionalHosts"); + } + + // --------------------------------------------------------------------------- + // Fail-fast validation (no CA call of any kind) + // --------------------------------------------------------------------------- + + [Theory] + [InlineData(null)] // not set -> SSL-only "dv" default + [InlineData("dv")] + [InlineData("ov")] + [InlineData("igtf-personal")] // appears only in the spec's create-*response* echo enum + public async Task Enroll_V2_PrivatePki_InvalidOrMissingVariant_FailsFastWithoutAnyCaCall(string variant) + { + var mock = NewMock(); + + var result = await EnrollAsync(BuildV2Plugin(mock.Object), MakePrivatePkiProductInfo(variant: variant), + new Dictionary { ["dnsname"] = new[] { Hostname } }); + + result.Status.Should().Be((int)EndEntityStatus.FAILED); + result.CARequestID.Should().BeEmpty(); + result.StatusMessage.Should().Contain("ProductVariant") + .And.Contain("intranet-ssl").And.Contain("igtf-host"); + mock.Invocations.Should().BeEmpty("validation must happen before any CA call"); + } + + [Fact] + public async Task Enroll_V2_PrivatePki_NoExplicitProductCode_PlacesOrderWithNoProductCode() + { + // X-Product-Code is the spec's optional override: CERTInext resolves the Private PKI + // product from `variant`. The SSL ProductTypeIdsV2 table must never supply a code for + // the Private PKI endpoint, and the catalog is not consulted. + var mock = NewMock(); + string capturedCode = "sentinel"; + StubPrivatePkiOrder(mock); + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), It.IsAny())) + .Callback((code, _, __) => capturedCode = code) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = OrderId, Status = "pending-csr" }); + + var result = await EnrollAsync(BuildV2Plugin(mock.Object), MakePrivatePkiProductInfo(productCode: null), + new Dictionary { ["dnsname"] = new[] { Hostname } }); + + result.CARequestID.Should().Be(OrderId); + capturedCode.Should().BeNull("no ProductCode was set on the template, so no X-Product-Code override is sent"); + mock.Verify(c => c.GetProductDetailsV2Async(It.IsAny()), Times.Never); + } + + [Fact] + public async Task Enroll_V2_PrivatePki_ExplicitProductCode_StillSentAsOverride() + { + var mock = NewMock(); + string capturedCode = null; + StubPrivatePkiOrder(mock); + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), It.IsAny())) + .Callback((code, _, __) => capturedCode = code) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = OrderId, Status = "pending-csr" }); + + await EnrollAsync(BuildV2Plugin(mock.Object), MakePrivatePkiProductInfo(productCode: "149"), + new Dictionary { ["dnsname"] = new[] { Hostname } }); + + capturedCode.Should().Be("149"); + } + + // --------------------------------------------------------------------------- + // signature (Document Signer): open design decision -> fail fast + // --------------------------------------------------------------------------- + + [Fact] + public async Task Enroll_V2_Signature_FailsFastWithoutAnyCaCall_InsteadOfSendingTheSslBody() + { + var mock = NewMock(); + var productInfo = new EnrollmentProductInfo + { + ProductID = Constants.Products.DvSsl, + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductFamily"] = "signature", + ["ProductCode"] = "819" + } + }; + + var result = await BuildV2Plugin(mock.Object).Enroll( + csr: MockCertificateData.FakeCsrPem, + subject: "CN=Sarah Johnson", + san: new Dictionary(), + productInfo: productInfo, + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.Status.Should().Be((int)EndEntityStatus.FAILED); + result.CARequestID.Should().BeEmpty(); + result.StatusMessage.Should().Contain("signature").And.Contain("not yet supported"); + mock.Invocations.Should().BeEmpty( + "nothing is sent to /signature-certificates (no SSL body is sent to the wrong family endpoint)"); + } + + // --------------------------------------------------------------------------- + // ValidateProductInfo (builds its own CERTInextClient -> WireMock) + // --------------------------------------------------------------------------- + + private static void StubToken(WireMockServer server) => + server.Given(Request.Create().WithPath("/oauth/token").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2TokenResponseJson())); + + private static void StubCatalog(WireMockServer server, string productCode, string productTypeId) => + server.Given(Request.Create().WithPath("/api/certinext/v2/catalog/products").UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody($"[{{\"productCode\":\"{productCode}\",\"productName\":\"Test Product\",\"productTypeID\":\"{productTypeId}\"}}]")); + + private static Dictionary V2ConnectionInfo(string apiUrl) => new Dictionary + { + ["UseV2Api"] = true, + ["ApiUrl"] = apiUrl, + ["OAuthClientId"] = "my-client", + ["OAuthClientSecret"] = "my-secret" + }; + + [Fact] + public async Task ValidateProductInfo_V2_PrivatePki_Succeeds_WhenExplicitCodeIsAPrivatePkiProduct() + { + // The SSL ProductId (DV SSL -> productTypeID 13) must not be cross-checked against a + // Private PKI code (productTypeID 39) — otherwise "does not correspond to the selected + // product" would be thrown and no private-pki template could ever be saved. + using var server = WireMockServer.Start(); + StubToken(server); + StubCatalog(server, "149", Constants.ApiV2.PrivatePkiProductTypeId); + + Func act = () => BuildV2Plugin(NewMock().Object) + .ValidateProductInfo(MakePrivatePkiProductInfo(), V2ConnectionInfo(server.Urls[0])); + + await act.Should().NotThrowAsync(); + } + + [Fact] + public async Task ValidateProductInfo_V2_PrivatePki_Throws_WhenExplicitCodeIsNotAPrivatePkiProduct() + { + using var server = WireMockServer.Start(); + StubToken(server); + StubCatalog(server, "842", "13"); // DV SSL + + Func act = () => BuildV2Plugin(NewMock().Object) + .ValidateProductInfo(MakePrivatePkiProductInfo(productCode: "842"), V2ConnectionInfo(server.Urls[0])); + + await act.Should().ThrowAsync().WithMessage("*not a Private PKI product*"); + } + + [Fact] + public async Task ValidateProductInfo_V2_PrivatePki_Throws_WhenCodeNotInCatalog() + { + using var server = WireMockServer.Start(); + StubToken(server); + StubCatalog(server, "100", Constants.ApiV2.PrivatePkiProductTypeId); + + Func act = () => BuildV2Plugin(NewMock().Object) + .ValidateProductInfo(MakePrivatePkiProductInfo(productCode: "149"), V2ConnectionInfo(server.Urls[0])); + + await act.Should().ThrowAsync().WithMessage("*not found*"); + } + + [Theory] + [InlineData(null, "149", "ProductVariant")] + [InlineData("dv", "149", "ProductVariant")] + public async Task ValidateProductInfo_V2_PrivatePki_RejectsBadTemplateParams_BeforeAnyCatalogCall( + string variant, string productCode, string expectedField) + { + using var server = WireMockServer.Start(); + StubToken(server); + StubCatalog(server, "149", Constants.ApiV2.PrivatePkiProductTypeId); + + Func act = () => BuildV2Plugin(NewMock().Object) + .ValidateProductInfo(MakePrivatePkiProductInfo(variant: variant, productCode: productCode), + V2ConnectionInfo(server.Urls[0])); + + await act.Should().ThrowAsync().WithMessage($"*{expectedField}*"); + server.LogEntries.Should().NotContain(e => e.RequestMessage.Path == "/api/certinext/v2/catalog/products"); + } + + [Fact] + public async Task ValidateProductInfo_V2_PrivatePki_NoProductCode_PassesWithoutCatalogCall() + { + using var server = WireMockServer.Start(); + StubToken(server); + StubCatalog(server, "149", Constants.ApiV2.PrivatePkiProductTypeId); + + Func act = () => BuildV2Plugin(NewMock().Object) + .ValidateProductInfo(MakePrivatePkiProductInfo(productCode: null), V2ConnectionInfo(server.Urls[0])); + + await act.Should().NotThrowAsync("ProductCode is an optional override; CERTInext resolves the product from the variant"); + server.LogEntries.Should().NotContain(e => e.RequestMessage.Path == "/api/certinext/v2/catalog/products"); + } + + // --------------------------------------------------------------------------- + // Shared validation helper + // --------------------------------------------------------------------------- + + [Theory] + [InlineData("intranet-ssl", "149", "intranet-ssl")] + [InlineData("IGTF-HOST", "149", "igtf-host")] + public void ValidatePrivatePkiEnrollmentParams_ValidParams_ReturnsNull_AndNormalizesVariant( + string variant, string productCode, string expectedVariant) + { + var ep = new Models.EnrollmentParams(MakePrivatePkiProductInfo(variant: variant, productCode: productCode)); + + CERTInextCAPlugin.ValidatePrivatePkiEnrollmentParams(ep, out string normalized).Should().BeNull(); + normalized.Should().Be(expectedVariant); + } + + [Fact] + public void ValidatePrivatePkiEnrollmentParams_UnsetVariant_SaysNotSetRatherThanEchoingTheSslDefault() + { + var ep = new Models.EnrollmentParams(MakePrivatePkiProductInfo(variant: null)); + + string error = CERTInextCAPlugin.ValidatePrivatePkiEnrollmentParams(ep, out string normalized); + + error.Should().Contain("not set"); + normalized.Should().BeNull(); + } + } +} diff --git a/CERTInext.Tests/V2ProductCodeResolutionTests.cs b/CERTInext.Tests/V2ProductCodeResolutionTests.cs new file mode 100644 index 0000000..888fd45 --- /dev/null +++ b/CERTInext.Tests/V2ProductCodeResolutionTests.cs @@ -0,0 +1,257 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Generic; +using System.Linq; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Microsoft.Extensions.Logging; +using Moq; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// X-Product-Code is the V2 spec's optional override: CERTInext's wrapper picks the catalog + /// product from the variant, whether certificate.domain starts with *., and + /// whether additionalDomains is non-empty. These tests pin that EnrollV2Async + /// sends a code only when the template sets one, never consults the catalog or the connector's + /// DefaultProductCode otherwise, decides wildcard/UCC from the request shape, and logs + /// the response's resolvedProductCode. Driven through + /// against a Strict mock (an unexpected catalog call fails the test). + /// + [Collection(LoggingStateCollection.Name)] + public class V2ProductCodeResolutionTests + { + private const string OrderId = "ord_pcr_001"; + + private static CERTInextConfig Config(string defaultProductCode = null, string organizationNumber = null) => + new CERTInextConfig + { + UseV2Api = true, + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + SignerPlace = "New York", + DefaultProductCode = defaultProductCode, + OrganizationNumber = organizationNumber, + PickupRetries = 0 + }; + + private sealed class Captured + { + public string ProductCode = "sentinel-not-called"; + public V2CreateSslOrderRequest Request; + public bool Placed; + } + + private static (Mock Mock, Captured Cap) NewSslMock(string resolvedProductCode = null) + { + var mock = new Mock(MockBehavior.Strict); + var cap = new Captured(); + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .Callback((_, code, req, __) => + { + cap.ProductCode = code; + cap.Request = req; + cap.Placed = true; + }) + .ReturnsAsync(new V2CreateOrderResponse + { + OrderId = OrderId, Status = "pending-dcv", ResolvedProductCode = resolvedProductCode + }); + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "pending-dcv" }); + return (mock, cap); + } + + private static EnrollmentProductInfo ProductInfo( + string productId, string domainName = "example.com", string productCode = null) + { + var p = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductFamily"] = "ssl", + ["DomainName"] = domainName + }; + if (productCode != null) p["ProductCode"] = productCode; + return new EnrollmentProductInfo { ProductID = productId, ProductParameters = p }; + } + + private static Task EnrollAsync( + CERTInextCAPlugin plugin, EnrollmentProductInfo info, params string[] dnsSans) => + plugin.Enroll(MockCertificateData.FakeCsrPem, $"CN={info.ProductParameters["DomainName"]}", + new Dictionary { ["dnsname"] = dnsSans }, info, + RequestFormat.PKCS10, EnrollmentType.New); + + [Fact] + public async Task NoExplicitProductCode_SendsNoCode_AndNeverReadsTheCatalog() + { + var (mock, cap) = NewSslMock(); + var plugin = new CERTInextCAPlugin(mock.Object, Config(organizationNumber: "ORG-1")); + + var result = await EnrollAsync(plugin, ProductInfo(Constants.Products.OvSsl), "example.com"); + + result.CARequestID.Should().Be(OrderId); + cap.Placed.Should().BeTrue(); + cap.ProductCode.Should().BeNull("an unset template ProductCode means no X-Product-Code override"); + cap.Request.ProductVariant.Should().Be("ov"); + mock.Verify(c => c.GetProductDetailsV2Async(It.IsAny()), Times.Never); + } + + [Theory] + [InlineData("842")] // names one of several matching catalog entries + [InlineData("999")] // not even in a catalog + public async Task NoExplicitProductCode_ConnectorDefaultProductCode_NoLongerPinsV2Orders(string defaultProductCode) + { + var (mock, cap) = NewSslMock(); + var plugin = new CERTInextCAPlugin(mock.Object, Config(defaultProductCode)); + + await EnrollAsync(plugin, ProductInfo(Constants.Products.DvSsl), "example.com"); + + cap.ProductCode.Should().BeNull(); + mock.Verify(c => c.GetProductDetailsV2Async(It.IsAny()), Times.Never); + } + + [Fact] + public async Task ExplicitProductCode_IsStillSent_AndCatalogStillDecidesUcc() + { + var (mock, cap) = NewSslMock(); + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = "844", ProductTypeId = "15", Active = true } // DV SSL UCC + }); + var plugin = new CERTInextCAPlugin(mock.Object, Config(defaultProductCode: "842")); + + // ProductId is a NON-UCC product; the explicit code's catalog entry is UCC, so the + // catalog (not the ProductId) decides and the extra SAN goes out as additionalDomains. + await EnrollAsync(plugin, ProductInfo(Constants.Products.DvSsl, productCode: "844"), + "example.com", "extra.example.com"); + + cap.ProductCode.Should().Be("844"); + cap.Request.Certificate.AdditionalDomains.Should().Equal("extra.example.com"); + mock.Verify(c => c.GetProductDetailsV2Async(It.IsAny()), Times.Once); + } + + [Fact] + public async Task ExplicitProductCode_NonUccCatalogEntry_StillRejectsExtraSans() + { + var (mock, cap) = NewSslMock(); + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = "842", ProductTypeId = "13", Active = true } + }); + var plugin = new CERTInextCAPlugin(mock.Object, Config()); + + var result = await EnrollAsync(plugin, ProductInfo(Constants.Products.DvSsl, productCode: "842"), + "example.com", "extra.example.com"); + + result.Status.Should().Be((int)EndEntityStatus.FAILED); + cap.Placed.Should().BeFalse(); + } + + [Fact] + public async Task NoExplicitProductCode_WildcardDomain_IsDetectedFromTheDomain_ApexIsNotAnExtraSan() + { + var (mock, cap) = NewSslMock(); + var plugin = new CERTInextCAPlugin(mock.Object, Config()); + + // The template product is the plain DV SSL, but the domain is a wildcard: the wrapper + // keys on the "*." shape. The bare apex alongside it is not an extra SAN. + await EnrollAsync(plugin, ProductInfo(Constants.Products.DvSsl, domainName: "*.example.com"), + "*.example.com", "example.com"); + + cap.ProductCode.Should().BeNull(); + cap.Request.Certificate.Domain.Should().Be("*.example.com"); + cap.Request.Certificate.AdditionalDomains.Should().BeNull( + "a wildcard plus its apex is not multi-domain, so the wrapper must resolve a wildcard, not a UCC, product"); + } + + [Fact] + public async Task NoExplicitProductCode_UccTemplateProduct_SendsAdditionalDomains() + { + var (mock, cap) = NewSslMock(); + var plugin = new CERTInextCAPlugin(mock.Object, Config()); + + await EnrollAsync(plugin, ProductInfo(Constants.Products.DvSslUcc), "example.com", "a.example.com", "b.example.com"); + + cap.ProductCode.Should().BeNull(); + cap.Request.Certificate.AdditionalDomains.Should().BeEquivalentTo("a.example.com", "b.example.com"); + } + + [Fact] + public async Task NoExplicitProductCode_ExtraDnsSansOnANonUccTemplate_BecomeAdditionalDomains_InsteadOfFailing() + { + var (mock, cap) = NewSslMock(); + var plugin = new CERTInextCAPlugin(mock.Object, Config()); + + // With no explicit code the wrapper chooses a UCC product whenever additionalDomains is + // non-empty, so the request shape decides; the single-domain guard (explicit non-UCC + // code only) must not reject it. + var result = await EnrollAsync(plugin, ProductInfo(Constants.Products.DvSsl), "example.com", "extra.example.com"); + + result.CARequestID.Should().Be(OrderId); + cap.Request.Certificate.AdditionalDomains.Should().Equal("extra.example.com"); + } + + [Fact] + public async Task NoExplicitProductCode_PrimaryDomainAndWwwVariantOnly_IsNotUcc() + { + var (mock, cap) = NewSslMock(); + var plugin = new CERTInextCAPlugin(mock.Object, Config()); + + await EnrollAsync(plugin, ProductInfo(Constants.Products.DvSsl), "example.com", "www.example.com"); + + cap.Request.Certificate.AdditionalDomains.Should().BeNull(); + } + + [Fact] + public async Task OrderCreated_LogsResolvedProductCodeFromTheResponse() + { + using var capture = new PluginLogCapture(); + var (mock, _) = NewSslMock(resolvedProductCode: "842"); + var plugin = new CERTInextCAPlugin(mock.Object, Config()); + + await EnrollAsync(plugin, ProductInfo(Constants.Products.DvSsl), "example.com"); + + var lines = capture.Lines(LogLevel.Information, "V2 order placed"); + lines.Should().ContainSingle(); + lines[0].Should().Contain("ResolvedProductCode=842").And.Contain("XProductCodeSent=(none)"); + } + + [Fact] + public async Task OrderCreated_WithoutResolvedProductCodeInResponse_LogsNotReported() + { + using var capture = new PluginLogCapture(); + var (mock, _) = NewSslMock(resolvedProductCode: null); + var plugin = new CERTInextCAPlugin(mock.Object, Config()); + + await EnrollAsync(plugin, ProductInfo(Constants.Products.DvSsl, productCode: "842"), "example.com"); + + // (the explicit code path reads the catalog; it is not stubbed here, so the plugin logs a + // warning and treats the order as single-domain) + var lines = capture.Lines(LogLevel.Information, "V2 order placed"); + lines.Should().ContainSingle(); + lines[0].Should().Contain("ResolvedProductCode=(not reported)").And.Contain("XProductCodeSent=842"); + } + } +} diff --git a/CERTInext.Tests/V2ProductVariantDerivationTests.cs b/CERTInext.Tests/V2ProductVariantDerivationTests.cs new file mode 100644 index 0000000..70dc337 --- /dev/null +++ b/CERTInext.Tests/V2ProductVariantDerivationTests.cs @@ -0,0 +1,451 @@ +// Copyright 2026 Keyfactor +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; +using System.Collections.Generic; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Moq; +using WireMock.RequestBuilders; +using WireMock.ResponseBuilders; +using WireMock.Server; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Tests guarding against the V2 + /// SSL create body's productVariant defaulting to "dv" regardless of the selected + /// product: an OV/EV template with no explicit ProductVariant enrollment parameter + /// must not send a DV-shaped body — skipping the mandatory OV/EV organization block + /// — nor should an explicit-but-contradictory override (e.g. "dv" configured for "OV SSL") pass + /// through unchecked. Covers directly, + /// end-to-end through , and through + /// (template-save-time rejection). + /// + public class V2ProductVariantDerivationTests + { + // --------------------------------------------------------------------------- + // ResolveSslProductVariant — pure unit tests, no CA calls + // --------------------------------------------------------------------------- + + [Theory] + [InlineData(Constants.Products.DvSsl, "dv")] + [InlineData(Constants.Products.DvSslWildcard, "dv")] + [InlineData(Constants.Products.OvSsl, "ov")] + [InlineData(Constants.Products.OvSslWildcard, "ov")] + [InlineData(Constants.Products.EvSsl, "ev")] + [InlineData(Constants.Products.EvSslUcc, "ev")] + public void ResolveSslProductVariant_NoExplicitVariant_DerivesFromProduct(string productId, string expectedVariant) + { + var ep = new Models.EnrollmentParams(new EnrollmentProductInfo + { + ProductID = productId, + ProductParameters = new Dictionary() + }); + + string error = CERTInextCAPlugin.ResolveSslProductVariant(ep, out string resolved); + + error.Should().BeNull(); + resolved.Should().Be(expectedVariant); + } + + [Theory] + [InlineData(Constants.Products.OvSsl, "OV", "ov")] + [InlineData(Constants.Products.EvSsl, "Ev", "ev")] + [InlineData(Constants.Products.DvSsl, "DV", "dv")] + public void ResolveSslProductVariant_ExplicitVariant_AgreesWithProduct_ReturnsItLowercased( + string productId, string explicitVariant, string expectedResolved) + { + var ep = new Models.EnrollmentParams(new EnrollmentProductInfo + { + ProductID = productId, + ProductParameters = new Dictionary { ["ProductVariant"] = explicitVariant } + }); + + string error = CERTInextCAPlugin.ResolveSslProductVariant(ep, out string resolved); + + error.Should().BeNull(); + resolved.Should().Be(expectedResolved); + } + + [Fact] + public void ResolveSslProductVariant_ExplicitVariant_ContradictsProduct_ReturnsActionableError() + { + // An OV product with the SSL-only "dv" + // default explicitly configured. + var ep = new Models.EnrollmentParams(new EnrollmentProductInfo + { + ProductID = Constants.Products.OvSsl, + ProductParameters = new Dictionary { ["ProductVariant"] = "dv" } + }); + + string error = CERTInextCAPlugin.ResolveSslProductVariant(ep, out string resolved); + + resolved.Should().BeNull(); + error.Should().NotBeNull(); + error.Should().Contain(Constants.EnrollmentParam.ProductVariant) + .And.Contain("'dv'") + .And.Contain(Constants.Products.OvSsl) + .And.Contain("'ov'"); + } + + [Fact] + public void ResolveSslProductVariant_ExplicitVariant_ContradictsProduct_EvVsDv() + { + var ep = new Models.EnrollmentParams(new EnrollmentProductInfo + { + ProductID = Constants.Products.DvSsl, + ProductParameters = new Dictionary { ["ProductVariant"] = "ev" } + }); + + string error = CERTInextCAPlugin.ResolveSslProductVariant(ep, out string resolved); + + resolved.Should().BeNull(); + error.Should().Contain("'ev'").And.Contain(Constants.Products.DvSsl).And.Contain("'dv'"); + } + + [Fact] + public void ResolveSslProductVariant_UnmappedProductId_NoExplicitVariant_KeepsCurrentSslDefault() + { + // No entry in Constants.Products.ProductVariantsV2 for this ProductId (none of the 10 + // real SSL products are named this) — don't invent a mapping, keep + // the SSL-only "dv" default rather than guessing. + var ep = new Models.EnrollmentParams(new EnrollmentProductInfo + { + ProductID = "Some Unmapped Product", + ProductParameters = new Dictionary() + }); + + string error = CERTInextCAPlugin.ResolveSslProductVariant(ep, out string resolved); + + error.Should().BeNull(); + resolved.Should().Be("dv"); + } + + [Fact] + public void ResolveSslProductVariant_UnmappedProductId_ExplicitVariant_NotCrossChecked() + { + // Same "don't invent a mapping" rule applied to the explicit-override path: with no + // authoritative product->variant mapping, an explicit override is passed through + // rather than rejected against a guess. + var ep = new Models.EnrollmentParams(new EnrollmentProductInfo + { + ProductID = "Some Unmapped Product", + ProductParameters = new Dictionary { ["ProductVariant"] = "ev" } + }); + + string error = CERTInextCAPlugin.ResolveSslProductVariant(ep, out string resolved); + + error.Should().BeNull(); + resolved.Should().Be("ev"); + } + + // --------------------------------------------------------------------------- + // Enroll_V2 — end-to-end through CERTInextCAPlugin.Enroll + // --------------------------------------------------------------------------- + + private static Mock NewMock() => + new Mock(MockBehavior.Strict); + + private static CERTInextCAPlugin BuildV2Plugin(ICERTInextClient client, string organizationNumber = null) => + new CERTInextCAPlugin(client, new CERTInextConfig + { + UseV2Api = true, + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + SignerIp = "1.2.3.4", + SignerPlace = "New York", + OrganizationNumber = organizationNumber, + PickupRetries = 0 + }); + + private static EnrollmentProductInfo MakeProductInfo(string productId, string productVariant = null) => + new EnrollmentProductInfo + { + ProductID = productId, + ProductParameters = productVariant == null + ? new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductFamily"] = "ssl", + ["DomainName"] = "example.com" + } + : new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductFamily"] = "ssl", + ["ProductVariant"] = productVariant, + ["DomainName"] = "example.com" + } + }; + + private static void StubCatalog(Mock mock, string productCode, string productTypeId) => + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = productCode, ProductTypeId = productTypeId, Active = true } + }); + + private static void StubHappyOrderPlacement(Mock mock, string orderId, string status = "pending-dcv") + { + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), orderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), orderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = orderId, Status = status }); + } + + [Fact] + public async Task Enroll_V2_OvProduct_NoExplicitProductVariant_SendsOvAndOrganizationBlock() + { + var mock = NewMock(); + StubCatalog(mock, "846", "16"); // OV SSL, non-UCC + StubHappyOrderPlacement(mock, "ord_variant_ov", "pending-organization-verification"); + + V2CreateSslOrderRequest captured = null; + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .Callback((_, __, req, ___) => captured = req) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = "ord_variant_ov", Status = "pending-organization-verification" }); + + var plugin = BuildV2Plugin(mock.Object, organizationNumber: "ORG-TEST"); + + var result = await plugin.Enroll( + csr: MockCertificateData.FakeCsrPem, + subject: "CN=example.com", + san: new Dictionary(), + productInfo: MakeProductInfo(Constants.Products.OvSsl), // no ProductVariant set + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.CARequestID.Should().Be("ord_variant_ov"); + captured.Should().NotBeNull(); + captured!.ProductVariant.Should().Be("ov", + "with no explicit ProductVariant, the wire value must be derived from ProductID 'OV SSL'"); + captured.Organization.Should().NotBeNull( + "deriving 'ov' must engage the same OV/EV organization-block requirement as an explicit 'ov'"); + captured.Organization.OrganizationNumber.Should().Be("ORG-TEST"); + } + + [Fact] + public async Task Enroll_V2_EvProduct_NoExplicitProductVariant_SendsEvAndOrganizationBlock() + { + var mock = NewMock(); + StubCatalog(mock, "847", "19"); // EV SSL, non-UCC + StubHappyOrderPlacement(mock, "ord_variant_ev", "pending-organization-verification"); + + V2CreateSslOrderRequest captured = null; + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .Callback((_, __, req, ___) => captured = req) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = "ord_variant_ev", Status = "pending-organization-verification" }); + + var plugin = BuildV2Plugin(mock.Object, organizationNumber: "ORG-TEST"); + + var result = await plugin.Enroll( + csr: MockCertificateData.FakeCsrPem, + subject: "CN=example.com", + san: new Dictionary(), + productInfo: MakeProductInfo(Constants.Products.EvSsl), // no ProductVariant set + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.CARequestID.Should().Be("ord_variant_ev"); + captured!.ProductVariant.Should().Be("ev"); + captured.Organization.Should().NotBeNull(); + } + + [Fact] + public async Task Enroll_V2_DvProduct_NoExplicitProductVariant_StaysDv_NoOrganizationBlock() + { + // Guard: the DV default path (the overwhelming majority of existing + // templates) must be completely unaffected by variant derivation. + var mock = NewMock(); + StubCatalog(mock, "842", "13"); // DV SSL, non-UCC + StubHappyOrderPlacement(mock, "ord_variant_dv"); + + V2CreateSslOrderRequest captured = null; + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .Callback((_, __, req, ___) => captured = req) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = "ord_variant_dv", Status = "pending-dcv" }); + + // Deliberately no OrganizationNumber configured — a DV order must not need it. + var plugin = BuildV2Plugin(mock.Object, organizationNumber: null); + + var result = await plugin.Enroll( + csr: MockCertificateData.FakeCsrPem, + subject: "CN=example.com", + san: new Dictionary(), + productInfo: MakeProductInfo(Constants.Products.DvSsl), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.CARequestID.Should().Be("ord_variant_dv"); + captured!.ProductVariant.Should().Be("dv"); + captured.Organization.Should().BeNull(); + } + + [Theory] + [InlineData(Constants.Products.OvSsl, "dv")] + [InlineData(Constants.Products.DvSsl, "ov")] + [InlineData(Constants.Products.EvSsl, "dv")] + public async Task Enroll_V2_ExplicitProductVariantContradictsProduct_FailsFastWithoutAnyCaCall( + string productId, string contradictingVariant) + { + // Strict mock with NOTHING stubbed: the mismatch must be rejected before any CA call + // at all (no catalog lookup, no order placement) — mirrors the private-pki variant + // guard's own Strict-mock test. + var mock = NewMock(); + var plugin = BuildV2Plugin(mock.Object, organizationNumber: "ORG-TEST"); + + var result = await plugin.Enroll( + csr: MockCertificateData.FakeCsrPem, + subject: "CN=example.com", + san: new Dictionary(), + productInfo: MakeProductInfo(productId, contradictingVariant), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.Status.Should().Be((int)EndEntityStatus.FAILED); + result.CARequestID.Should().BeEmpty(); + result.StatusMessage.Should().Contain(Constants.EnrollmentParam.ProductVariant); + mock.Invocations.Should().BeEmpty("the mismatch must be rejected before any CA call"); + } + + // --------------------------------------------------------------------------- + // ValidateProductInfo — rejected at template save, before any catalog call + // --------------------------------------------------------------------------- + + private static void StubToken(WireMockServer server) => + server.Given(Request.Create().WithPath("/oauth/token").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2TokenResponseJson())); + + private static void StubCatalogServer(WireMockServer server, string productCode, string productTypeId) => + server.Given(Request.Create().WithPath("/api/certinext/v2/catalog/products").UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody($"[{{\"productCode\":\"{productCode}\",\"productName\":\"Test Product\",\"productTypeID\":\"{productTypeId}\"}}]")); + + private static Dictionary V2ConnectionInfo(string apiUrl) => new Dictionary + { + ["UseV2Api"] = true, + ["ApiUrl"] = apiUrl, + ["OAuthClientId"] = "my-client", + ["OAuthClientSecret"] = "my-secret" + }; + + [Fact] + public async Task ValidateProductInfo_V2_Ssl_NoExplicitProductVariant_Succeeds() + { + using var server = WireMockServer.Start(); + StubToken(server); + StubCatalogServer(server, "846", "16"); // OV SSL + + var productInfo = new EnrollmentProductInfo + { + ProductID = Constants.Products.OvSsl, + ProductParameters = new Dictionary() + }; + + Func act = () => BuildV2Plugin(NewMock().Object) + .ValidateProductInfo(productInfo, V2ConnectionInfo(server.Urls[0])); + + await act.Should().NotThrowAsync(); + } + + [Fact] + public async Task ValidateProductInfo_V2_Ssl_ExplicitProductVariantMatchesProduct_Succeeds() + { + using var server = WireMockServer.Start(); + StubToken(server); + StubCatalogServer(server, "846", "16"); // OV SSL + + var productInfo = new EnrollmentProductInfo + { + ProductID = Constants.Products.OvSsl, + ProductParameters = new Dictionary { ["ProductVariant"] = "ov" } + }; + + Func act = () => BuildV2Plugin(NewMock().Object) + .ValidateProductInfo(productInfo, V2ConnectionInfo(server.Urls[0])); + + await act.Should().NotThrowAsync(); + } + + [Fact] + public async Task ValidateProductInfo_V2_Ssl_ExplicitProductVariantContradictsProduct_ThrowsBeforeAnyCatalogCall() + { + using var server = WireMockServer.Start(); + StubToken(server); + StubCatalogServer(server, "846", "16"); // OV SSL — never reached + + var productInfo = new EnrollmentProductInfo + { + ProductID = Constants.Products.OvSsl, + ProductParameters = new Dictionary { ["ProductVariant"] = "dv" } + }; + + Func act = () => BuildV2Plugin(NewMock().Object) + .ValidateProductInfo(productInfo, V2ConnectionInfo(server.Urls[0])); + + await act.Should().ThrowAsync() + .WithMessage($"*{Constants.EnrollmentParam.ProductVariant}*"); + server.LogEntries.Should().NotContain(e => e.RequestMessage.Path == "/api/certinext/v2/catalog/products", + "the ProductVariant/ProductId mismatch must be rejected before any catalog call"); + } + + [Fact] + public async Task ValidateProductInfo_V2_PrivatePki_NotAffectedByThisSslCheck() + { + // Sanity: a private-pki template's own ProductVariant (intranet-ssl/igtf-host) must + // never be run through the SSL cross-check this issue adds — it's checked by + // ValidatePrivatePkiEnrollmentParams instead, unaffected here. + using var server = WireMockServer.Start(); + StubToken(server); + StubCatalogServer(server, "149", Constants.ApiV2.PrivatePkiProductTypeId); + + var productInfo = new EnrollmentProductInfo + { + ProductID = Constants.Products.DvSsl, + ProductParameters = new Dictionary + { + ["ProductFamily"] = "private-pki", + ["ProductVariant"] = "intranet-ssl", + ["ProductCode"] = "149" + } + }; + + Func act = () => BuildV2Plugin(NewMock().Object) + .ValidateProductInfo(productInfo, V2ConnectionInfo(server.Urls[0])); + + await act.Should().NotThrowAsync(); + } + } +} diff --git a/CERTInext.Tests/V2SignerPlaceRequiredTests.cs b/CERTInext.Tests/V2SignerPlaceRequiredTests.cs new file mode 100644 index 0000000..a54bca0 --- /dev/null +++ b/CERTInext.Tests/V2SignerPlaceRequiredTests.cs @@ -0,0 +1,272 @@ +// Copyright 2026 Keyfactor +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; +using System.Collections.Generic; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Moq; +using WireMock.RequestBuilders; +using WireMock.ResponseBuilders; +using WireMock.Server; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Tests for signerPlace: the V2 spec marks SSL create + /// agreement.signerPlace "Conditional - required if `agreement` sent", and the plugin + /// always sends agreement on V2 SSL orders, so a blank signerPlace must not be dropped. + /// V2 connectors require SignerPlace in + /// (before any network call), and EnrollV2Async fails fast for an SSL order whose + /// resolved signer place is blank. V1 and V2 Private PKI (no agreement) are unaffected. + /// + public class V2SignerPlaceRequiredTests + { + private static Mock NewMock() => + new Mock(MockBehavior.Strict); + + private static Dictionary V2ConnectionInfo(string apiUrl, object signerPlace) + { + var info = new Dictionary + { + ["UseV2Api"] = true, + ["ApiUrl"] = apiUrl, + ["OAuthClientId"] = "my-client", + ["OAuthClientSecret"] = "my-secret" + }; + if (signerPlace != null) info["SignerPlace"] = signerPlace; + return info; + } + + private static CERTInextConfig V2Config(string signerPlace) => new CERTInextConfig + { + UseV2Api = true, + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + SignerIp = "1.2.3.4", + SignerPlace = signerPlace, + PickupRetries = 0 + }; + + private static EnrollmentProductInfo SslProductInfo(string templateSignerPlace = null) + { + var parameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = "842", + ["ProductFamily"] = "ssl", + ["ProductVariant"] = "dv", + ["DomainName"] = "example.com" + }; + if (templateSignerPlace != null) parameters["SignerPlace"] = templateSignerPlace; + return new EnrollmentProductInfo { ProductID = Constants.Products.DvSsl, ProductParameters = parameters }; + } + + // --------------------------------------------------------------------------- + // ValidateCAConnectionInfo + // --------------------------------------------------------------------------- + + [Theory] + [InlineData(null)] // key absent + [InlineData("")] + [InlineData(" ")] + public async Task ValidateCAConnectionInfo_V2_BlankSignerPlace_RejectedWithoutAnyHttpCall(string signerPlace) + { + // ApiUrl points at a live WireMock server with no stubs: if validation reached the + // connectivity test, the server would record the token request. + using var server = WireMockServer.Start(); + var plugin = new CERTInextCAPlugin(NewMock().Object, V2Config("New York")); + + Func act = () => plugin.ValidateCAConnectionInfo(V2ConnectionInfo(server.Urls[0], signerPlace)); + + var ex = await act.Should().ThrowAsync(); + ex.Which.Message.Should().Contain("'SignerPlace' is required when UseV2Api is true") + .And.Contain("Subscriber Agreement"); + server.LogEntries.Should().BeEmpty("the SignerPlace check must run before any network call"); + } + + [Fact] + public async Task ValidateCAConnectionInfo_V2_SignerPlaceSet_Passes() + { + using var server = WireMockServer.Start(); + server + .Given(Request.Create().WithPath("/oauth/token").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2TokenResponseJson())); + server + .Given(Request.Create().WithPath("/api/certinext/v2/auth/me").UsingGet()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2AuthMeJson())); + + var plugin = new CERTInextCAPlugin(NewMock().Object, V2Config("New York")); + + Func act = () => plugin.ValidateCAConnectionInfo(V2ConnectionInfo(server.Urls[0], "San Francisco, CA")); + + await act.Should().NotThrowAsync(); + } + + [Fact] + public async Task ValidateCAConnectionInfo_V1_BlankSignerPlace_NotReportedAsError() + { + // V1 config that fails for an unrelated reason (no AccountNumber) with SignerPlace + // blank: the aggregated error list must not name SignerPlace — V1 is unchanged. + var plugin = new CERTInextCAPlugin(NewMock().Object, V2Config("New York")); + var info = new Dictionary + { + ["ApiUrl"] = "https://v1.certinext.io/emSignHub-API/", + ["UseV2Api"] = false, + ["SignerPlace"] = "" + }; + + Func act = () => plugin.ValidateCAConnectionInfo(info); + + var ex = await act.Should().ThrowAsync(); + ex.Which.Message.Should().Contain("AccountNumber").And.NotContain("SignerPlace"); + } + + [Fact] + public async Task ValidateCAConnectionInfo_V1_BlankSignerPlace_Passes() + { + using var server = WireMockServer.Start(); + server + .Given(Request.Create().WithPath("/ValidateCredentials").UsingPost()) + .RespondWith(Response.Create() + .WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody("{\"meta\":{\"status\":\"1\"}}")); + + var plugin = new CERTInextCAPlugin(NewMock().Object, V2Config("New York")); + var info = new Dictionary + { + ["ApiUrl"] = server.Urls[0] + "/", + ["UseV2Api"] = false, + ["AccountNumber"] = "12345", + ["AuthMode"] = "AccessKey", + ["ApiKey"] = "v1-key", + ["SignerPlace"] = "" + }; + + Func act = () => plugin.ValidateCAConnectionInfo(info); + + await act.Should().NotThrowAsync("V1 does not require SignerPlace"); + } + + // --------------------------------------------------------------------------- + // EnrollV2Async defence in depth + // --------------------------------------------------------------------------- + + [Theory] + [InlineData("")] + [InlineData(" ")] + public async Task Enroll_V2Ssl_BlankResolvedSignerPlace_FailsFastWithNoCaCall(string connectorSignerPlace) + { + // Strict mock with no setups: any client call (catalog, PlaceOrder, ...) throws. + var mock = NewMock(); + var plugin = new CERTInextCAPlugin(mock.Object, V2Config(connectorSignerPlace)); + + var result = await plugin.Enroll( + MockCertificateData.FakeCsrPem, "CN=example.com", new Dictionary(), + SslProductInfo(), RequestFormat.PKCS10, EnrollmentType.New); + + result.Status.Should().Be((int)EndEntityStatus.FAILED); + result.CARequestID.Should().BeEmpty(); + result.StatusMessage.Should().Contain("requires a signer place") + .And.Contain("No order was placed"); + mock.Verify(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny()), + Times.Never); + mock.VerifyNoOtherCalls(); + } + + [Fact] + public async Task Enroll_V2Ssl_TemplateSignerPlaceOverridesBlankConnector_SendsTemplateValue() + { + var mock = NewMock(); + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = "842", ProductTypeId = "13", Active = true } + }); + V2CreateSslOrderRequest captured = null; + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .Callback((_, __, req, ___) => captured = req) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = "ord_sp_001", Status = "pending-csr" }); + mock.Setup(c => c.SubmitCsrV2Async(It.IsAny(), "ord_sp_001", It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), "ord_sp_001", It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = "ord_sp_001", Status = "pending-approval" }); + + var plugin = new CERTInextCAPlugin(mock.Object, V2Config("")); + + var result = await plugin.Enroll( + MockCertificateData.FakeCsrPem, "CN=example.com", new Dictionary(), + SslProductInfo(templateSignerPlace: "Austin, TX"), RequestFormat.PKCS10, EnrollmentType.New); + + result.Status.Should().NotBe((int)EndEntityStatus.FAILED); + captured.Should().NotBeNull(); + captured!.Agreement.SignerPlace.Should().Be("Austin, TX"); + } + + [Fact] + public async Task Enroll_V2PrivatePki_BlankSignerPlace_StillPlacesOrder() + { + // Private PKI has no Subscriber Agreement, so a blank SignerPlace must not block it. + var mock = NewMock(); + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = "ord_pki_sp", Status = "pending-csr" }); + mock.Setup(c => c.SubmitCsrV2Async( + Constants.ApiV2.FamilyPrivatePki, "ord_pki_sp", It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.TrackOrderV2Async(Constants.ApiV2.FamilyPrivatePki, "ord_pki_sp", It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = "ord_pki_sp", Status = "pending-approval" }); + + var plugin = new CERTInextCAPlugin(mock.Object, V2Config("")); + var productInfo = new EnrollmentProductInfo + { + ProductID = Constants.Products.DvSsl, + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductFamily"] = "private-pki", + ["ProductVariant"] = "intranet-ssl", + ["ProductCode"] = "149", + ["DomainName"] = "intranet.acme.local" + } + }; + + var result = await plugin.Enroll( + MockCertificateData.FakeCsrPem, "CN=intranet.acme.local", new Dictionary(), + productInfo, RequestFormat.PKCS10, EnrollmentType.New); + + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + result.CARequestID.Should().Be("ord_pki_sp"); + mock.Verify(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), It.IsAny()), Times.Once); + } + } +} diff --git a/CERTInext.Tests/V2SingleCallCreateTests.cs b/CERTInext.Tests/V2SingleCallCreateTests.cs new file mode 100644 index 0000000..771cd68 --- /dev/null +++ b/CERTInext.Tests/V2SingleCallCreateTests.cs @@ -0,0 +1,493 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Generic; +using System.Linq; +using System.Text.Json; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using WireMock.RequestBuilders; +using WireMock.ResponseBuilders; +using WireMock.Server; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// End-to-end (real against WireMock) guards for the V2 + /// single-call enrollment: the CSR goes inline on POST /{family}, the product is pinned + /// with X-Product-Code, and SSL/TLS never sends PUT .../csr when V2InlineCsr=true + /// (Private PKI ignores the flag and keeps create + Submit CSR; the default is the two-call flow). + /// + public class V2SingleCallCreateTests : IDisposable + { + private const string OrderId = "ord_single_001"; + private const string SslPath = "/api/certinext/v2/ssl-certificates"; + private const string PkiPath = "/api/certinext/v2/private-pki-certificates"; + + private readonly WireMockServer _server = WireMockServer.Start(); + + public void Dispose() => _server.Stop(); + + private CERTInextConfig Config() => new CERTInextConfig + { + ApiUrl = _server.Urls[0], + UseV2Api = true, + OAuthClientId = "my-v2-client", + OAuthClientSecret = "my-v2-secret", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + SignerIp = "1.2.3.4", + SignerPlace = "New York", + PickupRetries = 0, + // Every test in this class exercises the opt-in single-call flow unless it says otherwise. + V2InlineCsr = true + }; + + private CERTInextCAPlugin BuildPlugin(CERTInextConfig config = null) + { + config ??= Config(); + return new CERTInextCAPlugin(new CERTInextClient(config), config); + } + + private void StubToken() => + _server.Given(Request.Create().WithPath("/oauth/token").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2TokenResponseJson())); + + private void StubCatalog() => + _server.Given(Request.Create().WithPath("/api/certinext/v2/catalog/products").UsingGet()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody("[{\"productCode\":\"842\",\"productTypeID\":\"13\",\"productName\":\"DV SSL\",\"active\":true}]")); + + private void StubCreate(string path, int status, string body) => + _server.Given(Request.Create().WithPath(path).UsingPost()) + .RespondWith(Response.Create().WithStatusCode(status) + .WithHeader("Content-Type", "application/json").WithBody(body)); + + private void StubTrack(string path, string json) => + _server.Given(Request.Create().WithPath($"{path}/{OrderId}").UsingGet()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json").WithBody(json)); + + private static EnrollmentProductInfo SslProductInfo(string productCode = "842") => new EnrollmentProductInfo + { + ProductID = "DV SSL", + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = productCode, + ["ProductFamily"] = "ssl", + ["ProductVariant"] = "dv", + ["DomainName"] = "example.com" + } + }; + + private static EnrollmentProductInfo PkiProductInfo() => new EnrollmentProductInfo + { + ProductID = "DV SSL", + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = "149", + ["ProductFamily"] = "private-pki", + ["ProductVariant"] = "intranet-ssl", + ["DomainName"] = "intranet.example.com" + } + }; + + private static Task Enroll( + CERTInextCAPlugin plugin, EnrollmentProductInfo info, string csr = null, + EnrollmentType type = EnrollmentType.New, string subject = "CN=example.com") => + plugin.Enroll(csr ?? MockCertificateData.FakeCsrPem, subject, new Dictionary(), + info, RequestFormat.PKCS10, type); + + private List Requests(string method) => + _server.LogEntries.Where(e => e.RequestMessage.Method.Equals(method, StringComparison.OrdinalIgnoreCase)).ToList(); + + private void AssertNoPutAndNoCsrPath() + { + Requests("PUT").Should().BeEmpty("the CSR goes inline on create — Submit CSR no longer exists"); + _server.LogEntries.Should().NotContain(e => e.RequestMessage.Path.EndsWith("/csr", StringComparison.OrdinalIgnoreCase)); + } + + [Theory] + [InlineData(EnrollmentType.New)] + [InlineData(EnrollmentType.Reissue)] + [InlineData(EnrollmentType.RenewOrReissue)] + public async Task Ssl_CreateReturnsIssued_DownloadsInSameCall_CsrInlineAndProductPinned_NoPut(EnrollmentType type) + { + StubToken(); + StubCatalog(); + StubCreate(SslPath, 201, MockCertificateData.V2CreateOrderIssuedJson(OrderId)); + StubTrack(SslPath, MockCertificateData.V2TrackOrderIssuedJson(OrderId)); + _server.Given(Request.Create().WithPath($"{SslPath}/{OrderId}/certificate").UsingGet()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2CertificateDownloadJson(OrderId))); + + var result = await Enroll(BuildPlugin(), SslProductInfo(), type: type); + + result.Status.Should().Be((int)EndEntityStatus.GENERATED); + result.CARequestID.Should().Be(OrderId); + result.Certificate.Should().NotBeNullOrWhiteSpace(); + + var creates = Requests("POST").Where(e => e.RequestMessage.Path == SslPath).ToList(); + creates.Should().HaveCount(1, "order creation is never retried"); + creates[0].RequestMessage.Headers.Should().ContainKey("X-Product-Code") + .WhoseValue.Should().Contain("842"); + using var body = JsonDocument.Parse(creates[0].RequestMessage.Body ?? string.Empty); + body.RootElement.GetProperty("csr").GetString().Should().Be(MockCertificateData.FakeCsrPem, + "the CSR is sent unchanged, PEM as received"); + AssertNoPutAndNoCsrPath(); + } + + [Fact] + public async Task Ssl_CreateReturnsPendingApproval_ReturnsPendingWithOrderId_NoPut() + { + StubToken(); + StubCatalog(); + StubCreate(SslPath, 201, + $"{{\"orderId\":\"{OrderId}\",\"requestId\":\"r1\",\"status\":\"pending-approval\"}}"); + StubTrack(SslPath, + $"{{\"orderId\":\"{OrderId}\",\"requestId\":\"r1\",\"status\":\"pending-approval\",\"productVariant\":\"dv\",\"domain\":\"example.com\"}}"); + + var result = await Enroll(BuildPlugin(), SslProductInfo()); + + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + result.CARequestID.Should().Be(OrderId); + result.Certificate.Should().BeNull(); + AssertNoPutAndNoCsrPath(); + } + + [Fact] + public async Task Ssl_IssuedButCertificateNotYetDownloadable_Ems1165_ReturnsPendingNotAnError() + { + // Finding 10: right after 'issued' the download can still return 422 EMS-1165. The + // order exists and carries its CSR, so the enrollment must come back pending with the + // order id (sync imports the certificate), not throw. + StubToken(); + StubCatalog(); + StubCreate(SslPath, 201, MockCertificateData.V2CreateOrderIssuedJson(OrderId)); + StubTrack(SslPath, MockCertificateData.V2TrackOrderIssuedJson(OrderId)); + _server.Given(Request.Create().WithPath($"{SslPath}/{OrderId}/certificate").UsingGet()) + .RespondWith(Response.Create().WithStatusCode(422) + .WithHeader("Content-Type", "application/problem+json") + .WithBody("{\"type\":\"EMS-1165\",\"title\":\"Unprocessable\",\"status\":422,\"detail\":\"certificate not available\"}")); + + var result = await Enroll(BuildPlugin(), SslProductInfo()); + + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + result.CARequestID.Should().Be(OrderId); + AssertNoPutAndNoCsrPath(); + } + + [Fact] + public async Task PrivatePki_FlagOn_IgnoresIt_TwoCall_CreateWithoutCsr_ThenExactlyOnePutCsr_ProductPinned() + { + // Private PKI keeps create + Submit CSR (the sandbox rejects an inline csr there with 422); + // this is the ONLY path in the plugin that sends PUT .../csr. + StubToken(); + StubCreate(PkiPath, 201, + $"{{\"orderId\":\"{OrderId}\",\"requestId\":\"r1\",\"status\":\"pending-csr\",\"variant\":\"intranet-ssl\"}}"); + _server.Given(Request.Create().WithPath($"{PkiPath}/{OrderId}/csr").UsingPut()) + .RespondWith(Response.Create().WithStatusCode(204)); + StubTrack(PkiPath, + $"{{\"orderId\":\"{OrderId}\",\"requestId\":\"r1\",\"status\":\"pending-approval\",\"variant\":\"intranet-ssl\"}}"); + + var result = await Enroll(BuildPlugin(), PkiProductInfo(), subject: "CN=intranet.example.com"); + + result.CARequestID.Should().Be(OrderId); + var creates = Requests("POST").Where(e => e.RequestMessage.Path == PkiPath).ToList(); + creates.Should().HaveCount(1); + creates[0].RequestMessage.Headers.Should().ContainKey("X-Product-Code").WhoseValue.Should().Contain("149"); + using var body = JsonDocument.Parse(creates[0].RequestMessage.Body ?? string.Empty); + body.RootElement.TryGetProperty("csr", out _).Should().BeFalse("Private PKI create carries no inline csr"); + + var puts = Requests("PUT"); + puts.Should().HaveCount(1, "Private PKI submits the CSR exactly once, never retried"); + puts[0].RequestMessage.Path.Should().Be($"{PkiPath}/{OrderId}/csr"); + using var putBody = JsonDocument.Parse(puts[0].RequestMessage.Body ?? string.Empty); + putBody.RootElement.GetProperty("csr").GetString().Should().Be(MockCertificateData.FakeCsrPem); + } + + [Fact] + public async Task Ssl_DefaultConfig_TwoCall_CreateWithoutCsr_ThenExactlyOnePutCsr() + { + // V2InlineCsr defaults to false: SSL/TLS behaves as before — create without csr, then PUT .../csr. + StubToken(); + StubCatalog(); + StubCreate(SslPath, 201, + $"{{\"orderId\":\"{OrderId}\",\"requestId\":\"r1\",\"status\":\"pending-csr\"}}"); + _server.Given(Request.Create().WithPath($"{SslPath}/{OrderId}/csr").UsingPut()) + .RespondWith(Response.Create().WithStatusCode(204)); + StubTrack(SslPath, + $"{{\"orderId\":\"{OrderId}\",\"requestId\":\"r1\",\"status\":\"pending-approval\",\"productVariant\":\"dv\",\"domain\":\"example.com\"}}"); + var config = Config(); + config.V2InlineCsr = false; + + var result = await Enroll(BuildPlugin(config), SslProductInfo()); + + result.CARequestID.Should().Be(OrderId); + var creates = Requests("POST").Where(e => e.RequestMessage.Path == SslPath).ToList(); + creates.Should().HaveCount(1); + creates[0].RequestMessage.Headers.Should().ContainKey("X-Product-Code").WhoseValue.Should().Contain("842"); + using var body = JsonDocument.Parse(creates[0].RequestMessage.Body ?? string.Empty); + body.RootElement.TryGetProperty("csr", out _).Should().BeFalse("the default create carries no inline csr"); + var puts = Requests("PUT"); + puts.Should().HaveCount(1); + puts[0].RequestMessage.Path.Should().Be($"{SslPath}/{OrderId}/csr"); + } + + [Fact] + public async Task Ssl_DefaultConfig_CsrRejected_CancelsOrphanedOrderOnce() + { + StubToken(); + StubCatalog(); + StubCreate(SslPath, 201, + $"{{\"orderId\":\"{OrderId}\",\"requestId\":\"r1\",\"status\":\"pending-csr\"}}"); + _server.Given(Request.Create().WithPath($"{SslPath}/{OrderId}/csr").UsingPut()) + .RespondWith(Response.Create().WithStatusCode(400) + .WithHeader("Content-Type", "application/problem+json") + .WithBody("{\"title\":\"Bad Request\",\"status\":400,\"detail\":\"bad csr\"}")); + _server.Given(Request.Create().WithPath($"{SslPath}/{OrderId}/cancel").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(204)); + var config = Config(); + config.V2InlineCsr = false; + + var result = await Enroll(BuildPlugin(config), SslProductInfo()); + + result.Status.Should().Be((int)EndEntityStatus.FAILED); + result.CARequestID.Should().Be(OrderId); + Requests("PUT").Should().HaveCount(1, "Submit CSR is never retried"); + Requests("POST").Count(e => e.RequestMessage.Path == $"{SslPath}/{OrderId}/cancel").Should().Be(1); + } + + [Fact] + public async Task Ssl_Create5xx_ThrowsDoNotResubmitMessage_NoRetry_NoTrack_NoPut() + { + StubToken(); + StubCatalog(); + StubCreate(SslPath, 500, "{\"title\":\"Internal Server Error\",\"status\":500}"); + + Func act = () => Enroll(BuildPlugin(), SslProductInfo()); + + (await act.Should().ThrowAsync()) + .WithMessage("*next synchronization*do not resubmit*"); + Requests("POST").Count(e => e.RequestMessage.Path == SslPath).Should().Be(1, "create is non-idempotent: never retried"); + Requests("GET").Should().NotContain(e => e.RequestMessage.Path.StartsWith(SslPath + "/"), + "no order id was returned, so there is nothing to track"); + AssertNoPutAndNoCsrPath(); + } + + [Fact] + public async Task Ssl_Create2xxWithEmptyBody_ThrowsDoNotResubmitMessage_NoRetry() + { + // The CA accepted the create but we cannot read the order id: the order exists with its + // inline CSR, so the message must steer the operator away from resubmitting. + StubToken(); + StubCatalog(); + _server.Given(Request.Create().WithPath(SslPath).UsingPost()) + .RespondWith(Response.Create().WithFault(FaultType.EMPTY_RESPONSE)); + + Func act = () => Enroll(BuildPlugin(), SslProductInfo()); + + (await act.Should().ThrowAsync()) + .WithMessage("*next synchronization*do not resubmit*"); + Requests("POST").Count(e => e.RequestMessage.Path == SslPath).Should().Be(1); + AssertNoPutAndNoCsrPath(); + } + + [Fact] + public async Task Client_CreateWithNoHttpStatus_TransportFailure_ThrowsDoNotResubmitMessage() + { + // No HTTP status at all (timeout / refused / dropped connection) is the same "created but we + // never heard back" case as a 5xx. Prime the token cache, then take the server away. + StubToken(); + _server.Given(Request.Create().WithPath("/api/certinext/v2/auth/me").UsingGet()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json").WithBody(MockCertificateData.V2AuthMeJson())); + using var client = new CERTInextClient(Config()); + await client.GetAuthMeV2Async(); + _server.Stop(); + + Func act = () => client.PlaceOrderV2Async( + Constants.ApiV2.FamilySsl, "842", + new API.V2.V2CreateSslOrderRequest + { + Requestor = new API.V2.V2Requestor { Name = "T", Email = "t@t.com" }, + Certificate = new API.V2.V2CertificateParams { Domain = "example.com" }, + Subscription = new API.V2.V2SubscriptionParams(), + Csr = MockCertificateData.FakeCsrPem + }); + + (await act.Should().ThrowAsync()) + .WithMessage("*next synchronization*do not resubmit*"); + } + + [Fact] + public async Task Ssl_Create4xx_KeepsDefiniteRejectionMessage_NotTheDoNotResubmitWording() + { + StubToken(); + StubCatalog(); + StubCreate(SslPath, 422, + "{\"type\":\"EMS-1\",\"title\":\"Unprocessable\",\"status\":422,\"detail\":\"bad csr\"}"); + + Func act = () => Enroll(BuildPlugin(), SslProductInfo()); + + var ex = await act.Should().ThrowAsync(); + ex.Which.Message.Should().Contain("HTTP 422").And.NotContain("do not resubmit"); + AssertNoPutAndNoCsrPath(); + } + + [Fact] + public async Task Ssl_DefaultConfig_Create5xx_DoesNotUseDoNotResubmitMessage_NoRetry_NoPut() + { + // Two-call mode: an order created behind a lost response has no CSR and never issues, so the + // inline-only "do not resubmit; the next sync imports it" message would be wrong (af036ae behaviour). + StubToken(); + StubCatalog(); + StubCreate(SslPath, 500, "{\"title\":\"Internal Server Error\",\"status\":500}"); + var config = Config(); + config.V2InlineCsr = false; + + Func act = () => Enroll(BuildPlugin(config), SslProductInfo()); + + var ex = await act.Should().ThrowAsync(); + ex.Which.Message.Should().NotContain("do not resubmit").And.NotContain("next synchronization"); + Requests("POST").Count(e => e.RequestMessage.Path == SslPath).Should().Be(1, "create is non-idempotent: never retried"); + Requests("PUT").Should().BeEmpty("no order id came back, so there is no CSR to submit"); + } + + [Fact] + public async Task Ssl_DefaultConfig_Create2xxUnreadableBody_DoesNotUseDoNotResubmitMessage() + { + StubToken(); + StubCatalog(); + StubCreate(SslPath, 201, "this is not json"); + var config = Config(); + config.V2InlineCsr = false; + + Func act = () => Enroll(BuildPlugin(config), SslProductInfo()); + + var ex = await act.Should().ThrowAsync(); + ex.Which.Message.Should().NotContain("do not resubmit").And.NotContain("next synchronization"); + Requests("POST").Count(e => e.RequestMessage.Path == SslPath).Should().Be(1); + Requests("PUT").Should().BeEmpty(); + } + + [Fact] + public async Task Ssl_InlineMode_Create2xxUnreadableBody_ThrowsDoNotResubmitMessage() + { + StubToken(); + StubCatalog(); + StubCreate(SslPath, 201, "this is not json"); + + Func act = () => Enroll(BuildPlugin(), SslProductInfo()); + + (await act.Should().ThrowAsync()) + .WithMessage("*most likely created*next synchronization*do not resubmit*"); + Requests("POST").Count(e => e.RequestMessage.Path == SslPath).Should().Be(1); + AssertNoPutAndNoCsrPath(); + } + + [Fact] + public async Task PrivatePki_FlagOn_Create5xx_DoesNotUseDoNotResubmitMessage() + { + // The flag is ignored for Private PKI (always two-call), so the inline-only wording must not appear. + StubToken(); + StubCreate(PkiPath, 500, "{\"title\":\"Internal Server Error\",\"status\":500}"); + + Func act = () => Enroll(BuildPlugin(), PkiProductInfo(), subject: "CN=intranet.example.com"); + + var ex = await act.Should().ThrowAsync(); + ex.Which.Message.Should().NotContain("do not resubmit").And.NotContain("next synchronization"); + Requests("POST").Count(e => e.RequestMessage.Path == PkiPath).Should().Be(1, "create is never retried"); + Requests("PUT").Should().BeEmpty("no order id came back, so there is no CSR to submit"); + } + + [Fact] + public async Task PrivatePki_FlagOn_Create2xxUnreadableBody_DoesNotUseDoNotResubmitMessage() + { + StubToken(); + StubCreate(PkiPath, 201, "this is not json"); + + Func act = () => Enroll(BuildPlugin(), PkiProductInfo(), subject: "CN=intranet.example.com"); + + var ex = await act.Should().ThrowAsync(); + ex.Which.Message.Should().NotContain("do not resubmit").And.NotContain("next synchronization"); + Requests("PUT").Should().BeEmpty(); + } + + [Fact] + public async Task Client_DefaultConfig_CreateWithNoHttpStatus_DoesNotUseDoNotResubmitMessage() + { + // Same transport failure as Client_CreateWithNoHttpStatus_TransportFailure_..., but in two-call mode. + StubToken(); + _server.Given(Request.Create().WithPath("/api/certinext/v2/auth/me").UsingGet()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json").WithBody(MockCertificateData.V2AuthMeJson())); + var config = Config(); + config.V2InlineCsr = false; + using var client = new CERTInextClient(config); + await client.GetAuthMeV2Async(); + _server.Stop(); + + Func act = () => client.PlaceOrderV2Async( + Constants.ApiV2.FamilySsl, "842", + new API.V2.V2CreateSslOrderRequest + { + Requestor = new API.V2.V2Requestor { Name = "T", Email = "t@t.com" }, + Certificate = new API.V2.V2CertificateParams { Domain = "example.com" }, + Subscription = new API.V2.V2SubscriptionParams() + }); + + var ex = await act.Should().ThrowAsync(); + ex.Which.Message.Should().NotContain("do not resubmit").And.NotContain("next synchronization"); + } + + [Theory] + [InlineData(null)] + [InlineData("")] + [InlineData(" ")] + public async Task Ssl_BlankCsr_FailsBeforeAnyRequest(string csr) + { + var result = await plugin_Enroll(csr); + + result.Status.Should().Be((int)EndEntityStatus.FAILED); + result.StatusMessage.Should().Contain("no CSR").And.Contain("No order was placed"); + _server.LogEntries.Should().BeEmpty("a blank CSR must be rejected before any CA call"); + + Task plugin_Enroll(string c) => + BuildPlugin().Enroll(c, "CN=example.com", new Dictionary(), SslProductInfo(), + RequestFormat.PKCS10, EnrollmentType.New); + } + + [Fact] + public async Task Ssl_WhitespaceProductCode_IsTreatedAsUnset_NoHeader_NoCatalogCall() + { + // A whitespace ProductCode is treated as unset: no X-Product-Code is sent (CERTInext's + // wrapper resolves the product) and the catalog is not consulted at all. + StubToken(); + StubCreate(SslPath, 201, + $"{{\"orderId\":\"{OrderId}\",\"requestId\":\"r1\",\"status\":\"pending-approval\"}}"); + StubTrack(SslPath, + $"{{\"orderId\":\"{OrderId}\",\"requestId\":\"r1\",\"status\":\"pending-approval\",\"productVariant\":\"dv\",\"domain\":\"example.com\"}}"); + + await Enroll(BuildPlugin(), SslProductInfo(productCode: " ")); + + var create = Requests("POST").Single(e => e.RequestMessage.Path == SslPath); + create.RequestMessage.Headers.Should().NotContainKey("X-Product-Code"); + _server.LogEntries.Should().NotContain(e => e.RequestMessage.Path.Contains("/catalog/products"), + "with no explicit ProductCode there is nothing to look up in the catalog"); + } + } +} diff --git a/CERTInext.Tests/V2SslComValidationTests.cs b/CERTInext.Tests/V2SslComValidationTests.cs new file mode 100644 index 0000000..4c2521a --- /dev/null +++ b/CERTInext.Tests/V2SslComValidationTests.cs @@ -0,0 +1,654 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Generic; +using System.Linq; +using System.Text.Json; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Microsoft.Extensions.Logging; +using Moq; +using WireMock.RequestBuilders; +using WireMock.ResponseBuilders; +using WireMock.Server; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// SSL.com organization validation for V2 OV/EV SSL orders: the typed model and its defensive + /// "validated for level" logic, the three client calls, and the plugin pre-check, which is + /// strictly advisory (every failure or not-validated outcome warns and the order is placed anyway). + /// All sample values are placeholders (no real names or emails). + /// + [Collection(LoggingStateCollection.Name)] + public class V2SslComValidationTests : IDisposable + { + private const string OrgNumber = "1234567"; + private const string ContactEmail = "contact.person@example.org"; + private const string AdminEmail = "pki-admin@example.com"; + private const string OrderId = "ord_sslcom_001"; + + private readonly WireMockServer _server = WireMockServer.Start(); + public void Dispose() => _server.Stop(); + + // The shape of a live read-only GET on a never-submitted organization (values replaced). + private const string LiveNotSubmittedJson = @"{ + ""caName"":""SSL.com"",""lastError"":"""",""organizationNumber"":""1234567"", + ""readiness"":{""current"":{""contactTitle"":"""",""registrationNumber"":""R-1"",""contactName"":""Placeholder"", + ""businessCategoryId"":"""",""organizationPhone"":""""}, + ""softMissing"":[""Organization phone number""],""evMissing"":[""Business category"",""Contact designation""], + ""ready"":true,""evReady"":false,""missing"":[]}, + ""lastSyncedAt"":"""",""enabled"":true,""subscriberAgreementAccepted"":false,""externalOrgId"":"""", + ""defaultLevels"":[""OV""], + ""contact"":{""companyNumber"":""R-1"",""name"":""Placeholder"",""title"":"""",""email"":""contact.person@example.org""}, + ""submittedAt"":"""",""ca"":""sslcom"",""validatedAt"":"""",""levels"":[],""status"":""NOT_SUBMITTED"", + ""someFutureField"":{""x"":1}}"; + + private static V2SslComValidation Parse(string json) => JsonSerializer.Deserialize(json); + + // --------------------------------------------------------------------------- + // Model + // --------------------------------------------------------------------------- + + [Fact] + public void Model_ParsesTheLiveShape_AndKeepsUnknownFields() + { + var v = Parse(LiveNotSubmittedJson); + + v.Status.Should().Be("NOT_SUBMITTED"); + v.DefaultLevels.Should().Equal("OV"); + v.SubscriberAgreementAccepted.Should().BeFalse(); + v.Readiness.Ready.Should().BeTrue(); + v.Readiness.EvReady.Should().BeFalse(); + v.Readiness.Missing.Should().BeEmpty(); + v.Readiness.EvMissing.Should().Equal("Business category", "Contact designation"); + v.Readiness.SoftMissing.Should().Equal("Organization phone number"); + v.Contact.Email.Should().Be(ContactEmail); + v.Levels.ValueKind.Should().Be(JsonValueKind.Array); + v.ExtensionData.Should().ContainKey("someFutureField"); + v.IsLevelValidated("OV").Should().BeFalse(); + v.IsLevelValidated("EV").Should().BeFalse(); + v.IsLevelListed("OV").Should().BeFalse(); + } + + [Fact] + public void Model_EmptyObject_ParsesAndIsNotValidated() + { + var v = Parse("{}"); + v.IsLevelValidated("OV").Should().BeFalse(); + v.IsLevelListed("OV").Should().BeFalse(); + } + + [Theory] + // per-level objects + [InlineData(@"{""levels"":[{""level"":""OV"",""status"":""VALIDATED"",""validTill"":""2099-01-01T00:00:00Z""}]}", "OV", true)] + [InlineData(@"{""levels"":[{""level"":""OV"",""status"":""VALIDATED"",""validTill"":""2099-01-01T00:00:00Z""}]}", "EV", false)] + [InlineData(@"{""levels"":[{""level"":""ov"",""status"":""approved""}]}", "OV", true)] + [InlineData(@"{""levels"":[{""level"":""EV"",""state"":""ACTIVE""}]}", "EV", true)] + [InlineData(@"{""levels"":[{""name"":""OV"",""validTill"":""2099-01-01""}]}", "OV", true)] // no status, future expiry + [InlineData(@"{""levels"":[{""level"":""OV"",""validated"":true}]}", "OV", true)] + [InlineData(@"{""levels"":[{""level"":""OV"",""status"":""VALIDATED"",""validTill"":""2001-01-01T00:00:00Z""}]}", "OV", false)] // expired + [InlineData(@"{""levels"":[{""level"":""OV"",""status"":""PENDING""}]}", "OV", false)] + [InlineData(@"{""levels"":[{""level"":""OV"",""status"":""NOT_SUBMITTED""}]}", "OV", false)] + [InlineData(@"{""levels"":[{""level"":""OV"",""validTill"":""2001-01-01""}]}", "OV", false)] // no status, past expiry + [InlineData(@"{""levels"":[{""level"":""OV""}]}", "OV", false)] // listed, no evidence + // bare level names: only count with an overall validated status + [InlineData(@"{""status"":""VALIDATED"",""levels"":[""OV""]}", "OV", true)] + [InlineData(@"{""status"":""NOT_SUBMITTED"",""levels"":[""OV""]}", "OV", false)] + [InlineData(@"{""status"":""VALIDATED"",""levels"":[""OV""]}", "EV", false)] + // map keyed by level + [InlineData(@"{""levels"":{""OV"":{""status"":""VALIDATED""},""EV"":""PENDING""}}", "OV", true)] + [InlineData(@"{""levels"":{""OV"":{""status"":""VALIDATED""},""EV"":""PENDING""}}", "EV", false)] + [InlineData(@"{""levels"":{""EV"":""VALIDATED""}}", "EV", true)] + // a level-named top-level member + [InlineData(@"{""OV"":{""status"":""VALIDATED""}}", "OV", true)] + // the overall status or validatedAt alone is never per-level evidence + [InlineData(@"{""status"":""VALIDATED"",""levels"":[]}", "OV", false)] + [InlineData(@"{""validatedAt"":""2026-01-01T00:00:00Z"",""defaultLevels"":[""OV""]}", "OV", false)] + // unrecognizable shapes are "not validated" + [InlineData(@"{""levels"":""weird""}", "OV", false)] + [InlineData(@"{""levels"":[1,2,3]}", "OV", false)] + [InlineData(@"{""levels"":null}", "OV", false)] + public void IsLevelValidated_DefensiveAcrossPlausibleShapes(string json, string level, bool expected) + { + Parse(json).IsLevelValidated(level).Should().Be(expected); + } + + [Theory] + [InlineData(@"{""levels"":[{""level"":""OV"",""status"":""PENDING""}]}", "OV", true)] + [InlineData(@"{""levels"":[""OV""]}", "OV", true)] + [InlineData(@"{""levels"":{""EV"":""PENDING""}}", "EV", true)] + [InlineData(@"{""levels"":[{""level"":""OV"",""status"":""PENDING""}]}", "EV", false)] + [InlineData(@"{""levels"":[]}", "OV", false)] + public void IsLevelListed_FindsARequestedLevelInAnyState(string json, string level, bool expected) + { + Parse(json).IsLevelListed(level).Should().Be(expected); + } + + [Theory] + [InlineData(true, true, 0, "OV", true)] + [InlineData(true, true, 1, "OV", false)] // something still missing + [InlineData(false, true, 0, "OV", false)] + [InlineData(true, false, 0, "EV", false)] // OV ready but EV not + [InlineData(true, true, 0, "EV", true)] + public void SslComReadyFor_UsesTheMatchingFlagAndMissingList(bool ready, bool evReady, int missingCount, string level, bool expected) + { + var missing = Enumerable.Repeat("x", missingCount).ToList(); + var r = new V2SslComReadiness + { + Ready = ready, EvReady = evReady, + Missing = level == "OV" ? missing : new List(), + EvMissing = level == "EV" ? missing : new List() + }; + CERTInextCAPlugin.SslComReadyFor(r, level).Should().Be(expected); + } + + [Fact] + public void SslComReadyFor_NoReadinessBlock_IsNotReady() + { + CERTInextCAPlugin.SslComReadyFor(null, "OV").Should().BeFalse(); + CERTInextCAPlugin.SslComReadyFor(new V2SslComReadiness(), "OV").Should().BeFalse(); + } + + // --------------------------------------------------------------------------- + // Client (WireMock) + // --------------------------------------------------------------------------- + + private CERTInextClient BuildClient() => new CERTInextClient(new CERTInextConfig + { + ApiUrl = _server.Urls[0], + UseV2Api = true, + OAuthClientId = "my-v2-client", + OAuthClientSecret = "my-v2-secret", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + PageSize = 100 + }); + + private void StubToken() => + _server.Given(Request.Create().WithPath("/oauth/token").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.V2TokenResponseJson(3600))); + + private const string SslComPath = "/api/certinext/v2/organizations/" + OrgNumber + "/ca-validations/sslcom"; + + [Fact] + public async Task Client_Get_ReadsTheStatusFromTheDocumentedPath() + { + StubToken(); + _server.Given(Request.Create().WithPath(SslComPath).UsingGet()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json").WithBody(LiveNotSubmittedJson)); + + using var client = BuildClient(); + var v = await client.GetSslComValidationAsync(OrgNumber); + + v.Status.Should().Be("NOT_SUBMITTED"); + v.Readiness.Ready.Should().BeTrue(); + } + + [Fact] + public async Task Client_Sync_PostsWithoutABody_ToTheSyncPath() + { + StubToken(); + _server.Given(Request.Create().WithPath(SslComPath + "/sync").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json").WithBody(LiveNotSubmittedJson)); + + using var client = BuildClient(); + var v = await client.SyncSslComValidationAsync(OrgNumber); + + v.Status.Should().Be("NOT_SUBMITTED"); + var entry = _server.LogEntries.Single(e => e.RequestMessage.Path.EndsWith("/sync")); + entry.RequestMessage.Method.Should().Be("POST"); + (entry.RequestMessage.Body ?? string.Empty).Should().BeEmpty(); + } + + [Fact] + public async Task Client_Submit_PostsLevelsAgreementFlagAndAdminEmail() + { + StubToken(); + _server.Given(Request.Create().WithPath(SslComPath).UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json").WithBody(@"{""status"":""SUBMITTED"",""levels"":[""OV""]}")); + + using var client = BuildClient(); + var v = await client.SubmitSslComValidationAsync(OrgNumber, new V2SslComSubmitRequest + { + Levels = new List { "OV" }, SubscriberAgreementAccepted = true, AdminEmail = AdminEmail + }); + + v.Status.Should().Be("SUBMITTED"); + var entry = _server.LogEntries.Single(e => e.RequestMessage.Path == SslComPath); + using var doc = JsonDocument.Parse(entry.RequestMessage.Body!); + doc.RootElement.GetProperty("levels").EnumerateArray().Select(e => e.GetString()).Should().Equal("OV"); + doc.RootElement.GetProperty("subscriberAgreementAccepted").GetBoolean().Should().BeTrue(); + doc.RootElement.GetProperty("adminEmail").GetString().Should().Be(AdminEmail); + } + + [Fact] + public async Task Client_Submit_OmitsAdminEmailWhenUnset_AndToleratesAnEmptyResponseBody() + { + StubToken(); + _server.Given(Request.Create().WithPath(SslComPath).UsingPost()) + .RespondWith(Response.Create().WithStatusCode(204)); + + using var client = BuildClient(); + var v = await client.SubmitSslComValidationAsync(OrgNumber, new V2SslComSubmitRequest + { + Levels = new List { "EV" }, SubscriberAgreementAccepted = true + }); + + v.Should().BeNull(); + var entry = _server.LogEntries.Single(e => e.RequestMessage.Path == SslComPath); + entry.RequestMessage.Body.Should().NotContain("adminEmail"); + } + + [Fact] + public async Task Client_Get_EscapesTheOrganizationNumber_AndCaErrorsThrow() + { + StubToken(); + _server.Given(Request.Create().WithPath("/api/certinext/v2/organizations/*/ca-validations/sslcom").UsingGet()) + .RespondWith(Response.Create().WithStatusCode(404) + .WithHeader("Content-Type", "application/problem+json") + .WithBody(@"{""title"":""Not Found"",""status"":404,""detail"":""Organization not found""}")); + + using var client = BuildClient(); + Func act = () => client.GetSslComValidationAsync("a/b c"); + + await act.Should().ThrowAsync().WithMessage("*HTTP 404*"); + _server.LogEntries.Last().RequestMessage.Url.Should().Contain("a%2Fb"); + } + + // --------------------------------------------------------------------------- + // Plugin + // --------------------------------------------------------------------------- + + private static CERTInextConfig Config(bool submit = false, string adminEmail = null, string organizationNumber = OrgNumber) => + new CERTInextConfig + { + UseV2Api = true, + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + SignerPlace = "New York", + OrganizationNumber = organizationNumber, + SslComSubmitOrganization = submit, + SslComAdminEmail = adminEmail, + PickupRetries = 0 + }; + + private sealed class Harness + { + public Mock Mock = new Mock(MockBehavior.Strict); + public List Calls = new List(); + public V2SslComSubmitRequest Submitted; + } + + private static Harness NewHarness( + Func get, Func sync = null, Func submit = null, + Exception getError = null, Exception syncError = null, Exception submitError = null) + { + var h = new Harness(); + if (getError != null) + h.Mock.Setup(c => c.GetSslComValidationAsync(OrgNumber, It.IsAny())) + .Callback(() => h.Calls.Add("get")).ThrowsAsync(getError); + else if (get != null) + h.Mock.Setup(c => c.GetSslComValidationAsync(OrgNumber, It.IsAny())) + .Callback(() => h.Calls.Add("get")).ReturnsAsync(() => get()); + if (syncError != null) + h.Mock.Setup(c => c.SyncSslComValidationAsync(OrgNumber, It.IsAny())) + .Callback(() => h.Calls.Add("sync")).ThrowsAsync(syncError); + else if (sync != null) + h.Mock.Setup(c => c.SyncSslComValidationAsync(OrgNumber, It.IsAny())) + .Callback(() => h.Calls.Add("sync")).ReturnsAsync(() => sync()); + if (submitError != null) + h.Mock.Setup(c => c.SubmitSslComValidationAsync(OrgNumber, It.IsAny(), It.IsAny())) + .Callback((_, r, __) => { h.Calls.Add("submit"); h.Submitted = r; }) + .ThrowsAsync(submitError); + else if (submit != null) + h.Mock.Setup(c => c.SubmitSslComValidationAsync(OrgNumber, It.IsAny(), It.IsAny())) + .Callback((_, r, __) => { h.Calls.Add("submit"); h.Submitted = r; }) + .ReturnsAsync(() => submit()); + + h.Mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .Callback(() => h.Calls.Add("place")) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = OrderId, Status = "pending-csr" }); + h.Mock.Setup(c => c.SubmitCsrV2Async(It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + h.Mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "pending-approval" }); + return h; + } + + private static V2SslComValidation NotSubmitted(bool ready = true, bool evReady = true) => Parse( + @"{""status"":""NOT_SUBMITTED"",""levels"":[],""defaultLevels"":[""OV""],""lastError"":""contact.person@example.org rejected""," + + @"""readiness"":{""ready"":" + (ready ? "true" : "false") + @",""evReady"":" + (evReady ? "true" : "false") + + @",""missing"":[],""evMissing"":[],""softMissing"":[""Organization phone number""]}," + + @"""contact"":{""name"":""Placeholder"",""email"":""" + ContactEmail + @"""}}"); + + private static V2SslComValidation Validated(string level) => Parse( + @"{""status"":""VALIDATED"",""levels"":[{""level"":""" + level + @""",""status"":""VALIDATED"",""validTill"":""2099-01-01T00:00:00Z""}]}"); + + private static Task EnrollAsync(CERTInextCAPlugin plugin, string productId = Constants.Products.OvSsl, + string family = "ssl") + { + var p = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductFamily"] = family, ["DomainName"] = "example.com" + }; + if (family == "private-pki") p["ProductVariant"] = "intranet-ssl"; + return plugin.Enroll(MockCertificateData.FakeCsrPem, "CN=example.com", + new Dictionary { ["dnsname"] = new[] { "example.com" } }, + new EnrollmentProductInfo { ProductID = productId, ProductParameters = p }, + RequestFormat.PKCS10, EnrollmentType.New); + } + + [Fact] + public async Task Ov_AlreadyValidated_OnlyReadsTheStatus_ThenPlacesTheOrder() + { + using var capture = new PluginLogCapture(); + var h = NewHarness(get: () => Validated("OV")); + var plugin = new CERTInextCAPlugin(h.Mock.Object, Config(submit: true)); + + var result = await EnrollAsync(plugin); + + result.CARequestID.Should().Be(OrderId); + h.Calls.Should().Equal("get", "place"); + capture.Entries.Where(e => e.Level >= LogLevel.Warning).Should().BeEmpty(); + } + + [Fact] + public async Task Ov_ValidatedAfterTheSyncRefresh_NoSubmit() + { + var h = NewHarness(get: () => NotSubmitted(), sync: () => Validated("OV"), submit: () => NotSubmitted()); + var plugin = new CERTInextCAPlugin(h.Mock.Object, Config(submit: true)); + + await EnrollAsync(plugin); + + h.Calls.Should().Equal("get", "sync", "place"); + } + + [Fact] + public async Task Ov_NotValidated_SubmitOff_WarnsOnce_NeverSubmits_AndStillPlacesTheOrder() + { + using var capture = new PluginLogCapture(); + var h = NewHarness(get: () => NotSubmitted(), sync: () => NotSubmitted()); + var plugin = new CERTInextCAPlugin(h.Mock.Object, Config(submit: false)); + + var result = await EnrollAsync(plugin); + + result.CARequestID.Should().Be(OrderId); + h.Calls.Should().Equal("get", "sync", "place"); + var warnings = capture.Entries.Where(e => e.Level == LogLevel.Warning).Select(e => e.Message).ToList(); + warnings.Should().ContainSingle(); + warnings[0].Should().Contain("has not validated organization " + OrgNumber) + .And.Contain("NOT_SUBMITTED") + .And.Contain("Organization phone number") + .And.Contain("SslComSubmitOrganization is off") + .And.Contain("placing the order anyway"); + // personal data: the SSL.com contact email and the email echoed inside lastError are masked + warnings[0].Should().NotContain(ContactEmail).And.Contain("c***@example.org"); + } + + [Fact] + public async Task Ov_NotValidated_SubmitOn_SubmitsOnce_AuditsFirst_WithTheSpecBody() + { + using var capture = new PluginLogCapture(); + var h = NewHarness(get: () => NotSubmitted(), sync: () => NotSubmitted(), + submit: () => Parse(@"{""status"":""SUBMITTED"",""levels"":[{""level"":""OV"",""status"":""PENDING""}]}")); + var plugin = new CERTInextCAPlugin(h.Mock.Object, Config(submit: true, adminEmail: AdminEmail)); + + var result = await EnrollAsync(plugin); + + result.CARequestID.Should().Be(OrderId); + h.Calls.Should().Equal("get", "sync", "submit", "place"); + h.Submitted.Levels.Should().Equal("OV"); + h.Submitted.SubscriberAgreementAccepted.Should().BeTrue(); + h.Submitted.AdminEmail.Should().Be(AdminEmail); + + var all = capture.Entries.Select(e => e.Message).ToList(); + int audit = all.FindIndex(m => m.Contains("submission attempt started")); + int done = all.FindIndex(m => m.Contains("organization validation submitted")); + audit.Should().BeGreaterOrEqualTo(0); + done.Should().BeGreaterThan(audit, "the acceptance is audit-logged before the call"); + all[audit].Should().Contain("subscriber agreement").And.Contain(OrgNumber) + .And.NotContain(AdminEmail).And.Contain("p***@example.com"); + // submitted but not yet validated: still warns, still places the order + capture.Lines(LogLevel.Warning, "has not validated organization").Should().ContainSingle() + .Which.Should().Contain("SubmittedThisCall=True"); + } + + [Fact] + public async Task Ov_SubmitOn_ButNoAdminEmail_SendsNone() + { + var h = NewHarness(get: () => NotSubmitted(), sync: () => NotSubmitted(), submit: () => NotSubmitted()); + var plugin = new CERTInextCAPlugin(h.Mock.Object, Config(submit: true)); + + await EnrollAsync(plugin); + + h.Submitted.AdminEmail.Should().BeNull(); + } + + [Fact] + public async Task Ov_SubmitOn_ButNotReady_DoesNotSubmit_AndSaysWhy() + { + using var capture = new PluginLogCapture(); + var h = NewHarness(get: () => NotSubmitted(ready: false), sync: () => NotSubmitted(ready: false)); + var plugin = new CERTInextCAPlugin(h.Mock.Object, Config(submit: true)); + + await EnrollAsync(plugin); + + h.Calls.Should().Equal("get", "sync", "place"); + capture.Lines(LogLevel.Warning, "has not validated organization").Should().ContainSingle() + .Which.Should().Contain("not ready for OV"); + } + + [Fact] + public async Task Ov_SubmitOn_NoReadinessInformation_IsTreatedAsNotReady() + { + var bare = Parse(@"{""status"":""NOT_SUBMITTED"",""levels"":[]}"); + var h = NewHarness(get: () => bare, sync: () => bare); + var plugin = new CERTInextCAPlugin(h.Mock.Object, Config(submit: true)); + + await EnrollAsync(plugin); + + h.Calls.Should().Equal("get", "sync", "place"); + } + + [Fact] + public async Task Ov_SubmitOn_LevelAlreadyRequested_DoesNotSubmitAgain() + { + var pending = Parse(@"{""status"":""SUBMITTED"",""levels"":[{""level"":""OV"",""status"":""PENDING""}], + ""readiness"":{""ready"":true,""evReady"":true,""missing"":[],""evMissing"":[]}}"); + var h = NewHarness(get: () => pending, sync: () => pending); + var plugin = new CERTInextCAPlugin(h.Mock.Object, Config(submit: true)); + + await EnrollAsync(plugin); + + h.Calls.Should().Equal("get", "sync", "place"); + } + + [Fact] + public async Task Ev_UsesTheEvReadinessAndSubmitsTheEvLevel() + { + var notReadyForEv = NotSubmitted(ready: true, evReady: false); + var h1 = NewHarness(get: () => notReadyForEv, sync: () => notReadyForEv); + await EnrollAsync(new CERTInextCAPlugin(h1.Mock.Object, Config(submit: true)), Constants.Products.EvSsl); + h1.Calls.Should().Equal("get", "sync", "place"); + + var readyForEv = NotSubmitted(ready: false, evReady: true); + var h2 = NewHarness(get: () => readyForEv, sync: () => readyForEv, submit: () => readyForEv); + await EnrollAsync(new CERTInextCAPlugin(h2.Mock.Object, Config(submit: true)), Constants.Products.EvSsl); + h2.Calls.Should().Equal("get", "sync", "submit", "place"); + h2.Submitted.Levels.Should().Equal("EV"); + } + + [Fact] + public async Task StatusReadFails_WarnsAndStillPlacesTheOrder_WithNoFurtherSslComCalls() + { + using var capture = new PluginLogCapture(); + var h = NewHarness(get: null, getError: new Exception("CERTInext V2 API error during 'V2 SSL.com validation status'. HTTP 500. boom")); + var plugin = new CERTInextCAPlugin(h.Mock.Object, Config(submit: true)); + + var result = await EnrollAsync(plugin); + + result.CARequestID.Should().Be(OrderId); + h.Calls.Should().Equal("get", "place"); + capture.Lines(LogLevel.Warning, "could not be read").Should().ContainSingle(); + } + + [Fact] + public async Task SyncFails_WarnsAndStillEvaluatesTheEarlierStatus() + { + using var capture = new PluginLogCapture(); + var h = NewHarness(get: () => NotSubmitted(), syncError: new Exception("HTTP 500"), submit: () => NotSubmitted()); + var plugin = new CERTInextCAPlugin(h.Mock.Object, Config(submit: true)); + + await EnrollAsync(plugin); + + h.Calls.Should().Equal("get", "sync", "submit", "place"); + capture.Lines(LogLevel.Warning, "validation refresh").Should().ContainSingle(); + } + + [Fact] + public async Task SubmitFails_WarnsAndStillPlacesTheOrder() + { + using var capture = new PluginLogCapture(); + var h = NewHarness(get: () => NotSubmitted(), sync: () => NotSubmitted(), submitError: new Exception("HTTP 422")); + var plugin = new CERTInextCAPlugin(h.Mock.Object, Config(submit: true)); + + var result = await EnrollAsync(plugin); + + result.CARequestID.Should().Be(OrderId); + h.Calls.Should().Equal("get", "sync", "submit", "place"); + capture.Lines(LogLevel.Warning, "submission failed").Should().ContainSingle(); + } + + [Theory] + [InlineData("DV SSL", "ssl")] + [InlineData("DV SSL", "private-pki")] + public async Task DvAndPrivatePki_NeverCallSslCom(string productId, string family) + { + var h = NewHarness(get: () => NotSubmitted()); + if (family == "private-pki") + h.Mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), It.IsAny())) + .Callback(() => h.Calls.Add("place")) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = OrderId, Status = "pending-csr" }); + if (family == "private-pki") + { + h.Mock.Setup(c => c.SubmitCsrV2Async(Constants.ApiV2.FamilyPrivatePki, OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + h.Mock.Setup(c => c.TrackOrderV2Async(Constants.ApiV2.FamilyPrivatePki, OrderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "pending-approval" }); + } + var plugin = new CERTInextCAPlugin(h.Mock.Object, Config(submit: true)); + + await EnrollAsync(plugin, productId, family); + + h.Calls.Should().Equal("place"); + } + + [Fact] + public async Task Ov_WithoutOrganizationNumber_IsRejectedBeforeAnySslComCall() + { + var h = NewHarness(get: () => NotSubmitted()); + var plugin = new CERTInextCAPlugin(h.Mock.Object, Config(submit: true, organizationNumber: null)); + + var result = await EnrollAsync(plugin); + + result.Status.Should().Be((int)EndEntityStatus.FAILED); + h.Calls.Should().BeEmpty(); + } + + // --------------------------------------------------------------------------- + // Settings + // --------------------------------------------------------------------------- + + [Fact] + public void Annotations_SslComSubmitOrganization_IsABooleanDefaultingToFalse_AndWarnsAboutTheAgreement() + { + var annotations = CERTInextCAPluginConfig.GetCAConnectorAnnotations(); + + annotations.Should().ContainKey("SslComSubmitOrganization"); + var a = annotations["SslComSubmitOrganization"]; + a.Type.Should().Be("Boolean"); + a.DefaultValue.Should().Be(false); + a.Comments.Should().ContainEquivalentOf("accepts SSL.com's subscriber agreement on the organization's behalf"); + annotations.Should().ContainKey("SslComAdminEmail"); + annotations["SslComAdminEmail"].Type.Should().Be("String"); + new CERTInextConfig().SslComSubmitOrganization.Should().BeFalse(); + } + + [Fact] + public void Config_DeserializesTheSslComSettings() + { + var cfg = JsonSerializer.Deserialize( + $"{{\"SslComSubmitOrganization\":true,\"SslComAdminEmail\":\"{AdminEmail}\"}}"); + cfg!.SslComSubmitOrganization.Should().BeTrue(); + cfg.SslComAdminEmail.Should().Be(AdminEmail); + } + + private static Dictionary Info(string key, object value) => new Dictionary + { + ["UseV2Api"] = true, + ["ApiUrl"] = "not-a-url", // invalid on purpose: errors are collected with the one under test + ["OAuthClientId"] = "id", + ["OAuthClientSecret"] = "secret", + ["SignerPlace"] = "NY", + [key] = value + }; + + [Theory] + [InlineData("yes")] + [InlineData("true")] + [InlineData(1)] + public async Task ValidateCAConnectionInfo_RejectsNonBooleanSslComSubmitOrganization(object value) + { + var plugin = new CERTInextCAPlugin(new Mock(MockBehavior.Strict).Object); + Func act = () => plugin.ValidateCAConnectionInfo(Info("SslComSubmitOrganization", value)); + await act.Should().ThrowAsync().WithMessage("*SslComSubmitOrganization*must be true or false*"); + } + + [Theory] + [InlineData("not-an-email")] + [InlineData("two@@example.com")] + [InlineData("a b@example.com")] + [InlineData("a@nodot")] + public async Task ValidateCAConnectionInfo_RejectsAMalformedSslComAdminEmail(string value) + { + var plugin = new CERTInextCAPlugin(new Mock(MockBehavior.Strict).Object); + Func act = () => plugin.ValidateCAConnectionInfo(Info("SslComAdminEmail", value)); + await act.Should().ThrowAsync().WithMessage("*SslComAdminEmail*"); + } + + [Fact] + public async Task ValidateCAConnectionInfo_AcceptsTheSslComSettings() + { + var plugin = new CERTInextCAPlugin(new Mock(MockBehavior.Strict).Object); + var info = Info("SslComSubmitOrganization", true); + info["SslComAdminEmail"] = AdminEmail; + Func act = () => plugin.ValidateCAConnectionInfo(info); + + var ex = await act.Should().ThrowAsync(); // ApiUrl is invalid on purpose + ex.Which.Message.Should().NotContain("SslComSubmitOrganization").And.NotContain("SslComAdminEmail"); + } + } +} diff --git a/CERTInext.Tests/V2SslOrderBodyGoldenTests.cs b/CERTInext.Tests/V2SslOrderBodyGoldenTests.cs new file mode 100644 index 0000000..acfd8e5 --- /dev/null +++ b/CERTInext.Tests/V2SslOrderBodyGoldenTests.cs @@ -0,0 +1,237 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Generic; +using System.Text.Json; +using System.Text.Json.Serialization; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Moq; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Golden-body guard: branching EnrollV2Async on product family must not + /// change a single byte of the SSL/TLS create-order body. Each test drives a full V2 SSL + /// enrollment against a Strict mock, captures the handed + /// to the client, serializes it with the client's own serializer options, and compares the + /// result to a golden JSON string. + /// + public class V2SslOrderBodyGoldenTests + { + // Mirrors CERTInextClient.GetJsonOptions() (private) — the options PlaceOrderV2Async + // uses to produce the actual wire body. + private static JsonSerializerOptions ClientEquivalentJsonOptions() => new JsonSerializerOptions + { + PropertyNameCaseInsensitive = true, + DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull + }; + + private static async Task<(string Json, string FamilySlug, string ProductCode)> CaptureSslBodyAsync( + CERTInextConfig config, + EnrollmentProductInfo productInfo, + string catalogCode, + string catalogTypeId, + Dictionary san, + string subject) + { + const string orderId = "ord_golden_001"; + var mock = new Mock(MockBehavior.Strict); + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = catalogCode, ProductTypeId = catalogTypeId, Active = true } + }); + + V2CreateSslOrderRequest captured = null; + string capturedSlug = null; + string capturedCode = null; + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .Callback((slug, code, req, _) => + { + capturedSlug = slug; + capturedCode = code; + captured = req; + }) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = orderId, Status = "pending-dcv" }); + mock.Setup(c => c.SubmitCsrV2Async(It.IsAny(), orderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), orderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = orderId, Status = "pending-dcv" }); + + var plugin = new CERTInextCAPlugin(mock.Object, config); + await plugin.Enroll( + csr: MockCertificateData.FakeCsrPem, + subject: subject, + san: san, + productInfo: productInfo, + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + captured.Should().NotBeNull("the SSL enrollment must reach PlaceOrderV2Async"); + return (JsonSerializer.Serialize(captured, ClientEquivalentJsonOptions()), capturedSlug, capturedCode); + } + + [Fact] + public async Task SslOvUccOrder_AllOptionalConfigSet_WireBodyMatchesGolden() + { + var config = new CERTInextConfig + { + UseV2Api = true, + V2InlineCsr = false, // body without csr; the inline body has its own golden test + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + RequestorIsdCode = "1", + RequestorMobileNumber = "5551234567", + RequestorDesignation = "PKI Admin", + SignerIp = "1.2.3.4", + SignerPlace = "New York", + OrganizationNumber = "ORG-001", + GroupNumber = "GRP-9", + EmailNotifications = "1", + SubscriptionAutoRenew = "1", + SubscriptionRenewCriteriaDays = "15", + AutoSecureWww = "1", + TechnicalContactName = "Tech Person", + TechnicalContactEmail = "tech@example.com", + TechnicalContactIsdCode = "44", + TechnicalContactMobileNumber = "7700900000", + PickupRetries = 0 + }; + var productInfo = new EnrollmentProductInfo + { + ProductID = Constants.Products.OvSslUcc, + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = "848", + ["ProductFamily"] = "ssl", + ["ProductVariant"] = "ov", + ["DomainName"] = "example.com", + ["ValidityYears"] = "2" + } + }; + + var (json, slug, code) = await CaptureSslBodyAsync( + config, productInfo, "848", "18", + new Dictionary { ["dnsname"] = new[] { "example.com", "san1.example.com", "san2.example.com" } }, + "CN=example.com"); + + slug.Should().Be(Constants.ApiV2.FamilySsl); + code.Should().Be("848"); + json.Should().Be( + "{\"productVariant\":\"ov\",\"emailNotifications\":\"all\"," + + "\"requestor\":{\"name\":\"Test User\",\"email\":\"test@example.com\",\"phone\":\"\\u002B15551234567\",\"designation\":\"PKI Admin\"}," + + "\"organization\":{\"organizationNumber\":\"ORG-001\",\"preVetted\":true}," + + "\"certificate\":{\"domain\":\"example.com\",\"autoSecureWww\":true,\"additionalDomains\":[\"san1.example.com\",\"san2.example.com\"]}," + + "\"subscription\":{\"validityYears\":2,\"autoRenew\":true,\"renewBeforeDays\":15}," + + "\"agreement\":{\"signerName\":\"Test User\",\"signerPlace\":\"New York\",\"accepted\":true}," + + "\"technicalPointOfContact\":{\"name\":\"Tech Person\",\"email\":\"tech@example.com\",\"phone\":\"\\u002B447700900000\",\"designation\":\"Technical Contact\"}," + + "\"remarks\":\"Issued via Keyfactor Command AnyCA REST Gateway.\",\"groupNumber\":\"GRP-9\"}"); + } + + [Fact] + public async Task SslDvOrder_DefaultConfig_WireBodyMatchesGolden() + { + var config = new CERTInextConfig + { + UseV2Api = true, + V2InlineCsr = false, // body without csr; the inline body has its own golden test + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + // SignerPlace is required for V2 SSL orders (spec: agreement.signerPlace + // "Conditional - required if `agreement` sent"), so the "default config" fixture sets it + // and the expected agreement block below carries signerPlace. + SignerPlace = "Austin", + PickupRetries = 0 + }; + // No ProductFamily / ProductVariant / DomainName: exercises the ssl + dv defaults and + // the CN-derived domain. + var productInfo = new EnrollmentProductInfo + { + ProductID = Constants.Products.DvSsl, + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = "842" + } + }; + + var (json, slug, code) = await CaptureSslBodyAsync( + config, productInfo, "842", "13", + new Dictionary { ["dnsname"] = new[] { "example.com" } }, + "CN=example.com"); + + slug.Should().Be(Constants.ApiV2.FamilySsl); + code.Should().Be("842"); + json.Should().Be( + "{\"productVariant\":\"dv\",\"emailNotifications\":\"consent-only\"," + + "\"requestor\":{\"name\":\"Test User\",\"email\":\"test@example.com\",\"phone\":\"\"}," + + "\"certificate\":{\"domain\":\"example.com\",\"autoSecureWww\":false}," + + "\"subscription\":{\"validityYears\":1,\"autoRenew\":false,\"renewBeforeDays\":30}," + + "\"agreement\":{\"signerName\":\"Test User\",\"signerPlace\":\"Austin\",\"accepted\":true}," + + "\"technicalPointOfContact\":{\"name\":\"Test User\",\"email\":\"test@example.com\",\"phone\":\"\",\"designation\":\"Technical Contact\"}," + + "\"remarks\":\"Issued via Keyfactor Command AnyCA REST Gateway.\"}"); + } + + [Fact] + public async Task SslDvOrder_V2InlineCsrOn_WireBodyCarriesCsrBetweenContactAndRemarks() + { + var config = new CERTInextConfig + { + UseV2Api = true, + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + SignerPlace = "Austin", + PickupRetries = 0, + V2InlineCsr = true + }; + var productInfo = new EnrollmentProductInfo + { + ProductID = Constants.Products.DvSsl, + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = "842" + } + }; + + var (json, slug, code) = await CaptureSslBodyAsync( + config, productInfo, "842", "13", + new Dictionary { ["dnsname"] = new[] { "example.com" } }, + "CN=example.com"); + + slug.Should().Be(Constants.ApiV2.FamilySsl); + code.Should().Be("842"); + // Same body as the default golden above, plus the CSR exactly as Enroll received it (PEM). + json.Should().Be( + "{\"productVariant\":\"dv\",\"emailNotifications\":\"consent-only\"," + + "\"requestor\":{\"name\":\"Test User\",\"email\":\"test@example.com\",\"phone\":\"\"}," + + "\"certificate\":{\"domain\":\"example.com\",\"autoSecureWww\":false}," + + "\"subscription\":{\"validityYears\":1,\"autoRenew\":false,\"renewBeforeDays\":30}," + + "\"agreement\":{\"signerName\":\"Test User\",\"signerPlace\":\"Austin\",\"accepted\":true}," + + "\"technicalPointOfContact\":{\"name\":\"Test User\",\"email\":\"test@example.com\",\"phone\":\"\",\"designation\":\"Technical Contact\"}," + + "\"csr\":" + System.Text.Json.JsonSerializer.Serialize(MockCertificateData.FakeCsrPem) + "," + + "\"remarks\":\"Issued via Keyfactor Command AnyCA REST Gateway.\"}"); + } + } +} diff --git a/CERTInext.Tests/V2SubscriptionEnrollmentTests.cs b/CERTInext.Tests/V2SubscriptionEnrollmentTests.cs new file mode 100644 index 0000000..982e6e6 --- /dev/null +++ b/CERTInext.Tests/V2SubscriptionEnrollmentTests.cs @@ -0,0 +1,323 @@ +// Copyright 2026 Keyfactor +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; +using System.Collections.Generic; +using System.Text.Json; +using System.Text.Json.Serialization; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Moq; +using Org.BouncyCastle.Asn1.X509; +using Org.BouncyCastle.Crypto; +using Org.BouncyCastle.Crypto.Generators; +using Org.BouncyCastle.Pkcs; +using Org.BouncyCastle.Security; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Tests that the V2 order body's subscription block is sourced from the connector's + /// SubscriptionAutoRenew/SubscriptionRenewCriteriaDays config rather than + /// hardcoded autoRenew=false / renewBeforeDays=30. These tests exercise + /// EnrollV2Async end-to-end (through ) against a + /// Strict mock, plus direct DTO serialization checks for + /// . + /// + public class V2SubscriptionEnrollmentTests + { + private static Mock NewMock() => + new Mock(MockBehavior.Strict); + + // Defaults here intentionally match CERTInextConfig's own property defaults ("0"/"30") — + // NOT a `?? "30"`-style fallback applied to the parameter, which would silently coerce an + // explicitly-passed null (a real Theory case below) back to "30" and defeat that test case. + private static CERTInextCAPlugin BuildV2Plugin( + ICERTInextClient client, + string subscriptionAutoRenew = "0", + string subscriptionRenewCriteriaDays = "30") => + new CERTInextCAPlugin(client, new CERTInextConfig + { + UseV2Api = true, + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + SignerIp = "1.2.3.4", + SignerPlace = "New York", + PickupRetries = 0, + SubscriptionAutoRenew = subscriptionAutoRenew, + SubscriptionRenewCriteriaDays = subscriptionRenewCriteriaDays + }); + + private static EnrollmentProductInfo MakeV2ProductInfo(string productCode, string productVariant) => + new EnrollmentProductInfo + { + ProductID = "DV SSL", + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = productCode, + ["ProductFamily"] = "ssl", + ["ProductVariant"] = productVariant, + ["DomainName"] = "example.com" + } + }; + + private static void StubCatalog(Mock mock, string productCode, string productTypeId) => + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = productCode, ProductTypeId = productTypeId, Active = true } + }); + + private static void StubHappyOrderPlacement(Mock mock, string orderId) + { + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), orderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), orderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = orderId, Status = "pending-dcv" }); + } + + private static string GenerateCsrPem(string cn) + { + var keyGen = new RsaKeyPairGenerator(); + keyGen.Init(new KeyGenerationParameters(new SecureRandom(), 2048)); + AsymmetricCipherKeyPair kp = keyGen.GenerateKeyPair(); + + var csr = new Pkcs10CertificationRequest( + "SHA256withRSA", new X509Name($"CN={cn}"), kp.Public, null, kp.Private); + + return "-----BEGIN CERTIFICATE REQUEST-----\n" + + Convert.ToBase64String(csr.GetEncoded(), Base64FormattingOptions.InsertLineBreaks) + + "\n-----END CERTIFICATE REQUEST-----"; + } + + private static async Task<(EnrollmentResult Result, V2CreateSslOrderRequest Captured)> RunEnrollAsync( + Mock mock, CERTInextCAPlugin plugin, string orderId = "ord_sub_001") + { + V2CreateSslOrderRequest captured = null; + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .Callback((_, __, req, ___) => captured = req) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = orderId, Status = "pending-dcv" }); + + var result = await plugin.Enroll( + csr: GenerateCsrPem("example.com"), + subject: "CN=example.com", + san: null, + productInfo: MakeV2ProductInfo("842", "dv"), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + return (result, captured); + } + + // --------------------------------------------------------------------------- + // EnrollV2Async wiring — SubscriptionAutoRenew -> Subscription.AutoRenew + // --------------------------------------------------------------------------- + + [Fact] + public async Task Enroll_V2_SubscriptionAutoRenew_1_SetsAutoRenewTrue() + { + var mock = NewMock(); + StubCatalog(mock, "842", "13"); // DV SSL (non-UCC) + StubHappyOrderPlacement(mock, "ord_sub_001"); + + var plugin = BuildV2Plugin(mock.Object, subscriptionAutoRenew: "1"); + + var (result, captured) = await RunEnrollAsync(mock, plugin); + + result.CARequestID.Should().Be("ord_sub_001"); + captured.Should().NotBeNull(); + captured!.Subscription.Should().NotBeNull(); + captured.Subscription.AutoRenew.Should().BeTrue( + "SubscriptionAutoRenew=\"1\" must set Subscription.AutoRenew=true, the same bare " + + "\"1\"-means-true comparison AutoSecureWww already uses"); + } + + [Theory] + [InlineData("0")] + [InlineData("")] + [InlineData("yes")] + [InlineData("true")] + public async Task Enroll_V2_SubscriptionAutoRenew_NonOneValues_SetsAutoRenewFalse(string configValue) + { + var mock = NewMock(); + StubCatalog(mock, "842", "13"); + StubHappyOrderPlacement(mock, "ord_sub_002"); + + var plugin = BuildV2Plugin(mock.Object, subscriptionAutoRenew: configValue); + + var (result, captured) = await RunEnrollAsync(mock, plugin, "ord_sub_002"); + + result.CARequestID.Should().Be("ord_sub_002"); + captured!.Subscription.AutoRenew.Should().BeFalse( + $"only the literal value \"1\" should set AutoRenew=true — '{configValue}' must not"); + } + + // --------------------------------------------------------------------------- + // EnrollV2Async wiring — SubscriptionRenewCriteriaDays -> Subscription.RenewBeforeDays + // --------------------------------------------------------------------------- + + [Theory] + [InlineData(null)] + [InlineData("")] + [InlineData(" ")] + public async Task Enroll_V2_SubscriptionRenewCriteriaDays_Blank_OmitsRenewBeforeDays(string configValue) + { + var mock = NewMock(); + StubCatalog(mock, "842", "13"); + StubHappyOrderPlacement(mock, "ord_sub_003"); + + var plugin = BuildV2Plugin(mock.Object, subscriptionRenewCriteriaDays: configValue); + + var (result, captured) = await RunEnrollAsync(mock, plugin, "ord_sub_003"); + + result.CARequestID.Should().Be("ord_sub_003"); + captured!.Subscription.RenewBeforeDays.Should().BeNull( + "a blank/unset SubscriptionRenewCriteriaDays must leave RenewBeforeDays null so the " + + "field is omitted and the CA's documented default of 30 applies"); + } + + [Fact] + public async Task Enroll_V2_SubscriptionRenewCriteriaDays_ValidValue_SetsRenewBeforeDays() + { + var mock = NewMock(); + StubCatalog(mock, "842", "13"); + StubHappyOrderPlacement(mock, "ord_sub_004"); + + var plugin = BuildV2Plugin(mock.Object, subscriptionRenewCriteriaDays: "45"); + + var (result, captured) = await RunEnrollAsync(mock, plugin, "ord_sub_004"); + + result.CARequestID.Should().Be("ord_sub_004"); + captured!.Subscription.RenewBeforeDays.Should().Be(45, + "a configured SubscriptionRenewCriteriaDays must be forwarded to RenewBeforeDays " + + "as-is, independent of the AutoRenew value"); + } + + [Fact] + public async Task Enroll_V2_SubscriptionRenewCriteriaDays_ZeroIsValid_SetsRenewBeforeDaysZero() + { + var mock = NewMock(); + StubCatalog(mock, "842", "13"); + StubHappyOrderPlacement(mock, "ord_sub_005"); + + var plugin = BuildV2Plugin(mock.Object, subscriptionRenewCriteriaDays: "0"); + + var (result, captured) = await RunEnrollAsync(mock, plugin, "ord_sub_005"); + + result.CARequestID.Should().Be("ord_sub_005"); + captured!.Subscription.RenewBeforeDays.Should().Be(0, + "zero is a valid non-negative integer and must be sent as-is, not treated as blank"); + } + + // --------------------------------------------------------------------------- + // EnrollV2Async — bad SubscriptionRenewCriteriaDays fails fast, before any CA call + // --------------------------------------------------------------------------- + + [Theory] + [InlineData("abc")] + [InlineData("-1")] + public async Task Enroll_V2_SubscriptionRenewCriteriaDays_Invalid_FailsEnrollment_NoHttpCallMade(string configValue) + { + // Strict mock with NO setups at all: if EnrollV2Async made any client call before + // failing validation, Moq would throw a MockException for the unstubbed invocation + // and this test would fail — that, plus the explicit Verify(Times.Never) calls below, + // together confirm zero HTTP requests are sent for an invalid config value. + var mock = NewMock(); + + var plugin = BuildV2Plugin(mock.Object, subscriptionRenewCriteriaDays: configValue); + + var result = await plugin.Enroll( + csr: GenerateCsrPem("example.com"), + subject: "CN=example.com", + san: null, + productInfo: MakeV2ProductInfo("842", "dv"), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.Status.Should().Be((int)EndEntityStatus.FAILED); + result.StatusMessage.Should().Contain("SubscriptionRenewCriteriaDays", + "the failure message must name the offending config field"); + + mock.Verify(c => c.GetProductDetailsV2Async(It.IsAny()), Times.Never); + mock.Verify(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny()), Times.Never); + } + + // --------------------------------------------------------------------------- + // DTO serialization — renewBeforeDays key present/absent on the wire + // + // Unlike GroupNumber/PreVettingToken (which carry their own per-property + // [JsonIgnore(Condition = WhenWritingNull)]), RenewBeforeDays relies solely on the + // client's global serializer options (CERTInextClient.GetJsonOptions, + // DefaultIgnoreCondition = WhenWritingNull) to omit it when null — by design. + // GetJsonOptions() is private, so these tests build an equivalent + // JsonSerializerOptions inline to verify that global-option omission actually works for + // this property, rather than relying on plain JsonSerializer.Serialize(req) (whose default + // options do NOT ignore nulls and would show "renewBeforeDays":null instead of omitting it). + // --------------------------------------------------------------------------- + + private static JsonSerializerOptions ClientEquivalentJsonOptions() => new JsonSerializerOptions + { + PropertyNameCaseInsensitive = true, + DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull + }; + + [Fact] + public void V2SubscriptionParams_Serialization_OmitsRenewBeforeDays_WhenNull() + { + var subscription = new V2SubscriptionParams + { + ValidityYears = 1, + AutoRenew = false, + RenewBeforeDays = null + }; + + string json = JsonSerializer.Serialize(subscription, ClientEquivalentJsonOptions()); + + json.Should().NotContain("renewBeforeDays", + "the renewBeforeDays key itself must be absent when unset, not present-but-null, " + + "under the client's actual serializer options"); + } + + [Fact] + public void V2SubscriptionParams_Serialization_IncludesRenewBeforeDays_WhenSet() + { + var subscription = new V2SubscriptionParams + { + ValidityYears = 1, + AutoRenew = true, + RenewBeforeDays = 45 + }; + + string json = JsonSerializer.Serialize(subscription, ClientEquivalentJsonOptions()); + + json.Should().Contain("\"renewBeforeDays\":45"); + } + } +} diff --git a/CERTInext.Tests/V2TechnicalContactEnrollmentTests.cs b/CERTInext.Tests/V2TechnicalContactEnrollmentTests.cs new file mode 100644 index 0000000..0ca9473 --- /dev/null +++ b/CERTInext.Tests/V2TechnicalContactEnrollmentTests.cs @@ -0,0 +1,305 @@ +// Copyright 2026 Keyfactor +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; +using System.Collections.Generic; +using System.Text.Json; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Moq; +using Org.BouncyCastle.Asn1.X509; +using Org.BouncyCastle.Crypto; +using Org.BouncyCastle.Crypto.Generators; +using Org.BouncyCastle.Pkcs; +using Org.BouncyCastle.Security; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Tests that the V2 SSL order body carries a technicalPointOfContact block, as V1's + /// equivalent (TechnicalPointOfContact) does, populated from the connector's + /// TechnicalContact* config fields (falling back to the corresponding + /// Requestor* value when blank). These tests exercise EnrollV2Async end-to-end + /// (through ) against a Strict + /// mock, plus direct DTO serialization checks for the new + /// property and the new + /// ISD-code + mobile-number composition helper. + /// + public class V2TechnicalContactEnrollmentTests + { + private static Mock NewMock() => + new Mock(MockBehavior.Strict); + + private static CERTInextConfig BaseConfig() => new CERTInextConfig + { + UseV2Api = true, + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + RequestorIsdCode = "1", + RequestorMobileNumber = "5550000000", + SignerIp = "1.2.3.4", + SignerPlace = "New York", + PickupRetries = 0 + }; + + private static CERTInextCAPlugin BuildV2Plugin(ICERTInextClient client, CERTInextConfig config) => + new CERTInextCAPlugin(client, config); + + private static EnrollmentProductInfo MakeV2ProductInfo(string productCode, string productVariant) => + new EnrollmentProductInfo + { + ProductID = "DV SSL", + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = productCode, + ["ProductFamily"] = "ssl", + ["ProductVariant"] = productVariant, + ["DomainName"] = "example.com" + } + }; + + private static void StubCatalog(Mock mock, string productCode, string productTypeId) => + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = productCode, ProductTypeId = productTypeId, Active = true } + }); + + private static void StubHappyOrderPlacement(Mock mock, string orderId) + { + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), orderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), orderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = orderId, Status = "pending-dcv" }); + } + + private static string GenerateCsrPem(string cn) + { + var keyGen = new RsaKeyPairGenerator(); + keyGen.Init(new KeyGenerationParameters(new SecureRandom(), 2048)); + AsymmetricCipherKeyPair kp = keyGen.GenerateKeyPair(); + + var csr = new Pkcs10CertificationRequest( + "SHA256withRSA", new X509Name($"CN={cn}"), kp.Public, null, kp.Private); + + return "-----BEGIN CERTIFICATE REQUEST-----\n" + + Convert.ToBase64String(csr.GetEncoded(), Base64FormattingOptions.InsertLineBreaks) + + "\n-----END CERTIFICATE REQUEST-----"; + } + + private static async Task RunEnrollAndCaptureOrderAsync( + CERTInextConfig config, string orderId = "ord_tpc_001") + { + var mock = NewMock(); + StubCatalog(mock, "842", "13"); // DV SSL (non-UCC) + StubHappyOrderPlacement(mock, orderId); + + V2CreateSslOrderRequest captured = null; + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .Callback((_, __, req, ___) => captured = req) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = orderId, Status = "pending-dcv" }); + + var plugin = BuildV2Plugin(mock.Object, config); + + var result = await plugin.Enroll( + csr: GenerateCsrPem("example.com"), + subject: "CN=example.com", + san: null, + productInfo: MakeV2ProductInfo("842", "dv"), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.CARequestID.Should().Be(orderId); + captured.Should().NotBeNull(); + return captured; + } + + // --------------------------------------------------------------------------- + // EnrollV2Async wiring — technicalPointOfContact populated on the order body + // --------------------------------------------------------------------------- + + [Fact] + public async Task Enroll_V2_TechnicalContactConfigured_PopulatesTechnicalPointOfContactOnOrderBody() + { + var config = BaseConfig(); + config.TechnicalContactName = "TPoC Name"; + config.TechnicalContactEmail = "tpoc@example.com"; + config.TechnicalContactIsdCode = "44"; + config.TechnicalContactMobileNumber = "7911123456"; + + var captured = await RunEnrollAndCaptureOrderAsync(config); + + captured.TechnicalPointOfContact.Should().NotBeNull( + "the technicalPointOfContact block must always be populated, even though every " + + "subfield is spec-Optional"); + captured.TechnicalPointOfContact.Name.Should().Be("TPoC Name"); + captured.TechnicalPointOfContact.Email.Should().Be("tpoc@example.com"); + captured.TechnicalPointOfContact.Phone.Should().Be("+447911123456", + "the configured TechnicalContactIsdCode and TechnicalContactMobileNumber must be " + + "combined into a single E.164-style phone value for the V2 shape"); + captured.TechnicalPointOfContact.Designation.Should().Be("Technical Contact"); + } + + [Fact] + public async Task Enroll_V2_TechnicalContactBlank_FallsBackToRequestorValues() + { + var config = BaseConfig(); + // TechnicalContact* fields left at their default (blank) values. + + var captured = await RunEnrollAndCaptureOrderAsync(config, orderId: "ord_tpc_002"); + + captured.TechnicalPointOfContact.Should().NotBeNull( + "V1's fallback-to-Requestor* semantics mean the block is populated, never omitted, " + + "even when no TechnicalContact* field is configured"); + captured.TechnicalPointOfContact.Name.Should().Be(config.RequestorName, + "a blank TechnicalContactName must fall back to RequestorName, mirroring V1"); + captured.TechnicalPointOfContact.Email.Should().Be(config.RequestorEmail, + "a blank TechnicalContactEmail must fall back to RequestorEmail, mirroring V1"); + captured.TechnicalPointOfContact.Phone.Should().Be("+15550000000", + "a blank TechnicalContactIsdCode/TechnicalContactMobileNumber must fall back to " + + "RequestorIsdCode/RequestorMobileNumber, mirroring V1, composed into one phone value"); + captured.TechnicalPointOfContact.Designation.Should().Be("Technical Contact"); + } + + [Fact] + public async Task Enroll_V2_TechnicalContactPartiallyConfigured_FallsBackFieldByField() + { + var config = BaseConfig(); + // Only name is overridden; email/isd/mobile stay blank and must each fall back + // independently to their own Requestor* counterpart (matching V1's per-field, not + // all-or-nothing, fallback semantics). + config.TechnicalContactName = "Override Name Only"; + + var captured = await RunEnrollAndCaptureOrderAsync(config, orderId: "ord_tpc_003"); + + captured.TechnicalPointOfContact.Name.Should().Be("Override Name Only"); + captured.TechnicalPointOfContact.Email.Should().Be(config.RequestorEmail); + captured.TechnicalPointOfContact.Phone.Should().Be("+15550000000"); + } + + // --------------------------------------------------------------------------- + // Requestor.Phone — ISD-code + mobile-number composition. + // Requestor.Phone combines RequestorIsdCode with RequestorMobileNumber rather than sending + // the raw mobile number only, the same way TechnicalPointOfContact.Phone (above) uses + // ComposeV2Phone. + // --------------------------------------------------------------------------- + + [Fact] + public async Task Enroll_V2_RequestorPhone_ComposesIsdAndMobile() + { + var config = BaseConfig(); + // BaseConfig: RequestorIsdCode="1", RequestorMobileNumber="5550000000". + + var captured = await RunEnrollAndCaptureOrderAsync(config, orderId: "ord_req_phone_001"); + + captured.Requestor.Should().NotBeNull(); + captured.Requestor.Phone.Should().Be("+15550000000", + "Requestor.Phone must combine RequestorIsdCode and RequestorMobileNumber the same " + + "way TechnicalPointOfContact.Phone already does, via ComposeV2Phone"); + } + + [Fact] + public async Task Enroll_V2_RequestorPhone_UsesConfiguredIsdCode_NotDefault() + { + var config = BaseConfig(); + config.RequestorIsdCode = "44"; + config.RequestorMobileNumber = "7911123456"; + + var captured = await RunEnrollAndCaptureOrderAsync(config, orderId: "ord_req_phone_002"); + + captured.Requestor.Phone.Should().Be("+447911123456", + "a non-default RequestorIsdCode must be reflected in Requestor.Phone, not just " + + "the TechnicalPointOfContact fallback path"); + } + + [Fact] + public async Task Enroll_V2_RequestorPhone_BlankIsdCode_FallsBackToDefault() + { + var config = BaseConfig(); + config.RequestorIsdCode = ""; + config.RequestorMobileNumber = "5550000000"; + + var captured = await RunEnrollAndCaptureOrderAsync(config, orderId: "ord_req_phone_003"); + + captured.Requestor.Phone.Should().Be("+15550000000", + "a blank RequestorIsdCode must fall back to the same default ('1') used " + + "elsewhere in EnrollV2Async, not an unprefixed raw mobile number"); + } + + // --------------------------------------------------------------------------- + // DTO serialization — technicalPointOfContact key/shape on the wire + // --------------------------------------------------------------------------- + + [Fact] + public void V2CreateSslOrderRequest_Serialization_IncludesTechnicalPointOfContact_WhenSet() + { + var req = new V2CreateSslOrderRequest + { + ProductVariant = "dv", + Requestor = new V2Requestor { Name = "Jane Doe", Email = "jane@example.com" }, + Certificate = new V2CertificateParams { Domain = "example.com" }, + TechnicalPointOfContact = new V2TechnicalPointOfContact + { + Name = "TPoC Name", + Email = "tpoc@example.com", + Phone = "+447911123456", + Designation = "Technical Contact" + } + }; + + string json = JsonSerializer.Serialize(req); + + // System.Text.Json escapes '+' as + by default, so the phone value is checked + // by parsing the JSON rather than substring-matching the raw serialized text (which + // would never contain a literal '+'). + using var doc = JsonDocument.Parse(json); + var tpc = doc.RootElement.GetProperty("technicalPointOfContact"); + tpc.GetProperty("name").GetString().Should().Be("TPoC Name"); + tpc.GetProperty("email").GetString().Should().Be("tpoc@example.com"); + tpc.GetProperty("phone").GetString().Should().Be("+447911123456"); + tpc.GetProperty("designation").GetString().Should().Be("Technical Contact"); + } + + // --------------------------------------------------------------------------- + // ComposeV2Phone — ISD-code + mobile-number composition helper + // --------------------------------------------------------------------------- + + [Theory] + [InlineData("1", "5550000000", "+15550000000")] + [InlineData("44", "7911123456", "+447911123456")] + [InlineData("+1", "5550000000", "+15550000000")] + [InlineData("", "5550000000", "5550000000")] + [InlineData(null, "5550000000", "5550000000")] + [InlineData("1", "", "")] + [InlineData("1", null, "")] + [InlineData(null, null, "")] + public void ComposeV2Phone_ComposesExpectedValue(string isdCode, string mobileNumber, string expected) + { + CERTInextCAPlugin.ComposeV2Phone(isdCode, mobileNumber).Should().Be(expected); + } + } +} diff --git a/CERTInext.Tests/V2UccEnrollmentTests.cs b/CERTInext.Tests/V2UccEnrollmentTests.cs new file mode 100644 index 0000000..6a7eaeb --- /dev/null +++ b/CERTInext.Tests/V2UccEnrollmentTests.cs @@ -0,0 +1,446 @@ +// Copyright 2026 Keyfactor +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; +using System.Collections.Generic; +using System.Linq; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Moq; +using Org.BouncyCastle.Asn1.Pkcs; +using Org.BouncyCastle.Asn1.X509; +using Org.BouncyCastle.Crypto; +using Org.BouncyCastle.Crypto.Generators; +using Org.BouncyCastle.Pkcs; +using Org.BouncyCastle.Security; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Tests for V2 UCC (multi-SAN) order-create + /// support. (V2 path) is driven end-to-end against a + /// Strict mock so the assertions exercise + /// EnrollV2Async's actual UCC-detection and additionalDomains-population logic, + /// not a re-implementation of it. + /// + public class V2UccEnrollmentTests + { + private static Mock NewMock() => + new Mock(MockBehavior.Strict); + + private static CERTInextCAPlugin BuildV2Plugin(ICERTInextClient client) => + new CERTInextCAPlugin(client, new CERTInextConfig + { + UseV2Api = true, + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + SignerIp = "1.2.3.4", + SignerPlace = "New York", + PickupRetries = 0 + }); + + private static EnrollmentProductInfo MakeV2ProductInfo(string productCode) => + new EnrollmentProductInfo + { + ProductID = "DV SSL UCC", + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = productCode, + ["ProductFamily"] = "ssl", + ["ProductVariant"] = "dv", + ["DomainName"] = "example.com" + } + }; + + private static void StubCatalog(Mock mock, string productCode, string productTypeId) => + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = productCode, ProductTypeId = productTypeId, Active = true } + }); + + private static void StubHappyOrderPlacement(Mock mock, string orderId = "ord_ucc_001") + { + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = orderId, Status = "pending-dcv" }); + + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), orderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), orderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = orderId, Status = "pending-dcv" }); + } + + // --------------------------------------------------------------------------- + // CSR generation (BouncyCastle — project crypto policy). Mirrors SanSubmissionTests' + // helper of the same shape; duplicated locally per this repo's existing convention of + // small per-test-file helpers (see NewMock()/BuildV2Plugin() duplicated across the V2 + // test files) rather than sharing test infrastructure across files. + // --------------------------------------------------------------------------- + + private static string GenerateCsrPem(string cn, params string[] dnsSans) + { + var keyGen = new RsaKeyPairGenerator(); + keyGen.Init(new KeyGenerationParameters(new SecureRandom(), 2048)); + AsymmetricCipherKeyPair kp = keyGen.GenerateKeyPair(); + + Org.BouncyCastle.Asn1.Asn1Set attributes = null; + if (dnsSans != null && dnsSans.Length > 0) + { + var names = dnsSans.Select(d => new GeneralName(GeneralName.DnsName, d)).ToArray(); + var extGen = new X509ExtensionsGenerator(); + extGen.AddExtension(X509Extensions.SubjectAlternativeName, critical: false, + extValue: new GeneralNames(names)); + + attributes = new Org.BouncyCastle.Asn1.DerSet(new AttributePkcs( + PkcsObjectIdentifiers.Pkcs9AtExtensionRequest, + new Org.BouncyCastle.Asn1.DerSet(extGen.Generate()))); + } + + var csr = new Pkcs10CertificationRequest( + "SHA256withRSA", new X509Name($"CN={cn}"), kp.Public, attributes, kp.Private); + + return "-----BEGIN CERTIFICATE REQUEST-----\n" + + Convert.ToBase64String(csr.GetEncoded(), Base64FormattingOptions.InsertLineBreaks) + + "\n-----END CERTIFICATE REQUEST-----"; + } + + // --------------------------------------------------------------------------- + // UCC detection + additionalDomains population + // --------------------------------------------------------------------------- + + [Fact] + public async Task Enroll_V2_UccProduct_PopulatesAdditionalDomainsFromGatewaySanDictionary() + { + var mock = NewMock(); + StubCatalog(mock, "844", "15"); // DV SSL Certificate UCC + StubHappyOrderPlacement(mock); + + V2CreateSslOrderRequest captured = null; + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .Callback((_, __, req, ___) => captured = req) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = "ord_ucc_001", Status = "pending-dcv" }); + + var plugin = BuildV2Plugin(mock.Object); + + var result = await plugin.Enroll( + csr: GenerateCsrPem("example.com"), // CSR carries ONLY the primary domain — spec requirement for UCC + subject: "CN=example.com", + san: new Dictionary + { + ["dns"] = new[] { "example.com", "san1.example.com", "san2.example.com" } + }, + productInfo: MakeV2ProductInfo("844"), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.CARequestID.Should().Be("ord_ucc_001"); + captured.Should().NotBeNull(); + V2CreateSslOrderRequest req = captured!; + req.Certificate.Domain.Should().Be("example.com"); + req.Certificate.AdditionalDomains.Should().BeEquivalentTo( + new[] { "san1.example.com", "san2.example.com" }, + "the primary domain must not be repeated in additionalDomains, and the SAN dictionary " + + "(not the CSR) is the source for a UCC order's additional domains"); + } + + [Fact] + public async Task Enroll_V2_NonUccProduct_SanDictionaryCarriesExtras_StillFailsFastWithNoPlaceOrderCall() + { + // A CSR-only guard (looking at the CSR alone) would miss the case where the + // CSR carries only the primary domain but the SAN dictionary's extra + // domain silently vanishes — a non-UCC order never sends additionalDomains at all, so + // there is nowhere for it to go. The guard must consider the SAN dictionary too + // and reject, the same way it already rejects CSR-borne extras + // (Enroll_V2_NonUccProduct_CsrCarriesExtraSans_StillFailsFastWithNoPlaceOrderCall). + var mock = NewMock(); + StubCatalog(mock, "842", "13"); // DV SSL (non-UCC) + + var plugin = BuildV2Plugin(mock.Object); + + var result = await plugin.Enroll( + csr: GenerateCsrPem("example.com"), + subject: "CN=example.com", + san: new Dictionary + { + ["dns"] = new[] { "example.com", "san1.example.com" } + }, + productInfo: MakeV2ProductInfo("842"), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.Status.Should().Be((int)EndEntityStatus.FAILED); + result.StatusMessage.Should().Contain("1 SAN(s) beyond"); + result.StatusMessage.Should().Contain("single domain"); + + mock.Verify(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny()), Times.Never, + "a rejected non-UCC request must never reach order placement, whether the extra " + + "SAN came from the CSR or the SAN dictionary"); + } + + [Fact] + public async Task Enroll_V2_NonUccProduct_SanDictionaryHasOnlyPrimary_ButCsrCarriesExtraSan_StillFailsFastWithNoPlaceOrderCall() + { + // A non-null SAN dictionary that carries only the primary domain must not make the + // guard defer to the dictionary and skip the CSR. SubmitCsrV2Async sends the CSR to + // CERTInext verbatim regardless of what the SAN dictionary contains, so a + // CSR-embedded extra domain still reaches the CA even when the dictionary is + // single-domain — the guard must reject this exactly like the CSR-only case + // (Enroll_V2_NonUccProduct_CsrCarriesExtraSans_StillFailsFastWithNoPlaceOrderCall). + var mock = NewMock(); + StubCatalog(mock, "842", "13"); // DV SSL (non-UCC) + + var plugin = BuildV2Plugin(mock.Object); + + var result = await plugin.Enroll( + csr: GenerateCsrPem("example.com", "example.com", "other.example.com"), + subject: "CN=example.com", + san: new Dictionary { ["dns"] = new[] { "example.com" } }, + productInfo: MakeV2ProductInfo("842"), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.Status.Should().Be((int)EndEntityStatus.FAILED); + result.StatusMessage.Should().Contain("1 SAN(s) beyond"); + result.StatusMessage.Should().Contain("single domain"); + + mock.Verify(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny()), Times.Never, + "a non-null SAN dictionary carrying only the primary domain must not make the " + + "guard defer to it and miss a CSR-embedded extra SAN"); + } + + [Fact] + public async Task Enroll_V2_NonUccProduct_SanDictionaryHasOnlyPrimaryAndWwwVariant_Allowed() + { + // The guard's existing primary-domain / www. allowance must still apply when + // those names arrive via the SAN dictionary rather than the CSR. + var mock = NewMock(); + StubCatalog(mock, "842", "13"); // DV SSL (non-UCC) + + V2CreateSslOrderRequest captured = null; + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .Callback((_, __, req, ___) => captured = req) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = "ord_nonucc_002", Status = "pending-dcv" }); + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), "ord_nonucc_002", It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), "ord_nonucc_002", It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = "ord_nonucc_002", Status = "pending-dcv" }); + + var plugin = BuildV2Plugin(mock.Object); + + var result = await plugin.Enroll( + csr: GenerateCsrPem("example.com"), + subject: "CN=example.com", + san: new Dictionary + { + ["dns"] = new[] { "example.com", "www.example.com" } + }, + productInfo: MakeV2ProductInfo("842"), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.CARequestID.Should().Be("ord_nonucc_002"); + captured.Should().NotBeNull(); + captured!.Certificate.AdditionalDomains.Should().BeNull( + "non-UCC V2 products must keep the single-domain wire shape even when the " + + "dictionary only ever carried allowed names"); + } + + [Fact] + public async Task Enroll_V2_NonUccProduct_SanDictionaryHasOnlyNonDnsExtras_Allowed() + { + // dnsOnly semantics: a non-DNS SAN dictionary entry can never appear in + // additionalDomains and must not trip the reject guard either. + var mock = NewMock(); + StubCatalog(mock, "842", "13"); // DV SSL (non-UCC) + + V2CreateSslOrderRequest captured = null; + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .Callback((_, __, req, ___) => captured = req) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = "ord_nonucc_003", Status = "pending-dcv" }); + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), "ord_nonucc_003", It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), "ord_nonucc_003", It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = "ord_nonucc_003", Status = "pending-dcv" }); + + var plugin = BuildV2Plugin(mock.Object); + + var result = await plugin.Enroll( + csr: GenerateCsrPem("example.com"), + subject: "CN=example.com", + san: new Dictionary + { + ["dns"] = new[] { "example.com" }, + ["rfc822name"] = new[] { "admin@example.com" } + }, + productInfo: MakeV2ProductInfo("842"), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.CARequestID.Should().Be("ord_nonucc_003"); + captured.Should().NotBeNull(); + captured!.Certificate.AdditionalDomains.Should().BeNull( + "a non-DNS dictionary entry must not trip the non-UCC reject guard"); + } + + [Fact] + public async Task Enroll_V2_UccProduct_CsrCarriesExtraSans_OrderIsPlacedWithSansAsAdditionalDomains() + { + // The CSR-SAN-count guard must not run unconditionally before UCC + // detection: a real UCC CSR enrollment (the CSR itself carries the extra DNS + // SANs, as Command actually builds it for CSR-based enrollments) must not be + // rejected before any CA order is placed. UCC products must + // be exempt: the guard should not fire, and BuildSanList's own CSR fallback + // (triggered here via san: null) should carry those same CSR SANs into + // additionalDomains, exactly like the gateway-SAN-dictionary case already covered by + // Enroll_V2_UccProduct_PopulatesAdditionalDomainsFromGatewaySanDictionary above. + var mock = NewMock(); + StubCatalog(mock, "844", "15"); // DV SSL Certificate UCC + + V2CreateSslOrderRequest captured = null; + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .Callback((_, __, req, ___) => captured = req) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = "ord_ucc_002", Status = "pending-dcv" }); + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), "ord_ucc_002", It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), "ord_ucc_002", It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = "ord_ucc_002", Status = "pending-dcv" }); + + var plugin = BuildV2Plugin(mock.Object); + + var result = await plugin.Enroll( + csr: GenerateCsrPem("example.com", "example.com", "extra1.example.com", "extra2.example.com"), + subject: "CN=example.com", + san: null, // no gateway SAN dictionary — BuildSanList falls back to the CSR's own SANs + productInfo: MakeV2ProductInfo("844"), // UCC product code + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION, + "the order should proceed to CA placement rather than fail fast"); + result.CARequestID.Should().Be("ord_ucc_002"); + captured.Should().NotBeNull(); + V2CreateSslOrderRequest req = captured!; + req.Certificate.Domain.Should().Be("example.com"); + req.Certificate.AdditionalDomains.Should().BeEquivalentTo( + new[] { "extra1.example.com", "extra2.example.com" }, + "a UCC product's CSR-embedded extra SANs must flow into additionalDomains instead of " + + "tripping the single-domain guard"); + } + + [Fact] + public async Task Enroll_V2_NonUccProduct_CsrCarriesExtraSans_StillFailsFastWithNoPlaceOrderCall() + { + // Counterpart to the UCC case above: a non-UCC product with the same multi-SAN CSR + // must keep the fail-fast behavior — FAILED, no order placed — even though + // the guard now necessarily runs after the (live) catalog lookup that determines + // UCC-ness, rather than before it. + var mock = NewMock(); + StubCatalog(mock, "842", "13"); // DV SSL (non-UCC) + + var plugin = BuildV2Plugin(mock.Object); + + var result = await plugin.Enroll( + csr: GenerateCsrPem("example.com", "example.com", "extra1.example.com", "extra2.example.com"), + subject: "CN=example.com", + san: null, + productInfo: MakeV2ProductInfo("842"), // non-UCC product code + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.Status.Should().Be((int)EndEntityStatus.FAILED); + result.StatusMessage.Should().Contain("2 SAN(s) beyond"); + result.StatusMessage.Should().Contain("single domain"); + result.StatusMessage.Should().NotContain("The V2 API only supports single-domain certificates", + "the message must not claim V2 is single-domain-only in general — it's only true for non-UCC products"); + + mock.Verify(c => c.GetProductDetailsV2Async(It.IsAny()), Times.Once, + "UCC-ness can only be known after the catalog lookup, so the guard now runs after it"); + mock.Verify(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny()), Times.Never, + "a rejected non-UCC request must never reach order placement"); + } + + [Fact] + public async Task Enroll_V2_CatalogLookupFails_TreatedAsNonUcc_EnrollmentStillSucceeds() + { + var mock = NewMock(); + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ThrowsAsync(new Exception("simulated transient catalog failure")); + + V2CreateSslOrderRequest captured = null; + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .Callback((_, __, req, ___) => captured = req) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = "ord_fallback_001", Status = "pending-dcv" }); + + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), "ord_fallback_001", It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), "ord_fallback_001", It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = "ord_fallback_001", Status = "pending-dcv" }); + + var plugin = BuildV2Plugin(mock.Object); + + // A catalog-lookup failure fails UCC-ness safe to false, so a non-empty + // SAN dictionary extra here would trip the dictionary-aware non-UCC reject + // guard instead of exercising this test's actual intent. Single-domain SAN data keeps + // the test focused on the catalog-lookup fallback it's named for. + var result = await plugin.Enroll( + csr: GenerateCsrPem("example.com"), + subject: "CN=example.com", + san: new Dictionary { ["dns"] = new[] { "example.com" } }, + productInfo: MakeV2ProductInfo("844"), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.CARequestID.Should().Be("ord_fallback_001", + "a catalog lookup failure must not block enrollment"); + captured.Should().NotBeNull(); + V2CreateSslOrderRequest req = captured!; + req.Certificate.AdditionalDomains.Should().BeNull( + "on a catalog failure, UCC-ness must fail safe to false rather than guess"); + } + } +} diff --git a/CERTInext.Tests/V2UccNonDnsSanLoggingTests.cs b/CERTInext.Tests/V2UccNonDnsSanLoggingTests.cs new file mode 100644 index 0000000..d0db384 --- /dev/null +++ b/CERTInext.Tests/V2UccNonDnsSanLoggingTests.cs @@ -0,0 +1,313 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Concurrent; +using System.Collections.Generic; +using System.Linq; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.Logging; +using Keyfactor.PKI.Enums.EJBCA; +using Microsoft.Extensions.Logging; +using Moq; +using Org.BouncyCastle.Asn1.X509; +using Org.BouncyCastle.Crypto; +using Org.BouncyCastle.Crypto.Generators; +using Org.BouncyCastle.Pkcs; +using Org.BouncyCastle.Security; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Tests for non-DNS SAN logging on the V2 SSL UCC path: BuildSanList's V1-worded + /// warning claims non-DNS SANs "are submitted rather than dropped on purpose", which is not + /// true for V2 because EnrollV2Async always strips them from additionalDomains. + /// The V2 path must log its own "excluded from V2 additionalDomains" message (SAN types only, no + /// values), V1 must keep its original wording and wire behaviour, and private-pki must be + /// unaffected. + /// + /// Log capture: CERTInextCAPlugin._logger is a per-instance field resolved from + /// at construction, so swapping the factory before building + /// the plugin captures its messages (same seam as , + /// and the same non-parallel collection). Other test classes may log through the swapped + /// factory concurrently, so assertions only consider messages carrying this call's unique + /// subject marker. + /// + [Collection(LoggingStateCollection.Name)] + public class V2UccNonDnsSanLoggingTests + { + private const string V1SubmittedWording = "submitted rather than dropped"; + private const string V1DroppedWording = "DROPPED because SubmitNonDnsSans is false"; + private const string V2ExcludedWording = "non-DNS SAN(s) excluded from V2 additionalDomains"; + private const string EmailSan = "admin@example.com"; + + private sealed class CapturingLoggerProvider : ILoggerProvider + { + public ConcurrentQueue Messages { get; } = new(); + public ILogger CreateLogger(string categoryName) => new CapturingLogger(Messages); + public void Dispose() { } + + private sealed class CapturingLogger : ILogger + { + private readonly ConcurrentQueue _messages; + public CapturingLogger(ConcurrentQueue messages) => _messages = messages; + public IDisposable BeginScope(TState state) => null; + public bool IsEnabled(LogLevel logLevel) => true; + public void Log(LogLevel logLevel, EventId eventId, TState state, Exception exception, + Func formatter) + => _messages.Enqueue(formatter(state, exception)); + } + } + + /// + /// Builds the plugin (after swapping ), runs + /// , and returns every captured message mentioning + /// . + /// + private static async Task> CaptureAsync( + string marker, Func buildPlugin, Func enroll) + { + var provider = new CapturingLoggerProvider(); + var factory = LoggerFactory.Create(b => b.AddProvider(provider).SetMinimumLevel(LogLevel.Trace)); + try + { + LogHandler.Factory = factory; + var plugin = buildPlugin(); // constructed AFTER the swap so _logger resolves through it + await enroll(plugin); + } + finally + { + LogHandler.Factory = Microsoft.Extensions.Logging.Abstractions.NullLoggerFactory.Instance; + factory.Dispose(); + } + + return provider.Messages.Where(m => m != null && m.Contains(marker)).ToList(); + } + + private static string NewMarker() => "sanlog-" + Guid.NewGuid().ToString("N"); + + // BouncyCastle only (project crypto policy). CN only — UCC CSRs carry only the primary domain. + private static string GenerateCsrPem(string cn) + { + var keyGen = new RsaKeyPairGenerator(); + keyGen.Init(new KeyGenerationParameters(new SecureRandom(), 2048)); + AsymmetricCipherKeyPair kp = keyGen.GenerateKeyPair(); + var csr = new Pkcs10CertificationRequest( + "SHA256withRSA", new X509Name($"CN={cn}"), kp.Public, null, kp.Private); + return "-----BEGIN CERTIFICATE REQUEST-----\n" + + Convert.ToBase64String(csr.GetEncoded(), Base64FormattingOptions.InsertLineBreaks) + + "\n-----END CERTIFICATE REQUEST-----"; + } + + private static Dictionary MixedSans(string primary) => new() + { + ["dnsname"] = new[] { primary, "san1." + primary }, + ["ipaddress"] = new[] { "192.0.2.10" }, + ["rfc822name"] = new[] { EmailSan } + }; + + // --------------------------------------------------------------------------- + // V2 SSL UCC + // --------------------------------------------------------------------------- + + [Theory] + [InlineData(true)] + [InlineData(false)] + public async Task Enroll_V2_Ucc_NonDnsSans_LogsV2ExclusionNotV1Wording_WireStaysDnsOnly(bool submitNonDnsSans) + { + string marker = NewMarker(); + string primary = marker + ".example.com"; + + var mock = new Mock(MockBehavior.Strict); + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = "844", ProductTypeId = "15", Active = true } // DV SSL UCC + }); + V2CreateSslOrderRequest captured = null; + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .Callback((_, __, req, ___) => captured = req) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = "ord_ucc_nondns", Status = "pending-dcv" }); + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), "ord_ucc_nondns", It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), "ord_ucc_nondns", It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = "ord_ucc_nondns", Status = "pending-dcv" }); + + var config = new CERTInextConfig + { + UseV2Api = true, + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + SignerIp = "1.2.3.4", + SignerPlace = "New York", + PickupRetries = 0, + SubmitNonDnsSans = submitNonDnsSans + }; + var productInfo = new EnrollmentProductInfo + { + ProductID = "DV SSL UCC", + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = "844", + ["ProductFamily"] = "ssl", + ["ProductVariant"] = "dv", + ["DomainName"] = primary + } + }; + + var messages = await CaptureAsync(marker, + () => new CERTInextCAPlugin(mock.Object, config), + p => p.Enroll(GenerateCsrPem(primary), $"CN={primary}", MixedSans(primary), productInfo, + RequestFormat.PKCS10, EnrollmentType.New)); + + // Wire unchanged: additionalDomains stays DNS-only regardless of SubmitNonDnsSans. + captured.Should().NotBeNull(); + captured!.Certificate.AdditionalDomains.Should().Equal(new[] { "san1." + primary }); + + messages.Should().NotContain(m => m.Contains(V1SubmittedWording), + "V2 additionalDomains never carries non-DNS SANs, so the V1 'submitted' claim is false here"); + messages.Should().NotContain(m => m.Contains(V1DroppedWording), + "SubmitNonDnsSans is a V1 switch and does not decide the V2 outcome"); + + var v2 = messages.Where(m => m.Contains(V2ExcludedWording)).ToList(); + v2.Should().ContainSingle(); + v2[0].Should().StartWith("EnrollV2Async: 2 non-DNS SAN(s) excluded from V2 additionalDomains"); + v2[0].Should().Contain("Types=[ip, email]"); + + // Scoped to the SAN-resolution log sites this path owns. The Enroll-wide "Enrollment + // attempt started" audit line (shared with V1) logs the raw SAN dictionary and is + // out of scope here. + v2[0].Should().NotContain(EmailSan, + "an email SAN value is personal data; the V2 exclusion message logs SAN types only"); + messages.Where(m => m.StartsWith("Resolved ")).Should().ContainSingle() + .Which.Should().NotContain(EmailSan, + "in DNS-only mode the resolved-SAN audit line describes only what V2 submits"); + } + + // --------------------------------------------------------------------------- + // V1 — original wording and wire behaviour preserved + // --------------------------------------------------------------------------- + + [Fact] + public async Task Enroll_V1_NonDnsSans_StillLogsSubmittedWording_AndSubmitsThem() + { + string marker = NewMarker(); + string primary = marker + ".example.com"; + + EnrollCertificateRequest captured = null; + var mock = new Mock(MockBehavior.Loose); + mock.Setup(c => c.EnrollCertificateAsync(It.IsAny(), It.IsAny())) + .Callback((req, _) => captured = req) + .ReturnsAsync(new EnrollCertificateResponse + { + Id = "ORD-UCC-NONDNS", Status = "issued", Certificate = MockCertificateData.FakePemCertificate + }); + + var productInfo = new EnrollmentProductInfo + { + ProductID = "DV SSL", + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = "842" + } + }; + + var messages = await CaptureAsync(marker, + () => new CERTInextCAPlugin(mock.Object, new CERTInextConfig { PickupRetries = 0 }), + p => p.Enroll(GenerateCsrPem(primary), $"CN={primary}", MixedSans(primary), productInfo, + RequestFormat.PKCS10, EnrollmentType.New)); + + captured.Should().NotBeNull(); + captured!.Sans.Select(s => s.Value).Should().Contain(new[] { "192.0.2.10", EmailSan }, + "V1 submits non-DNS SANs on purpose when SubmitNonDnsSans is true (the default)"); + + messages.Should().Contain(m => m.Contains(V1SubmittedWording)); + messages.Should().NotContain(m => m.Contains(V2ExcludedWording)); + } + + // --------------------------------------------------------------------------- + // Private PKI — unaffected + // --------------------------------------------------------------------------- + + [Fact] + public async Task Enroll_V2_PrivatePki_IpSansStillInAdditionalHosts_NoSslSanWording() + { + string marker = NewMarker(); + const string hostname = "intranet.acme.local"; + + var mock = new Mock(MockBehavior.Strict); + V2CreatePrivatePkiOrderRequest captured = null; + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), It.IsAny())) + .Callback((_, req, __) => captured = req) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = "ord_pki_nondns", Status = "pending-csr" }); + mock.Setup(c => c.SubmitCsrV2Async( + Constants.ApiV2.FamilyPrivatePki, "ord_pki_nondns", It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.TrackOrderV2Async(Constants.ApiV2.FamilyPrivatePki, "ord_pki_nondns", It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = "ord_pki_nondns", Status = "pending-approval" }); + + var config = new CERTInextConfig + { + UseV2Api = true, + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + RequestorName = "DevOps Team", + RequestorEmail = "devops@acme.com", + RequestorIsdCode = "1", + RequestorMobileNumber = "4155551234", + SignerIp = "1.2.3.4", + SignerPlace = "New York", + PickupRetries = 0, + SubmitNonDnsSans = false + }; + var productInfo = new EnrollmentProductInfo + { + ProductID = Constants.Products.DvSsl, + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductFamily"] = "private-pki", + ["ProductVariant"] = "intranet-ssl", + ["ProductCode"] = "149", + ["DomainName"] = hostname + } + }; + + var messages = await CaptureAsync(marker, + () => new CERTInextCAPlugin(mock.Object, config), + p => p.Enroll(MockCertificateData.FakeCsrPem, $"CN={hostname}, OU={marker}", + new Dictionary + { + ["dnsname"] = new[] { hostname }, + ["ipaddress"] = new[] { "10.0.0.50" } + }, + productInfo, RequestFormat.PKCS10, EnrollmentType.New)); + + captured.Should().NotBeNull(); + captured!.AdditionalHosts.Should().Equal(new[] { "10.0.0.50" }, + "private-pki carries IP SANs natively and never consults SubmitNonDnsSans"); + + messages.Should().NotContain(m => m.Contains(V2ExcludedWording)); + messages.Should().NotContain(m => m.Contains(V1SubmittedWording)); + messages.Should().NotContain(m => m.Contains(V1DroppedWording)); + } + } +} diff --git a/CERTInext.Tests/V2UnknownStatusTests.cs b/CERTInext.Tests/V2UnknownStatusTests.cs new file mode 100644 index 0000000..11d870c --- /dev/null +++ b/CERTInext.Tests/V2UnknownStatusTests.cs @@ -0,0 +1,107 @@ +// Copyright 2026 Keyfactor +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; +using System.Collections.Generic; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Moq; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Tests for the `unknown` status: the V2 spec lists `unknown` among its documented order + /// statuses, and StatusMapper.V2StatusToRequestDisposition maps it to + /// EXTERNALVALIDATION (not FAILED), since the order may still be live; these tests cover the enroll and single-record callers end to end. + /// + public class V2UnknownStatusTests + { + private const string OrderId = "ord_unknown_001"; + + private static CERTInextConfig V2Config() => new CERTInextConfig + { + UseV2Api = true, + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + SignerIp = "1.2.3.4", + SignerPlace = "New York", + PickupRetries = 0 + }; + + [Fact] + public async Task Enroll_V2_PostCsrStatusUnknown_ReturnsPendingWithOrderId() + { + var mock = new Mock(MockBehavior.Strict); + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = "842", ProductTypeId = "13", Active = true } + }); + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = OrderId, Status = "pending-csr" }); + mock.Setup(c => c.SubmitCsrV2Async(It.IsAny(), OrderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), OrderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = OrderId, Status = "unknown" }); + + var plugin = new CERTInextCAPlugin(mock.Object, V2Config()); + var productInfo = new EnrollmentProductInfo + { + ProductID = Constants.Products.DvSsl, + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = "842", + ["ProductFamily"] = "ssl", + ["ProductVariant"] = "dv", + ["DomainName"] = "example.com" + } + }; + + var result = await plugin.Enroll( + MockCertificateData.FakeCsrPem, "CN=example.com", new Dictionary(), + productInfo, RequestFormat.PKCS10, EnrollmentType.New); + + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION, + "a spec-documented `unknown` order may still be live and must not be reported as FAILED"); + result.CARequestID.Should().Be(OrderId); + } + + [Fact] + public async Task GetSingleRecord_V2_StatusUnknown_ReturnsPendingRecord() + { + var mock = new Mock(); // Loose: only the resolve/track result matters + mock.Setup(c => c.ResolveAndTrackOrderV2WithFamilyAsync(OrderId, It.IsAny())) + .ReturnsAsync((Constants.ApiV2.FamilySsl, new V2OrderStatusResponse { OrderId = OrderId, Status = "unknown" })); + + var plugin = new CERTInextCAPlugin(mock.Object, V2Config()); + var record = await plugin.GetSingleRecord(OrderId); + + record.CARequestID.Should().Be(OrderId); + record.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + mock.Verify(c => c.ResolveAndDownloadCertificateV2Async(It.IsAny(), It.IsAny()), + Times.Never, "a pending order has no certificate to download"); + } + } +} diff --git a/CERTInext.Tests/V2WildcardEnrollmentTests.cs b/CERTInext.Tests/V2WildcardEnrollmentTests.cs new file mode 100644 index 0000000..f79117e --- /dev/null +++ b/CERTInext.Tests/V2WildcardEnrollmentTests.cs @@ -0,0 +1,216 @@ +// Copyright 2026 Keyfactor +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +using System; +using System.Collections.Generic; +using System.Threading; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Keyfactor.PKI.Enums.EJBCA; +using Moq; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Tests for the non-UCC V2 single-domain SAN guard's wildcard-apex exemption: + /// a wildcard product's CSR/SAN dictionary routinely also carries the bare apex alongside + /// the wildcard domain itself (e.g. "example.com" alongside "*.example.com"), and the guard + /// must not reject that apex as an "extra SAN" the way it would for any other non-UCC + /// product. Only the apex is exempt — any other extra SAN is still rejected, and non-wildcard + /// products are unaffected. + /// + /// NOTE: these tests only confirm the guard's accept/reject decision. What is actually sent + /// to the CA for the apex (whether additionalDomains needs it, or CERTInext handles it + /// automatically for a wildcard product) has not been confirmed against the live API — see + /// the comment in EnrollV2Async above the guard. + /// + public class V2WildcardEnrollmentTests + { + private static Mock NewMock() => + new Mock(MockBehavior.Strict); + + private static CERTInextCAPlugin BuildV2Plugin(ICERTInextClient client, string organizationNumber = null) => + new CERTInextCAPlugin(client, new CERTInextConfig + { + UseV2Api = true, + ApiUrl = "https://v2.certinext.io", + OAuthClientId = "my-client", + OAuthClientSecret = "my-secret", + RequestorName = "Test User", + RequestorEmail = "test@example.com", + SignerIp = "1.2.3.4", + SignerPlace = "New York", + OrganizationNumber = organizationNumber, + PickupRetries = 0 + }); + + private static EnrollmentProductInfo MakeWildcardProductInfo( + string productId, string productCode, string domainName) => + new EnrollmentProductInfo + { + ProductID = productId, + ProductParameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProductCode"] = productCode, + ["ProductFamily"] = "ssl", + // No explicit ProductVariant — it is derived from ProductID + // ("dv"/"ov"), avoiding a mismatch reject for the OV wildcard test. + ["DomainName"] = domainName + } + }; + + private static void StubCatalog(Mock mock, string productCode, string productTypeId) => + mock.Setup(c => c.GetProductDetailsV2Async(It.IsAny())) + .ReturnsAsync(new List + { + new ProductDetail { ProductCode = productCode, ProductTypeId = productTypeId, Active = true } + }); + + private static void StubHappyOrderPlacement(Mock mock, string orderId = "ord_wc_001") + { + mock.Setup(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny())) + .ReturnsAsync(new V2CreateOrderResponse { OrderId = orderId, Status = "pending-dcv" }); + + mock.Setup(c => c.SubmitCsrV2Async( + It.IsAny(), orderId, It.IsAny(), It.IsAny())) + .Returns(Task.CompletedTask); + + mock.Setup(c => c.TrackOrderV2Async(It.IsAny(), orderId, It.IsAny())) + .ReturnsAsync(new V2OrderStatusResponse { OrderId = orderId, Status = "pending-dcv" }); + } + + [Fact] + public async Task Enroll_V2_DvWildcard_ApexInSanDictionary_IsNotRejected() + { + var mock = NewMock(); + StubCatalog(mock, "839", "14"); // DV SSL Wildcard + StubHappyOrderPlacement(mock); + + var plugin = BuildV2Plugin(mock.Object); + + var result = await plugin.Enroll( + csr: MockCertificateData.FakeCsrPem, + subject: "CN=*.example.com", + san: new Dictionary + { + // Apex alongside the wildcard domain — routine for a wildcard CSR. + ["dns"] = new[] { "*.example.com", "example.com" } + }, + productInfo: MakeWildcardProductInfo(Constants.Products.DvSslWildcard, "839", "*.example.com"), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION, + "the apex must be exempted from the single-domain guard for a wildcard product, " + + "not rejected as an extra SAN"); + mock.Verify(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny()), Times.Once); + } + + [Fact] + public async Task Enroll_V2_OvWildcard_ApexInSanDictionary_IsNotRejected() + { + var mock = NewMock(); + StubCatalog(mock, "843", "17"); // OV SSL Wildcard + StubHappyOrderPlacement(mock); + + // OV requires an organization block. + var plugin = BuildV2Plugin(mock.Object, organizationNumber: "ORG-TEST-001"); + + var result = await plugin.Enroll( + csr: MockCertificateData.FakeCsrPem, + subject: "CN=*.example.com", + san: new Dictionary + { + ["dns"] = new[] { "*.example.com", "example.com" } + }, + productInfo: MakeWildcardProductInfo(Constants.Products.OvSslWildcard, "843", "*.example.com"), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.Status.Should().Be((int)EndEntityStatus.EXTERNALVALIDATION); + mock.Verify(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny()), Times.Once); + } + + [Fact] + public async Task Enroll_V2_DvWildcard_NonApexExtraSan_StillRejected_WithoutSuggestingUcc() + { + var mock = NewMock(); + StubCatalog(mock, "839", "14"); // DV SSL Wildcard + + var plugin = BuildV2Plugin(mock.Object); + + var result = await plugin.Enroll( + csr: MockCertificateData.FakeCsrPem, + subject: "CN=*.example.com", + san: new Dictionary + { + // The apex is exempt, but an unrelated extra domain is not. + ["dns"] = new[] { "*.example.com", "example.com", "other.example.com" } + }, + productInfo: MakeWildcardProductInfo(Constants.Products.DvSslWildcard, "839", "*.example.com"), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.Status.Should().Be((int)EndEntityStatus.FAILED); + result.StatusMessage.Should().Contain("1 SAN(s) beyond"); + result.StatusMessage.Should().NotContain("UCC", + "a wildcard enrollment rejection must not suggest buying a UCC product"); + + mock.Verify(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny()), Times.Never); + } + + [Fact] + public async Task Enroll_V2_NonWildcardProduct_ApexNotExempt_StillRejected_AndSuggestsUcc() + { + // Sanity check that the exemption is wildcard-specific: a non-wildcard, non-UCC + // product's "extra" SAN set is unaffected by this fix, and its rejection message + // still offers the UCC suggestion (only wildcard products' wording changes). + var mock = NewMock(); + StubCatalog(mock, "842", "13"); // DV SSL (non-wildcard, non-UCC) + + var plugin = BuildV2Plugin(mock.Object); + + var result = await plugin.Enroll( + csr: MockCertificateData.FakeCsrPem, + subject: "CN=example.com", + san: new Dictionary + { + ["dns"] = new[] { "example.com", "other.example.com" } + }, + productInfo: MakeWildcardProductInfo(Constants.Products.DvSsl, "842", "example.com"), + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + result.Status.Should().Be((int)EndEntityStatus.FAILED); + result.StatusMessage.Should().Contain("UCC"); + + mock.Verify(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), + It.IsAny(), It.IsAny()), Times.Never); + } + } +} diff --git a/CERTInext.Tests/ValidityResolutionTests.cs b/CERTInext.Tests/ValidityResolutionTests.cs new file mode 100644 index 0000000..88e3f68 --- /dev/null +++ b/CERTInext.Tests/ValidityResolutionTests.cs @@ -0,0 +1,149 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Generic; +using System.Linq; +using System.Text.Json; +using System.Threading.Tasks; +using FluentAssertions; +using Keyfactor.AnyGateway.Extensions; +using Keyfactor.Extensions.CAPlugin.CERTInext.Client; +using Moq; +using WireMock.RequestBuilders; +using WireMock.ResponseBuilders; +using WireMock.Server; +using Xunit; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Tests +{ + /// + /// Pins the subscription-term rule max(ValidityYears, ceil(ValidityDays / 365)) (each counted + /// only when set), falling back to the connector's SubscriptionValidityYears. Both template + /// fields default to one year, so a field left at its default must never beat an explicit value in + /// the other (a template saved with ValidityDays=730 and the default ValidityYears=1 was a 2-year + /// order in 1.0.0). Drives the real plugin over a real client against WireMock and asserts on the + /// captured subscriptionDetails.validity. + /// + [Collection(LoggingStateCollection.Name)] + public class ValidityResolutionTests : IDisposable + { + private readonly WireMockServer _server; + + public ValidityResolutionTests() + { + _server = WireMockServer.Start(); + _server.Given(Request.Create().WithPath("/GenerateOrderSSL").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.GenerateOrderSuccessJson(MockCertificateData.OrderNumber1))); + _server.Given(Request.Create().WithPath("/TrackOrder").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.TrackOrderIssuedJson(MockCertificateData.OrderNumber1))); + _server.Given(Request.Create().WithPath("/GetCertificate").UsingPost()) + .RespondWith(Response.Create().WithStatusCode(200) + .WithHeader("Content-Type", "application/json") + .WithBody(MockCertificateData.GetCertificateSuccessJson())); + } + + public void Dispose() => _server.Stop(); + + private CERTInextClient BuildClient(string connectorValidityYears) => new CERTInextClient(new CERTInextConfig + { + ApiUrl = _server.Urls[0], + AuthMode = "AccessKey", + ApiKey = "test-key", + AccountNumber = "12345", + RequestorName = "Default Requestor", + RequestorEmail = "default@example.com", + RequestorIsdCode = "1", + RequestorMobileNumber = "5550000000", + SignerPlace = "Austin", + SignerIp = "203.0.113.10", + PageSize = 100, + SubscriptionValidityYears = connectorValidityYears + }); + + private static EnrollmentProductInfo MakeProductInfo(string years, string days, Dictionary extras = null) + { + var parameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["ProfileId"] = "842" + }; + if (years != null) parameters["ValidityYears"] = years; + if (days != null) parameters["ValidityDays"] = days; + if (extras != null) + foreach (var kv in extras) + parameters[kv.Key] = kv.Value; + return new EnrollmentProductInfo { ProductID = "842", ProductParameters = parameters }; + } + + private string CapturedValidity() + { + var posts = _server.LogEntries.Where(e => e.RequestMessage.Path == "/GenerateOrderSSL").ToList(); + posts.Should().HaveCount(1, "exactly one GenerateOrderSSL POST should have been emitted"); + return JsonDocument.Parse(posts[0].RequestMessage.Body!).RootElement + .GetProperty("orderDetails").GetProperty("subscriptionDetails").GetProperty("validity").GetString(); + } + + // years/days: null = parameter absent from the template; connector: SubscriptionValidityYears. + [Theory] + [InlineData("1", "730", "1", "2")] // default years must not shorten an explicit days value (1.0.0 behavior) + [InlineData("3", "365", "1", "3")] // default days must not shorten an explicit years value + [InlineData("2", "730", "1", "2")] + [InlineData("1", "365", "1", "1")] // both at defaults + [InlineData(null, "45", "1", "1")] // sub-year days round up to one year + [InlineData(null, "400", "1", "2")] + [InlineData(null, "365", "3", "1")] // set template value beats connector default + [InlineData("0", "0", "2", "2")] // zero = unset -> connector value + [InlineData(null, null, "2", "2")] // neither set -> connector value + [InlineData(null, null, "", "1")] // neither set, blank connector config + public async Task Enroll_New_FromTemplateParameters_SendsResolvedSubscriptionTerm( + string years, string days, string connector, string expected) + { + var plugin = new CERTInextCAPlugin(BuildClient(connector), new CERTInextConfig { PickupRetries = 0 }); + + await plugin.Enroll( + MockCertificateData.FakeCsrPem, "CN=test.example.com", + new Dictionary { ["dns"] = new[] { "test.example.com" } }, + MakeProductInfo(years, days), RequestFormat.PKCS10, EnrollmentType.New); + + CapturedValidity().Should().Be(expected); + } + + [Theory] + [InlineData("1", "730", "1", "2")] + [InlineData("3", "365", "1", "3")] + [InlineData(null, null, "2", "2")] + public async Task Enroll_RenewOrReissue_RenewalApi_FromTemplateParameters_UsesSameRule( + string years, string days, string connector, string expected) + { + var reader = new Mock(); + reader.Setup(r => r.GetRequestIDBySerialNumber(It.IsAny())) + .ReturnsAsync(MockCertificateData.CertId1); + reader.Setup(r => r.GetExpirationDateByRequestId(MockCertificateData.CertId1)) + .Returns(DateTime.UtcNow.AddDays(30)); + + var plugin = new CERTInextCAPlugin(BuildClient(connector), reader.Object); + + await plugin.Enroll( + MockCertificateData.FakeCsrPem, "CN=test.example.com", + new Dictionary { ["dns"] = new[] { "test.example.com" } }, + MakeProductInfo(years, days, new Dictionary + { + ["PriorCertSN"] = "AABB", + ["RenewalWindowDays"] = "90" + }), + RequestFormat.PKCS10, EnrollmentType.RenewOrReissue); + + // Guard: the renewal API path (not the new-enroll fallback) must have produced the body. + reader.Verify(r => r.GetExpirationDateByRequestId(MockCertificateData.CertId1), Times.Once); + CapturedValidity().Should().Be(expected); + } + } +} diff --git a/CERTInext/API/CertificateRequest.cs b/CERTInext/API/CertificateRequest.cs index 7f02df0..d4194a1 100644 --- a/CERTInext/API/CertificateRequest.cs +++ b/CERTInext/API/CertificateRequest.cs @@ -121,6 +121,25 @@ public class SslOrderDetails [JsonPropertyName("emailNotifications")] public string EmailNotifications { get; set; } = "1"; + /// + /// CERTInext account group (delegation) number the order is placed under. Sent at + /// orderDetails.groupNumber, which is where CERTInext reads it. Omitted when null, + /// in which case CERTInext places the order against the account's default group. + /// + [JsonPropertyName("groupNumber")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string GroupNumber { get; set; } + + /// + /// "1" = CERTInext also secures the www. variant of the primary domain (which then + /// needs its own DCV); "0" = only the supplied domain names. Sent at + /// orderDetails.autoSecureWWW, which is where CERTInext reads it. When omitted, + /// CERTInext applies its own default of "1". + /// + [JsonPropertyName("autoSecureWWW")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string AutoSecureWww { get; set; } + [JsonPropertyName("requestorInformation")] public RequestorInformation RequestorInformation { get; set; } @@ -142,10 +161,6 @@ public class SslOrderDetails [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public OrganizationDetails OrganizationDetails { get; set; } - [JsonPropertyName("delegationInformation")] - [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] - public DelegationInformation DelegationInformation { get; set; } - [JsonPropertyName("technicalPointOfContact")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public TechnicalPointOfContact TechnicalPointOfContact { get; set; } @@ -200,10 +215,8 @@ public class CertificateInformation [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public List AdditionalDomains { get; set; } - /// "1" = also secure www variant (default); "0" = disable. - [JsonPropertyName("autoSecureWWW")] - [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] - public string AutoSecureWww { get; set; } + // autoSecureWWW is NOT a certificateInformation field - CERTInext reads it from + // orderDetails. See SslOrderDetails.AutoSecureWww. } public class AgreementDetails @@ -233,36 +246,27 @@ public class OrganizationDetails } /// - /// Routes the order to a specific account group within CERTInext. Required by many - /// accounts even though the V1 docs list it as optional — without it, orders may be - /// placed against the default group and queued for additional review. - /// - public class DelegationInformation - { - [JsonPropertyName("groupNumber")] - [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] - public string GroupNumber { get; set; } - } - - /// - /// Technical point of contact metadata sent with SSL orders. CERTInext uses these - /// fields as the secondary contact for issuance-related notifications. When omitted, - /// some product configurations queue the order in Pending System RA waiting - /// for the field to be populated manually. + /// Technical point of contact sent at orderDetails.technicalPointOfContact on SSL + /// orders. Field names follow the shape CERTInext reads + /// (pocFirstName/pocLastName/pocEmail/pocIsdCode/pocMobileNumber). No defaults are + /// applied here - the order builder resolves every value from connector config. /// public class TechnicalPointOfContact { - [JsonPropertyName("tpcName")] - public string TpcName { get; set; } + [JsonPropertyName("pocFirstName")] + public string PocFirstName { get; set; } - [JsonPropertyName("tpcEmail")] - public string TpcEmail { get; set; } + [JsonPropertyName("pocLastName")] + public string PocLastName { get; set; } - [JsonPropertyName("tpcIsdCode")] - public string TpcIsdCode { get; set; } = "1"; + [JsonPropertyName("pocEmail")] + public string PocEmail { get; set; } - [JsonPropertyName("tpcMobileNumber")] - public string TpcMobileNumber { get; set; } + [JsonPropertyName("pocIsdCode")] + public string PocIsdCode { get; set; } + + [JsonPropertyName("pocMobileNumber")] + public string PocMobileNumber { get; set; } } public class AdditionalInformation @@ -570,6 +574,10 @@ public class EnrollCertificateRequest [JsonPropertyName("csr")] public string Csr { get; set; } + [JsonPropertyName("validityYears")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public int? ValidityYears { get; set; } + [JsonPropertyName("validityDays")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public int? ValidityDays { get; set; } @@ -594,6 +602,21 @@ public class EnrollCertificateRequest [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public string Comment { get; set; } + /// Per-template agreement signer name; blank falls back to the connector value. + [JsonPropertyName("signerName")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string SignerName { get; set; } + + /// Per-template agreement signer place; blank falls back to the connector value. + [JsonPropertyName("signerPlace")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string SignerPlace { get; set; } + + /// Per-template agreement signer IP; blank falls back to the connector value. + [JsonPropertyName("signerIp")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string SignerIp { get; set; } + [JsonPropertyName("keyType")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public string KeyType { get; set; } @@ -622,6 +645,36 @@ public class RenewCertificateRequest [JsonPropertyName("csr")] public string Csr { get; set; } + /// + /// Distinguished name of the certificate being renewed. Supplies the renewal order's + /// primary domain via its CN — without it the renewal falls back to the prior order's + /// requestor name, which is not a domain at all. + /// + [JsonPropertyName("subject")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string Subject { get; set; } + + /// + /// Template/enrollment product code to submit the renewal order under. Without it, the + /// renewal falls back to the connector-level default product code, which is often unset — + /// leaving renewals to go out under an empty product code regardless of the template used. + /// + [JsonPropertyName("profileId")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string ProfileId { get; set; } + + /// + /// SANs to carry onto the renewal order; without them a renewed UCC certificate + /// would hold only its primary domain. + /// + [JsonPropertyName("sans")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public System.Collections.Generic.List Sans { get; set; } + + [JsonPropertyName("validityYears")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public int? ValidityYears { get; set; } + [JsonPropertyName("validityDays")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public int? ValidityDays { get; set; } @@ -637,6 +690,21 @@ public class RenewCertificateRequest [JsonPropertyName("comment")] [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] public string Comment { get; set; } + + /// Per-template agreement signer name; blank falls back to the connector value. + [JsonPropertyName("signerName")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string SignerName { get; set; } + + /// Per-template agreement signer place; blank falls back to the connector value. + [JsonPropertyName("signerPlace")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string SignerPlace { get; set; } + + /// Per-template agreement signer IP; blank falls back to the connector value. + [JsonPropertyName("signerIp")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string SignerIp { get; set; } } /// diff --git a/CERTInext/API/CertificateResponse.cs b/CERTInext/API/CertificateResponse.cs index 3b3103f..c8ee66a 100644 --- a/CERTInext/API/CertificateResponse.cs +++ b/CERTInext/API/CertificateResponse.cs @@ -1,4 +1,4 @@ -// Copyright 2024 Keyfactor +// Copyright 2026 Keyfactor // Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. // You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 // Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, @@ -587,6 +587,7 @@ public List FlattenProducts() ProductCode = p.ProductCode, ProductName = p.ProductName, ProductType = cat.CategoryName, + ProductTypeId = p.ProductTypeId, Active = true // API does not return an active flag at this level }); } @@ -658,6 +659,15 @@ public class ProductDetail [JsonPropertyName("productType")] public string ProductType { get; set; } + /// + /// Numeric product type ID from the wire (), + /// e.g. "13" for DV SSL. UCC (multi-SAN) family values are 15/18/20/21/22. + /// Not populated by every parse path (only set + /// where the source shape actually carries a productTypeID field). + /// + [JsonPropertyName("productTypeID")] + public string ProductTypeId { get; set; } + /// /// Always true for products returned by the API — the API only /// returns products that are available on the account. diff --git a/CERTInext/API/V2/CertificateRequestV2.cs b/CERTInext/API/V2/CertificateRequestV2.cs new file mode 100644 index 0000000..c29fc5b --- /dev/null +++ b/CERTInext/API/V2/CertificateRequestV2.cs @@ -0,0 +1,544 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System.Text.Json.Serialization; +using System.Text.Json; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.API.V2 +{ + // --------------------------------------------------------------------------- + // V2 REST API — Request DTOs + // + // Auth: POST {ApiUrl}/oauth/token (form-encoded client_credentials; ApiUrl is the V2 base + // URL when UseV2Api=true) + // Product code: optional X-Product-Code override header (not in body); when omitted CERTInext's + // wrapper resolves the product from productVariant/variant, the wildcard shape and additionalDomains + // Idempotency: Idempotency-Key header sent on order-create/revoke, but the spec doesn't + // document it for those endpoints and only says "parsed today, enforced in a future release" + // for the endpoints (Verify DCV, Domains) it does document it on. + // --------------------------------------------------------------------------- + + /// + /// Requestor information block sent with every V2 order. + /// + public class V2Requestor + { + [JsonPropertyName("name")] + public string Name { get; set; } + + [JsonPropertyName("email")] + public string Email { get; set; } + + [JsonPropertyName("phone")] + public string Phone { get; set; } + + [JsonPropertyName("designation")] + public string Designation { get; set; } + } + + /// + /// Certificate parameters block for V2 SSL orders. + /// + public class V2CertificateParams + { + [JsonPropertyName("domain")] + public string Domain { get; set; } + + [JsonPropertyName("autoSecureWww")] + public bool AutoSecureWww { get; set; } = false; + + /// + /// SAN list for UCC (multi-SAN) product variants — DV/OV/EV UCC and DV/OV Wildcard UCC + /// (Catalog productTypeID 15/18/20/21/22). Each entry must be a valid FQDN + /// (wildcards allowed only for the Wildcard UCC variants). Per the V2 spec's Submit CSR + /// guidance, these SANs come from the order, not the CSR — the CSR must carry only the + /// primary domain in CN for UCC orders. Omitted from the wire body for non-UCC products + /// (single-domain orders are unaffected). + /// + [JsonPropertyName("additionalDomains")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public System.Collections.Generic.List AdditionalDomains { get; set; } + } + + /// + /// Organization block for V2 SSL orders. Per the V2 spec's field table (SSL/TLS + /// Certificates folder description), this block is "Conditional — Mandatory for OV / EV" + /// and every OV/EV create example in the spec sends exactly these three fields. Submitting + /// an OV order with no organization block gets + /// HTTP 422 [EMS-1180] Organization Name cannot be empty — CERTInext resolves the + /// certificate's organization name server-side from organizationNumber, so an + /// absent/empty block leaves it with nothing to resolve. There is no separate + /// "organization name" field to send; supplying a valid, pre-vetted + /// organizationNumber is what the CA needs. + /// + public class V2OrganizationParams + { + [JsonPropertyName("organizationNumber")] + public string OrganizationNumber { get; set; } + + /// + /// Re-uses an existing vetted organization instead of queuing the order for manual + /// vetting. Mirrors the V1 OrganizationDetails.PreVetting="1" semantics — sent + /// as JSON true whenever OrganizationNumber is configured. + /// + [JsonPropertyName("preVetted")] + public bool PreVetted { get; set; } = true; + + /// + /// Optional per spec (re-vetting flow token). Not currently surfaced as plugin config; + /// omitted from the wire body when null/empty. + /// + [JsonPropertyName("preVettingToken")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string PreVettingToken { get; set; } + } + + /// + /// Subscription parameters block for V2 orders (validity, auto-renewal). Per the V2 spec, + /// omitting this block entirely defaults auto-renew to ON (1-year, 30-day window) at the CA, + /// so EnrollV2Async always sends it, driving / + /// from the connector's SubscriptionAutoRenew/ + /// SubscriptionRenewCriteriaDays config. + /// + public class V2SubscriptionParams + { + [JsonPropertyName("validityYears")] + public int ValidityYears { get; set; } = 1; + + [JsonPropertyName("autoRenew")] + public bool AutoRenew { get; set; } = false; + + /// + /// Days before expiry CERTInext auto-renews; only meaningful when + /// is true. Null when the connector's SubscriptionRenewCriteriaDays is blank/unset — the + /// client's global JSON serializer options (CERTInextClient.GetJsonOptions, + /// DefaultIgnoreCondition = WhenWritingNull) omit the field from the wire in that + /// case, letting the CA fall back to its documented default of 30. + /// + [JsonPropertyName("renewBeforeDays")] + public int? RenewBeforeDays { get; set; } + } + + /// + /// Technical point-of-contact block for V2 orders. Per the V2 spec's field table (SSL/TLS + /// Certificates folder description — identical for the Document Signer and + /// Private PKI folders; and + /// reuse this type), all four + /// subfields are documented Optional. Unlike + /// V1's , + /// which sends ISD code and mobile number as two separate fields + /// (tpcIsdCode/tpcMobileNumber), the V2 shape has a single phone field — + /// composed from the connector's ISD-code + mobile-number config pair by + /// . + /// Despite being spec-Optional, EnrollV2Async always populates this block (never omits + /// it), mirroring V1's fallback-to-Requestor* defaulting so a blank connector config never + /// results in a silently-blank contact. + /// + public class V2TechnicalPointOfContact + { + [JsonPropertyName("name")] + public string Name { get; set; } + + [JsonPropertyName("email")] + public string Email { get; set; } + + [JsonPropertyName("phone")] + public string Phone { get; set; } + + [JsonPropertyName("designation")] + public string Designation { get; set; } + } + + /// + /// Subscriber agreement block required for V2 SSL orders. Mirrors the spec's Agreement + /// schema exactly (signerName, signerPlace, accepted), which the SSL and + /// Document Signer create bodies share. There is deliberately no signerIp: the schema + /// has none (the CA records the signer's IP itself, from the request), so the connector/template + /// SignerIp settings are V1-only. The same shape is the body of + /// POST .../ssl-certificates/{orderId}/agreement (AgreementAcceptRequest). + /// + public class V2AgreementParams + { + [JsonPropertyName("signerName")] + public string SignerName { get; set; } + + /// Optional in V2. Omitted from serialisation when null or empty. + [JsonPropertyName("signerPlace")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string SignerPlace { get; set; } + + [JsonPropertyName("accepted")] + public bool Accepted { get; set; } = true; + } + + /// + /// Request body for POST /api/certinext/v2/ssl-certificates. + /// The optional product-code override is sent as the X-Product-Code header (not in this body). + /// + public class V2CreateSslOrderRequest + { + [JsonPropertyName("productVariant")] + public string ProductVariant { get; set; } = "dv"; + + /// + /// Spec enum consent-only | all: "all" = full notification set, "consent-only" = the + /// silent setting (the connector's EmailNotifications=0), null = omitted (CA defaults + /// to "all"). + /// See + /// for the connector config mapping. No default here — relies solely + /// on the client's global DefaultIgnoreCondition = WhenWritingNull serializer option + /// to omit the key when null, the same pattern + /// uses. + /// + [JsonPropertyName("emailNotifications")] + public string EmailNotifications { get; set; } + + [JsonPropertyName("requestor")] + public V2Requestor Requestor { get; set; } + + /// + /// Mandatory for OV/EV, omitted entirely for DV (per spec, "Conditional — Mandatory + /// for OV / EV"). + /// leaves this null for DV orders rather than sending an empty/placeholder block that + /// could itself trigger a different validation error. + /// + [JsonPropertyName("organization")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public V2OrganizationParams Organization { get; set; } + + [JsonPropertyName("certificate")] + public V2CertificateParams Certificate { get; set; } + + [JsonPropertyName("subscription")] + public V2SubscriptionParams Subscription { get; set; } + + [JsonPropertyName("agreement")] + public V2AgreementParams Agreement { get; set; } + + /// + /// Optional per spec, but always populated by EnrollV2Async — see + /// for the fallback/composition rules. + /// + [JsonPropertyName("technicalPointOfContact")] + public V2TechnicalPointOfContact TechnicalPointOfContact { get; set; } + + /// + /// PKCS#10 CSR, sent inline on the create call exactly as received from Command (PEM), only + /// when the connector's V2InlineCsr setting is on (the default; when off it is null, omitted, + /// and the CSR is submitted with PUT .../csr after create). Live-verified on SSL: a create carrying + /// csr issues with no follow-up PUT (a PUT after an inline CSR is rejected 422). Covered by + /// the body-log redaction (CERTInextClient.ApplyLoggingRedaction). + /// + [JsonPropertyName("csr")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string Csr { get; set; } + + [JsonPropertyName("remarks")] + public string Remarks { get; set; } + + /// + /// Optional billing group to attribute this order to. Mirrors V1's + /// — + /// omitted entirely (rather than sent empty) when the connector has no + /// GroupNumber configured, so the order falls back to the account's default group. + /// + [JsonPropertyName("groupNumber")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string GroupNumber { get; set; } + } + + /// + /// Request body for POST /api/certinext/v2/private-pki-certificates. Modelled + /// from the V2 spec's "Private PKI Certificates" folder field table ("Field requirements (in + /// body order)"): variant, requestor.name, requestor.email and + /// hostname are strictly mandatory ("400 if missing"); everything else is Optional. + /// Per the spec, "Private PKI has no DCV, no organization block, and no Subscriber + /// Agreement" — so, unlike , there is no + /// productVariant, organization, certificate or agreement block + /// here. SANs go in , which (unlike SSL's FQDN-only + /// additionalDomains) accepts IP literals. + /// + /// Only the fields EnrollV2Async populates are modelled. Spec-Optional fields the + /// plugin has no source for (caProfileId, masterProductId — both "derived from + /// X-Product-Code" — saveAsDraft, requestId, csr, tags, + /// customFields) are deliberately omitted, matching how the SSL DTO treats its own + /// unused optional fields. The CSR is submitted by the separate Submit CSR call, per the + /// spec's Private PKI workflow (Create -> Submit CSR -> Track -> Download). + /// The optional product-code override is sent as the X-Product-Code header (not in this body). + /// + public class V2CreatePrivatePkiOrderRequest + { + /// + /// Mandatory. Spec enum for create: intranet-ssl / igtf-host + /// (). + /// + [JsonPropertyName("variant")] + public string Variant { get; set; } + + /// + /// Optional (spec default all). Same connector mapping as + /// ; null is omitted on the wire. + /// + [JsonPropertyName("emailNotifications")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string EmailNotifications { get; set; } + + /// Optional. Omitted when the connector has no GroupNumber configured. + [JsonPropertyName("groupNumber")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string GroupNumber { get; set; } + + /// Mandatory (name + email strictly mandatory; phone/designation optional). + [JsonPropertyName("requestor")] + public V2Requestor Requestor { get; set; } + + // No inline `csr` on the Private PKI create: the live sandbox rejects it (HTTP 422), so Private + // PKI uses the two-call flow (create, then PUT .../csr via V2SubmitCsrRequest). + + /// Mandatory. Spec: "hostname - primary CN". + [JsonPropertyName("hostname")] + public string Hostname { get; set; } + + /// + /// Optional. Spec: "additionalHosts[] - SAN list (DNS names or IPv4 / IPv6)". + /// Omitted from the wire body when null (no additional SANs). + /// + [JsonPropertyName("additionalHosts")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public System.Collections.Generic.List AdditionalHosts { get; set; } + + /// Optional (autoRenew defaults ON at the CA when omitted — always sent, as for SSL). + [JsonPropertyName("subscription")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public V2SubscriptionParams Subscription { get; set; } + + [JsonPropertyName("remarks")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string Remarks { get; set; } + + /// Optional per spec; populated with the same fallbacks the SSL body uses. + [JsonPropertyName("technicalPointOfContact")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public V2TechnicalPointOfContact TechnicalPointOfContact { get; set; } + } + + /// + /// subject block of a V2 Document Signer (signature) order. Modelled from + /// the V2 spec's "Document Signer Certificates" folder field table. Only + /// is strictly mandatory ("400 if missing"); the rest are Optional or Conditional on + /// subjectType: + /// - firstName / lastName: "required for natural-person / legal-person" + /// - organizationName: "required for legal-person / legal-entity" + /// - organizationIdentificationNumber: "typically required for legal-entity" + /// - businessCategory: "legal-entity" + /// - countryCode: "Optional (ISO 3166-1 alpha-2)" + /// Every non-mandatory field is omitted from the wire when null so a legal-entity body never + /// carries empty person-name keys (and vice versa). + /// + public class V2SignatureSubject + { + [JsonPropertyName("firstName")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string FirstName { get; set; } + + [JsonPropertyName("lastName")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string LastName { get; set; } + + /// Mandatory for every subjectType. + [JsonPropertyName("email")] + public string Email { get; set; } + + [JsonPropertyName("phone")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string Phone { get; set; } + + [JsonPropertyName("designation")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string Designation { get; set; } + + [JsonPropertyName("organizationName")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string OrganizationName { get; set; } + + [JsonPropertyName("organizationUnit")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string OrganizationUnit { get; set; } + + [JsonPropertyName("organizationIdentificationNumber")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string OrganizationIdentificationNumber { get; set; } + + /// Spec examples: Business Entity | Government | Non-Commercial Entity. + [JsonPropertyName("businessCategory")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string BusinessCategory { get; set; } + + /// Spec examples: passport | driving-license | national-id. + [JsonPropertyName("identityDocumentType")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string IdentityDocumentType { get; set; } + + [JsonPropertyName("identificationNumber")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string IdentificationNumber { get; set; } + + [JsonPropertyName("streetAddress1")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string StreetAddress1 { get; set; } + + [JsonPropertyName("streetAddress2")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string StreetAddress2 { get; set; } + + [JsonPropertyName("locality")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string Locality { get; set; } + + [JsonPropertyName("state")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string State { get; set; } + + [JsonPropertyName("postalCode")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string PostalCode { get; set; } + + [JsonPropertyName("countryCode")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string CountryCode { get; set; } + } + + /// + /// Request body for POST /api/certinext/v2/signature-certificates. Modelled from + /// the V2 spec's "Document Signer Certificates" folder field table. Strictly mandatory ("400 + /// if missing"): subjectType, requestor.name, requestor.email, + /// subject.email; "The subject.* fields beyond email vary by subjectType - + /// the backend applies stricter per-type rules." + /// + /// Not yet wired into EnrollV2Async. The body shape is fully determined by the + /// spec, but several of its mandatory/conditional values (subjectType, + /// subject.email, the per-type subject name/organization fields) have no settled + /// source in the Command enrollment inputs yet. Until that is decided, + /// EnrollV2Async fails a ProductFamily=signature enrollment fast instead of + /// sending any body. The DTO and its client overload exist so that wiring is a pure + /// source-mapping change. + /// + /// reuses (the spec's signature and + /// SSL agreement schemas are identical: signerName, signerPlace, + /// accepted; neither has a signerIp). + /// The optional product-code override is sent as the X-Product-Code header (not in this body). + /// + public class V2CreateSignatureOrderRequest + { + /// + /// Mandatory. Spec enum: natural-person / legal-person / legal-entity + /// (). + /// + [JsonPropertyName("subjectType")] + public string SubjectType { get; set; } + + [JsonPropertyName("emailNotifications")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string EmailNotifications { get; set; } + + [JsonPropertyName("groupNumber")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string GroupNumber { get; set; } + + /// Mandatory (name + email strictly mandatory). + [JsonPropertyName("requestor")] + public V2Requestor Requestor { get; set; } + + /// Mandatory; see for the per-type rules. + [JsonPropertyName("subject")] + public V2SignatureSubject Subject { get; set; } + + [JsonPropertyName("subscription")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public V2SubscriptionParams Subscription { get; set; } + + /// Spec: "Optional - required before issuance". + [JsonPropertyName("agreement")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public V2AgreementParams Agreement { get; set; } + + [JsonPropertyName("remarks")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string Remarks { get; set; } + + [JsonPropertyName("technicalPointOfContact")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public V2TechnicalPointOfContact TechnicalPointOfContact { get; set; } + } + + /// + /// Request body for PUT /api/certinext/v2/{family}-certificates/{orderId}/csr. The spec + /// documents the identical { "csr", "attested" } body for the SSL/TLS, Private PKI + /// and Document Signer families, so one shape serves all three. + /// + public class V2SubmitCsrRequest + { + [JsonPropertyName("csr")] + public string Csr { get; set; } + + [JsonPropertyName("attested")] + public bool Attested { get; set; } = false; + } + + /// + /// Request body for POST /api/certinext/v2/{family}-certificates/{orderId}/revoke. + /// + public class V2RevokeRequest + { + /// + /// RFC 5280 string reason, kebab-case per the V2 spec. Valid values: unspecified, + /// key-compromise, ca-compromise, affiliation-changed, superseded, + /// cessation-of-operation, certificate-hold, privilege-withdrawn (plus + /// aa-compromise on the signature-certificates / private-pki-certificates + /// endpoints). Sending camelCase gets HTTP 400. + /// + [JsonPropertyName("reason")] + public string Reason { get; set; } = "unspecified"; + + [JsonPropertyName("note")] + public string Note { get; set; } + } + + /// + /// Request body for POST /api/certinext/v2/{family}-certificates/{orderId}/cancel + /// ("Cancel Order"). The SSL spec entry marks reason as "required free-text. + /// Persisted in the audit log"; an empty reason is rejected with EMS-984. + /// + public class V2CancelOrderRequest + { + [JsonPropertyName("reason")] + public string Reason { get; set; } + } + + /// + /// Request body for POST /api/certinext/v2/ssl-certificates/{orderId}/agreement ("Accept the + /// Subscriber Agreement", schema AgreementAcceptRequest): { "agreement": { signerName, + /// signerPlace, accepted } }. Same block the create body carries. + /// + public class V2AcceptAgreementRequest + { + [JsonPropertyName("agreement")] + public V2AgreementParams Agreement { get; set; } + } + + /// + /// Outcome of a V2 Cancel Order call that did not throw. + /// + public enum V2CancelOrderOutcome + { + /// HTTP 2xx (spec: 204 No Content) — the order is cancelled. + Cancelled, + + /// HTTP 422 — spec: "order already in a terminal state"; nothing was cancelled. + AlreadyTerminal + } +} diff --git a/CERTInext/API/V2/CertificateResponseV2.cs b/CERTInext/API/V2/CertificateResponseV2.cs new file mode 100644 index 0000000..4c4b997 --- /dev/null +++ b/CERTInext/API/V2/CertificateResponseV2.cs @@ -0,0 +1,522 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Generic; +using System.Text.Json.Serialization; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.API.V2 +{ + // --------------------------------------------------------------------------- + // V2 REST API — Response DTOs + // --------------------------------------------------------------------------- + + /// + /// Standard OAuth2 client_credentials token response (flat shape — no tokenDetails wrapper). + /// POST {ApiUrl}/oauth/token with form-encoded body (ApiUrl is the V2 base URL when + /// UseV2Api=true). + /// + public class V2TokenResponse + { + [JsonPropertyName("access_token")] + public string AccessToken { get; set; } + + [JsonPropertyName("token_type")] + public string TokenType { get; set; } + + /// Lifetime in seconds. Typically 3600 (1 hour). + [JsonPropertyName("expires_in")] + public int ExpiresIn { get; set; } = 3600; + + [JsonPropertyName("refresh_token")] + public string RefreshToken { get; set; } + } + + /// + /// HATEOAS link object present in V2 responses. + /// + public class V2Link + { + [JsonPropertyName("href")] + public string Href { get; set; } + } + + /// + /// _links map returned by V2 order responses. + /// Known keys: self, dcv, csr, agreement, certificate, cancel, revoke. + /// + public class V2Links + { + [JsonPropertyName("self")] + public V2Link Self { get; set; } + + [JsonPropertyName("dcv")] + public V2Link Dcv { get; set; } + + [JsonPropertyName("csr")] + public V2Link Csr { get; set; } + + [JsonPropertyName("agreement")] + public V2Link Agreement { get; set; } + + [JsonPropertyName("certificate")] + public V2Link Certificate { get; set; } + + [JsonPropertyName("cancel")] + public V2Link Cancel { get; set; } + + [JsonPropertyName("revoke")] + public V2Link Revoke { get; set; } + } + + /// + /// Response body for POST /api/certinext/v2/{family}-certificates (201 Created). + /// + public class V2CreateOrderResponse + { + [JsonPropertyName("orderId")] + public string OrderId { get; set; } + + [JsonPropertyName("requestId")] + public string RequestId { get; set; } + + /// + /// Initial order status. Typically "pending-dcv" for SSL DV orders. + /// + [JsonPropertyName("status")] + public string Status { get; set; } + + /// + /// The catalog product code CERTInext's wrapper actually used for the order. The spec's + /// create description lists it in the 201 response; it is what tells an operator which + /// product an order with no X-Product-Code header resolved to. Logged by the + /// plugin; absent when the CA does not return it. + /// + [JsonPropertyName("resolvedProductCode")] + public string ResolvedProductCode { get; set; } + + [JsonPropertyName("_links")] + public V2Links Links { get; set; } + } + + /// + /// Response body for GET /api/certinext/v2/{family}-certificates/{orderId}. + /// Contains lifecycle status only — serial number and validity dates are NOT present; + /// those are only in the Download Certificate response. + /// + public class V2OrderStatusResponse + { + [JsonPropertyName("orderId")] + public string OrderId { get; set; } + + [JsonPropertyName("requestId")] + public string RequestId { get; set; } + + /// Current order status string (e.g. "pending-dcv", "issued", "revoked"). + [JsonPropertyName("status")] + public string Status { get; set; } + + [JsonPropertyName("productVariant")] + public string ProductVariant { get; set; } + + [JsonPropertyName("domain")] + public string Domain { get; set; } + + [JsonPropertyName("_links")] + public V2Links Links { get; set; } + + /// + /// Populated only when is "revoked". Absent entirely from the wire — + /// not present-but-null — when the order has never been revoked, which + /// System.Text.Json deserializes as a null + /// reference with no special handling required. + /// + [JsonPropertyName("revocation")] + public V2RevocationDetails Revocation { get; set; } + + /// + /// CERTInext's free-text order state (e.g. "Order Accepted"), as returned on Track Order. + /// Undocumented vocabulary: for diagnostics and log lines only, never branch logic on it. + /// + [JsonPropertyName("orderState")] + public string OrderState { get; set; } + + /// + /// CERTInext's free-text certificate state (live values seen: "Approved by System", + /// "Certificate Generated", "System Error"). Undocumented vocabulary: for diagnostics and + /// log lines only, never branch logic on it. Notably an order can report + /// "issued" while this still reads "Approved by System" and the + /// certificate cannot be downloaded yet (Download Certificate answers 422 EMS-1165). + /// + [JsonPropertyName("certificateState")] + public string CertificateState { get; set; } + + /// ISO 8601 timestamp when the certificate was issued. Present when status = "issued". + [JsonPropertyName("issuedAt")] + public string IssuedAt { get; set; } + + /// ISO 8601 timestamp when the certificate expires. Present when status = "issued". + [JsonPropertyName("expiresAt")] + public string ExpiresAt { get; set; } + + /// + /// Per-domain DCV/CAA verification detail. Present on UCC orders whose + /// additional SANs each carry their own DCV state. Absent entirely on older/simpler + /// response shapes — callers must treat + /// a null / + /// the same as "no per-domain detail available" and fall back to the single top-level + /// field. + /// + [JsonPropertyName("verifications")] + public V2Verifications Verifications { get; set; } + } + + /// + /// Top-level verifications object on the V2 Track Order response. + /// Only the domain sub-block is modeled — that is the only one this plugin's DCV + /// automation drives. + /// + public class V2Verifications + { + [JsonPropertyName("domain")] + public V2DomainVerification Domain { get; set; } + } + + /// + /// verifications.domain block. is an aggregate that + /// is NOT reliable for driving DCV decisions — it can stay + /// "PENDING" even after the parent order was cancelled and every per-domain + /// had already flipped to REJECTED. Use it + /// for logging only; always decide per-domain from . + /// + public class V2DomainVerification + { + /// Aggregate status (e.g. "PENDING"). Logging only — see class remarks. + [JsonPropertyName("status")] + public string Status { get; set; } + + /// Per-domain verification entries — one per domain on the order (primary + any + /// UCC additional SANs). + [JsonPropertyName("domains")] + public List Domains { get; set; } + } + + /// + /// A single entry in verifications.domain.domains[]. Example shape: + /// {"domain":"a.pending....example.com","domainStatus":"ACTIVE","dcvStatus":"PENDING","caaStatus":"SKIPPED"} + /// for a still-pending SAN, versus + /// {"domain":"...","domainStatus":"ACTIVE","dcvMethod":"dns-txt","dcvStatus":"VERIFIED","verifiedAt":"...","caaStatus":"PASSED"} + /// once verified. and are absent entirely + /// (not present-but-null) on a pending entry — both are nullable here for exactly that + /// reason; a fix must not assume is populated before treating an + /// entry as needing DNS-01 DCV. + /// + public class V2DomainVerificationEntry + { + [JsonPropertyName("domain")] + public string Domain { get; set; } + + [JsonPropertyName("domainStatus")] + public string DomainStatus { get; set; } + + /// Absent on the wire until reaches VERIFIED — see class + /// remarks. This plugin only ever drives dns-txt DCV, so a null/absent value here is + /// treated as "use DNS-01", never as an unknown/unsupported method. + [JsonPropertyName("dcvMethod")] + public string DcvMethod { get; set; } + + /// PENDING / VERIFIED / REJECTED (see + /// DcvStatus* constants). Drive all per-domain DCV decisions from this field, never from + /// the aggregate . + [JsonPropertyName("dcvStatus")] + public string DcvStatus { get; set; } + + /// ISO 8601 timestamp. Absent until reaches VERIFIED. + [JsonPropertyName("verifiedAt")] + public string VerifiedAt { get; set; } + + [JsonPropertyName("caaStatus")] + public string CaaStatus { get; set; } + } + + /// + /// Nested revocation object on the V2 Track Order response. Example shape, from a + /// revoked SSL order: + /// {"status":"Certificate Revoked","reason":"cessation-of-operation","processedAt":"2026-09-24T20:44:41Z"} + /// + public class V2RevocationDetails + { + /// + /// Human-readable revocation engine status (e.g. "Certificate Revoked"), mirroring the + /// outer certificateState field on the same response. Not a distinct enum worth + /// modeling separately from . + /// + [JsonPropertyName("status")] + public string Status { get; set; } + + /// + /// RFC 5280 reason name, hyphenated on the wire (e.g. "cessation-of-operation", + /// "key-compromise") — NOT V1's camelCase convention. See + /// for the known values and + /// Models.StatusMapper.V2RevocationReasonToCrlCode for the reverse mapping back + /// to an RFC 5280 CRL reason code. + /// + [JsonPropertyName("reason")] + public string Reason { get; set; } + + /// Effective revocation time (CA-recorded). RFC 3339 / ISO 8601 UTC. + [JsonPropertyName("processedAt")] + public DateTime? ProcessedAt { get; set; } + } + + /// + /// Response body for GET /api/certinext/v2/{family}-certificates/{orderId}/certificate. + /// Returns the leaf certificate and, when present, intermediate chain PEM strings. + /// + public class V2CertificateDownloadResponse + { + [JsonPropertyName("orderId")] + public string OrderId { get; set; } + + [JsonPropertyName("serialNumber")] + public string SerialNumber { get; set; } + + [JsonPropertyName("subject")] + public string Subject { get; set; } + + [JsonPropertyName("issuer")] + public string Issuer { get; set; } + + [JsonPropertyName("notBefore")] + public DateTime? NotBefore { get; set; } + + [JsonPropertyName("notAfter")] + public DateTime? NotAfter { get; set; } + + /// PEM-encoded leaf certificate. + [JsonPropertyName("certificatePem")] + public string CertificatePem { get; set; } + + /// + /// Array of intermediate PEM strings returned alongside the leaf cert. + /// May be null or empty when the CA does not include chain in the response. + /// + [JsonPropertyName("chainPem")] + public List ChainPem { get; set; } + } + + /// + /// Response body for GET /api/certinext/v2/ssl-certificates/{orderId}/dcv. + /// Returns the DCV challenge token needed to publish a DNS TXT record. + /// + /// Actual wire shape: exactly two fields — + /// {"tokenExpiryDate": "...", "token": "..."}. This matches neither the spec's + /// own worked example for this endpoint (orderNumber/domainName/ + /// dcvMethod/fileNameContent) nor the + /// spec's prose for the same endpoint (method/txtToken). There is no + /// orderNumber, domainName, or method field on the wire, so none are + /// modeled here: + /// - order id and domain name are already known from the local order-placement + /// context before DCV is ever attempted (see call sites of + /// ), so they don't need + /// to be echoed back by this response. + /// - the V2 DCV path only ever performs DNS-TXT validation — the hostname + /// (_emudhra-challenge.{domain}) and validator ("dns-01") are both hardcoded + /// in , which never reads a + /// method from this response — so no method field is needed. + /// + public class V2DcvChallengeResponse + { + /// Value to publish as the DNS TXT record. + [JsonPropertyName("token")] + public string Token { get; set; } + + [JsonPropertyName("tokenExpiryDate")] + public string TokenExpiryDate { get; set; } + } + + /// + /// Request body for POST /api/certinext/v2/ssl-certificates/{orderId}/dcv/verify. + /// + public class V2DcvVerifyRequest + { + [JsonPropertyName("domain")] + public string Domain { get; set; } + + /// "dns-txt" for DNS TXT record validation. + [JsonPropertyName("method")] + public string Method { get; set; } + } + + /// + /// Response body for POST /api/certinext/v2/ssl-certificates/{orderId}/dcv/verify. + /// 200 OK with this body, or 204 No Content, both indicate success. + /// 422 with overallStatus="FAILED" indicates verification failure. + /// + public class V2DcvVerifyResponse + { + /// "VERIFIED" on success, "FAILED" on failure. + [JsonPropertyName("overallStatus")] + public string OverallStatus { get; set; } + + [JsonPropertyName("method")] + public string Method { get; set; } + + [JsonPropertyName("verifiedAt")] + public string VerifiedAt { get; set; } + } + + /// + /// RFC 7807 Problem Details error response from the V2 API. + /// Content-Type: application/problem+json + /// + public class V2ProblemDetails + { + [JsonPropertyName("type")] + public string Type { get; set; } + + [JsonPropertyName("title")] + public string Title { get; set; } + + [JsonPropertyName("status")] + public int Status { get; set; } + + [JsonPropertyName("detail")] + public string Detail { get; set; } + + [JsonPropertyName("instance")] + public string Instance { get; set; } + + /// Field-level validation errors (optional). + [JsonPropertyName("errors")] + public List Errors { get; set; } + } + + /// + /// A single field-level validation error from RFC 7807 errors array. + /// + public class V2FieldError + { + [JsonPropertyName("field")] + public string Field { get; set; } + + [JsonPropertyName("message")] + public string Message { get; set; } + } + + /// + /// Response body for GET /api/certinext/v2/auth/me. + /// Used as the V2 connectivity/ping check. + /// + public class V2AuthMeResponse + { + [JsonPropertyName("accountNumber")] + public string AccountNumber { get; set; } + + [JsonPropertyName("authType")] + public string AuthType { get; set; } + } + + /// + /// Spring-style page envelope for GET /api/certinext/v2/reports/orders. The spec's + /// example body is stale; its field table is what's actually returned. + /// + public class V2OrdersReportResponse + { + [JsonPropertyName("content")] + public List Content { get; set; } + + /// 1-based page index (mirrors the request's page query param). + [JsonPropertyName("page")] + public int Page { get; set; } + + [JsonPropertyName("size")] + public int Size { get; set; } + + [JsonPropertyName("totalElements")] + public long TotalElements { get; set; } + + [JsonPropertyName("totalPages")] + public int TotalPages { get; set; } + } + + /// + /// A single row from the V2 /reports/orders "content" array. Field names match the live + /// field table (NOT the spec's stale example body, which + /// uses different field names — state/identifier/account/group/product). + /// + /// orderStatus/certificateStatus are human-readable display strings (e.g. "Order Accepted", + /// "Certificate Downloaded") — NOT the V2 `status` enum used by TrackOrder + /// (see and + /// Keyfactor.Extensions.CAPlugin.CERTInext.Models.StatusMapper.V2StatusToRequestDisposition). + /// See CERTInextCAPlugin.MapV2ReportStatusToDisposition for how these display strings + /// are mapped; the vocabulary handled there is not guaranteed exhaustive. + /// + public class OrderReportEntryV2 + { + [JsonPropertyName("orderNumber")] + public string OrderNumber { get; set; } + + /// Most-recent request identifier on the order (reissues create new requests). + [JsonPropertyName("requestNumber")] + public string RequestNumber { get; set; } + + /// Human-readable order state, e.g. "Order Accepted", "Order Fulfilled". + [JsonPropertyName("orderStatus")] + public string OrderStatus { get; set; } + + /// Human-readable request/certificate state, e.g. "Pending for Approver", "Certificate Downloaded". + [JsonPropertyName("certificateStatus")] + public string CertificateStatus { get; set; } + + /// Hex serial assigned by the CA. Empty until issuance. + [JsonPropertyName("certificateSerialNumber")] + public string CertificateSerialNumber { get; set; } + + /// Certificate notAfter. Empty until issuance. Kept as string — format not guaranteed. + [JsonPropertyName("certificateExpiryDate")] + public string CertificateExpiryDate { get; set; } + + /// Issuing CA's CN. Empty until issuance. + [JsonPropertyName("issuerCA")] + public string IssuerCa { get; set; } + + /// + /// Catalog product code. Often empty on report rows — do not rely on this + /// for family resolution; use ResolveAndTrackOrderV2WithFamilyAsync instead. + /// + [JsonPropertyName("productCode")] + public string ProductCode { get; set; } + + /// Primary CN for SSL/TLS orders. Empty for non-SSL families. + [JsonPropertyName("domainName")] + public string DomainName { get; set; } + + [JsonPropertyName("groupNumber")] + public string GroupNumber { get; set; } + + /// Order creation time (UTC). Kept as string and parsed defensively by the caller — + /// mirrors the V1 pattern. + [JsonPropertyName("orderDate")] + public string OrderDate { get; set; } + + [JsonPropertyName("organizationName")] + public string OrganizationName { get; set; } + + [JsonPropertyName("countryName")] + public string CountryName { get; set; } + + [JsonPropertyName("originator")] + public string Originator { get; set; } + + [JsonPropertyName("tags")] + public List Tags { get; set; } + + [JsonPropertyName("customFields")] + public List CustomFields { get; set; } + } +} diff --git a/CERTInext/API/V2/SslComValidationV2.cs b/CERTInext/API/V2/SslComValidationV2.cs new file mode 100644 index 0000000..0389069 --- /dev/null +++ b/CERTInext/API/V2/SslComValidationV2.cs @@ -0,0 +1,318 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Generic; +using System.Globalization; +using System.Linq; +using System.Text.Json; +using System.Text.Json.Serialization; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.API.V2 +{ + // --------------------------------------------------------------------------- + // V2 SSL.com organization validation + // + // GET /api/certinext/v2/organizations/{orgNumber}/ca-validations/sslcom + // POST /api/certinext/v2/organizations/{orgNumber}/ca-validations/sslcom (submit) + // POST /api/certinext/v2/organizations/{orgNumber}/ca-validations/sslcom/sync (refresh) + // + // The spec documents these endpoints only in prose ("Status per level (OV, EV) with validTill, + // what is still missing before it can be submitted, and the SSL.com contact"; the responses are + // untyped `object`). The model below is built from a live read-only sample, so every member is + // optional, unknown members are kept in ExtensionData, and the per-level question ("is OV/EV + // validated?") is answered defensively by V2SslComValidation.IsLevelValidated rather than + // trusted to one field. + // --------------------------------------------------------------------------- + + /// Response body of the SSL.com validation GET / sync / submit calls. + public class V2SslComValidation + { + [JsonPropertyName("ca")] + public string Ca { get; set; } + + [JsonPropertyName("caName")] + public string CaName { get; set; } + + [JsonPropertyName("organizationNumber")] + public string OrganizationNumber { get; set; } + + /// Overall state, e.g. NOT_SUBMITTED. Undocumented vocabulary. + [JsonPropertyName("status")] + public string Status { get; set; } + + /// + /// Per-level state. Seen live as an empty array on a never-submitted organization; the spec + /// says it carries "status per level (OV, EV) with validTill". Kept as raw JSON because the + /// element shape is unconfirmed (objects with a level and a status, or bare level strings); + /// see . + /// + [JsonPropertyName("levels")] + public JsonElement Levels { get; set; } + + /// Levels SSL.com validates for this organization by default (seen live: ["OV"]). + [JsonPropertyName("defaultLevels")] + public List DefaultLevels { get; set; } + + [JsonPropertyName("subscriberAgreementAccepted")] + public bool? SubscriberAgreementAccepted { get; set; } + + [JsonPropertyName("validatedAt")] + public string ValidatedAt { get; set; } + + [JsonPropertyName("submittedAt")] + public string SubmittedAt { get; set; } + + [JsonPropertyName("lastSyncedAt")] + public string LastSyncedAt { get; set; } + + [JsonPropertyName("lastError")] + public string LastError { get; set; } + + [JsonPropertyName("readiness")] + public V2SslComReadiness Readiness { get; set; } + + /// The SSL.com contact. Personal data: never log it unmasked. + [JsonPropertyName("contact")] + public V2SslComContact Contact { get; set; } + + /// Any member this model doesn't know, so a new field never breaks parsing. + [JsonExtensionData] + public Dictionary ExtensionData { get; set; } + + // Words that, as a status, mean the level is validated. Matched case-insensitively and exactly; + // anything else (including not-yet-seen words such as "PENDING" or "SUBMITTED") is "not validated". + private static readonly HashSet ValidatedWords = new HashSet(StringComparer.OrdinalIgnoreCase) + { + "VALIDATED", "VALID", "APPROVED", "ACTIVE", "COMPLETE", "COMPLETED", "ISSUED" + }; + + private static readonly string[] LevelNameKeys = { "level", "name", "type", "levelName", "validationLevel", "id", "code" }; + private static readonly string[] StatusKeys = { "status", "state", "validationStatus" }; + private static readonly string[] ValidTillKeys = { "validTill", "validUntil", "validTo", "expiresAt", "expiry" }; + private static readonly string[] ValidatedFlagKeys = { "validated", "isValidated" }; + + /// + /// True when SSL.com reports ("OV" or "EV") as validated. The shape + /// of is unconfirmed, so this accepts what a per-level entry could + /// reasonably carry and otherwise answers "not validated" (the plugin only warns on that, so + /// the cost of a false negative is a warning, never a blocked order): + /// + /// an array element or a map entry for the level, as an object carrying a status word + /// (see ValidatedWords) or a true validated flag, and not past a validTill; + /// an entry with no status but a future validTill also counts; + /// a bare string element naming the level counts only when the overall + /// is a validated word (the string alone doesn't say what state it is in); + /// a top-level member named after the level (OV/EV), same entry rules. + /// + /// The overall and alone are never enough: they + /// aren't per level. + /// + public bool IsLevelValidated(string level, DateTime? utcNow = null) + { + if (string.IsNullOrWhiteSpace(level)) return false; + DateTime now = utcNow ?? DateTime.UtcNow; + + foreach (var entry in EnumerateLevelEntries(level)) + { + if (entry.ValueKind == JsonValueKind.String) + { + // A bare level name, or a bare status under a level-keyed member. + string text = entry.GetString(); + if (string.Equals(text?.Trim(), level, StringComparison.OrdinalIgnoreCase)) + { + if (IsValidatedWord(Status)) return true; + } + else if (IsValidatedWord(text)) + { + return true; + } + continue; + } + if (entry.ValueKind == JsonValueKind.True) return true; // "OV": true + if (entry.ValueKind != JsonValueKind.Object) continue; + + if (EntryIsValidated(entry, now)) return true; + } + + return false; + } + + /// + /// True when appears in (or as a top-level + /// member) in any state, i.e. it has already been requested from SSL.com. + /// + public bool IsLevelListed(string level) => + !string.IsNullOrWhiteSpace(level) && EnumerateLevelEntries(level).Any(); + + // Entries that talk about `level`: array elements naming it, level-keyed map members, and + // level-keyed top-level members. + private IEnumerable EnumerateLevelEntries(string level) + { + if (Levels.ValueKind == JsonValueKind.Array) + { + foreach (var e in Levels.EnumerateArray()) + { + if (e.ValueKind == JsonValueKind.String) + { + if (string.Equals(e.GetString()?.Trim(), level, StringComparison.OrdinalIgnoreCase)) + yield return e; + } + else if (e.ValueKind == JsonValueKind.Object && ObjectNamesLevel(e, level)) + { + yield return e; + } + } + } + else if (Levels.ValueKind == JsonValueKind.Object) + { + foreach (var p in Levels.EnumerateObject()) + if (string.Equals(p.Name, level, StringComparison.OrdinalIgnoreCase)) + yield return p.Value; + } + + if (ExtensionData != null) + { + foreach (var kv in ExtensionData) + if (string.Equals(kv.Key, level, StringComparison.OrdinalIgnoreCase)) + yield return kv.Value; + } + } + + private static bool ObjectNamesLevel(JsonElement obj, string level) + { + foreach (var key in LevelNameKeys) + if (TryGetString(obj, key, out string v) && string.Equals(v?.Trim(), level, StringComparison.OrdinalIgnoreCase)) + return true; + return false; + } + + private static bool EntryIsValidated(JsonElement entry, DateTime now) + { + // An expiry in the past overrides any status word. + bool hasValidTill = false; + DateTime validTill = default; + foreach (var key in ValidTillKeys) + { + if (TryGetString(entry, key, out string v) && !string.IsNullOrWhiteSpace(v) + && DateTime.TryParse(v, CultureInfo.InvariantCulture, + DateTimeStyles.AdjustToUniversal | DateTimeStyles.AssumeUniversal, out validTill)) + { + hasValidTill = true; + break; + } + } + if (hasValidTill && validTill <= now) return false; + + foreach (var key in ValidatedFlagKeys) + if (TryGetElement(entry, key, out var flag) && flag.ValueKind == JsonValueKind.True) + return true; + + foreach (var key in StatusKeys) + { + if (TryGetString(entry, key, out string status)) + return IsValidatedWord(status); + } + + // No status field at all: a future expiry is the only per-level evidence. + return hasValidTill; + } + + private static bool IsValidatedWord(string value) => + !string.IsNullOrWhiteSpace(value) && ValidatedWords.Contains(value.Trim()); + + private static bool TryGetElement(JsonElement obj, string name, out JsonElement value) + { + foreach (var p in obj.EnumerateObject()) + { + if (string.Equals(p.Name, name, StringComparison.OrdinalIgnoreCase)) + { + value = p.Value; + return true; + } + } + value = default; + return false; + } + + private static bool TryGetString(JsonElement obj, string name, out string value) + { + value = null; + if (!TryGetElement(obj, name, out var el)) return false; + if (el.ValueKind == JsonValueKind.String) { value = el.GetString(); return true; } + return false; + } + } + + /// The readiness block: what is still missing before the organization can be submitted. + public class V2SslComReadiness + { + /// The organization has what an OV submission needs. + [JsonPropertyName("ready")] + public bool? Ready { get; set; } + + /// The organization has what an EV submission needs. + [JsonPropertyName("evReady")] + public bool? EvReady { get; set; } + + /// Field names still missing for OV (blocking). + [JsonPropertyName("missing")] + public List Missing { get; set; } + + /// Field names still missing for EV (blocking). + [JsonPropertyName("evMissing")] + public List EvMissing { get; set; } + + /// Field names that are advisable but not blocking. + [JsonPropertyName("softMissing")] + public List SoftMissing { get; set; } + + /// Echo of the organization's current values; never read or logged by the plugin. + [JsonExtensionData] + public Dictionary ExtensionData { get; set; } + } + + /// The SSL.com contact. Personal data. + public class V2SslComContact + { + [JsonPropertyName("name")] + public string Name { get; set; } + + [JsonPropertyName("title")] + public string Title { get; set; } + + [JsonPropertyName("email")] + public string Email { get; set; } + + [JsonPropertyName("companyNumber")] + public string CompanyNumber { get; set; } + + [JsonExtensionData] + public Dictionary ExtensionData { get; set; } + } + + /// + /// Request body of POST .../ca-validations/sslcom (spec prose): levels (["OV"], + /// ["EV"] or both; empty = the organization's default), subscriberAgreementAccepted (must be + /// true) and an optional adminEmail. The spec's other fields (organizationPhone, + /// businessCategoryId, registrationNumber, contactTitle, "only where the + /// organization lacks them") are deliberately not sent: the plugin only submits when the + /// readiness block says nothing is missing. + /// + public class V2SslComSubmitRequest + { + [JsonPropertyName("levels")] + public List Levels { get; set; } + + [JsonPropertyName("subscriberAgreementAccepted")] + public bool SubscriberAgreementAccepted { get; set; } + + [JsonPropertyName("adminEmail")] + [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)] + public string AdminEmail { get; set; } + } +} diff --git a/CERTInext/CERTInext.csproj b/CERTInext/CERTInext.csproj index f683ea8..50252af 100644 --- a/CERTInext/CERTInext.csproj +++ b/CERTInext/CERTInext.csproj @@ -7,26 +7,24 @@ warnings 12.0 - false + true $(DefineConstants);SUPPORTS_DCV true - + matches the gateway host: 3.3.0 (DCV / 26.x hosts) by + default, or 3.2.0 (no-DCV / 25.5.x hosts) with -p:DcvSupport=false. The 3.3-only + IDomainValidatorFactory is only referenced from #if SUPPORTS_DCV code, so the DcvSupport=false + 3.2.0 build compiles cleanly. --> + diff --git a/CERTInext/CERTInextCAPlugin.cs b/CERTInext/CERTInextCAPlugin.cs index 231f611..9b5a48c 100644 --- a/CERTInext/CERTInextCAPlugin.cs +++ b/CERTInext/CERTInextCAPlugin.cs @@ -1,4 +1,4 @@ -// Copyright 2024 Keyfactor +// Copyright 2026 Keyfactor // Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. // You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 // Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, @@ -14,6 +14,7 @@ using System.Threading.Tasks; using Keyfactor.AnyGateway.Extensions; using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; using Keyfactor.Extensions.CAPlugin.CERTInext.Client; using Keyfactor.Extensions.CAPlugin.CERTInext.Models; using Keyfactor.Logging; @@ -34,6 +35,9 @@ public class CERTInextCAPlugin : IAnyCAPlugin, IDisposable { private readonly ILogger _logger = LogHandler.GetClassLogger(); + // 1 once the "Private PKI ignores V2InlineCsr" notice has been logged (once per plugin instance). + private int _loggedPrivatePkiIgnoresInlineCsr; + private CERTInextConfig _config; private ICERTInextClient _client; private ICertificateDataReader _certificateDataReader; @@ -129,16 +133,32 @@ internal CERTInextCAPlugin(ICERTInextClient client, ICertificateDataReader certD _config = new CERTInextConfig(); } + /// + /// Internal test-injection constructor — client, certificate-data reader and config, for + /// tests that must control the gateway's stored-certificate view (the bodyless-REVOKED + /// guard, renewals) as well as config such as PickupRetries. + /// + internal CERTInextCAPlugin(ICERTInextClient client, ICertificateDataReader certDataReader, CERTInextConfig config) + { + _client = client; + _clientWasInjected = true; + _certificateDataReader = certDataReader; + _config = config ?? new CERTInextConfig(); + } + /// /// Internal test-injection constructor — pass a mock /// and a specific for tests that need to override - /// configuration fields such as IgnoreExpired. + /// configuration fields such as IgnoreExpired. + /// is optional (defaults to null) and lets tests exercise the bodyless-REVOKED + /// guard, which consults . /// - internal CERTInextCAPlugin(ICERTInextClient client, CERTInextConfig config) + internal CERTInextCAPlugin(ICERTInextClient client, CERTInextConfig config, ICertificateDataReader certDataReader = null) { _client = client; _clientWasInjected = true; _config = config ?? new CERTInextConfig(); + _certificateDataReader = certDataReader; } /// @@ -229,6 +249,34 @@ public void Initialize(IAnyCAPluginConfigProvider configProvider, ICertificateDa _config = JsonSerializer.Deserialize(rawConfig) ?? throw new InvalidOperationException("Failed to deserialize CERTInext plugin configuration."); + // Compliance gap fix: ValidateCAConnectionInfo enforces https-or-loopback on ApiUrl + // (and, in V1 OAuth mode, OAuthTokenUrl) at connection-test time, but a connector + // saved before that enforcement existed would otherwise sail straight through here + // on every gateway restart and keep sending its API key / OAuth client secret in + // cleartext. Re-check the config itself (not just the client we're about to build) + // before any client is built or used — this applies even when a test has already + // injected a mock client via `_client ??=` below, because the gap is in the saved + // config, not in which ICERTInextClient instance ends up talking to it. + void EnsureValidUrl(string fieldName, string url, string requiredSuffix) + { + string error = string.IsNullOrWhiteSpace(url) + ? $"'{fieldName}' is required{requiredSuffix}." + : ValidateHttpsOrLoopbackUrl(fieldName, url); + if (error == null) + return; + + _logger.LogError( + "CERTInext plugin initialization failed — invalid configuration. {Error}", error); + throw new InvalidOperationException(error); + } + + EnsureValidUrl(Constants.Config.ApiUrl, _config.ApiUrl, string.Empty); + + string authModeUpper = (_config.AuthMode ?? string.Empty).Trim().ToUpperInvariant(); + bool isV1OAuth = !_config.UseV2Api && (authModeUpper == "OAUTH" || authModeUpper == "OAUTH2"); + if (isV1OAuth) + EnsureValidUrl(Constants.Config.OAuth2TokenUrl, _config.OAuth2TokenUrl, " when AuthMode is 'OAuth'"); + // Only create a real client if one wasn't injected (test scenario) _client ??= new CERTInextClient(_config); @@ -240,6 +288,13 @@ public void Initialize(IAnyCAPluginConfigProvider configProvider, ICertificateDa bool hasClientId = !string.IsNullOrWhiteSpace(_config.OAuth2ClientId); bool hasClientSecret= !string.IsNullOrWhiteSpace(_config.OAuth2ClientSecret); bool hasTokenUrl = !string.IsNullOrWhiteSpace(_config.OAuth2TokenUrl); + bool hasOrganizationNumber = !string.IsNullOrWhiteSpace(_config.OrganizationNumber); + bool hasDefaultProductCode = !string.IsNullOrWhiteSpace(_config.DefaultProductCode); + bool hasGroupNumber = !string.IsNullOrWhiteSpace(_config.GroupNumber); + + int effectivePickupRetries = _config.GetEffectivePickupRetries(); + int effectivePickupDelay = _config.GetEffectivePickupDelaySeconds(); + string preVettingMode = hasOrganizationNumber ? "1 (use pre-vetted org)" : "omitted (no org configured)"; _logger.LogInformation( "CERTInext plugin initialized. " + @@ -247,16 +302,36 @@ public void Initialize(IAnyCAPluginConfigProvider configProvider, ICertificateDa "ApiKeyPresent={ApiKeyPresent}, UsernamePresent={UsernamePresent}, " + "PasswordPresent={PasswordPresent}, OAuth2ClientIdPresent={OAuth2ClientIdPresent}, " + "OAuth2ClientSecretPresent={OAuth2ClientSecretPresent}, OAuth2TokenUrlPresent={OAuth2TokenUrlPresent}, " + - "PageSize={PageSize}, IgnoreExpired={IgnoreExpired}, " + + "OrganizationNumber={OrganizationNumber}, PreVetting={PreVetting}, " + + "DefaultProductCode={DefaultProductCode}, GroupNumber={GroupNumber}, " + + "AccountingModel={AccountingModel}, EmailNotifications={EmailNotifications}, " + + "AutoSecureWww={AutoSecureWww}, ValidityYears={ValidityYears}, " + + "AutoRenew={AutoRenew}, RenewCriteriaDays={RenewCriteriaDays}, " + + "PageSize={PageSize}, IgnoreExpired={IgnoreExpired}, SubmitNonDnsSans={SubmitNonDnsSans}, " + + "PickupRetries={PickupRetries}, PickupDelay={PickupDelay}, " + "DcvEnabled={DcvEnabled}, DcvTxtRecordTemplate={DcvTxtRecordTemplate}, " + - "DomainValidatorFactoryInjected={FactoryInjected}", + "DcvPropagationDelaySeconds={DcvPropagationDelay}, DcvTimeoutMinutes={DcvTimeout}, " + + "DcvWaitForChallengeSeconds={DcvWaitChallenge}, DcvWaitForIssuanceSeconds={DcvWaitIssuance}, " + + "DomainValidatorFactoryInjected={FactoryInjected}, LogSensitiveRequestData={LogSensitiveRequestData}", _config.ApiUrl, _config.AuthMode, _config.Enabled, hasApiKey, hasUsername, hasPassword, hasClientId, hasClientSecret, hasTokenUrl, - _config.PageSize, _config.IgnoreExpired, + hasOrganizationNumber ? _config.OrganizationNumber : "(not configured)", preVettingMode, + hasDefaultProductCode ? _config.DefaultProductCode : "(not configured)", + hasGroupNumber ? _config.GroupNumber : "(not configured)", + string.IsNullOrWhiteSpace(_config.AccountingModel) ? "2 (default)" : _config.AccountingModel, + string.IsNullOrWhiteSpace(_config.EmailNotifications) ? "0 (default)" : _config.EmailNotifications, + string.IsNullOrWhiteSpace(_config.AutoSecureWww) ? "0 (default)" : _config.AutoSecureWww, + string.IsNullOrWhiteSpace(_config.SubscriptionValidityYears) ? "1 (default)" : _config.SubscriptionValidityYears, + string.IsNullOrWhiteSpace(_config.SubscriptionAutoRenew) ? "0 (default)" : _config.SubscriptionAutoRenew, + string.IsNullOrWhiteSpace(_config.SubscriptionRenewCriteriaDays) ? "30 (default)" : _config.SubscriptionRenewCriteriaDays, + _config.PageSize, _config.IgnoreExpired, _config.SubmitNonDnsSans, + effectivePickupRetries, effectivePickupDelay, _config.DcvEnabled, _config.DcvTxtRecordTemplate, - _domainValidatorFactory != null); + _config.DcvPropagationDelaySeconds, _config.DcvTimeoutMinutes, + _config.DcvWaitForChallengeSeconds, _config.DcvWaitForIssuanceSeconds, + _domainValidatorFactory != null, _config.LogSensitiveRequestData); // SOC2 CC7.1: surface silent functional downgrades. If DCV is enabled in // config but no factory was injected (e.g. v3.2 gateway host), DCV will be @@ -271,6 +346,30 @@ public void Initialize(IAnyCAPluginConfigProvider configProvider, ICertificateDa "gateway image that supplies the factory, or set DcvEnabled=false to clear " + "this warning."); } + + // Audit trail: this is the one place that records sensitive-data logging + // was switched on, so a reviewer scanning gateway logs can see exactly when it started + // (and, from the absence of a corresponding line on a later restart, when it stopped). + // Audit trail: this setting makes the plugin accept SSL.com's subscriber agreement on an + // organization's behalf during OV/EV enrollment, so its state is recorded on every start. + if (_config.UseV2Api && _config.SslComSubmitOrganization) + { + _logger.LogWarning( + "SslComSubmitOrganization=true — OV/EV enrollments for an organization that SSL.com has not " + + "validated will submit it to SSL.com, which ACCEPTS SSL.COM'S SUBSCRIBER AGREEMENT ON THE " + + "ORGANIZATION'S BEHALF. Each acceptance is audit-logged. AdminEmailConfigured={AdminEmailConfigured}", + !string.IsNullOrWhiteSpace(_config.SslComAdminEmail)); + } + + if (_config.LogSensitiveRequestData) + { + _logger.LogWarning( + "LogSensitiveRequestData=true — this CERTInext connector will write requestor " + + "personal data (name, email, phone, and other organization contact details) and " + + "full CA request/response payloads to the gateway logs. This is intended for " + + "temporary use while verifying a new deployment; turn it back off once " + + "verification is complete."); + } _logger.MethodExit(LogLevel.Debug); } @@ -330,15 +429,24 @@ public async Task Ping() try { - await _client.PingAsync(); - // SOC2 CC9.2: connectivity confirmation is a security-relevant event; must be - // at Information so it survives production log filters. - _logger.LogInformation("CERTInext ping successful. ApiUrl={ApiUrl}", _config.ApiUrl); + if (_config.UseV2Api) + { + await _client.PingV2Async(); + _logger.LogInformation("CERTInext V2 ping successful. ApiUrl={ApiUrl}", _config.ApiUrl); + } + else + { + await _client.PingAsync(); + // SOC2 CC9.2: connectivity confirmation is a security-relevant event; must be + // at Information so it survives production log filters. + _logger.LogInformation("CERTInext ping successful. ApiUrl={ApiUrl}", _config.ApiUrl); + } } catch (Exception ex) { - _logger.LogError(ex, "CERTInext ping failed. ApiUrl={ApiUrl}", _config.ApiUrl); - throw new Exception($"Unable to reach CERTInext at {_config.ApiUrl}: {ex.Message}", ex); + string url = _config.ApiUrl; + _logger.LogError(ex, "CERTInext ping failed. Url={Url}, UseV2Api={UseV2Api}", url, _config.UseV2Api); + throw new Exception($"Unable to reach CERTInext at {url}: {ex.Message}", ex); } finally { @@ -346,6 +454,27 @@ public async Task Ping() } } + /// True for a bool or a JSON true/false element (a string would fail config deserialization). + /// True for a plausible single email address: one '@', no whitespace, text on both sides, a dot in the domain. + internal static bool LooksLikeEmailAddress(string value) + { + if (string.IsNullOrWhiteSpace(value)) return false; + string v = value.Trim(); + if (v.Any(char.IsWhiteSpace)) return false; + int at = v.IndexOf('@'); + if (at <= 0 || at != v.LastIndexOf('@') || at == v.Length - 1) return false; + string domain = v.Substring(at + 1); + return domain.Contains('.') && !domain.StartsWith(".") && !domain.EndsWith("."); + } + + internal static bool IsBooleanSettingValue(object value) + { + if (value is bool) return true; + if (value is System.Text.Json.JsonElement je) + return je.ValueKind == System.Text.Json.JsonValueKind.True || je.ValueKind == System.Text.Json.JsonValueKind.False; + return false; + } + /// public async Task ValidateCAConnectionInfo(Dictionary connectionInfo) { @@ -373,44 +502,128 @@ public async Task ValidateCAConnectionInfo(Dictionary connection var errors = new List(); - // ApiUrl and AccountNumber are always required + // ApiUrl is always required in both modes — its meaning follows UseV2Api (V1 base + // URL incl. /emSignHub-API vs the bare V2 host). string apiUrl = GetStringValue(connectionInfo, Constants.Config.ApiUrl); if (string.IsNullOrWhiteSpace(apiUrl)) errors.Add($"'{Constants.Config.ApiUrl}' is required."); - else if (!Uri.TryCreate(apiUrl, UriKind.Absolute, out _)) - errors.Add($"'{Constants.Config.ApiUrl}' is not a valid absolute URI."); - - string accountNumber = GetStringValue(connectionInfo, Constants.Config.AccountNumber); - if (string.IsNullOrWhiteSpace(accountNumber)) - errors.Add($"'{Constants.Config.AccountNumber}' is required."); - - // Auth mode — validate the required credentials for the chosen mode - string authMode = GetStringValue(connectionInfo, Constants.Config.AuthMode, Constants.Config.AuthModeAccessKey); - switch (authMode.ToUpperInvariant()) - { - case "ACCESSKEY": - case "APIKEY": // legacy alias - string apiKey = GetStringValue(connectionInfo, Constants.Config.ApiKey); - if (string.IsNullOrWhiteSpace(apiKey)) - errors.Add($"'{Constants.Config.ApiKey}' is required when AuthMode is 'AccessKey'."); - break; + else + { + // The OAuth client secret (V2) / API key (V1) is sent to this URL on every + // request; http would transmit it in cleartext. http is allowed only for + // loopback hosts (localhost/127.0.0.1/::1) so local mock-server tests keep + // working without a real TLS endpoint. Shared with the OAuthTokenUrl check + // below and with Initialize's config-time enforcement of the same rule. + string apiUrlError = ValidateHttpsOrLoopbackUrl(Constants.Config.ApiUrl, apiUrl); + if (apiUrlError != null) + errors.Add(apiUrlError); + } - case "OAUTH": - case "OAUTH2": - string tokenUrl = GetStringValue(connectionInfo, Constants.Config.OAuth2TokenUrl); - string clientId = GetStringValue(connectionInfo, Constants.Config.OAuth2ClientId); - string clientSecret = GetStringValue(connectionInfo, Constants.Config.OAuth2ClientSecret); - if (string.IsNullOrWhiteSpace(tokenUrl)) - errors.Add($"'{Constants.Config.OAuth2TokenUrl}' is required when AuthMode is 'OAuth'."); - if (string.IsNullOrWhiteSpace(clientId)) - errors.Add($"'{Constants.Config.OAuth2ClientId}' is required when AuthMode is 'OAuth'."); - if (string.IsNullOrWhiteSpace(clientSecret)) - errors.Add($"'{Constants.Config.OAuth2ClientSecret}' is required when AuthMode is 'OAuth'."); - break; + bool useV2 = connectionInfo.TryGetValue(Constants.ConfigV2.UseV2Api, out object v2Obj) + && v2Obj is bool v2Bool && v2Bool; - default: - errors.Add($"'{Constants.Config.AuthMode}' must be one of: AccessKey, OAuth. Got: '{authMode}'."); - break; + if (useV2) + { + // V2 mode: OAuth2 client_credentials against {ApiUrl}/oauth/token, reusing the + // same OAuthClientId/OAuthClientSecret fields V1's AuthMode=OAuth uses. V1-only + // credentials (AccountNumber, AuthMode, ApiKey, ...) are NOT required here — the + // V1 AuthMode switch below is skipped entirely. + string oauthClientId = GetStringValue(connectionInfo, Constants.Config.OAuthClientId); + string oauthClientSecret = GetStringValue(connectionInfo, Constants.Config.OAuthClientSecret); + + if (string.IsNullOrWhiteSpace(oauthClientId)) + errors.Add($"'{Constants.Config.OAuthClientId}' is required when UseV2Api is true."); + + if (string.IsNullOrWhiteSpace(oauthClientSecret)) + errors.Add($"'{Constants.Config.OAuthClientSecret}' is required when UseV2Api is true."); + + // Every V2 SSL create order sends an `agreement` block, and the V2 spec marks + // agreement.signerPlace "Conditional - required if `agreement` sent". Required + // at the connector level (user decision) even though a per-template SignerPlace + // enrollment parameter can override it — EnrollV2Async also fails fast if the + // resolved value is blank. + string signerPlace = GetStringValue(connectionInfo, Constants.Config.SignerPlace); + if (string.IsNullOrWhiteSpace(signerPlace)) + errors.Add($"'{Constants.Config.SignerPlace}' is required when UseV2Api is true — the CERTInext " + + "V2 Subscriber Agreement sent with every SSL order requires the signing place " + + "(city/location, e.g. 'San Francisco, CA')."); + } + else + { + // V1 mode: AccountNumber is always required, plus whatever the selected AuthMode needs. + string accountNumber = GetStringValue(connectionInfo, Constants.Config.AccountNumber); + if (string.IsNullOrWhiteSpace(accountNumber)) + errors.Add($"'{Constants.Config.AccountNumber}' is required."); + + string authMode = GetStringValue(connectionInfo, Constants.Config.AuthMode, Constants.Config.AuthModeAccessKey); + switch (authMode.ToUpperInvariant()) + { + case "ACCESSKEY": + case "APIKEY": // legacy alias + string apiKey = GetStringValue(connectionInfo, Constants.Config.ApiKey); + if (string.IsNullOrWhiteSpace(apiKey)) + errors.Add($"'{Constants.Config.ApiKey}' is required when AuthMode is 'AccessKey'."); + break; + + case "OAUTH": + case "OAUTH2": + string tokenUrl = GetStringValue(connectionInfo, Constants.Config.OAuth2TokenUrl); + string clientId = GetStringValue(connectionInfo, Constants.Config.OAuth2ClientId); + string clientSecret = GetStringValue(connectionInfo, Constants.Config.OAuth2ClientSecret); + if (string.IsNullOrWhiteSpace(tokenUrl)) + errors.Add($"'{Constants.Config.OAuth2TokenUrl}' is required when AuthMode is 'OAuth'."); + else + { + // The OAuth client secret is POSTed to this URL on every token + // refresh (CERTInextClient.GetOrRefreshTokenAsync) — same cleartext- + // credential exposure as ApiUrl, so it gets the same https-or-loopback + // rule. + string tokenUrlError = ValidateHttpsOrLoopbackUrl(Constants.Config.OAuth2TokenUrl, tokenUrl); + if (tokenUrlError != null) + errors.Add(tokenUrlError); + } + if (string.IsNullOrWhiteSpace(clientId)) + errors.Add($"'{Constants.Config.OAuth2ClientId}' is required when AuthMode is 'OAuth'."); + if (string.IsNullOrWhiteSpace(clientSecret)) + errors.Add($"'{Constants.Config.OAuth2ClientSecret}' is required when AuthMode is 'OAuth'."); + break; + + default: + errors.Add($"'{Constants.Config.AuthMode}' must be one of: AccessKey, OAuth. Got: '{authMode}'."); + break; + } + } + + // V2InlineCsr is a Boolean setting (V2 only): reject a value that is not true/false instead of + // letting it fail later at configuration load. + if (connectionInfo.TryGetValue(Constants.Config.V2InlineCsr, out object inlineCsrObj) && inlineCsrObj != null + && !IsBooleanSettingValue(inlineCsrObj)) + { + errors.Add($"'{Constants.Config.V2InlineCsr}' must be true or false. Got: '{inlineCsrObj}'."); + } + else if (!useV2 && inlineCsrObj != null + && (inlineCsrObj is bool inlineOn ? inlineOn + : inlineCsrObj is System.Text.Json.JsonElement inlineJe && inlineJe.ValueKind == System.Text.Json.JsonValueKind.True)) + { + _logger.LogWarning( + "'{Setting}' is true but UseV2Api is false: the setting only applies to the V2 API and is ignored.", + Constants.Config.V2InlineCsr); + } + + // SslComSubmitOrganization is a Boolean (V2 only), validated like V2InlineCsr. It accepts a + // third party's subscriber agreement on the organization's behalf, so a malformed value must + // not silently fall back to anything. + if (connectionInfo.TryGetValue(Constants.Config.SslComSubmitOrganization, out object sslComSubmitObj) + && sslComSubmitObj != null && !IsBooleanSettingValue(sslComSubmitObj)) + { + errors.Add($"'{Constants.Config.SslComSubmitOrganization}' must be true or false. Got: '{sslComSubmitObj}'."); + } + + // SslComAdminEmail, when set, must look like one email address (it is sent to SSL.com). + string sslComAdminEmail = GetStringValue(connectionInfo, Constants.Config.SslComAdminEmail); + if (!string.IsNullOrWhiteSpace(sslComAdminEmail) && !LooksLikeEmailAddress(sslComAdminEmail)) + { + errors.Add($"'{Constants.Config.SslComAdminEmail}' must be a single email address (for example admin@example.com), or blank."); } if (errors.Any()) @@ -430,9 +643,14 @@ public async Task ValidateCAConnectionInfo(Dictionary connection // Build a transient config from the supplied connectionInfo so we don't // rely on the already-initialized _client (which may hold stale creds) string rawConfig = JsonSerializer.Serialize(connectionInfo); - tempConfig = JsonSerializer.Deserialize(rawConfig); + tempConfig = JsonSerializer.Deserialize(rawConfig) + ?? throw new InvalidOperationException("Failed to deserialize connection info."); tempClient = new CERTInextClient(tempConfig); - await tempClient.PingAsync(); + + if (tempConfig.UseV2Api) + await tempClient.PingV2Async(); + else + await tempClient.PingAsync(); } catch (Exception ex) { @@ -441,8 +659,8 @@ public async Task ValidateCAConnectionInfo(Dictionary connection _logger.LogError( ex, "CA connection validation failed — live connectivity test unsuccessful. " + - "ApiUrl={ApiUrl}, AuthMode={AuthMode}", - attemptedApiUrl, attemptedAuthMode); + "ApiUrl={ApiUrl}, UseV2Api={UseV2Api}, AuthMode={AuthMode}", + attemptedApiUrl, tempConfig?.UseV2Api ?? false, attemptedAuthMode); // The inner exception message is NOT forwarded to the AnyCAValidationException // because it may contain HTTP response bodies or header fragments from the @@ -464,6 +682,7 @@ public async Task ValidateCAConnectionInfo(Dictionary connection tempConfig.OAuthClientSecret = string.Empty; tempConfig.Password = string.Empty; } + tempClient?.Dispose(); } _logger.LogInformation( @@ -478,17 +697,22 @@ public async Task ValidateProductInfo(EnrollmentProductInfo productInfo, Diction _logger.MethodEntry(LogLevel.Debug); string rawConfig = JsonSerializer.Serialize(connectionInfo); - var tempConfig = JsonSerializer.Deserialize(rawConfig); - var tempClient = new CERTInextClient(tempConfig); + var tempConfig = JsonSerializer.Deserialize(rawConfig) + ?? throw new InvalidOperationException("Failed to deserialize connection info."); + bool useV2 = tempConfig.UseV2Api; var params_ = new EnrollmentParams(productInfo); string profileId = params_.ProfileId; - _logger.LogInformation( - "Product/profile validation attempt started. ProfileId={ProfileId}, ProductID={ProductID}", - profileId, productInfo?.ProductID); + // On V2 the template's ProductCode is an optional override (sent as X-Product-Code + // only when set); without one CERTInext's wrapper resolves the product itself, so + // there is nothing to require here. params_.ProfileId must not be used for V2 in that + // case: its fallback is the V1-era code table. + bool v2WithoutProductCode = useV2 && !params_.HasExplicitProductCode; + if (v2WithoutProductCode) + profileId = null; - if (string.IsNullOrWhiteSpace(profileId)) + if (string.IsNullOrWhiteSpace(profileId) && !v2WithoutProductCode) { _logger.LogWarning( "Product/profile validation failed — ProfileId parameter is missing or empty. ProductID={ProductID}", @@ -497,20 +721,174 @@ public async Task ValidateProductInfo(EnrollmentProductInfo productInfo, Diction $"Template parameter '{Constants.EnrollmentParam.ProfileId}' is required but was not set."); } + _logger.LogInformation( + "Product/profile validation attempt started. ProfileId={ProfileId}, ProductID={ProductID}, UseV2Api={UseV2Api}", + v2WithoutProductCode ? "(none — CERTInext resolves the product)" : profileId, productInfo?.ProductID, useV2); + + bool isPrivatePki = useV2 + && string.Equals(params_.ProductFamilySlug, Constants.ApiV2.FamilyPrivatePki, StringComparison.Ordinal); + // Gate the SSL-only ProductVariant cross-check below on the SSL family specifically + // (not just "!isPrivatePki") so a signature (Document Signer) template — which has + // no productVariant concept — is left unaffected. + bool isSsl = useV2 + && string.Equals(params_.ProductFamilySlug, Constants.ApiV2.FamilySsl, StringComparison.Ordinal); + + var tempClient = new CERTInextClient(tempConfig); + try { - var profiles = await tempClient.GetProfilesAsync(); - bool found = profiles.Any(p => - string.Equals(p.Id, profileId, StringComparison.OrdinalIgnoreCase)); + // A V2 private-pki template needs a Private PKI ProductVariant — checked before any + // catalog call, with the same rules EnrollV2Async enforces, so a template that can + // never enroll is rejected at save time. Inside the try so the finally block's + // credential scrubbing still runs. + if (isPrivatePki) + { + string pkiConfigError = ValidatePrivatePkiEnrollmentParams(params_, out _); + if (pkiConfigError != null) + { + _logger.LogWarning( + "Product/profile validation failed — {Reason} ProductID={ProductID}", + pkiConfigError, params_.ProductId); + throw new AnyCAValidationException(pkiConfigError); + } + } + + // An SSL template's explicit ProductVariant must agree with the + // product it's paired with — checked before any catalog call, same fail-fast + // placement as the private-pki check above, so a template that would silently + // send a DV-shaped body for an OV/EV product (or vice versa) is rejected at save + // time instead of at enroll. + if (isSsl) + { + string variantError = ResolveSslProductVariant(params_, out _); + if (variantError != null) + { + _logger.LogWarning( + "Product/profile validation failed — {Reason} ProductID={ProductID}", + variantError, params_.ProductId); + throw new AnyCAValidationException(variantError); + } + } + + // V2 catalog validation mirrors ValidateCAConnectionInfo's UseV2Api branch: + // GetProfilesAsync/GetProductDetailsAsync are V1-only and 404 against a + // V2-shaped ApiUrl. There is no soft-accept difference between modes + // — an empty/unusable catalog is treated as "not found", same as V1. + List availableIds; + bool found; + + if (v2WithoutProductCode) + { + // No explicit ProductCode: no X-Product-Code header is sent at enroll time and + // CERTInext's wrapper picks the product from the variant, wildcard shape and + // additional domains, so there is no code to look up in the catalog (and an + // ambiguous catalog match is no longer a template error). The ProductVariant + // and private-pki checks above already ran. + _logger.LogInformation( + "Product/profile validation: no explicit ProductCode on the V2 template, so no catalog " + + "check is needed; CERTInext resolves the product at order time. ProductID={ProductID}", + params_.ProductId); + availableIds = new List(); + found = true; + } + else if (useV2) + { + var products = await tempClient.GetProductDetailsV2Async(); + availableIds = products.Select(p => p.ProductCode).ToList(); + + if (isPrivatePki) + { + // The SSL ProductId -> productTypeID cross-check below would + // always reject a Private PKI code (GetProductIds only advertises SSL/TLS + // product names). Check the code against the spec's Private PKI + // productTypeID instead ("39" | Private PKI | Private PKI (8)). + var matchedProduct = products.FirstOrDefault(p => + string.Equals(p.ProductCode, profileId, StringComparison.OrdinalIgnoreCase)); + + if (matchedProduct == null) + { + var available = string.Join(", ", availableIds); + _logger.LogWarning( + "Product/profile validation failed — configured private-pki ProductCode '{ProfileId}' " + + "was not found in the CERTInext V2 catalog. AvailableCount={AvailableCount}", + profileId, availableIds.Count); + throw new AnyCAValidationException( + $"ProductCode '{profileId}' was not found in the CERTInext V2 catalog. " + + $"Available codes: {available}"); + } + + if (!string.Equals(matchedProduct.ProductTypeId, Constants.ApiV2.PrivatePkiProductTypeId, StringComparison.OrdinalIgnoreCase)) + { + _logger.LogWarning( + "Product/profile validation failed — configured ProductCode '{ProfileId}' exists in the " + + "CERTInext V2 catalog, but its productTypeID ('{ActualTypeId}') is not the Private PKI " + + "productTypeID ('{ExpectedTypeId}') while ProductFamily is 'private-pki'.", + profileId, matchedProduct.ProductTypeId, Constants.ApiV2.PrivatePkiProductTypeId); + throw new AnyCAValidationException( + $"ProductCode '{profileId}' exists in the CERTInext catalog, but it is not a Private PKI " + + "product, and the template's ProductFamily is 'private-pki'. Set ProductCode to a Private " + + "PKI product code from your account's catalog, or correct ProductFamily."); + } + + found = true; + } + else + { + // Explicit override (the no-ProductCode case was handled above): the code must exist in the catalog AND the matched + // catalog entry's productTypeID must actually correspond to the selected + // ProductId — not just "does this code exist as *some* product". A code + // can exist and still mean a different, wrong-assurance-level product than + // the one the administrator selected. + var matchedProduct = products.FirstOrDefault(p => + string.Equals(p.ProductCode, profileId, StringComparison.OrdinalIgnoreCase)); + + if (matchedProduct == null) + { + var available = string.Join(", ", availableIds); + _logger.LogWarning( + "Product/profile validation failed — configured ProductCode '{ProfileId}' was not " + + "found in the CERTInext V2 catalog. ProductID={ProductID}, AvailableCount={AvailableCount}", + profileId, params_.ProductId, availableIds.Count); + throw new AnyCAValidationException( + $"ProductCode '{profileId}' was not found in the CERTInext V2 catalog. " + + $"Available codes: {available}"); + } + + if (Constants.Products.ProductTypeIdsV2.TryGetValue(params_.ProductId ?? string.Empty, out string expectedTypeId) + && !string.Equals(matchedProduct.ProductTypeId, expectedTypeId, StringComparison.OrdinalIgnoreCase)) + { + _logger.LogWarning( + "Product/profile validation failed — configured ProductCode '{ProfileId}' exists in " + + "the CERTInext V2 catalog, but its catalog productTypeID ('{ActualTypeId}') does not " + + "match the selected ProductID '{ProductID}' (expected productTypeID '{ExpectedTypeId}'). " + + "This template would order a different product than the one selected.", + profileId, matchedProduct.ProductTypeId, params_.ProductId, expectedTypeId); + throw new AnyCAValidationException( + $"ProductCode '{profileId}' exists in the CERTInext catalog, but it does not " + + $"correspond to the selected product '{params_.ProductId}'. Verify the ProductCode " + + "override is correct for this product, or remove the override and let CERTInext " + + "resolve the product from the order shape."); + } + + found = true; + } + } + else + { + var profiles = await tempClient.GetProfilesAsync(); + availableIds = profiles.Select(p => p.Id).ToList(); + found = profiles.Any(p => + string.Equals(p.Id, profileId, StringComparison.OrdinalIgnoreCase)); + } if (!found) { - var available = string.Join(", ", profiles.Select(p => p.Id)); + var available = string.Join(", ", availableIds); // SOC2 CC7.2: log profile probe misses at Warning to support anomaly detection. _logger.LogWarning( "Product/profile validation failed — ProfileId not found in CERTInext. " + - "ProfileId={ProfileId}, AvailableCount={AvailableCount}", - profileId, profiles.Count); + "ProfileId={ProfileId}, AvailableCount={AvailableCount}, UseV2Api={UseV2Api}", + profileId, availableIds.Count, useV2); throw new AnyCAValidationException( $"Profile '{profileId}' was not found in CERTInext. " + $"Available profiles: {available}"); @@ -541,9 +919,12 @@ public async Task ValidateProductInfo(EnrollmentProductInfo productInfo, Diction tempConfig.OAuthClientSecret = string.Empty; tempConfig.Password = string.Empty; } + tempClient?.Dispose(); } - _logger.LogInformation("Product/profile validation succeeded. ProfileId={ProfileId}", profileId); + _logger.LogInformation( + "Product/profile validation succeeded. ProfileId={ProfileId}, UseV2Api={UseV2Api}", + profileId, useV2); _logger.MethodExit(LogLevel.Debug); } @@ -566,47 +947,72 @@ public async Task Enroll( // SOX / SOC2 CC7.3: log the enrollment attempt with full identifying context // so the event is independently auditable before any API call is made. - string sanSummary = san != null && san.Count > 0 - ? string.Join("; ", san.SelectMany(kvp => (kvp.Value ?? Array.Empty()) - .Select(v => $"{kvp.Key}:{v}"))) - : "(none)"; - - _logger.LogInformation( - "Enrollment attempt started. " + - "EnrollmentType={EnrollmentType}, Subject={Subject}, " + - "ProfileId={ProfileId}, SANs={SANs}, " + - "RequesterName={RequesterName}, RequesterEmail={RequesterEmail}", - enrollmentType, subject, - ep.ProfileId, sanSummary, - ep.RequesterName, ep.RequesterEmail); + // Email-type SAN values are personal data, masked unless LogSensitiveRequestData + // is on; DNS/IP/URI values stay verbatim as audit fields. + string sanSummary = LogSanitizer.FormatSans(san, _config.LogSensitiveRequestData); + + // RequesterName/RequesterEmail are personal data belonging to whoever placed the + // order. Off by default (LogSensitiveRequestData=false) — the name is dropped from + // the line entirely and the email is masked to keep only its domain. On, both fields + // are logged in full, for deployment verification. + if (_config.LogSensitiveRequestData) + { + _logger.LogInformation( + "Enrollment attempt started. " + + "EnrollmentType={EnrollmentType}, RequestFormat={RequestFormat}, Subject={Subject}, " + + "ProfileId={ProfileId}, SANs={SANs}, " + + "RequesterName={RequesterName}, RequesterEmail={RequesterEmail}", + enrollmentType, requestFormat, LogSanitizer.Strip(subject), + ep.ProfileId, sanSummary, + LogSanitizer.Strip(ep.RequesterName), LogSanitizer.Strip(ep.RequesterEmail)); + } + else + { + _logger.LogInformation( + "Enrollment attempt started. " + + "EnrollmentType={EnrollmentType}, RequestFormat={RequestFormat}, Subject={Subject}, " + + "ProfileId={ProfileId}, SANs={SANs}, " + + "RequesterEmail={RequesterEmail}", + enrollmentType, requestFormat, LogSanitizer.Strip(subject), + ep.ProfileId, sanSummary, + LogSanitizer.MaskEmail(LogSanitizer.Strip(ep.RequesterEmail))); + } if (string.IsNullOrWhiteSpace(ep.ProfileId)) { _logger.LogError( "Enrollment rejected — ProfileId parameter is missing. Subject={Subject}, EnrollmentType={EnrollmentType}", - subject, enrollmentType); + LogSanitizer.Strip(subject), enrollmentType); throw new Exception($"Template parameter '{Constants.EnrollmentParam.ProfileId}' is required."); } EnrollmentResult result; - switch (enrollmentType) + if (_config.UseV2Api) { - case EnrollmentType.New: - case EnrollmentType.Reissue: - result = await EnrollNewAsync(csr, subject, san, ep); - break; - - case EnrollmentType.Renew: - case EnrollmentType.RenewOrReissue: - result = await RenewOrReissueAsync(csr, subject, san, productInfo, ep); - break; - - default: - _logger.LogError( - "Enrollment rejected — unsupported enrollment type. EnrollmentType={EnrollmentType}, Subject={Subject}", - enrollmentType, subject); - throw new NotSupportedException($"Enrollment type '{enrollmentType}' is not supported."); + // V2 path: all enrollment types go through EnrollV2Async + result = await EnrollV2Async(csr, subject, san, ep, enrollmentType); + } + else + { + switch (enrollmentType) + { + case EnrollmentType.New: + case EnrollmentType.Reissue: + result = await EnrollNewAsync(csr, subject, san, ep); + break; + + case EnrollmentType.Renew: + case EnrollmentType.RenewOrReissue: + result = await RenewOrReissueAsync(csr, subject, san, productInfo, ep); + break; + + default: + _logger.LogError( + "Enrollment rejected — unsupported enrollment type. EnrollmentType={EnrollmentType}, Subject={Subject}", + enrollmentType, LogSanitizer.Strip(subject)); + throw new NotSupportedException($"Enrollment type '{enrollmentType}' is not supported."); + } } // SOX: the completion log must include the CA-assigned identifier, serial number, @@ -617,7 +1023,7 @@ public async Task Enroll( "SerialNumber={SerialNumber}, Subject={Subject}, ProfileId={ProfileId}", enrollmentType, result.CARequestID, result.Status, result.Certificate != null ? ExtractSerialFromPem(result.Certificate) : "(pending)", - subject, ep.ProfileId); + LogSanitizer.Strip(subject), ep.ProfileId); _logger.MethodExit(LogLevel.Debug); return result; } @@ -630,7 +1036,10 @@ public async Task Enroll( public async Task GetSingleRecord(string caRequestID) { _logger.MethodEntry(LogLevel.Debug); - _logger.LogInformation("GetSingleRecord started. CARequestID={Id}", caRequestID); + _logger.LogInformation("GetSingleRecord started. CARequestID={Id}, UseV2Api={UseV2Api}", caRequestID, _config.UseV2Api); + + if (_config.UseV2Api) + return await GetSingleRecordV2Async(caRequestID); try { @@ -661,11 +1070,26 @@ public async Task GetSingleRecord(string caRequestID) var record = MapToAnyCAPluginCertificate(cert); + // A REVOKED record with no certificate body must never be returned as-is unless + // the gateway already holds a body for this order — see + // DecideBodylessRevokedRecord. GetSingleRecord can't skip (it must return + // something), so both the no-row and can't-tell cases fall through to FAILED. + if (record.Status == (int)EndEntityStatus.REVOKED && string.IsNullOrWhiteSpace(record.Certificate)) + { + var decision = DecideBodylessRevokedRecord(caRequestID); + if (decision != BodylessRevokedDecision.EmitRevoked) + { + record.Status = (int)EndEntityStatus.FAILED; + record.RevocationDate = null; + record.RevocationReason = 0; + } + } + // SOC2 CC7.3: certificate retrieval is a security-relevant read operation; // must be logged at Information so it is captured in production. _logger.LogInformation( - "GetSingleRecord complete. CARequestID={Id}, Status={Status}, SerialNumber={Serial}", - caRequestID, cert.Status, cert.SerialNumber ?? "(none)"); + "GetSingleRecord complete. CARequestID={Id}, Status={Status}, Disposition={Disposition}, SerialNumber={Serial}", + caRequestID, cert.Status, record.Status, cert.SerialNumber ?? "(none)"); _logger.MethodExit(LogLevel.Debug); return record; } @@ -690,6 +1114,9 @@ public async Task Revoke(string caRequestID, string hexSerialNumber, uint r { _logger.MethodEntry(LogLevel.Debug); + if (_config.UseV2Api) + return await RevokeV2Async(caRequestID, hexSerialNumber, revocationReason); + string reasonString = StatusMapper.ToRevocationReason(revocationReason); // SOX: log the revocation attempt before any state change so the intent is @@ -727,7 +1154,7 @@ public async Task Revoke(string caRequestID, string hexSerialNumber, uint r _logger.LogWarning( "Revocation skipped — certificate is already revoked. " + "CARequestID={Id}, HexSerialNumber={Serial}, Subject={Subject}", - caRequestID, hexSerialNumber, current.Subject); + caRequestID, hexSerialNumber, LogSanitizer.Strip(current.Subject)); return (int)EndEntityStatus.REVOKED; } @@ -756,7 +1183,7 @@ public async Task Revoke(string caRequestID, string hexSerialNumber, uint r "Revocation complete. " + "CARequestID={Id}, HexSerialNumber={Serial}, Subject={Subject}, " + "ReasonCode={ReasonCode}, ReasonString={ReasonString}", - caRequestID, hexSerialNumber, current.Subject, + caRequestID, hexSerialNumber, LogSanitizer.Strip(current.Subject), revocationReason, reasonString); _logger.MethodExit(LogLevel.Debug); return (int)EndEntityStatus.REVOKED; @@ -775,15 +1202,31 @@ public async Task Synchronize( { _logger.MethodEntry(LogLevel.Debug); - DateTime? issuedAfter = fullSync ? (DateTime?)null : lastSync; + if (_config.UseV2Api) + { + // V2 mode routes Synchronize through V2 /reports/orders — the V1 + // GetOrderReport path below is never used, and V1 credentials are optional. + await SynchronizeV2Async(blockingBuffer, lastSync, fullSync, cancelToken); + _logger.MethodExit(LogLevel.Debug); + return; + } + + // Hold back pending/issued orders that an in-flight enrollment may still be about to + // save (full and incremental passes alike). + int recentOrderGraceSeconds = GetSyncRecentOrderGraceSeconds(_config); + + DateTime? issuedAfter = fullSync ? (DateTime?)null : GetSyncIssuedAfter(lastSync, recentOrderGraceSeconds); _logger.LogInformation( - "Starting CERTInext synchronization. FullSync={FullSync}, IssuedAfter={IssuedAfter}", - fullSync, issuedAfter?.ToString("O") ?? "none"); + "Starting CERTInext synchronization. FullSync={FullSync}, IssuedAfter={IssuedAfter}, " + + "RecentOrderGraceSeconds={Grace}, UseV2Api={UseV2Api}", + fullSync, issuedAfter?.ToString("O") ?? "none", recentOrderGraceSeconds, _config.UseV2Api); int synced = 0; int skipped = 0; + int deferredRecentOrders = 0; // pending/issued orders withheld because they are younger than the grace window int skippedWithBody = 0; // skipped records that nonetheless carried a cert body (should be 0) + int unchangedInGateway = 0; // incremental only: issued/revoked orders the gateway already holds as-is int errors = 0; #if SUPPORTS_DCV @@ -799,6 +1242,8 @@ public async Task Synchronize( // Emit-side accounting (issue 0003): what the plugin hands to the gateway buffer. int emittedGeneratedWithBody = 0, emittedGeneratedNoBody = 0, emittedRevoked = 0, emittedPending = 0; + // Bodyless-REVOKED guard decisions — see DecideBodylessRevokedRecord. + int emittedFailedFromBodylessRevoked = 0, skippedBodylessRevoked = 0; try { @@ -836,6 +1281,40 @@ public async Task Synchronize( current.OrderDate?.ToString("o") ?? "(none)", !string.IsNullOrWhiteSpace(current.Certificate)); + // Do not hand the gateway a row (pending, or issued with a body we would + // fetch) for an order whose enrollment may still be in flight. The gateway + // would insert a row with this CARequestID and the enrollment's own save + // would then fail on the unique (CA, CARequestID) index. Held before any DCV, + // refetch or download call. Not emitting is safe: the next incremental pass + // re-lists the order (the listing lookback keeps it in the window) and + // imports it. + if (ShouldDeferRecentOrder( + status, current.OrderDate, DateTime.UtcNow, recentOrderGraceSeconds, + out double recentOrderAgeSeconds)) + { + _logger.LogInformation( + "Sync: holding back recent order until the next pass (an enrollment may " + + "still be saving it). CARequestID={Id}, AgeSeconds={Age:F1}, GraceSeconds={Grace}.", + current.Id, recentOrderAgeSeconds, recentOrderGraceSeconds); + deferredRecentOrders++; + continue; + } + + // The V1 listing filter is a calendar day, so an incremental pass re-lists + // every order placed that day. Without this check each issued or revoked one + // costs a TrackOrder + DownloadCertificate on every pass, even when the + // gateway already holds it unchanged. Same rule as the Entrust ECS, HashiCorp + // Vault and Nexus plugins: skip when the gateway's status matches. Full sync + // still refreshes everything. (V2 has no equivalent yet.) + if (!fullSync + && (status == (int)EndEntityStatus.GENERATED + || status == (int)EndEntityStatus.REVOKED) + && await IsUnchangedInGatewayAsync(current.Id, status)) + { + unchangedInGateway++; + continue; + } + // Deferred DCV: pending orders (EXTERNALVALIDATION) often need DCV driven // forward during sync — CERTInext parks fresh orders and exposes the DCV // challenge minutes after enrollment, and scans are the only place that gets @@ -937,7 +1416,8 @@ public async Task Synchronize( status = StatusMapper.ToRequestDisposition(current.Status); _logger.LogDebug( "Sync: refetched order Id={Id} — status={Status}, certBytes={Bytes}, subject={Subject}.", - current.Id, status, current.Certificate?.Length ?? 0, current.Subject); + current.Id, status, current.Certificate?.Length ?? 0, + LogSanitizer.Strip(current.Subject)); } catch (Exception fetchEx) { @@ -956,6 +1436,32 @@ public async Task Synchronize( // persistence, not the plugin. Per-record detail is at Debug; the aggregate is // logged at Information in the completion summary below. bool recordHasBody = !string.IsNullOrWhiteSpace(record.Certificate); + + // Never hand the gateway buffer a REVOKED record with no certificate body + // unless the gateway already holds one for this order — see + // DecideBodylessRevokedRecord's doc comment. "Skip" means this row is + // dropped entirely (not added to blockingBuffer) rather than risk creating + // a row the gateway can never un-poison. + if (record.Status == (int)EndEntityStatus.REVOKED && !recordHasBody) + { + var bodylessDecision = DecideBodylessRevokedRecord(record.CARequestID); + if (bodylessDecision == BodylessRevokedDecision.Skip) + { + skipped++; + skippedBodylessRevoked++; + continue; + } + if (bodylessDecision == BodylessRevokedDecision.EmitFailed) + { + record.Status = (int)EndEntityStatus.FAILED; + record.RevocationDate = null; + record.RevocationReason = 0; + emittedFailedFromBodylessRevoked++; + } + // EmitRevoked falls through — record stays REVOKED with no body, + // exactly as before (propagates an out-of-band CA revoke). + } + if (record.Status == (int)EndEntityStatus.GENERATED) { if (recordHasBody) emittedGeneratedWithBody++; else emittedGeneratedNoBody++; @@ -970,7 +1476,8 @@ public async Task Synchronize( } _logger.LogDebug( "Sync emit: CARequestID={Id}, Status={Status}, CertBytes={CertBytes}, Subject={Subject}", - record.CARequestID, record.Status, record.Certificate?.Length ?? 0, current.Subject); + record.CARequestID, record.Status, record.Certificate?.Length ?? 0, + LogSanitizer.Strip(current.Subject)); blockingBuffer.Add(record, cancelToken); synced++; @@ -1021,10 +1528,16 @@ public async Task Synchronize( #endif _logger.LogInformation( "CERTInext synchronization complete. Synced={Synced}, Skipped={Skipped} (withBody={SkippedWithBody}), " + + "UnchangedInGateway={UnchangedInGateway} (incremental, already held — not refetched), " + "Errors={Errors}. Emitted to gateway buffer: GeneratedWithBody={GenWithBody}, " + - "GeneratedNoBody={GenNoBody}, Revoked={Revoked}, Pending={Pending}. {DcvClause}", - synced, skipped, skippedWithBody, errors, + "GeneratedNoBody={GenNoBody}, Revoked={Revoked}, Pending={Pending}, " + + "FailedFromBodylessRevoked={FailedFromBodylessRevoked}. " + + "BodylessRevokedSkipped={BodylessRevokedSkipped} (bodyless-REVOKED guard). " + + "RecentOrderDeferred={RecentOrderDeferred} (younger than {Grace}s, imported next pass). {DcvClause}", + synced, skipped, skippedWithBody, unchangedInGateway, errors, emittedGeneratedWithBody, emittedGeneratedNoBody, emittedRevoked, emittedPending, + emittedFailedFromBodylessRevoked, skippedBodylessRevoked, + deferredRecentOrders, recentOrderGraceSeconds, dcvClause); } catch (OperationCanceledException) @@ -1047,12 +1560,12 @@ public async Task Synchronize( // Private helpers // --------------------------------------------------------------------------- - /// The DCV-during-sync gate outcome for a single pending order (issue 0002). + /// The DCV-during-sync gate outcome for a single pending order. internal enum DcvSyncDecision { Attempt, SkipByAge, SkipByCap } /// /// Decides whether to attempt DCV completion for a pending order during a sync pass, - /// bounding the work so a large pending backlog can't make sync slow (issue 0002). + /// bounding the work so a large pending backlog can't make sync slow. /// Pure/stateless so it is unit-testable without the DCV machinery. /// /// Rules (checked in order): @@ -1079,627 +1592,4342 @@ internal static DcvSyncDecision EvaluateDcvSyncEligibility( return DcvSyncDecision.Attempt; } + // --------------------------------------------------------------------------- + // V2 API private helpers — only called when _config.UseV2Api is true + // --------------------------------------------------------------------------- + /// - /// Handles New and Reissue enrollment flows by submitting a fresh certificate - /// request to CERTInext. + /// Composes a single E.164-style phone value from separate ISD-code + mobile-number + /// config fields, for V2 request shapes that carry one phone field (e.g. + /// ) rather than V1's separate + /// IsdCode/MobileNumber pair. Returns an empty string when + /// is blank (nothing to compose); returns the bare + /// mobile number when is blank (never invents a code). + /// Internal + static for direct unit testing. /// - private async Task EnrollNewAsync( + internal static string ComposeV2Phone(string isdCode, string mobileNumber) + { + if (string.IsNullOrWhiteSpace(mobileNumber)) + return string.Empty; + if (string.IsNullOrWhiteSpace(isdCode)) + return mobileNumber.Trim(); + + return "+" + isdCode.Trim().TrimStart('+') + mobileNumber.Trim(); + } + + /// + /// DNS SANs on a V2 SSL request beyond what a single-domain order covers: the UNION of the + /// CSR's own subjectAltName entries and the gateway's SAN dictionary (deliberately not + /// BuildSanList's "dictionary wins, CSR only as fallback" rule — the create call + /// sends the CSR to CERTInext regardless of what the dictionary says, so a CSR-embedded + /// extra still reaches the CA), minus the primary , its + /// www. variant (autoSecureWww), and — for a wildcard order — the bare apex of the + /// wildcard (a wildcard CSR routinely carries it alongside *.example.com). + /// Lower-cased and de-duplicated. + /// + internal static List FindExtraDnsSans( + string csr, Dictionary san, string domain, bool isWildcard) + { + string wildcardApexDomain = isWildcard && domain != null + && domain.StartsWith("*.", StringComparison.Ordinal) + ? StripWildcardPrefix(domain) + : null; + + var csrSanEntries = ExtractSanEntriesFromCsr(csr, out _); + // CollectRequestedSanEntries(san, csr: null, ...) yields exactly the SAN + // dictionary's own (MapSanType-normalized) entries: when san is non-null the + // CSR-fallback branch never runs, and when san is null there is nothing to + // collect (csr: null makes the fallback branch's own CSR read a no-op) — the + // real CSR is already covered by csrSanEntries above, so no double-count. + var dictSanEntries = CollectRequestedSanEntries(san, csr: null, out _, out _); + return csrSanEntries + .Concat(dictSanEntries) + .Where(s => string.Equals(s.Type, "dns", StringComparison.OrdinalIgnoreCase)) + .Select(s => s.Value?.ToLowerInvariant()) + .Where(v => !string.IsNullOrWhiteSpace(v)) + .Where(v => !string.Equals(v, domain, StringComparison.OrdinalIgnoreCase)) + .Where(v => !string.Equals(v, "www." + domain, StringComparison.OrdinalIgnoreCase)) + .Where(v => wildcardApexDomain == null || !string.Equals(v, wildcardApexDomain, StringComparison.OrdinalIgnoreCase)) + .Distinct(StringComparer.OrdinalIgnoreCase) + .ToList(); + } + + /// + /// Validates the template parameters a V2 private-pki order needs + /// beyond the SSL ones, before any CA call. Shared by (fail + /// fast with a FAILED result) and (reject at template + /// save time). Returns null when valid, else an actionable message naming the field. + /// + /// - ProductVariant must be one of the spec's create-body variant values + /// (). Its SSL-only "dv" default is + /// rejected rather than silently mapped to a Private PKI variant. + /// - ProductCode is optional: the spec's X-Product-Code is an "explicit override" and + /// the wrapper resolves the Private PKI product from variant. It is sent only when + /// the template sets it (to disambiguate between several matching catalog products). + /// + internal static string ValidatePrivatePkiEnrollmentParams(EnrollmentParams ep, out string normalizedVariant) + { + normalizedVariant = null; + + string variant = ep.ProductVariant?.Trim(); + if (string.IsNullOrEmpty(variant) || !Constants.ApiV2.PrivatePkiVariants.Contains(variant)) + { + string configured = ep.HasExplicitProductVariant ? $"'{variant}'" : "not set (defaults to the SSL-only 'dv')"; + return $"ProductFamily 'private-pki' requires the '{Constants.EnrollmentParam.ProductVariant}' " + + $"template parameter to be one of: {Constants.ApiV2.PrivatePkiVariantIntranetSsl}, " + + $"{Constants.ApiV2.PrivatePkiVariantIgtfHost}. Current value: {configured}."; + } + + normalizedVariant = variant.ToLowerInvariant(); + return null; + } + + /// + /// Resolves the SSL family's productVariant value to send, and validates an + /// explicit template override against the product it's paired with. + /// must not simply default to "dv" + /// independent of : an OV/EV product with no + /// explicit ProductVariant sending productVariant:"dv" would skip the mandatory + /// OV/EV organization block (see isOvOrEv in ) + /// and silently order a DV-shaped body for an OV/EV product. + /// + /// Derivation source: , keyed by + /// ProductId (the same productTypeID assurance-level grouping + /// documents). SSL-only — callers must + /// not invoke this for private-pki (see ) + /// or signature (not yet supported for enrollment) families. + /// + /// Returns null and sets when valid: either the + /// template's explicit value (when it agrees with the derived variant, or no mapping + /// exists for this ProductId, in which case the explicit value is kept rather than + /// guessing), or the value derived from ProductId when no explicit override is + /// configured. Returns an actionable error message + /// ( = null) when an + /// explicit override contradicts the product's derived variant. + /// + internal static string ResolveSslProductVariant(EnrollmentParams ep, out string resolvedVariant) + { + bool hasMapping = Constants.Products.ProductVariantsV2.TryGetValue( + ep.ProductId ?? string.Empty, out string derivedVariant); + + if (!ep.HasExplicitProductVariant) + { + // No override configured — derive from the product when an authoritative + // mapping exists; otherwise fall back to the configured default rather than + // inventing a mapping for a product this table doesn't cover. + resolvedVariant = hasMapping ? derivedVariant : ep.ProductVariant; + return null; + } + + string explicitVariant = ep.ProductVariant.Trim(); + if (hasMapping && !string.Equals(explicitVariant, derivedVariant, StringComparison.OrdinalIgnoreCase)) + { + resolvedVariant = null; + return $"Template parameter '{Constants.EnrollmentParam.ProductVariant}' is set to " + + $"'{explicitVariant}', but the selected product '{ep.ProductId}' is " + + $"'{derivedVariant}'. Set '{Constants.EnrollmentParam.ProductVariant}' to " + + $"'{derivedVariant}' (or remove the override to let the plugin derive it " + + $"automatically from the product), or select a product whose assurance " + + $"level matches '{explicitVariant}'."; + } + + resolvedVariant = explicitVariant.ToLowerInvariant(); + return null; + } + + /// + /// Dispatches all enrollment types through the V2 REST API. + /// + private async Task EnrollV2Async( string csr, string subject, Dictionary san, - EnrollmentParams ep) + EnrollmentParams ep, + EnrollmentType enrollmentType) { _logger.MethodEntry(LogLevel.Debug); - var enrollReq = new EnrollCertificateRequest + _logger.LogInformation( + "EnrollV2Async started. EnrollmentType={EnrollmentType}, ProductFamily={Family}, ProductVariant={Variant}, " + + "ProductId={ProductId}, HasExplicitProductCode={HasExplicit}, ConfiguredProductCode={Code}", + enrollmentType, ep.ProductFamilySlug, ep.ProductVariant, ep.ProductId, ep.HasExplicitProductCode, + ep.HasExplicitProductCode ? ep.ProductCode : "(not set — CERTInext resolves it)"); + + // The create-order body is family-specific: Private PKI and Document Signer each need + // their own shape, not the SSL body (productVariant/certificate/agreement...). ssl + // (and any unrecognized ProductFamily, which ProductFamilySlug already maps to ssl) + // uses the SSL flow below. + bool isPrivatePki = string.Equals(ep.ProductFamilySlug, Constants.ApiV2.FamilyPrivatePki, StringComparison.Ordinal); + + // Document Signer (signature): the body DTO exists (V2CreateSignatureOrderRequest), + // but its mandatory subjectType / subject.email and the per-subject-type subject + // name/organization fields have no settled source in the Command enrollment inputs. + // Fail fast with a clear message, before any CA call, rather than guessing those + // values or sending the wrong-family SSL body (which the CA rejects anyway: + // subjectType and subject.email are "400 if missing"). + if (string.Equals(ep.ProductFamilySlug, Constants.ApiV2.FamilySignature, StringComparison.Ordinal)) { - ProfileId = ep.ProfileId, - Csr = csr, - ValidityDays = ep.ValidityDays > 0 ? ep.ValidityDays : (int?)null, - Subject = subject, - Sans = BuildSanList(san), - RequesterName = string.IsNullOrWhiteSpace(ep.RequesterName) ? null : ep.RequesterName, - RequesterEmail = string.IsNullOrWhiteSpace(ep.RequesterEmail) ? null : ep.RequesterEmail, - KeyType = string.IsNullOrWhiteSpace(ep.KeyType) ? null : ep.KeyType, - Comment = "Issued via Keyfactor Command AnyCA REST Gateway." - }; + _logger.LogWarning( + "EnrollV2Async rejected a ProductFamily=signature (Document Signer) order — V2 Document " + + "Signer enrollment is not yet supported by this plugin version. EnrollmentType={EnrollmentType}, " + + "ProductId={ProductId}", + enrollmentType, ep.ProductId); + _logger.MethodExit(LogLevel.Debug); + return new EnrollmentResult + { + CARequestID = string.Empty, + Certificate = null, + Status = (int)EndEntityStatus.FAILED, + StatusMessage = "V2 enrollment rejected: ProductFamily 'signature' (Document Signer) is not yet " + + "supported for enrollment by this plugin version. A Document Signer order needs " + + "signer-subject details (subjectType, subject email, and per-subject-type name or " + + "organization fields) that the plugin does not yet take from the enrollment request. " + + "No order was placed." + }; + } - var enrollResp = await _client.EnrollCertificateAsync(enrollReq); + // SSL/TLS sends the CSR inline on the create call and nothing re-sends it afterwards; Private + // PKI submits it right after create. Either way a blank CSR would leave an order stuck at + // pending-csr with no way to supply one, so reject it before any CA call. + if (string.IsNullOrWhiteSpace(csr)) + { + _logger.LogWarning( + "EnrollV2Async rejected an order before the create call — the enrollment carried no CSR. " + + "EnrollmentType={EnrollmentType}, ProductId={ProductId}", enrollmentType, ep.ProductId); + _logger.MethodExit(LogLevel.Debug); + return new EnrollmentResult + { + CARequestID = string.Empty, + Certificate = null, + Status = (int)EndEntityStatus.FAILED, + StatusMessage = "V2 enrollment rejected: the enrollment request carried no CSR, which every V2 " + + "order needs (inline on create for SSL/TLS, submitted after create for Private PKI). No order was placed." + }; + } -#if SUPPORTS_DCV - // DCV: run domain validation if enabled, the factory was injected, and the - // order was accepted (not immediately failed). - string orderNumber = enrollResp.Id; - if (_domainValidatorFactory != null && _config.DcvEnabled && !string.IsNullOrEmpty(orderNumber)) + string privatePkiVariant = null; + if (isPrivatePki) { - // SOX CC7.3: bound the entire DCV flow with a hard timeout so a stuck - // DNS provider or extreme propagation delay cannot hold a gateway worker - // thread indefinitely. Configurable via DcvTimeoutMinutes (config or - // CERTINEXT_DCV_TIMEOUT_MINUTES env var); defaults to 10 minutes. - // Log the resolved limit so an auditor can confirm the configured ceiling. - int dcvTimeoutMinutes = _config.GetEffectiveDcvTimeoutMinutes(); - _logger.LogInformation( - "Starting DCV for order {OrderNumber}. DcvTimeoutMinutes={Timeout}", - orderNumber, dcvTimeoutMinutes); - using var dcvCts = new CancellationTokenSource(TimeSpan.FromMinutes(dcvTimeoutMinutes)); + string pkiConfigError = ValidatePrivatePkiEnrollmentParams(ep, out privatePkiVariant); + if (pkiConfigError != null) + { + _logger.LogWarning( + "EnrollV2Async rejected a private-pki order before any CA call: {Reason}", pkiConfigError); + _logger.MethodExit(LogLevel.Debug); + return new EnrollmentResult + { + CARequestID = string.Empty, + Certificate = null, + Status = (int)EndEntityStatus.FAILED, + StatusMessage = "V2 enrollment rejected: " + pkiConfigError + }; + } + } - // Reserve the in-flight slot before running DCV so that any concurrent - // Synchronize / GetSingleRecord cycle won't try to stage TXT records for the - // same order from the sync-driven retry path. If something else already has - // the slot (the only realistic case: a duplicate Enroll for the same order - // ID), skip our own attempt and fall through to the pending result — the - // other caller will produce the same outcome and we shouldn't double-stage. - bool reserved = _dcvInFlight.TryAdd(orderNumber, 0); - if (!reserved) - { - _logger.LogInformation( - "DCV is already in flight for order {OrderNumber}; Enroll will skip its own DCV attempt " + - "and return the pending enroll response. The other caller will drive issuance.", - orderNumber); - } - else + // The SSL family's productVariant must reflect the actual product ordered + // — not the template's independent (and possibly wrong/stale) ProductVariant value. + // Resolve/validate before any CA call, same fail-fast placement as the private-pki + // check above. Private PKI (checked above) doesn't use this — its variant enum is + // unrelated (intranet-ssl/igtf-host). + string sslProductVariant = ep.ProductVariant; + if (!isPrivatePki) + { + string variantError = ResolveSslProductVariant(ep, out sslProductVariant); + if (variantError != null) { - try - { - bool dcvDone = await PerformDcvIfNeededAsync(orderNumber, dcvCts.Token); - if (dcvDone) - { - // Poll GetCertificate until CERTInext finishes generating the cert OR the - // issuance budget expires. CERTInext issuance is async — DCV may verify - // but the cert PEM isn't immediately available. Without this poll, Enroll - // returns a pending result and the cert is picked up on the next sync cycle, - // which is undesirable when the whole thing completes in under a minute. - var postDcv = await WaitForIssuanceAfterDcvAsync(orderNumber, dcvCts.Token); - if (postDcv != null) - { - return BuildEnrollmentResult(new EnrollCertificateResponse - { - Id = postDcv.Id, - Status = postDcv.Status, - Certificate = postDcv.Certificate, - SerialNumber = postDcv.SerialNumber, - Message = $"Post-DCV status: {postDcv.Status}." - }, ep.AutoApprove); - } - } - } - finally + _logger.LogWarning( + "EnrollV2Async rejected an SSL order before any CA call: {Reason}", variantError); + _logger.MethodExit(LogLevel.Debug); + return new EnrollmentResult { - _dcvInFlight.TryRemove(orderNumber, out _); - } + CARequestID = string.Empty, + Certificate = null, + Status = (int)EndEntityStatus.FAILED, + StatusMessage = "V2 enrollment rejected: " + variantError + }; } } -#endif - _logger.MethodExit(LogLevel.Debug); - return BuildEnrollmentResult(enrollResp, ep.AutoApprove); - } + // The SSL create body always carries an `agreement` block, and the V2 spec + // marks agreement.signerPlace "Conditional - required if `agreement` sent". Resolved + // per-template SignerPlace -> connector SignerPlace (which ValidateCAConnectionInfo + // already requires); fail fast here too, before any CA call, in case the connector was + // saved before that check existed. Private PKI sends no agreement, so it is exempt. + string signerPlace = string.IsNullOrWhiteSpace(ep.SignerPlace) ? _config.SignerPlace : ep.SignerPlace; + if (!isPrivatePki && string.IsNullOrWhiteSpace(signerPlace)) + { + _logger.LogWarning( + "EnrollV2Async rejected an SSL order before any CA call — no SignerPlace is configured " + + "(neither the template's SignerPlace enrollment parameter nor the CA connector's SignerPlace), " + + "but the V2 Subscriber Agreement requires it. EnrollmentType={EnrollmentType}, ProductId={ProductId}", + enrollmentType, ep.ProductId); + _logger.MethodExit(LogLevel.Debug); + return new EnrollmentResult + { + CARequestID = string.Empty, + Certificate = null, + Status = (int)EndEntityStatus.FAILED, + StatusMessage = "V2 enrollment rejected: the CERTInext V2 Subscriber Agreement requires a signer " + + "place, but SignerPlace is blank on both the CA connector and the template. Set " + + "SignerPlace on the CA connector (or the template's SignerPlace enrollment " + + "parameter) and retry. No order was placed." + }; + } - /// - /// Handles Renew and RenewOrReissue enrollment flows. - /// Determines whether to renew (API call on existing ID) or fall back to new - /// issuance depending on the certificate's current state. - /// - private async Task RenewOrReissueAsync( - string csr, - string subject, - Dictionary san, - EnrollmentProductInfo productInfo, - EnrollmentParams ep) - { - // Retrieve the prior certificate serial number from the product parameters. - // Command injects "PriorCertSN" for renewal flows. - string priorCertSn = null; - productInfo.ProductParameters?.TryGetValue("PriorCertSN", out priorCertSn); + // Derive the primary domain from subject CN (for private-pki this is the order's + // `hostname` — spec: "hostname - primary CN" — sourced the same way). + string domain = ep.DomainName; + if (string.IsNullOrWhiteSpace(domain)) + domain = ExtractCnFromSubject(subject); + if (string.IsNullOrWhiteSpace(domain)) + throw new Exception(isPrivatePki + ? "Cannot determine the primary hostname for V2 private-pki order — set the DomainName enrollment parameter or ensure the CSR subject has a CN." + : "Cannot determine primary domain for V2 order — set the DomainName enrollment parameter or ensure the CSR subject has a CN."); + + // organization is "Conditional — Mandatory for OV / EV" per the V2 spec's SSL field + // table; every OV/EV create example in the spec sends it, and it is omitted entirely + // for DV. CERTInext hard-rejects an OV/EV order with no organization block (HTTP 422 + // EMS-1180 "Organization Name cannot be empty"), so fail fast with a + // clear message here — before any catalog/order-placement call — rather than + // sending an incomplete block and letting the CA surface that opaque error. + // SSL-only: Private PKI "has no DCV, no organization block, and no Subscriber + // Agreement" per the spec, and its ProductVariant is intranet-ssl/igtf-host. + bool isOvOrEv = !isPrivatePki + && (string.Equals(sslProductVariant, Constants.ApiV2.ProductVariantOv, StringComparison.OrdinalIgnoreCase) + || string.Equals(sslProductVariant, Constants.ApiV2.ProductVariantEv, StringComparison.OrdinalIgnoreCase)); + + V2OrganizationParams organization = null; + if (isOvOrEv) + { + if (string.IsNullOrWhiteSpace(_config.OrganizationNumber)) + { + _logger.LogWarning( + "EnrollV2Async rejected a '{Variant}' order for domain '{Domain}' — the CA " + + "connector's OrganizationNumber is not configured, but an organization block is " + + "mandatory for OV/EV orders under the V2 API.", + sslProductVariant, LogSanitizer.Strip(domain)); + _logger.MethodExit(LogLevel.Debug); + return new EnrollmentResult + { + CARequestID = string.Empty, + Certificate = null, + Status = (int)EndEntityStatus.FAILED, + StatusMessage = $"V2 enrollment rejected: product variant '{sslProductVariant}' requires " + + "a pre-vetted organization, but the CA connector's OrganizationNumber " + + "setting is empty. Set OrganizationNumber on the CA connector before " + + "enrolling OV/EV certificates via the V2 API." + }; + } - // SOC2 CC6.1: a renewal/reissue read against the gateway's certificate - // inventory is a logical-access event and must be logged at Information. - _logger.LogInformation( - "Renewal/reissue probe — read PriorCertSN from EnrollmentProductInfo. " + - "Subject={Subject}, PriorCertSN={PriorCertSN}, RenewalWindowDays={WindowDays}", - subject, string.IsNullOrWhiteSpace(priorCertSn) ? "(none)" : priorCertSn, - ep.RenewalWindowDays); + organization = new V2OrganizationParams + { + OrganizationNumber = _config.OrganizationNumber, + PreVetted = true + }; + } - if (string.IsNullOrWhiteSpace(priorCertSn)) + // SubscriptionAutoRenew / SubscriptionRenewCriteriaDays — CA connector config that + // feeds the Subscription block below. AutoRenew uses the same bare "1"-means-true + // comparison AutoSecureWww already uses elsewhere in this method. RenewBeforeDays is + // validated up front — before any CA call — so a bad value fails the enrollment with + // a clear message rather than surfacing as an opaque CA-side error later, matching the + // fail-fast convention the OrganizationNumber check above already established. Blank/ + // unset stays null (omitted on the wire; the client's global WhenWritingNull option + // means the CA falls back to its documented default of 30). + bool subscriptionAutoRenew = _config.SubscriptionAutoRenew == "1"; + int? subscriptionRenewBeforeDays = null; + if (!string.IsNullOrWhiteSpace(_config.SubscriptionRenewCriteriaDays)) { - // SOC2 CC7.2: log policy-relevant decisions at Information so they survive - // production log filters and are available for anomaly detection. - _logger.LogInformation( - "Renewal/reissue has no PriorCertSN — treating as new enrollment. Subject={Subject}", - subject); - return await EnrollNewAsync(csr, subject, san, ep); + if (!int.TryParse(_config.SubscriptionRenewCriteriaDays, out int parsedRenewDays) || parsedRenewDays < 0) + { + _logger.LogError( + "EnrollV2Async rejected an order — the CA connector's SubscriptionRenewCriteriaDays " + + "value ('{Value}') is not a valid non-negative integer.", + _config.SubscriptionRenewCriteriaDays); + _logger.MethodExit(LogLevel.Debug); + return new EnrollmentResult + { + CARequestID = string.Empty, + Certificate = null, + Status = (int)EndEntityStatus.FAILED, + StatusMessage = $"V2 enrollment rejected: the CA connector's SubscriptionRenewCriteriaDays " + + $"setting ('{_config.SubscriptionRenewCriteriaDays}') must be a non-negative " + + "integer (or blank to use the CA's default of 30). Fix the CA connector " + + "configuration and retry." + }; + } + + subscriptionRenewBeforeDays = parsedRenewDays; } - // Resolve the CARequestID for the prior certificate - string priorCaRequestId; - try + // EmailNotifications: the connector field uses V1's "0"/"1" vocabulary and defaults + // to "0". The V2 spec's emailNotifications enum is `consent-only | all` (the old "0" is + // not a member of it), so the mapping below is user-decided, not a guess: + // "1" -> "all" (full notification set), "0" -> + // "consent-only" (the silent setting: only the mails the CA must send for consent), + // blank/unset -> null (omitted; the + // client's global WhenWritingNull option drops the key and the CA falls back to its + // documented default of "all", NOT silent — this is the one place V1 and V2 defaults + // diverge for a blank config value, since V1's own fallback always sends "0"). Any + // other value fails fast, before any CA call, mirroring the + // SubscriptionRenewCriteriaDays check above. + string emailNotifications; + string configEmailNotifications = _config.EmailNotifications?.Trim(); + if (string.IsNullOrEmpty(configEmailNotifications)) { - priorCaRequestId = await _certificateDataReader.GetRequestIDBySerialNumber(priorCertSn); + emailNotifications = null; } - catch (Exception ex) + else if (configEmailNotifications == "1") { - _logger.LogWarning(ex, - "Could not resolve CARequestID for serial '{SN}'. Falling back to new enrollment.", priorCertSn); - return await EnrollNewAsync(csr, subject, san, ep); + emailNotifications = "all"; + } + else if (configEmailNotifications == "0") + { + emailNotifications = Constants.ApiV2.EmailNotificationsConsentOnly; + } + else + { + _logger.LogError( + "EnrollV2Async rejected an order — the CA connector's EmailNotifications value " + + "('{Value}') is not one of the supported values.", + _config.EmailNotifications); + _logger.MethodExit(LogLevel.Debug); + return new EnrollmentResult + { + CARequestID = string.Empty, + Certificate = null, + Status = (int)EndEntityStatus.FAILED, + StatusMessage = $"V2 enrollment rejected: the CA connector's EmailNotifications " + + $"setting ('{_config.EmailNotifications}') must be \"0\", \"1\", or " + + "blank. Fix the CA connector configuration and retry." + }; } - if (string.IsNullOrWhiteSpace(priorCaRequestId)) + // Product selection. The spec makes X-Product-Code an optional override: CERTInext's + // wrapper resolves the catalog product itself from productVariant, whether + // certificate.domain is a wildcard (starts "*."), and whether additionalDomains is + // non-empty (UCC). So the header is sent ONLY when the template explicitly sets + // ProductCode (or the deprecated ProfileId alias) — to disambiguate between several + // matching catalog products. The connector's DefaultProductCode no longer pins a V2 + // order (it remains a V1 renewal fallback), and the V1-era Constants.Products. + // DefaultProductCodes table is never consulted (its numbering does not match the live + // V2 catalog). A null productCode means "send no header". + // + // UCC / wildcard detection decides whether extra DNS SANs are carried in + // additionalDomains (UCC) or rejected by the single-domain guard below: + // - Explicit override: the live catalog entry for the code is looked up and its + // productTypeID decides (UCC / non-UCC wildcard). A catalog lookup failure must not + // block enrollment — it falls back to non-UCC (single-domain), the strictly-safer + // failure mode: the guard below still runs and rejects a surplus-SAN CSR rather than + // silently accepting it. + // - No override: no catalog call at all. The wildcard shape is the domain itself + // (starts "*."), exactly what the wrapper keys on. UCC is the template's product + // type (ProductId -> productTypeID, as before) OR the request carrying DNS SANs + // beyond the primary domain (its www. variant and a wildcard's bare apex are not + // "extra"), which is what makes the wrapper pick a UCC product — so those extras go + // out in additionalDomains instead of failing the single-domain guard. + // + // Private PKI: ProductCode is likewise optional (the wrapper resolves it from + // `variant`); the catalog is never fetched because its only use on this path — SSL UCC + // detection — does not apply. + string productCode = ep.HasExplicitProductCode ? ep.ProductCode : null; + bool isUccProduct = false; + bool isWildcardProduct = false; + if (!isPrivatePki && ep.HasExplicitProductCode) + { + List catalog = null; + try + { + catalog = await _client.GetProductDetailsV2Async(); + } + catch (Exception catalogEx) + { + _logger.LogWarning(catalogEx, + "EnrollV2Async: could not fetch the live V2 product catalog to detect UCC/wildcard for the " + + "explicit ProductCode; treating the order as single-domain. ProductId={ProductId}", ep.ProductId); + } + + var matchedProduct = catalog?.FirstOrDefault(p => + string.Equals(p.ProductCode, ep.ProductCode, StringComparison.OrdinalIgnoreCase)); + isUccProduct = matchedProduct != null + && !string.IsNullOrWhiteSpace(matchedProduct.ProductTypeId) + && Constants.ApiV2.UccProductTypeIds.Contains(matchedProduct.ProductTypeId); + isWildcardProduct = matchedProduct != null + && !string.IsNullOrWhiteSpace(matchedProduct.ProductTypeId) + && Constants.ApiV2.WildcardProductTypeIds.Contains(matchedProduct.ProductTypeId); + } + else if (!isPrivatePki) { + isWildcardProduct = domain.StartsWith("*.", StringComparison.Ordinal); + bool templateIsUccType = Constants.Products.ProductTypeIdsV2.TryGetValue( + ep.ProductId ?? string.Empty, out string templateTypeId) + && Constants.ApiV2.UccProductTypeIds.Contains(templateTypeId); + var extraDnsSans = FindExtraDnsSans(csr, san, domain, isWildcardProduct); + isUccProduct = templateIsUccType || extraDnsSans.Count > 0; + _logger.LogInformation( - "CARequestID for serial '{SN}' is empty — falling back to new enrollment. Subject={Subject}", - priorCertSn, subject); - return await EnrollNewAsync(csr, subject, san, ep); + "EnrollV2Async: no explicit ProductCode — no X-Product-Code header will be sent; CERTInext " + + "resolves the product from the variant, wildcard shape and additional domains. " + + "ProductId={ProductId}, Wildcard={Wildcard}, Ucc={Ucc} (TemplateUccType={TemplateUccType}, " + + "ExtraDnsSanCount={ExtraCount})", + ep.ProductId, isWildcardProduct, isUccProduct, templateIsUccType, extraDnsSans.Count); } - // Determine whether this is within the renewal window. + // Non-UCC V2 products support only a single domain plus autoSecureWww's www. + // variant; any other DNS SAN — from the CSR OR Command's SAN dictionary — would be + // silently dropped or cause a CA-side rejection, so fail fast with a + // clear message rather than letting the CA return an opaque error, or the extra + // names vanish with no order-side signal at all. UCC (multi-domain) products are + // exempt — their extra SANs are the expected input and are carried into + // additionalDomains below instead. This check necessarily runs after UCC detection + // above, not before it, but it still runs before PlaceOrderV2Async, so a rejected + // non-UCC request never places a CA order. It can only trigger for an explicit + // ProductCode whose catalog entry is not UCC: with no explicit code the wrapper picks + // the product from the request shape, so any extra DNS SAN makes the order UCC above + // (and goes out in additionalDomains) instead of being rejected here. // - // Semantics (Option A — "window before expiry"): - // useRenewalApi = true when the cert expires within the next RenewalWindowDays. - // useRenewalApi = false when the cert expires further away than that (too early → reissue). - // useRenewalApi = false when the cert is already expired (graceful degradation → new order). + // Looking at the CSR alone misses the case where Command's SAN + // dictionary carries the extras and the CSR itself carries only the primary domain — + // a non-UCC order never sends additionalDomains at all, so those dictionary-only + // extras would have nowhere to go and would be dropped with no warning. // - // This matches operator expectation: "renew when within N days of expiry". - // Certs expiring far in the future should be reissued, not renewed via the CA's - // renew endpoint (which may assume near-expiry context on its side). - bool useRenewalApi = false; - try + // This guard deliberately takes the UNION of the CSR's own SANs and the SAN + // dictionary — NOT CollectRequestedSanEntries'/BuildSanList's "fallback, not union" + // rule (dictionary wins when non-null; CSR consulted only when the dictionary is + // null). That rule exists to decide what additionalDomains/additionalHosts actually + // send to the CA, where the CSR's own subjectAltName extension is otherwise ignored. + // Here it is wrong: the create call sends the CSR to CERTInext verbatim regardless + // of what the SAN dictionary contains, so a CSR-embedded extra domain still reaches + // the CA even when Command also supplied a (single-domain) SAN dictionary. Deferring + // to the dictionary alone whenever it is non-null would let that CSR-embedded extra + // slip past this guard unrejected for any enrollment that also happens to pass a SAN + // dictionary. + // + // SSL-only: a private-pki order carries its SANs in additionalHosts, + // which the spec defines as a multi-entry "SAN list (DNS names or IPv4 / IPv6)" for + // every Private PKI variant, so the single-domain restriction does not apply. + // + // Wildcard apex exemption: a non-UCC wildcard product's `domain` is the literal + // wildcard value (e.g. "*.example.com"), and a wildcard CSR/SAN dictionary + // routinely also carries the bare apex ("example.com") alongside it — rejecting + // that apex as an "extra SAN" would make every ordinary wildcard CSR unenrollable + // via this guard. Exempt exactly the apex (the wildcard domain with its leading + // "*." stripped) for wildcard products (productTypeID 14/17, + // Constants.ApiV2.WildcardProductTypeIds) — any other extra SAN is still rejected. + // NOTE: this only widens what the guard *accepts*; it does not change + // what is sent to the CA for the apex — additionalDomains is still not populated + // for non-UCC products below. Whether CERTInext's V2 order create needs the apex + // added to additionalDomains (or handles it automatically for a wildcard product) + // is unverified and should be confirmed against a live order before relying on it. + if (!isPrivatePki && !isUccProduct) { - DateTime? expiry = _certificateDataReader.GetExpirationDateByRequestId(priorCaRequestId); - if (expiry.HasValue) - { - DateTime now = DateTime.UtcNow; - DateTime renewalWindowEnd = now.AddDays(ep.RenewalWindowDays); - // Renew only if the cert is not yet expired AND expires within the window. - useRenewalApi = expiry.Value > now && expiry.Value <= renewalWindowEnd; + var extraSans = FindExtraDnsSans(csr, san, domain, isWildcardProduct); - // SOX CC6.2 / SOC2 CC7.2: the renewal window evaluation is a security-relevant - // policy decision (determines whether an existing CA record is reused). Logged - // at Information so it survives production log filters and is not suppressible - // by log-level configuration. - _logger.LogInformation( - "Renewal window evaluation complete. " + - "PriorCARequestID={PriorId}, CertExpiry={Expiry:O}, " + - "RenewalWindowEnd={WindowEnd:O}, RenewalWindowDays={Window}, UseRenewalApi={Use}", - priorCaRequestId, expiry.Value, renewalWindowEnd, ep.RenewalWindowDays, useRenewalApi); + if (extraSans.Count > 0) + { + _logger.LogWarning( + "EnrollV2Async rejected multi-SAN order on domain '{Domain}'. " + + "This product does not support additional domains via the V2 API " + + "(autoSecureWww covers www.); only UCC (multi-domain) products may carry " + + "extra SANs, whether requested via the CSR or Command's SAN dictionary. " + + "ExtraSans=[{ExtraSans}]", + LogSanitizer.Strip(domain), + LogSanitizer.Strip(string.Join(", ", extraSans))); + _logger.MethodExit(LogLevel.Debug); + // Wildcard products get their own wording: unlike a plain single-domain + // product, a wildcard product cannot be made to accept extra SANs by + // switching to a UCC product on this same domain, so the rejection must not + // suggest that. + string statusMessage = isWildcardProduct + ? $"V2 enrollment rejected: {extraSans.Count} SAN(s) beyond the primary wildcard " + + $"domain ('{domain}') and its www. variant were requested (via the CSR and/or " + + "Command's SAN dictionary). Only the primary wildcard domain and its bare apex " + + "are supported via the V2 API for this product. Resubmit with a CSR/SAN set " + + "carrying only those, and no other SANs." + : $"V2 enrollment rejected: {extraSans.Count} SAN(s) beyond the primary domain " + + $"('{domain}') and its www. variant were requested (via the CSR and/or Command's " + + "SAN dictionary). This product only supports a single domain via the V2 API " + + "(UCC/multi-domain products are the exception). Resubmit with a single-domain " + + "CSR and no additional SANs, or enroll against a UCC product if additional " + + "domains are required."; + return new EnrollmentResult + { + CARequestID = string.Empty, + Certificate = null, + Status = (int)EndEntityStatus.FAILED, + StatusMessage = statusMessage + }; } } - catch (Exception ex) + + // For UCC products, additionalDomains is populated from the same SAN source the V1 + // path uses for BuildAdditionalDomains (CERTInextClient.cs) — the gateway-supplied SAN + // dictionary, falling back to CSR SANs only when Command supplied no SAN dictionary at + // all (BuildSanList's own fallback rule). additionalDomains is a domain-name-only field + // per the V2 spec, so non-DNS SAN types are excluded (and logged) rather than submitted. + // BuildSanList runs in DNS-only mode here: V1's SubmitNonDnsSans switch + // and its "submitted rather than dropped" wording do not apply to this field, so the + // exclusion is logged below instead — SAN types only, since a value (e.g. an email + // address) may be personal data. + List additionalDomains = null; + if (isUccProduct) { - _logger.LogWarning(ex, - "Could not determine expiry for '{Id}'. Defaulting to new enrollment.", priorCaRequestId); + var resolvedSans = BuildSanList(san, csr, subject, dnsOnly: true, out var nonDnsSans); + if (nonDnsSans.Count > 0) + { + _logger.LogWarning( + "EnrollV2Async: {Count} non-DNS SAN(s) excluded from V2 additionalDomains " + + "(FQDNs only) — they will NOT appear on the issued certificate. " + + "Types=[{Types}], Subject={Subject}", + nonDnsSans.Count, + string.Join(", ", nonDnsSans.Select(s => s.Type).Distinct(StringComparer.OrdinalIgnoreCase)), + LogSanitizer.Strip(subject)); + } + + additionalDomains = resolvedSans? + .Where(s => string.Equals(s.Type, "dns", StringComparison.OrdinalIgnoreCase)) + .Select(s => s.Value?.Trim()) + .Where(v => !string.IsNullOrWhiteSpace(v)) + .Where(v => !string.Equals(v, domain, StringComparison.OrdinalIgnoreCase)) + .Distinct(StringComparer.OrdinalIgnoreCase) + .ToList(); + if (additionalDomains != null && additionalDomains.Count == 0) + additionalDomains = null; + + _logger.LogInformation( + "EnrollV2Async: resolved UCC product. ProductCode={ProductCode}, AdditionalDomainCount={Count}", + productCode, additionalDomains?.Count ?? 0); } - if (useRenewalApi) + // Private PKI additionalHosts: same SAN source rule as the UCC path + // above, but DNS names AND IP addresses are both native here (spec: "SAN list (DNS + // names or IPv4 / IPv6)"; the Intranet SSL example sends "10.0.0.50"). + List additionalHosts = null; + if (isPrivatePki) { - // SOX / SOC2 CC7.3: log the renewal attempt at Information so the intent is - // captured before the API call, enabling reconstruction if the call fails. + additionalHosts = BuildPrivatePkiAdditionalHosts(san, csr, subject, domain); _logger.LogInformation( - "Renewal via CERTInext renew API started. " + - "PriorCARequestID={PriorId}, Subject={Subject}, ProfileId={ProfileId}", - priorCaRequestId, subject, ep.ProfileId); + "EnrollV2Async: private-pki order. Variant={Variant}, ProductCode={ProductCode}, " + + "Hostname={Hostname}, AdditionalHostCount={Count}", + privatePkiVariant, productCode, LogSanitizer.Strip(domain), additionalHosts?.Count ?? 0); + } - var renewReq = new RenewCertificateRequest + string requestorName = string.IsNullOrWhiteSpace(ep.RequesterName) ? _config.RequestorName : ep.RequesterName; + string requestorEmail = string.IsNullOrWhiteSpace(ep.RequesterEmail) ? _config.RequestorEmail : ep.RequesterEmail; + string signerName = string.IsNullOrWhiteSpace(ep.SignerName) ? requestorName : ep.SignerName; + // The same resolved signer the create body carries, for the one-shot accept-agreement + // fallback below. SSL/TLS only: Private PKI has no Subscriber Agreement. + var agreementContext = isPrivatePki ? null : new V2AgreementAcceptContext(signerName, signerPlace); + // signerPlace is resolved (and required for SSL) near the top of this method. + int validityYears = ep.ValidityYears > 0 ? ep.ValidityYears + : (int.TryParse(_config.SubscriptionValidityYears, out int cfgYears) && cfgYears > 0 ? cfgYears : 1); + + // requestorIsd/requestorMobile are the same Requestor* defaults V1 falls back to for + // its own TechnicalPointOfContact (CERTInextClient.cs BuildTechnicalPointOfContact). + // Also used directly for this order's own Requestor.Phone (below) via ComposeV2Phone, + // which combines RequestorIsdCode with the mobile number rather than sending the raw + // mobile number alone — the same helper TechnicalPointOfContact.Phone uses. + string requestorIsd = string.IsNullOrWhiteSpace(_config.RequestorIsdCode) ? "1" : _config.RequestorIsdCode; + string requestorMobile = _config.RequestorMobileNumber ?? string.Empty; + + // Requestor.Designation is sourced from the RequestorDesignation config field + // rather than a hardcoded value (the V2 spec's own example for this Optional + // free-text field is "IT Administrator"); blank/unset leaves this null so the property is + // omitted from the wire JSON entirely (relies on the client's global + // DefaultIgnoreCondition = WhenWritingNull, CERTInextClient.GetJsonOptions()), rather than + // sending any default designation value. + string requestorDesignation = string.IsNullOrWhiteSpace(_config.RequestorDesignation) + ? null + : _config.RequestorDesignation.Trim(); + + // technicalPointOfContact — each field falls back to the requestor default when its + // TechnicalContact* counterpart is blank, mirroring V1's BuildOrderRequestFromLegacyEnrollRequest + // (CERTInextClient.cs:2335-2341). + string technicalContactName = string.IsNullOrWhiteSpace(_config.TechnicalContactName) ? requestorName : _config.TechnicalContactName; + string technicalContactEmail = string.IsNullOrWhiteSpace(_config.TechnicalContactEmail) ? requestorEmail : _config.TechnicalContactEmail; + string technicalContactIsd = string.IsNullOrWhiteSpace(_config.TechnicalContactIsdCode) ? requestorIsd : _config.TechnicalContactIsdCode; + string technicalContactMobile = string.IsNullOrWhiteSpace(_config.TechnicalContactMobileNumber) ? requestorMobile : _config.TechnicalContactMobileNumber; + + // Blocks shared verbatim by every family's create body — the spec's requestor, + // subscription and technicalPointOfContact field tables are identical for the SSL/TLS + // and Private PKI folders. + var requestor = new V2Requestor + { + Name = requestorName, + Email = requestorEmail, + Phone = ComposeV2Phone(requestorIsd, requestorMobile), + Designation = requestorDesignation + }; + var subscription = new V2SubscriptionParams + { + ValidityYears = validityYears, + AutoRenew = subscriptionAutoRenew, + RenewBeforeDays = subscriptionRenewBeforeDays + }; + // Always populated (never omitted), even though the spec marks every subfield + // Optional — mirrors V1's fallback-to-Requestor* TechnicalPointOfContact + // defaulting rather than leaving the block blank. + var technicalPointOfContact = new V2TechnicalPointOfContact + { + Name = technicalContactName, + Email = technicalContactEmail, + Phone = ComposeV2Phone(technicalContactIsd, technicalContactMobile), + Designation = Constants.ApiV2.DefaultTechnicalContactDesignation + }; + const string remarks = "Issued via Keyfactor Command AnyCA REST Gateway."; + // Mirrors V1's SslOrderDetails.GroupNumber — omit when unconfigured so the + // order falls back to the account's default billing group. + string groupNumber = string.IsNullOrWhiteSpace(_config.GroupNumber) ? null : _config.GroupNumber; + + // CSR delivery mode. Default (V2InlineCsr=true): SSL/TLS sends the CSR inline on create (single + // call, no PUT). V2InlineCsr=false selects the two-call flow (create without `csr`, then PUT + // .../csr), which fails for an already-validated domain: CERTInext approves the order at create + // and then rejects the CSR (Finding 32). Private PKI always stays two-call: the live sandbox rejects an inline `csr` + // on the Private PKI create with HTTP 422. + bool inlineCsr = _config.V2InlineCsr && !isPrivatePki; + if (isPrivatePki && _config.V2InlineCsr + && System.Threading.Interlocked.Exchange(ref _loggedPrivatePkiIgnoresInlineCsr, 1) == 0) + { + _logger.LogWarning( + "V2InlineCsr is enabled, but Private PKI orders ignore it and keep the two-call flow " + + "(create, then Submit CSR): the CA rejects an inline csr on the Private PKI create. " + + "SSL/TLS orders still use the single-call flow. This message is logged once per connector."); + } + + // OV/EV: SSL.com validates the organization out of band, and an order for an organization it + // has not validated stays pending. Check (and optionally submit) before placing the order. + // Strictly advisory: it never blocks or fails the enrollment. + if (isOvOrEv && !string.IsNullOrWhiteSpace(_config.OrganizationNumber)) + { + await EnsureSslComOrganizationValidationAsync( + _config.OrganizationNumber, sslProductVariant.ToUpperInvariant()); + } + + V2CreateOrderResponse createResp; + if (isPrivatePki) + { + // Spec "Private PKI Certificates" body: no productVariant / organization / + // certificate / agreement blocks — "Private PKI has no DCV, no organization + // block, and no Subscriber Agreement". + var privatePkiReq = new V2CreatePrivatePkiOrderRequest { - Csr = csr, - ValidityDays = ep.ValidityDays > 0 ? ep.ValidityDays : (int?)null, - RequesterName = string.IsNullOrWhiteSpace(ep.RequesterName) ? null : ep.RequesterName, - RequesterEmail = string.IsNullOrWhiteSpace(ep.RequesterEmail) ? null : ep.RequesterEmail, - Comment = $"Renewed via Keyfactor Command. Prior ID: {priorCaRequestId}." + Variant = privatePkiVariant, + EmailNotifications = emailNotifications, + GroupNumber = groupNumber, + Requestor = requestor, + Hostname = domain, + AdditionalHosts = additionalHosts, + Subscription = subscription, + Remarks = remarks, + TechnicalPointOfContact = technicalPointOfContact + }; + createResp = await _client.PlaceOrderV2Async(productCode, privatePkiReq); + } + else + { + var orderReq = new V2CreateSslOrderRequest + { + ProductVariant = sslProductVariant, + EmailNotifications = emailNotifications, + Requestor = requestor, + Csr = inlineCsr ? csr : null, + Organization = organization, + Certificate = new V2CertificateParams + { + Domain = domain, + AutoSecureWww = _config.AutoSecureWww == "1", + AdditionalDomains = additionalDomains + }, + Subscription = subscription, + Agreement = new V2AgreementParams + { + SignerName = signerName, + SignerPlace = string.IsNullOrWhiteSpace(signerPlace) ? null : signerPlace, + Accepted = true + }, + TechnicalPointOfContact = technicalPointOfContact, + Remarks = remarks, + GroupNumber = groupNumber }; + createResp = await _client.PlaceOrderV2Async(ep.ProductFamilySlug, productCode, orderReq); + } + string orderId = createResp.OrderId; - var renewResp = await _client.RenewCertificateAsync(priorCaRequestId, renewReq); - var renewResult = BuildEnrollmentResult(renewResp, ep.AutoApprove); + _logger.LogInformation( + "V2 order placed. OrderId={OrderId}, Status={Status}, EnrollmentType={EnrollmentType}, " + + "XProductCodeSent={ProductCodeSent}, ResolvedProductCode={ResolvedProductCode}", + orderId, createResp.Status, enrollmentType, + string.IsNullOrWhiteSpace(productCode) ? "(none)" : productCode, + string.IsNullOrWhiteSpace(createResp.ResolvedProductCode) ? "(not reported)" : createResp.ResolvedProductCode); + // Status bookkeeping shared by both flows below. + V2OrderStatusResponse postCreateStatus = null; + int disposition = 0; + // Raw CA status string behind the current `disposition` value — kept in step with it + // (reassigned everywhere `disposition` is recomputed from a fresh TrackOrderV2Async + // call) purely so a terminal REVOKED result can be logged/reported with the CA's own + // status text, not just Command's mapped disposition. + string lastKnownCaStatus = null; + bool statusResolved = false; + + if (!inlineCsr) + { + // Two-call flow (the default for SSL/TLS, and always for Private PKI): the order is + // created without a csr and the CSR is then submitted with PUT .../csr. + // If Submit CSR throws, the order already exists at pending-csr and Command would + // otherwise never learn its ID. A *definitive* CA rejection (a real HTTP 4xx response + // body) cancels the orphaned order once and returns FAILED. A transport-level failure + // or timeout tells us nothing about whether CERTInext recorded the CSR, so track the + // order first and only cancel if it is still pending-csr; if tracking itself fails, + // don't cancel — return pending so sync resolves it later. + try + { + await _client.SubmitCsrV2Async(ep.ProductFamilySlug, orderId, csr); + } + catch (Exception csrEx) + { + if (!IsTransportLevelCsrFailure(csrEx)) + { + var orphanResult = await CancelOrphanedV2OrderAfterCsrFailureAsync( + ep.ProductFamilySlug, orderId, csrEx); + _logger.MethodExit(LogLevel.Debug); + return orphanResult; + } - // SOX: log the renewal outcome so the new certificate ID and status are - // independently recorded (the outer Enroll method also logs, but this - // ensures the renew path is auditable if the result is further transformed). - _logger.LogInformation( - "Renewal via CERTInext renew API complete. " + - "PriorCARequestID={PriorId}, NewCARequestID={NewId}, Status={Status}", - priorCaRequestId, renewResult.CARequestID, renewResult.Status); + _logger.LogWarning(csrEx, + "V2 SubmitCsrV2Async failed with a transport-level or timeout error for order " + + "{OrderId}; tracking the order before deciding whether to cancel it (CERTInext " + + "may have already accepted the CSR).", orderId); - return renewResult; + V2OrderStatusResponse trackedAfterCsrFailure; + try + { + trackedAfterCsrFailure = await _client.TrackOrderV2Async(ep.ProductFamilySlug, orderId); + } + catch (Exception trackEx) + { + _logger.LogWarning(trackEx, + "V2 TrackOrderV2Async also failed while resolving an ambiguous CSR-submit " + + "failure for order {OrderId}; returning pending without cancelling.", orderId); + _logger.MethodExit(LogLevel.Debug); + return new EnrollmentResult + { + CARequestID = orderId, + Certificate = null, + Status = (int)EndEntityStatus.EXTERNALVALIDATION, + StatusMessage = $"V2 order {orderId} placed; CSR submission result is unknown " + + "after a transport error and the follow-up status check also " + + "failed — sync will resolve." + }; + } + + if (string.Equals(trackedAfterCsrFailure.Status, Constants.ApiV2.StatusPendingCsr, + StringComparison.OrdinalIgnoreCase)) + { + // Confirmed: the CSR never landed. Cancel the orphaned order. + var orphanResult = await CancelOrphanedV2OrderAfterCsrFailureAsync( + ep.ProductFamilySlug, orderId, csrEx); + _logger.MethodExit(LogLevel.Debug); + return orphanResult; + } + + _logger.LogInformation( + "V2 CSR submission actually succeeded despite a transport-level error — order " + + "{OrderId} progressed to status {Status}. Continuing normal post-CSR flow.", + orderId, trackedAfterCsrFailure.Status); + postCreateStatus = trackedAfterCsrFailure; + disposition = StatusMapper.V2StatusToRequestDisposition(trackedAfterCsrFailure.Status); + lastKnownCaStatus = trackedAfterCsrFailure.Status; + statusResolved = true; + } + + if (!statusResolved) + _logger.LogInformation("V2 CSR submitted. OrderId={OrderId}", orderId); } else { + // SSL/TLS: the CSR went inline on the create call, so the order is + // already past 'pending-csr' and there is no Submit CSR step. The create call itself usually holds + // until the CA has issued (or parked the order at pending-approval / pending-dcv). _logger.LogInformation( - "Certificate '{Id}' is outside the renewal window ({Window} days) — issuing new certificate. Subject={Subject}", - priorCaRequestId, ep.RenewalWindowDays, subject); - return await EnrollNewAsync(csr, subject, san, ep); + "V2 CSR sent inline on order create (no separate Submit CSR call). OrderId={OrderId}, Family={Family}", + orderId, ep.ProductFamilySlug); } - } - // --------------------------------------------------------------------------- - // DCV helpers - // --------------------------------------------------------------------------- + // Track once to read the authoritative status (and, for DV, the per-domain verification + // block the DCV step below needs). Guard: if TrackOrderV2Async fails transiently the order + // already exists and carries its CSR; return pending with the known orderId so Command has + // a CARequestID and the next sync can resolve the status. + if (!statusResolved) + { + try + { + postCreateStatus = await _client.TrackOrderV2Async(ep.ProductFamilySlug, orderId); + disposition = StatusMapper.V2StatusToRequestDisposition(postCreateStatus.Status); + lastKnownCaStatus = postCreateStatus.Status; + } + catch (Exception trackEx) + { + _logger.LogWarning(trackEx, + "V2 TrackOrderV2Async failed after order create for order {OrderId}; " + + "returning pending so sync can pick it up.", orderId); + _logger.MethodExit(LogLevel.Debug); + return new EnrollmentResult + { + CARequestID = orderId, + Certificate = null, + Status = (int)EndEntityStatus.EXTERNALVALIDATION, + StatusMessage = "V2 order placed with the CSR; status check failed transiently — sync will resolve." + }; + } + } - /// - /// True when a GetDcv failure is the CERTInext-side "DCV slot is exposed in - /// TrackOrder but the endpoint won't accept calls yet" condition. Observed as the - /// API error EMS-956 "Invalid Request for this API" for several hours after - /// enrollment — see analysis/certinext-support-ticket-2026-05-12.md. - /// - /// Detection is intentionally narrow: - /// * If the message contains the literal code EMS-956, treat it as the - /// known not-ready condition. - /// * Otherwise, only fall back to the human-readable phrase match when *no other* - /// EMS-NNN code is present. Without that guard, an upstream proxy or WAF - /// returning a 4xx whose body happens to contain "Invalid Request for this API …" - /// plus a different CERTInext code (e.g. EMS-401) would be silently deferred, - /// masking a real authentication or input-validation failure. - /// - private static bool IsDcvNotYetReady(Exception ex) + if (inlineCsr + && string.Equals(postCreateStatus?.Status, Constants.ApiV2.StatusPendingCsr, StringComparison.OrdinalIgnoreCase)) + { + // Not observed on SSL (every inline create left pending-csr immediately), but a + // family that silently ignores the inline csr would park here forever. + _logger.LogWarning( + "V2 order {OrderId} is still '{Status}' right after a create that carried the CSR inline — " + + "the CA may not have consumed the CSR. Family={Family}", + orderId, postCreateStatus?.Status, ep.ProductFamilySlug); + } + + // pending-agreement: the CA will not release the certificate until the Subscriber + // Agreement is accepted. The create body already carried the agreement, so this is a + // fallback for an order that still lands here; at most once per enrollment call. + await TryAcceptV2AgreementAsync(postCreateStatus, ep.ProductFamilySlug, orderId, agreementContext); + + // Whether the inline DCV block below took ownership of the in-call issuance wait for + // this order. Declared outside the #if so both build flavors compile the + // pickup-gate call below the same way (it simply stays false on the no-DCV build). + // Mirrors dcvIssuanceWaitRan in EnrollNewAsync, but the condition is derived + // differently: V2's outer gate here is only "order landed in pending-dcv" — whether + // DCV is actually configured/enabled is checked *inside* PerformDcvV2IfNeededAsync, not + // at this call site — so the flag cannot be pre-set before calling it (that would also + // catch the DCV-disabled case and wrongly skip pickup for every V2 order). Instead this + // is set from PerformDcvV2IfNeededAsync's own return contract ("true when DCV steps were + // executed, false when cleanly skipped"), which is the one source of truth for whether + // an in-call wait was actually spent. + bool dcvV2Ran = false; + +#if SUPPORTS_DCV + // Attempt DCV inline when the order lands in pending-dcv and DCV is configured + if (disposition == (int)EndEntityStatus.EXTERNALVALIDATION) + { + int timeoutMinutes = _config.GetEffectiveDcvTimeoutMinutes(); + using var dcvCts = CancellationTokenSource.CreateLinkedTokenSource(CancellationToken.None); + dcvCts.CancelAfter(TimeSpan.FromMinutes(timeoutMinutes)); + try + { + bool dcvDone = await PerformDcvV2IfNeededAsync( + orderId, domain, ep.ProductFamilySlug, dcvCts.Token, + postCreateStatus?.Verifications?.Domain?.Domains); + dcvV2Ran = dcvDone; + if (dcvDone) + { + // Re-check status after DCV completes + var tracked = await _client.TrackOrderV2Async(ep.ProductFamilySlug, orderId); + disposition = StatusMapper.V2StatusToRequestDisposition(tracked.Status); + lastKnownCaStatus = tracked.Status; + _logger.LogInformation( + "V2 DCV completed inline for order {OrderId}. Post-DCV status={Status}", + orderId, tracked.Status); + await TryAcceptV2AgreementAsync(tracked, ep.ProductFamilySlug, orderId, agreementContext); + } + } + catch (Exception dcvEx) + { + // Every early-exit path inside PerformDcvV2IfNeededAsync (not configured, no + // domain, in-flight elsewhere, GetDcv/staging/verify failure) is caught + // internally and returns false rather than throwing — the only way an + // exception reaches here is VerifyDcvV2Async failing *after* the TXT record + // was already staged and the propagation delay already spent. Real in-call + // wait time was consumed, so still treat this as "DCV ran" and defer to the + // next sync rather than stacking a pickup poll on top. + dcvV2Ran = true; + _logger.LogWarning(dcvEx, + "V2 inline DCV attempt failed for order {OrderId}; order will remain pending for sync.", + orderId); + } + } +#endif + + // If the order issued immediately, download the certificate + if (disposition == (int)EndEntityStatus.GENERATED) + { + try + { + var certResp = await _client.DownloadCertificateV2Async(ep.ProductFamilySlug, orderId); + string fullChain = AssembleV2CertChain(certResp); + _logger.LogInformation( + "V2 certificate downloaded immediately. OrderId={OrderId}, SerialNumber={Serial}, ChainPemCount={ChainCount}", + orderId, certResp.SerialNumber, certResp.ChainPem?.Count ?? 0); + _logger.MethodExit(LogLevel.Debug); + return new EnrollmentResult + { + CARequestID = orderId, + Certificate = fullChain, + Status = (int)EndEntityStatus.GENERATED, + StatusMessage = "Certificate issued via V2 API." + }; + } + catch (Exception dlEx) + { + if (IsCertificateNotGeneratedYet(dlEx)) + { + // Issued at the CA but the certificate is not generated yet (422 EMS-1165): + // expected, not an error. The pickup poll below keeps waiting for it. + _logger.LogDebug( + "V2 order {OrderId} is issued at CERTInext but its certificate is not generated yet " + + "(Download Certificate 422 EMS-1165). {States}. Returning pending; pickup polling continues.", + orderId, DescribeV2States(postCreateStatus)); + } + else + { + _logger.LogWarning(dlEx, + "V2 order is 'issued' but certificate download failed — returning pending. OrderId={OrderId}", + orderId); + } + } + } + + // Synchronous certificate pickup (V2 parity with the V1/Sectigo pickup poll): + // poll for the issued certificate so a fast-issuing DV order returns GENERATED + // + PEM in this same call instead of waiting for the next synchronization. No-op when + // the inline DCV block above already ran an in-call wait for this order (dcvV2Ran). + var pendingResult = new EnrollmentResult + { + CARequestID = orderId, + Certificate = null, + Status = disposition == (int)EndEntityStatus.GENERATED + ? (int)EndEntityStatus.EXTERNALVALIDATION + : disposition, + StatusMessage = $"V2 order placed. Status={createResp.Status}" + }; + var (pickedUpResult, observedCaStatus) = await PickUpEnrolledCertificateV2Async( + pendingResult, orderId, ep.ProductFamilySlug, dcvV2Ran, lastKnownCaStatus, + agreementContext: agreementContext); + + // Normalize a body-less REVOKED disposition to FAILED once here, right + // before returning — every path above that can surface REVOKED (the post-create + // status check, the post-DCV status re-check, and PickUpEnrolledCertificateV2Async's + // own poll) funnels through pickedUpResult, so a single check here covers all of them + // rather than patching each branch individually. See NormalizeV2RevokedEnrollResult. + var finalResult = NormalizeV2RevokedEnrollResult(pickedUpResult, orderId, observedCaStatus); + + _logger.MethodExit(LogLevel.Debug); + return finalResult; + } + + /// + /// Two-call flow only (V2InlineCsr=false, and always for Private PKI). + /// True when (thrown by SubmitCsrV2Async) + /// represents a transport-level failure, timeout, or cancellation — i.e. whether CERTInext + /// actually received and recorded the CSR is unknown — rather than a definitive CA-side + /// rejection (a real HTTP 4xx response CERTInext returned after processing the request). + /// CERTInextClient is built with ThrowOnAnyError=false, so a connection + /// failure/timeout never received a response and instead renders through + /// ThrowOnV2Failure's generic fallback as "... HTTP 0. ..." — 0 is the + /// RestSharp default when no response arrived. + /// A 5xx or any message shape this cannot parse is treated the same conservative way (not + /// a confirmed rejection): a CA server error or an unrecognized failure does not confirm + /// the CSR was rejected, so the safer default is to track the order rather than assume. + /// Only a parsed 4xx status is treated as definitive. + /// + internal static bool IsTransportLevelCsrFailure(Exception ex) { - if (ex == null) return false; - string msg = ex.Message ?? string.Empty; - if (msg.IndexOf("EMS-956", StringComparison.OrdinalIgnoreCase) >= 0) + if (ex == null) return true; + if (ex is OperationCanceledException) return true; + if (ex is System.Net.Http.HttpRequestException) return true; + if (ex is TimeoutException) return true; + + var m = System.Text.RegularExpressions.Regex.Match(ex.Message ?? string.Empty, @"HTTP (\d+)\."); + if (!m.Success) return true; + int status = int.Parse(m.Groups[1].Value, System.Globalization.CultureInfo.InvariantCulture); + return status < 400 || status >= 500; + } + + /// + /// SSL.com organization-validation pre-check for a V2 OV or EV SSL/TLS order. Advisory only: + /// every failure and every not-validated outcome is logged as a warning and the order is + /// placed anyway, so this never throws and never blocks an enrollment. + /// + /// 1. GET the organization's SSL.com status. If SSL.com reports + /// validated (), done. + /// 2. Otherwise POST /sync once (SSL.com may have validated it since the last read) and + /// re-evaluate. + /// 3. Still not validated: when SslComSubmitOrganization is on, the level isn't already + /// requested, and the readiness block says the organization is ready for that level (a + /// missing readiness block counts as not ready), POST the submission with + /// subscriberAgreementAccepted: true (and SslComAdminEmail if set). That + /// accepts SSL.com's subscriber agreement on the organization's behalf, so the intent is + /// audit-logged before the call. + /// 4. Anything still not validated is logged once at Warning with what SSL.com reports + /// missing; contact emails are masked unless LogSensitiveRequestData is on. + /// + private async Task EnsureSslComOrganizationValidationAsync(string organizationNumber, string level) + { + _logger.MethodEntry(LogLevel.Debug); + V2SslComValidation validation; + try + { + validation = await _client.GetSslComValidationAsync(organizationNumber); + } + catch (Exception ex) + { + _logger.LogWarning( + "SSL.com validation status for organization {OrganizationNumber} could not be read; placing the {Level} " + + "order anyway. Error={Error}", organizationNumber, level, RedactAndCapForLog(ex.Message)); + _logger.MethodExit(LogLevel.Debug); + return; + } + + if (validation != null && validation.IsLevelValidated(level)) + { + _logger.LogInformation( + "SSL.com has validated organization {OrganizationNumber} at {Level}.", organizationNumber, level); + _logger.MethodExit(LogLevel.Debug); + return; + } + + // Not validated according to the cached status: ask SSL.com once for a fresh read. + try + { + var refreshed = await _client.SyncSslComValidationAsync(organizationNumber); + if (refreshed != null) validation = refreshed; + if (validation != null && validation.IsLevelValidated(level)) + { + _logger.LogInformation( + "SSL.com has validated organization {OrganizationNumber} at {Level} (after a status refresh).", + organizationNumber, level); + _logger.MethodExit(LogLevel.Debug); + return; + } + } + catch (Exception ex) + { + _logger.LogWarning( + "SSL.com validation refresh for organization {OrganizationNumber} failed; using the status read earlier. " + + "Error={Error}", organizationNumber, RedactAndCapForLog(ex.Message)); + } + + bool submitted = false; + string submitSkipReason = null; + if (validation == null) + { + submitSkipReason = "SSL.com returned no status"; + } + else if (!_config.SslComSubmitOrganization) + { + submitSkipReason = "SslComSubmitOrganization is off"; + } + else if (validation.IsLevelListed(level)) + { + submitSkipReason = $"{level} was already requested from SSL.com"; + } + else if (!SslComReadyFor(validation.Readiness, level)) + { + submitSkipReason = $"SSL.com reports the organization is not ready for {level} (or no readiness information)"; + } + else + { + string adminEmail = string.IsNullOrWhiteSpace(_config.SslComAdminEmail) ? null : _config.SslComAdminEmail.Trim(); + + // Audit trail: this call accepts SSL.com's subscriber agreement on the organization's + // behalf, so the intent is recorded before it is made, even if the call then fails. + _logger.LogInformation( + "SSL.com organization validation submission attempt started. OrganizationNumber={OrganizationNumber}, " + + "Levels=[{Level}], SubscriberAgreementAccepted=true (SSL.com's subscriber agreement is accepted on the " + + "organization's behalf, per SslComSubmitOrganization=true), AdminEmail={AdminEmail}", + organizationNumber, level, + adminEmail == null ? "(none)" : MaskEmailForLog(adminEmail)); + + try + { + var response = await _client.SubmitSslComValidationAsync(organizationNumber, new V2SslComSubmitRequest + { + Levels = new List { level }, + SubscriberAgreementAccepted = true, + AdminEmail = adminEmail + }); + submitted = true; + if (response != null) validation = response; + _logger.LogInformation( + "SSL.com organization validation submitted. OrganizationNumber={OrganizationNumber}, Level={Level}, " + + "SslComStatus={Status}", organizationNumber, level, DescribeSslComText(validation?.Status)); + if (validation != null && validation.IsLevelValidated(level)) + { + _logger.MethodExit(LogLevel.Debug); + return; + } + } + catch (Exception ex) + { + _logger.LogWarning( + "SSL.com organization validation submission failed. OrganizationNumber={OrganizationNumber}, Level={Level}, " + + "Error={Error}", organizationNumber, level, RedactAndCapForLog(ex.Message)); + } + } + + // Not validated, whatever was tried: warn with what SSL.com says, then place the order anyway. + var readiness = validation?.Readiness; + var missing = string.Equals(level, "EV", StringComparison.OrdinalIgnoreCase) ? readiness?.EvMissing : readiness?.Missing; + _logger.LogWarning( + "SSL.com has not validated organization {OrganizationNumber} at {Level}; placing the order anyway, so it " + + "may stay pending until SSL.com validates the organization. SslComStatus={Status}, Levels={Levels}, " + + "LastError={LastError}, Missing=[{Missing}], SoftMissing=[{SoftMissing}], SubmittedThisCall={Submitted}, " + + "NotSubmittedBecause={SkipReason}, SslComContact={Contact}", + organizationNumber, level, + DescribeSslComText(validation?.Status), + validation == null ? "(unknown)" : DescribeSslComText(validation.Levels.ValueKind == System.Text.Json.JsonValueKind.Undefined + ? null : validation.Levels.GetRawText()), + DescribeSslComText(validation?.LastError), + string.Join(", ", (missing ?? new List()).Select(DescribeSslComText)), + string.Join(", ", (readiness?.SoftMissing ?? new List()).Select(DescribeSslComText)), + submitted, submitSkipReason ?? "(not applicable)", + string.IsNullOrWhiteSpace(validation?.Contact?.Email) ? "(none)" : MaskEmailForLog(validation.Contact.Email)); + _logger.MethodExit(LogLevel.Debug); + } + + /// + /// True when the SSL.com readiness block says the organization can be submitted at + /// : the matching ready flag is true and the matching missing list is empty. + /// A missing block, or a flag that is absent, counts as not ready. + /// + internal static bool SslComReadyFor(V2SslComReadiness readiness, string level) + { + if (readiness == null) return false; + bool ev = string.Equals(level, "EV", StringComparison.OrdinalIgnoreCase); + bool? flag = ev ? readiness.EvReady : readiness.Ready; + var missing = ev ? readiness.EvMissing : readiness.Missing; + return flag == true && (missing == null || missing.Count == 0); + } + + /// SSL.com/CA free text for a log line: control characters stripped, emails masked unless sensitive logging is on, capped. + private string DescribeSslComText(string text) + { + if (string.IsNullOrWhiteSpace(text)) return "(none)"; + string sanitized = LogSanitizer.SanitizeCaText(text, _config.LogSensitiveRequestData); + return sanitized.Length <= 200 ? sanitized : sanitized.Substring(0, 200) + "…"; + } + + private string MaskEmailForLog(string email) => + _config.LogSensitiveRequestData ? LogSanitizer.Strip(email) : LogSanitizer.MaskEmail(email); + + /// + /// The signer values for, and the per-order "already attempted" memory of, the V2 + /// accept-agreement fallback. One instance per enroll call or per sync pass, so an order is + /// attempted at most once in that scope. + /// + internal sealed class V2AgreementAcceptContext + { + public V2AgreementAcceptContext(string signerName, string signerPlace) + { + SignerName = signerName; + SignerPlace = signerPlace; + } + + public string SignerName { get; } + public string SignerPlace { get; } + public bool HasSigner => !string.IsNullOrWhiteSpace(SignerName) && !string.IsNullOrWhiteSpace(SignerPlace); + public HashSet AttemptedOrderIds { get; } = new HashSet(StringComparer.Ordinal); + } + + /// + /// When Track Order shows an SSL/TLS order at pending-agreement (the CA will not + /// release the certificate until the Subscriber Agreement is accepted), accepts it with + /// POST /ssl-certificates/{orderId}/agreement using the same signer values the create + /// body carried. At most once per order per ; never throws (a + /// failure is logged at Warning and the order simply stays pending for a later pass); + /// does nothing for any other status or for a non-SSL family. The intent is audit-logged + /// before the call, in the style of the revocation audit line; the signer's name and place + /// are personal data and only appear when LogSensitiveRequestData is on. Returns true + /// when the CA accepted the call. + /// + private async Task TryAcceptV2AgreementAsync( + V2OrderStatusResponse tracked, string familySlug, string orderId, + V2AgreementAcceptContext context, CancellationToken ct = default) + { + if (context == null || tracked == null || string.IsNullOrWhiteSpace(orderId)) return false; + if (!string.Equals(tracked.Status, Constants.ApiV2.StatusPendingAgreement, StringComparison.OrdinalIgnoreCase)) return false; + if (!string.Equals(familySlug, Constants.ApiV2.FamilySsl, StringComparison.Ordinal)) return false; + if (!context.AttemptedOrderIds.Add(orderId)) return false; + + if (string.IsNullOrWhiteSpace(context.SignerName) || string.IsNullOrWhiteSpace(context.SignerPlace)) + { + _logger.LogWarning( + "V2 order {OrderId} is waiting at pending-agreement but the Subscriber Agreement was not accepted: " + + "the signer name or place is blank (set RequestorName/SignerName and SignerPlace). The order stays pending.", + orderId); + return false; + } + + // Audit trail: accepting the Subscriber Agreement is a legal act made on the signer's behalf, + // so the intent is recorded before the call, even if the call then fails. + _logger.LogInformation( + "V2 Subscriber Agreement acceptance attempt started. CARequestID={Id}, Family={Family}, " + + "Trigger=pending-agreement, SignerName={SignerName}, SignerPlace={SignerPlace}", + orderId, familySlug, + _config.LogSensitiveRequestData ? LogSanitizer.Strip(context.SignerName) : "(withheld)", + _config.LogSensitiveRequestData ? LogSanitizer.Strip(context.SignerPlace) : "(withheld)"); + + try + { + await _client.AcceptAgreementV2Async(familySlug, orderId, new V2AgreementParams + { + SignerName = context.SignerName, + SignerPlace = context.SignerPlace, + Accepted = true + }, ct); + _logger.LogInformation( + "V2 Subscriber Agreement accepted. CARequestID={Id}, Family={Family}", orderId, familySlug); return true; - bool hasPhrase = msg.IndexOf("Invalid Request for this API", StringComparison.OrdinalIgnoreCase) >= 0; - bool hasOtherEmsCode = System.Text.RegularExpressions.Regex.IsMatch(msg, @"\bEMS-\d+\b"); - return hasPhrase && !hasOtherEmsCode; + } + catch (Exception ex) + { + if (ex is OperationCanceledException && ct.IsCancellationRequested) throw; + // Never fail the enrollment or the sync over this: the order stays pending and a + // later pass (or the CA's own processing) moves it on. + _logger.LogWarning( + "V2 Subscriber Agreement acceptance failed; the order stays pending. CARequestID={Id}, " + + "Family={Family}, Error={Error}", + orderId, familySlug, RedactAndCapForLog(ex.Message)); + return false; + } } - // (`DomainValidatorConfigProvider` nested helper removed — it declared an - // implementation of `Keyfactor.AnyGateway.Extensions.IDomainValidatorConfigProvider`, - // a v3.3-only interface, but the type was never instantiated anywhere in the - // plugin. Keeping a nested type whose base list references a missing assembly - // type is a hazard for CLR class-load on v3.2 hosts (see issue #7). Dead code - // that costs nothing to remove.) + /// + /// True when a V2 Download Certificate failure is CERTInext's 422 EMS-1165 + /// ("Invalid request status"). Callers only ask this for an order the CA already reports as + /// issued; there it means "issued at the CA, certificate not generated yet" (normally + /// about 20 s, though the sandbox has been seen to take far longer) rather than a real + /// failure. The same code also means "never downloadable" for a revoked order, but those + /// orders are not downloaded. The client throws ; + /// the message check covers any other that surfaces the same + /// 422 as a plain exception. + /// + internal static bool IsCertificateNotGeneratedYet(Exception ex) + { + if (ex is V2CertificateNotGeneratedException) return true; + string m = ex?.Message; + return m != null + && m.IndexOf("EMS-1165", StringComparison.OrdinalIgnoreCase) >= 0 + && m.IndexOf("HTTP 422", StringComparison.OrdinalIgnoreCase) >= 0; + } /// - /// Best-effort DCV retry for an order that may still be pending validation. - /// - /// Called from Synchronize and GetSingleRecord so that orders which CERTInext placed - /// into "Pending for Approver"/"Pending System RA" between enrollment and the next - /// gateway cycle (when domainVerification was still null at enroll time) can be - /// driven forward through DCV. Wraps with: - /// * a per-order in-flight guard so overlapping sync cycles or a sync+single - /// refresh do not double-stage TXT records, - /// * a bounded DCV timeout linked to the caller's cancellation token, - /// * swallowing of non-cancellation exceptions so a single bad order does not - /// halt a 12-hour sync — the order will be retried on the next cycle. - /// - /// Uses a single-shot challenge check (waitForChallengeSeconds=0) by default - /// because sync runs periodically: if CERTInext hasn't yet exposed the DCV slot for - /// this order, the next sync cycle will pick it up. Waiting per-order during sync - /// scales poorly — a single pending order's 60s budget becomes minutes of wasted - /// gateway thread time across an account with many orders. See PR #2 discussion. + /// CERTInext's free-text orderState/certificateState for a log line (masked and + /// stripped like other CA text). Diagnostic only: the vocabulary is undocumented, so no logic + /// branches on it. + /// + private string DescribeV2States(V2OrderStatusResponse status) + { + string Show(string v) => string.IsNullOrWhiteSpace(v) + ? "(not reported)" + : LogSanitizer.SanitizeCaText(v, _config?.LogSensitiveRequestData ?? false); + return $"OrderState='{Show(status?.OrderState)}', CertificateState='{Show(status?.CertificateState)}'"; + } + + /// + /// Cancel reason sent to CERTInext when Submit CSR fails after the order was created. + /// Deliberately fixed text: the CSR exception may carry CA response detail, + /// and the reason is persisted in the CA's audit log. + /// + internal const string OrphanedOrderCancelReason = + "Keyfactor gateway: CSR submission failed; cancelling orphaned order."; + + /// + /// calls this when SubmitCsrV2Async throws + /// after the order was placed. Makes exactly one best-effort CancelOrderV2Async + /// call (never retried, never rethrown) and returns a FAILED result that carries the + /// orderId and says whether the orphaned order was cancelled. + /// + private async Task CancelOrphanedV2OrderAfterCsrFailureAsync( + string familySlug, string orderId, Exception csrEx) + { + _logger.MethodEntry(LogLevel.Trace); + // The CSR exception message can carry CA response detail (problem+json "detail"), + // so it is redacted like any other CA body and capped at 500 characters. + string csrFailure = RedactAndCapForLog(csrEx.Message); + + string cancelOutcome; + string cancelMessage; + try + { + var outcome = await _client.CancelOrderV2Async(familySlug, orderId, OrphanedOrderCancelReason); + if (outcome == V2CancelOrderOutcome.Cancelled) + { + cancelOutcome = "cancelled"; + cancelMessage = "The orphaned order was cancelled."; + } + else + { + cancelOutcome = "not cancelled (HTTP 422: order already in a terminal state)"; + cancelMessage = "The orphaned order was NOT cancelled: the CA reported it is already in a " + + "terminal state (HTTP 422). Check the order in the CERTInext portal."; + } + } + catch (Exception cancelEx) + { + cancelOutcome = $"not cancelled (cancel failed: {cancelEx.GetType().Name}: " + + $"{RedactAndCapForLog(cancelEx.Message)})"; + cancelMessage = "The orphaned order was NOT cancelled: the cancel request failed. " + + "Cancel it manually in the CERTInext portal. See gateway logs for details."; + } + + _logger.LogWarning( + "V2 CSR submission failed after the order was placed. OrderId={OrderId}, Family={Family}, " + + "CsrFailure={CsrFailure}, CancelOutcome={CancelOutcome}", + orderId, familySlug, csrFailure, cancelOutcome); + + _logger.MethodExit(LogLevel.Trace); + return new EnrollmentResult + { + CARequestID = orderId, + Certificate = null, + Status = (int)EndEntityStatus.FAILED, + StatusMessage = $"V2 CSR submission failed for order {orderId}: {csrFailure} {cancelMessage}" + }; + } + + private string RedactAndCapForLog(string message) + { + string redacted = CERTInextClient.ApplyLoggingRedaction(message ?? string.Empty, _config?.LogSensitiveRequestData ?? false); + return redacted.Length <= 500 ? redacted : redacted.Substring(0, 500) + "…"; + } + + /// + /// At enroll time the gateway never holds a stored certificate body for a + /// brand-new order — unlike the Synchronize/GetSingleRecord guard (), there is no "gateway already holds a body" case + /// for to fall back to. A REVOKED disposition surfaced from V2 + /// enrollment — whether observed on the post-create status check, the post-DCV status + /// re-check, or 's own poll — is therefore + /// always body-less. Persisting that as a REVOKED row with Certificate = null would + /// poison the gateway (RevocationDate never clears, and every + /// later revoked-certificate search calls FromDER(null) and 500s). Mapped to FAILED here, + /// once, on the final result is about to return, rather than in + /// each branch that can produce a REVOKED disposition. + /// + private EnrollmentResult NormalizeV2RevokedEnrollResult(EnrollmentResult result, string orderId, string observedCaStatus) + { + if (result == null || result.Status != (int)EndEntityStatus.REVOKED) + return result; + + // SOC2 audit trail: the log must show the CA reported revoked and the plugin reported + // FAILED, with enough context (order id + raw CA status) to reconstruct why. + _logger.LogWarning( + "V2 enroll observed order '{OrderId}' as revoked at the CA (raw status='{CaStatus}') " + + "before a certificate was ever delivered. Mapping the enrollment result to FAILED " + + "instead of a body-less REVOKED record — Enroll has no stored certificate body to " + + "fall back on, unlike the Synchronize/GetSingleRecord guard.", + orderId, string.IsNullOrWhiteSpace(observedCaStatus) ? "(unknown)" : observedCaStatus); + + string statusSuffix = string.IsNullOrWhiteSpace(observedCaStatus) + ? string.Empty + : $" (CA status '{observedCaStatus}')"; + + return new EnrollmentResult + { + CARequestID = result.CARequestID, + Certificate = null, + Status = (int)EndEntityStatus.FAILED, + StatusMessage = $"Order '{orderId}' was revoked at the CA{statusSuffix} before a " + + "certificate could be delivered; reporting enrollment failure rather " + + "than a certificate revocation with no certificate body." + }; + } + + /// + /// True when the gateway already holds this order with the status the listing reports and + /// a stored certificate body, so an incremental V1 pass can skip the TrackOrder + + /// DownloadCertificate refetch. A row whose status differs (e.g. issued → revoked), a row + /// with no body (an earlier refetch failed), no row at all (new order), no reader, or any + /// lookup failure all return false and the order is processed as before. + /// + private async Task IsUnchangedInGatewayAsync(string caRequestId, int listedStatus) + { + if (_certificateDataReader == null || string.IsNullOrWhiteSpace(caRequestId)) + return false; + + try + { + int dbStatus = await _certificateDataReader.GetStatusByRequestID(caRequestId); + if (dbStatus != listedStatus) + return false; + + bool unchanged = _certificateDataReader.GetExpirationDateByRequestId(caRequestId).HasValue; + if (unchanged) + { + _logger.LogTrace( + "Sync: order '{Id}' is already held by the gateway with status {Status} — not refetching.", + caRequestId, listedStatus); + } + return unchanged; + } + catch (Exception ex) + { + // The reader throws when there is no gateway row yet (new order); treat that and any + // other failure as "changed" so the order is processed as before. + _logger.LogTrace(ex, + "Sync: could not confirm gateway state for order '{Id}'; processing it normally.", + caRequestId); + return false; + } + } + + /// + /// Outcome of — what a Synchronize or + /// GetSingleRecord caller (V1 or V2) should do with a REVOKED disposition that has no + /// downloadable certificate body. + /// + private enum BodylessRevokedDecision + { + /// Gateway already holds a body for this order — emit REVOKED with no + /// body (this is how out-of-band CA revokes propagate). + EmitRevoked, + /// Gateway has a row but no body — downgrade to FAILED so the gateway + /// never persists a REVOKED row with Certificate = null. + EmitFailed, + /// Gateway has no row at all (or the reader can't be consulted) — + /// the caller should not create a brand-new poisoned row. + Skip + } + + /// + /// CERTInext refuses to serve a revoked certificate's body (V2: 422 EMS-1165; V1: the + /// client never downloads a revoked order, see CERTInextClient.IsCertificateDownloadable), + /// so an order whose first gateway sighting is already revoked has no body to attach. + /// Used by both the V1 and V2 Synchronize / GetSingleRecord paths. + /// Emitting that as a body-less REVOKED record is what poisons the + /// gateway: it persists the row with RevocationDate set and Certificate = + /// null, never clears the date afterward, and its own revoked-certificate search + /// then calls FromDER(null) on every future scan of this CA — a 500 that blocks + /// *all* Command sync for the CA, not just this record. /// - /// Returns true when DCV actually executed (or DCV is already complete), - /// false when skipped. + /// A body-less REVOKED record is safe — and required, to propagate out-of-band CA + /// revokes — only when the gateway already holds a certificate body for this + /// CARequestID: the gateway keeps the stored body and applies status/date/reason on top + /// of it. is the per-order probe + /// for that: it returns the stored cert's NotAfter when a body is held, null when + /// the row exists but has no body, and throws when there + /// is no row at all. /// - private async Task TryRunDcvDuringSyncAsync(string orderNumber, CancellationToken ct, bool fastSync = false) + private BodylessRevokedDecision DecideBodylessRevokedRecord(string caRequestId) { - _logger.MethodEntry(LogLevel.Debug); -#if SUPPORTS_DCV - if (_domainValidatorFactory == null || !_config.DcvEnabled || string.IsNullOrEmpty(orderNumber)) + if (_certificateDataReader == null) + { + _logger.LogWarning( + "No ICertificateDataReader available to check whether the gateway holds a " + + "certificate body for revoked order '{Id}' — skipping this cycle rather than risk " + + "poisoning a fresh gateway row with a body-less REVOKED record.", caRequestId); + return BodylessRevokedDecision.Skip; + } + + try + { + DateTime? expiry = _certificateDataReader.GetExpirationDateByRequestId(caRequestId); + if (expiry.HasValue) + { + _logger.LogDebug( + "Gateway already holds a certificate body for revoked order '{Id}' " + + "(expires {Expiry:O}) — emitting body-less REVOKED to propagate the revocation.", + caRequestId, expiry.Value); + return BodylessRevokedDecision.EmitRevoked; + } + + _logger.LogInformation( + "Gateway has a row for revoked order '{Id}' with no certificate body — " + + "emitting FAILED instead of a body-less REVOKED record to avoid poisoning the " + + "gateway's revoked-certificate search.", caRequestId); + return BodylessRevokedDecision.EmitFailed; + } + catch (ArgumentException) + { + _logger.LogInformation( + "Gateway has no row at all for revoked order '{Id}' — skipping rather than " + + "create a body-less REVOKED row the gateway can never un-poison.", caRequestId); + return BodylessRevokedDecision.Skip; + } + catch (Exception ex) + { + _logger.LogWarning(ex, + "Failed to determine whether the gateway holds a certificate body for revoked " + + "order '{Id}' — skipping this cycle rather than risk emitting a body-less REVOKED " + + "record. The revocation will be retried on a later sync/single-record call.", caRequestId); + return BodylessRevokedDecision.Skip; + } + } + + /// + /// Retrieves a single certificate record via the V2 REST API. + /// + private async Task GetSingleRecordV2Async(string caRequestID) + { + _logger.MethodEntry(LogLevel.Debug); + + try + { + // Use the family-aware resolve so DCV (if needed) hits the correct endpoint for + // non-SSL families (private-pki, signature). ResolveAndTrackOrderV2Async discards + // the family; here we keep it to thread through PerformDcvV2IfNeededAsync. + var (resolvedFamily, statusResp) = await _client.ResolveAndTrackOrderV2WithFamilyAsync(caRequestID); + int disposition = StatusMapper.V2StatusToRequestDisposition(statusResp.Status); + +#if SUPPORTS_DCV + // Mirror V1 GetSingleRecord: attempt DCV on pending-dcv orders so a manual + // single-record refresh can unstick an order whose DCV wasn't completed at enroll + // time. A UCC order's own domainEntries[] can carry pending SANs even + // when the top-level Domain field is populated (the common case) or, defensively, + // if it were ever blank — either is enough to attempt DCV. + var pendingDomainEntries = statusResp.Verifications?.Domain?.Domains; + if (disposition == (int)EndEntityStatus.EXTERNALVALIDATION + && (!string.IsNullOrWhiteSpace(statusResp.Domain) || (pendingDomainEntries?.Count ?? 0) > 0)) + { + int timeoutMinutes = _config.GetEffectiveDcvTimeoutMinutes(); + using var dcvCts = new CancellationTokenSource(TimeSpan.FromMinutes(timeoutMinutes)); + try + { + bool dcvDone = await PerformDcvV2IfNeededAsync( + caRequestID, statusResp.Domain, resolvedFamily, dcvCts.Token, pendingDomainEntries); + if (dcvDone) + { + statusResp = await _client.ResolveAndTrackOrderV2Async(caRequestID); + disposition = StatusMapper.V2StatusToRequestDisposition(statusResp.Status); + } + } + catch (Exception dcvEx) + { + _logger.LogWarning(dcvEx, + "V2 GetSingleRecord: DCV attempt failed for order {Id}.", caRequestID); + } + } +#endif + + string certPem = null; + if (disposition == (int)EndEntityStatus.GENERATED) + { + if (!string.IsNullOrWhiteSpace(statusResp.ExpiresAt)) + _logger.LogDebug( + "V2 order expiry from status response. CARequestID={Id}, ExpiresAt={ExpiresAt}", + caRequestID, statusResp.ExpiresAt); + + try + { + var certResp = await _client.ResolveAndDownloadCertificateV2Async(caRequestID); + certPem = AssembleV2CertChain(certResp); + } + catch (Exception dlEx) + { + if (IsCertificateNotGeneratedYet(dlEx)) + { + _logger.LogInformation( + "V2 GetSingleRecord: order is issued at CERTInext but its certificate is not generated " + + "yet (Download Certificate 422 EMS-1165); returning the record without a certificate " + + "body. CARequestID={Id}, {States}", caRequestID, DescribeV2States(statusResp)); + } + else + { + _logger.LogWarning(dlEx, + "V2 GetSingleRecord: order is issued but certificate download failed. CARequestID={Id}", + caRequestID); + } + } + } + + // A REVOKED disposition with no certificate body must never be + // returned as-is unless the gateway already holds a body for this order — see + // DecideBodylessRevokedRecord. GetSingleRecord can't skip (it must return + // something), so both the no-row and can't-tell cases fall through to FAILED. + int effectiveDisposition = disposition; + DateTime? effectiveRevocationDate = statusResp.Revocation?.ProcessedAt; + int effectiveRevocationReason = statusResp.Revocation != null + ? StatusMapper.V2RevocationReasonToCrlCode(statusResp.Revocation.Reason) + : 0; + + if (disposition == (int)EndEntityStatus.REVOKED && string.IsNullOrWhiteSpace(certPem)) + { + var decision = DecideBodylessRevokedRecord(caRequestID); + if (decision != BodylessRevokedDecision.EmitRevoked) + { + effectiveDisposition = (int)EndEntityStatus.FAILED; + effectiveRevocationDate = null; + effectiveRevocationReason = 0; + } + } + + _logger.LogInformation( + "GetSingleRecordV2 complete. CARequestID={Id}, V2Status={Status}, Disposition={Disposition}", + caRequestID, statusResp.Status, effectiveDisposition); + _logger.MethodExit(LogLevel.Debug); + + return new AnyCAPluginCertificate + { + CARequestID = caRequestID, + Certificate = certPem, + Status = effectiveDisposition, + ProductID = statusResp.ProductVariant ?? string.Empty, + RevocationDate = effectiveRevocationDate, + RevocationReason = effectiveRevocationReason + }; + } + catch (KeyNotFoundException) + { + _logger.LogWarning("V2: Certificate not found. CARequestID={Id}", caRequestID); + throw; + } + catch (Exception ex) + { + _logger.LogError(ex, "V2: Error retrieving certificate. CARequestID={Id}", caRequestID); + throw; + } + } + + /// + /// Synchronizes certificates via the V2 /reports/orders endpoint. + /// Called from when _config.UseV2Api is true; V1 + /// credentials are not required on this path. + /// + /// Lookback window (incremental sync): whether the from/to filter brackets + /// order-placement date or issuance date is not documented. Rather than depend on that, + /// an incremental pass requests + /// from = lastSync - V2SyncLookbackHours (default 72h) so an order created before + /// lastSync but issued afterward (e.g. a slow-DCV order) still surfaces. + /// + private async Task SynchronizeV2Async( + BlockingCollection blockingBuffer, + DateTime? lastSync, + bool fullSync, + CancellationToken cancelToken) + { + _logger.MethodEntry(LogLevel.Debug); + + string from = null; + if (!fullSync && lastSync.HasValue) + { + int lookbackHours = _config.V2SyncLookbackHours > 0 + ? _config.V2SyncLookbackHours + : Constants.ApiV2.DefaultSyncLookbackHours; + DateTime effectiveFrom = lastSync.Value.ToUniversalTime().AddHours(-lookbackHours); + from = effectiveFrom.ToString("yyyy-MM-dd"); + } + + // Issue 0090: hold back pending and issued orders that an in-flight enrollment may still be + // about to save. Applies to full and incremental passes alike; the next incremental pass + // imports what was held back (its lookback reaches well before any held-back order). + int recentOrderGraceSeconds = GetSyncRecentOrderGraceSeconds(_config); + + _logger.LogInformation( + "Starting CERTInext V2 synchronization. FullSync={FullSync}, LastSync={LastSync}, " + + "LookbackFrom={From}, RecentOrderGraceSeconds={Grace}, UseV2Api=true", + fullSync, lastSync?.ToString("O") ?? "none", from ?? "(none — full history)", + recentOrderGraceSeconds); + + int synced = 0; + int skipped = 0; + int errors = 0; + int deferredRecentOrders = 0; // pending/issued orders withheld because they are younger than the grace window + int unresolvedStatusFallbacks = 0; // report rows whose display strings needed a live track call + int issuedNotGeneratedYet = 0; // issued orders whose download answered 422 EMS-1165 (certificate not generated yet) + // Sync has no template, so the agreement signer is the connector's: RequestorName (the + // enroll default for SignerName) and SignerPlace. One context per pass: each order is + // attempted at most once per pass. + var agreementContext = new V2AgreementAcceptContext(_config.RequestorName, _config.SignerPlace); + + // Emit-side accounting (mirrors the V1 path). + int emittedGeneratedWithBody = 0, emittedGeneratedNoBody = 0, emittedRevoked = 0, emittedPending = 0; + // Bodyless-REVOKED guard decisions — see DecideBodylessRevokedRecord. + int emittedFailedFromBodylessRevoked = 0, skippedBodylessRevoked = 0; + +#if SUPPORTS_DCV + bool dcvOperational = _config.DcvEnabled && _domainValidatorFactory != null; + int ageWindowHours = _config.DcvSyncMaxOrderAgeHours; + int perPassCap = _config.DcvSyncMaxPerPass; + int dcvAttempted = 0, dcvSkippedAge = 0, dcvSkippedCap = 0; +#endif + + try + { + await foreach (var row in _client.ListOrdersV2Async(from, null, _config.PageSize, cancelToken)) + { + cancelToken.ThrowIfCancellationRequested(); + + try + { + DateTime? orderDateUtc = null; + if (DateTime.TryParse( + row.OrderDate, System.Globalization.CultureInfo.InvariantCulture, + System.Globalization.DateTimeStyles.AdjustToUniversal | System.Globalization.DateTimeStyles.AssumeUniversal, + out DateTime parsedOrderDate)) + orderDateUtc = parsedOrderDate; + + // Skip expired certificates when IgnoreExpired is configured — mirrors the + // V1 check above. CertificateExpiryDate is a string + // whose format is not guaranteed (see the OrderReportEntryV2 doc comment), so an + // unparseable or missing value must NOT be skipped — only a value that + // parses cleanly and is actually in the past is treated as expired. + DateTime? certExpiryUtc = null; + if (!string.IsNullOrWhiteSpace(row.CertificateExpiryDate) + && DateTime.TryParse( + row.CertificateExpiryDate, System.Globalization.CultureInfo.InvariantCulture, + System.Globalization.DateTimeStyles.AdjustToUniversal | System.Globalization.DateTimeStyles.AssumeUniversal, + out DateTime parsedExpiry)) + certExpiryUtc = parsedExpiry; + + if (_config.IgnoreExpired + && certExpiryUtc.HasValue + && certExpiryUtc.Value < DateTime.UtcNow) + { + _logger.LogTrace( + "V2 sync: skipping expired certificate '{Id}' (expires {ExpiresAt:u}).", + row.OrderNumber, certExpiryUtc.Value); + skipped++; + continue; + } + + int? disposition = MapV2ReportStatusToDisposition(row.OrderStatus, row.CertificateStatus); + string resolvedFamily = null; + V2OrderStatusResponse trackedStatus = null; + + if (disposition == null) + { + // Unrecognised orderStatus/certificateStatus combination — the display- + // string vocabulary mapped below is NOT guaranteed + // exhaustive. Don't guess: fall back to a live TrackOrder call, which + // returns the authoritative V2 `status` enum via StatusMapper. + unresolvedStatusFallbacks++; + _logger.LogDebug( + "V2 sync: unrecognised report status — falling back to live track. " + + "Id={Id}, OrderStatus={OrderStatus}, CertificateStatus={CertificateStatus}", + row.OrderNumber, row.OrderStatus, row.CertificateStatus); + (resolvedFamily, trackedStatus) = + await _client.ResolveAndTrackOrderV2WithFamilyAsync(row.OrderNumber, cancelToken); + disposition = StatusMapper.V2StatusToRequestDisposition(trackedStatus.Status); + } + + if (disposition == (int)EndEntityStatus.FAILED) + { + _logger.LogTrace( + "V2 sync: skipping order '{Id}' with terminal status. OrderStatus={OrderStatus}, " + + "CertificateStatus={CertificateStatus}", + row.OrderNumber, row.OrderStatus, row.CertificateStatus); + skipped++; + continue; + } + + // Issue 0090: do not hand the gateway a row for a pending or issued order + // whose enrollment may still be in flight. The gateway would insert a row + // with this CARequestID and the enrollment's own save would then fail on the + // unique (CA, CARequestID) index. Not emitting is safe: the next incremental + // pass re-lists the order (lookback window) and imports it. This runs before + // the DCV attempt and the certificate download, so a held-back order costs + // no extra CA calls. + if (ShouldDeferRecentOrder( + disposition.Value, orderDateUtc, DateTime.UtcNow, recentOrderGraceSeconds, + out double recentOrderAgeSeconds)) + { + _logger.LogInformation( + "V2 sync: holding back recent order until the next pass (an enrollment may " + + "still be saving it). CARequestID={Id}, Disposition={Disposition}, " + + "AgeSeconds={Age:F1}, GraceSeconds={Grace}.", + row.OrderNumber, disposition.Value, recentOrderAgeSeconds, recentOrderGraceSeconds); + deferredRecentOrders++; + continue; + } + +#if SUPPORTS_DCV + if (dcvOperational && disposition == (int)EndEntityStatus.EXTERNALVALIDATION) + { + var decision = EvaluateDcvSyncEligibility( + orderDateUtc, DateTime.UtcNow, ageWindowHours, dcvAttempted, perPassCap); + + _logger.LogTrace( + "V2 sync DCV gate: Id={Id}, decision={Decision}, orderDate={OrderDate}, " + + "ageWindowHours={Age}, attemptedSoFar={Attempted}, perPassCap={Cap}", + row.OrderNumber, decision, orderDateUtc?.ToString("o") ?? "(none)", + ageWindowHours, dcvAttempted, perPassCap); + + if (decision == DcvSyncDecision.SkipByAge) + { + _logger.LogInformation( + "V2 sync: pending DV order aged out of the DCV-during-sync window and will " + + "not be advanced. CARequestID={Id}, OrderDate={OrderDate}, AgeWindowHours={Age}.", + row.OrderNumber, orderDateUtc?.ToString("o") ?? "(none)", ageWindowHours); + dcvSkippedAge++; + } + else if (decision == DcvSyncDecision.SkipByCap) + { + dcvSkippedCap++; + } + else + { + dcvAttempted++; + + // Resolve family lazily — only for rows actually attempting DCV. + // Report rows carry no family, and productCode is often empty, + // so this costs one extra call per attempted row, not per row in + // the page. + if (resolvedFamily == null) + { + (resolvedFamily, trackedStatus) = await _client.ResolveAndTrackOrderV2WithFamilyAsync( + row.OrderNumber, cancelToken); + } + + string domain = !string.IsNullOrWhiteSpace(trackedStatus?.Domain) + ? trackedStatus.Domain + : row.DomainName; + + if (!string.IsNullOrWhiteSpace(domain)) + { + int timeoutMinutes = _config.GetEffectiveDcvTimeoutMinutes(); + using var dcvCts = CancellationTokenSource.CreateLinkedTokenSource(cancelToken); + dcvCts.CancelAfter(TimeSpan.FromMinutes(timeoutMinutes)); + try + { + bool dcvDone = await PerformDcvV2IfNeededAsync( + row.OrderNumber, domain, resolvedFamily, dcvCts.Token, + trackedStatus?.Verifications?.Domain?.Domains); + if (dcvDone) + { + trackedStatus = await _client.ResolveAndTrackOrderV2Async(row.OrderNumber, cancelToken); + disposition = StatusMapper.V2StatusToRequestDisposition(trackedStatus.Status); + } + } + catch (Exception dcvEx) + { + _logger.LogWarning(dcvEx, + "V2 sync: DCV attempt failed for order {Id}.", row.OrderNumber); + } + } + else + { + _logger.LogWarning( + "V2 sync: no domain available for pending-dcv order {Id} — cannot drive DCV.", + row.OrderNumber); + } + } + } +#endif + + // pending-agreement: the CA holds the certificate until the Subscriber Agreement + // is accepted. Only a live Track Order response shows that status (the report's + // display strings are not mapped to it), so a still-pending SSL/TLS order (report + // rows carry a domain name only for that family) is tracked here when no earlier + // step already did, and accepted at most once per pass. Skipped without any call + // when no signer is configured. Never fails the row. + if (disposition == (int)EndEntityStatus.EXTERNALVALIDATION + && agreementContext.HasSigner + && !string.IsNullOrWhiteSpace(row.DomainName)) + { + try + { + if (trackedStatus == null) + { + (resolvedFamily, trackedStatus) = await _client.ResolveAndTrackOrderV2WithFamilyAsync( + row.OrderNumber, cancelToken); + } + await TryAcceptV2AgreementAsync( + trackedStatus, resolvedFamily, row.OrderNumber, agreementContext, cancelToken); + } + catch (Exception agrEx) when (!(agrEx is OperationCanceledException)) + { + _logger.LogWarning(agrEx, + "V2 sync: could not check pending order '{Id}' for a Subscriber Agreement to accept; " + + "continuing.", row.OrderNumber); + } + } + + // Report rows carry no revocation reason/date (OrderReportEntryV2 has no + // such fields) — only a live TrackOrder response's nested + // `revocation` object does. Resolve lazily, mirroring the DCV branch's + // "only for rows that actually need it" pattern above: this extra call is + // scoped to revoked rows whose disposition came from the report's display + // strings alone. trackedStatus is already populated (with .Revocation, if + // any) when disposition instead came from the unresolved-status fallback. + if (disposition == (int)EndEntityStatus.REVOKED && trackedStatus == null) + { + try + { + (resolvedFamily, trackedStatus) = await _client.ResolveAndTrackOrderV2WithFamilyAsync( + row.OrderNumber, cancelToken); + } + catch (Exception revEx) + { + _logger.LogWarning(revEx, + "V2 sync: failed to fetch revocation detail for revoked order '{Id}' — " + + "emitting without RevocationDate/RevocationReason.", row.OrderNumber); + } + } + + string certPem = null; + if (disposition == (int)EndEntityStatus.GENERATED) + { + try + { + var certResp = await _client.ResolveAndDownloadCertificateV2Async(row.OrderNumber, cancelToken); + certPem = AssembleV2CertChain(certResp); + } + catch (Exception dlEx) + { + if (IsCertificateNotGeneratedYet(dlEx)) + { + // Not a failure: issued at the CA, certificate not generated yet. + // Per-order line at Debug; the count is in the pass summary below. + issuedNotGeneratedYet++; + _logger.LogDebug( + "V2 sync: order '{Id}' is issued at CERTInext but its certificate is not generated " + + "yet (Download Certificate 422 EMS-1165) — emitting metadata-only record. {States}", + row.OrderNumber, DescribeV2States(trackedStatus)); + } + else + { + _logger.LogWarning(dlEx, + "V2 sync: order '{Id}' is issued but certificate download failed — emitting " + + "metadata-only record.", row.OrderNumber); + } + } + } + + // Prefer the report row's own ProductCode (matches V1's "trust the + // listing" precedent, MapToAnyCAPluginCertificate). Only when that's + // empty, fall back to whatever trackedStatus already exists + // in local scope from one of the lazy TrackOrder fetches above + // (unresolved-status fallback, DCV attempt, or revoked-row lookup) — never + // fetch just to backfill this field. + string productId = !string.IsNullOrWhiteSpace(row.ProductCode) + ? row.ProductCode + : (trackedStatus?.ProductVariant ?? string.Empty); + + var record = new AnyCAPluginCertificate + { + CARequestID = row.OrderNumber, + Certificate = certPem, + Status = disposition.Value, + ProductID = productId, + RevocationDate = trackedStatus?.Revocation?.ProcessedAt, + RevocationReason = trackedStatus?.Revocation != null + ? StatusMapper.V2RevocationReasonToCrlCode(trackedStatus.Revocation.Reason) + : 0 + }; + + bool recordHasBody = !string.IsNullOrWhiteSpace(record.Certificate); + + // Never hand the gateway buffer a REVOKED record with no + // certificate body unless the gateway already holds one for this order — + // see DecideBodylessRevokedRecord's doc comment. "Skip" means this row is + // dropped entirely (not added to blockingBuffer) rather than risk creating + // a row the gateway can never un-poison. + if (record.Status == (int)EndEntityStatus.REVOKED && !recordHasBody) + { + var decision = DecideBodylessRevokedRecord(record.CARequestID); + if (decision == BodylessRevokedDecision.Skip) + { + skipped++; + skippedBodylessRevoked++; + continue; + } + if (decision == BodylessRevokedDecision.EmitFailed) + { + record.Status = (int)EndEntityStatus.FAILED; + record.RevocationDate = null; + record.RevocationReason = 0; + emittedFailedFromBodylessRevoked++; + } + // EmitRevoked falls through — record stays REVOKED with no body, + // (propagates an out-of-band CA revoke). + } + + if (record.Status == (int)EndEntityStatus.GENERATED) + { + if (recordHasBody) emittedGeneratedWithBody++; else emittedGeneratedNoBody++; + } + else if (record.Status == (int)EndEntityStatus.REVOKED) + { + emittedRevoked++; + } + else if (record.Status == (int)EndEntityStatus.EXTERNALVALIDATION) + { + emittedPending++; + } + + _logger.LogDebug( + "V2 sync emit: CARequestID={Id}, Status={Status}, CertBytes={CertBytes}, " + + "OrderStatus={OrderStatus}, CertificateStatus={CertificateStatus}", + record.CARequestID, record.Status, record.Certificate?.Length ?? 0, + row.OrderStatus, row.CertificateStatus); + + blockingBuffer.Add(record, cancelToken); + synced++; + } + catch (OperationCanceledException) + { + _logger.LogWarning( + "CERTInext V2 synchronization cancelled by caller. FullSync={FullSync}, Synced={Synced}, " + + "Skipped={Skipped}, Errors={Errors}", + fullSync, synced, skipped, errors); + throw; + } + catch (Exception ex) + { + _logger.LogError(ex, "Error processing V2 order '{Id}' during synchronization.", row.OrderNumber); + errors++; + + // SOC1 completeness/accuracy: abort on an error-rate cliff rather than + // silently 'completing' with mostly-failed records (mirrors the V1 gate). + int totalSeen = synced + skipped + errors; + if (totalSeen >= 50 && errors > totalSeen / 4) + { + _logger.LogError( + "CERTInext V2 synchronization aborted — error rate ({Errors}/{Total}) exceeded " + + "25% threshold. Likely CA-side outage; will retry on next sync cycle.", + errors, totalSeen); + throw new Exception( + $"CERTInext V2 synchronization aborted after {errors}/{totalSeen} records failed " + + "(>25% error rate). See gateway logs for the underlying CA errors."); + } + } + } + + string dcvClause; +#if SUPPORTS_DCV + if (dcvOperational) + dcvClause = $"DCV-during-sync: Attempted={dcvAttempted}, SkippedByAge={dcvSkippedAge} (>{ageWindowHours}h), SkippedByCap={dcvSkippedCap} (cap={perPassCap})."; + else + dcvClause = $"DCV-during-sync: not active (DcvEnabled={_config.DcvEnabled}, DnsProviderInjected={_domainValidatorFactory != null}) — pending orders left as EXTERNALVALIDATION."; +#else + dcvClause = "DCV-during-sync: not supported on this build (IAnyCAPlugin 3.2.0)."; +#endif + _logger.LogInformation( + "CERTInext V2 synchronization complete. Synced={Synced}, Skipped={Skipped}, Errors={Errors}, " + + "UnresolvedStatusFallbacks={Fallbacks}. Emitted to gateway buffer: GeneratedWithBody={GenWithBody}, " + + "GeneratedNoBody={GenNoBody}, Revoked={Revoked}, Pending={Pending}, " + + "FailedFromBodylessRevoked={FailedFromBodylessRevoked}. " + + "BodylessRevokedSkipped={BodylessRevokedSkipped} (bodyless-revoked guard). " + + "RecentOrdersDeferred={RecentOrdersDeferred} (pending/issued, younger than {Grace}s, imported next pass). " + + "IssuedNotGeneratedYet={IssuedNotGeneratedYet} (issued at the CA, certificate not downloadable yet, " + + "422 EMS-1165; picked up by a later pass). {DcvClause}", + synced, skipped, errors, unresolvedStatusFallbacks, + emittedGeneratedWithBody, emittedGeneratedNoBody, emittedRevoked, emittedPending, + emittedFailedFromBodylessRevoked, skippedBodylessRevoked, + deferredRecentOrders, recentOrderGraceSeconds, + issuedNotGeneratedYet, + dcvClause); + } + catch (OperationCanceledException) + { + _logger.LogWarning("CERTInext V2 synchronization was cancelled."); + throw; + } + finally + { + blockingBuffer.CompleteAdding(); + } + + _logger.MethodExit(LogLevel.Debug); + } + + /// + /// Effective grace window (seconds) for holding back recent pending and issued orders in a + /// V1 or V2 sync (full or incremental): 0 disables, a negative value (invalid) falls back to + /// the default. + /// + internal static int GetSyncRecentOrderGraceSeconds(CERTInextConfig config) + { + int configured = config?.SyncRecentOrderGraceSeconds + ?? Constants.Api.DefaultSyncRecentOrderGraceSeconds; + return configured < 0 ? Constants.Api.DefaultSyncRecentOrderGraceSeconds : configured; + } + + /// + /// The issuedAfter passed to the V1 order listing for an incremental pass. The listing + /// keeps only the UTC calendar day of this value (orderDateFrom), so with the hold-back + /// active it is moved back by the hold window (grace plus clock margin) plus a slack for the + /// previous pass's duration. Without that, an order created in the last minutes before UTC + /// midnight and held back by a pass that starts after midnight would fall on a day before the + /// next pass's orderDateFrom and never be re-listed until a full sync. With the + /// hold-back disabled ( 0) the value is unchanged. V2 does not + /// need this: its listing already looks back V2SyncLookbackHours. + /// + internal static DateTime? GetSyncIssuedAfter(DateTime? lastSync, int graceSeconds) + { + if (!lastSync.HasValue || graceSeconds <= 0) + return lastSync; + + return lastSync.Value.AddSeconds( + -(graceSeconds + + Constants.Api.SyncRecentOrderClockMarginSeconds + + Constants.Api.SyncRecentOrderLookbackSlackSeconds)); + } + + /// + /// Issue 0090 gate: true when a V1 or V2 sync row should be withheld because it is pending + /// () or issued + /// () and was created less than + /// plus + /// ago, so an enrollment that is still in flight can save its own row first. + /// + /// Age is measured at the moment the row is processed (), which is + /// close to when the gateway inserts it. orderDate is whole-second UTC, truncated + /// (live-verified), so the margin absorbs the truncation and small CA/gateway clock skew. + /// A future-dated orderDate within the margin counts as age 0; one further ahead + /// than that means an untrustworthy CA clock and fails open (emitted as before), as do a + /// missing or unparseable date, a revoked or failed disposition, and a disabled + /// ( <= 0) window. + /// + internal static bool ShouldDeferRecentOrder( + int disposition, + DateTime? orderDateUtc, + DateTime nowUtc, + int graceSeconds, + out double ageSeconds) + { + ageSeconds = 0; + if (graceSeconds <= 0 + || (disposition != (int)EndEntityStatus.EXTERNALVALIDATION + && disposition != (int)EndEntityStatus.GENERATED) + || !orderDateUtc.HasValue) + return false; + + ageSeconds = (nowUtc - orderDateUtc.Value).TotalSeconds; + if (ageSeconds < -Constants.Api.SyncRecentOrderClockMarginSeconds) + return false; // order dated well in the future: clock disagreement, don't hold it back + + return ageSeconds < graceSeconds + Constants.Api.SyncRecentOrderClockMarginSeconds; + } + + /// + /// Maps a V2 /reports/orders row's human-readable orderStatus/ + /// certificateStatus display strings to an + /// disposition. These are display strings (e.g. "Order Accepted", + /// "Certificate Downloaded") — NOT the V2 status enum used by TrackOrder (see + /// for that). The vocabulary + /// below combines values seen on live orders (orderStatus "Order + /// Accepted"/"Order Fulfilled"; certificateStatus "Pending for Approver"/"Certificate + /// Downloaded") with additional values the spec's field-table prose names ("Approved by + /// System", "Issued", "Certificate Generated"). + /// + /// Returns null for anything not confidently recognised so the caller falls back + /// to a live TrackOrder call rather than guessing — the vocabulary below is NOT + /// guaranteed exhaustive, and silently misclassifying a row (e.g. treating a still-pending + /// order as issued, or dropping a row that is actually revoked) would be worse than the + /// cost of an extra API call. + /// + internal static int? MapV2ReportStatusToDisposition(string orderStatus, string certificateStatus) + { + // certificateStatus is the more specific signal when present — prefer it. + if (TryMapV2ReportDisplayStatus(certificateStatus, out int certDisposition)) + return certDisposition; + + if (TryMapV2ReportDisplayStatus(orderStatus, out int orderDisposition)) + return orderDisposition; + + return null; + } + + private static bool TryMapV2ReportDisplayStatus(string status, out int disposition) + { + disposition = default; + if (string.IsNullOrWhiteSpace(status)) + return false; + + switch (status.Trim().ToLowerInvariant()) + { + // Issued — certificate exists and is downloadable. + case "certificate downloaded": + case "certificate generated": + case "order fulfilled": + case "issued": + disposition = (int)EndEntityStatus.GENERATED; + return true; + + // Pending — somewhere in the approval/DCV/issuance workflow. + case "order accepted": + case "pending for approver": + case "approved by system": + disposition = (int)EndEntityStatus.EXTERNALVALIDATION; + return true; + + // Revoked. + case "revoked": + case "certificate revoked": + disposition = (int)EndEntityStatus.REVOKED; + return true; + + // Expired-but-not-revoked certs remain visible in inventory as GENERATED — + // mirrors StatusMapper.ToRequestDisposition's V1 convention. + case "expired": + disposition = (int)EndEntityStatus.GENERATED; + return true; + + // Terminal failure — never issued, or explicitly cancelled/rejected. + case "rejected": + case "cancelled": + case "certificate rejected": + case "order rejected": + case "order cancelled": + disposition = (int)EndEntityStatus.FAILED; + return true; + + default: + return false; + } + } + + /// + /// Assembles a full PEM chain from a V2 certificate download response. + /// Concatenates the leaf certificatePem and any intermediate PEM strings + /// in chainPem (when present) in leaf-first order, matching the V1 chain format. + /// + private static string AssembleV2CertChain(V2CertificateDownloadResponse certResp) + { + if (certResp?.ChainPem == null || certResp.ChainPem.Count == 0) + return certResp?.CertificatePem; + + var sb = new System.Text.StringBuilder(); + if (string.IsNullOrWhiteSpace(certResp.CertificatePem)) + throw new InvalidOperationException( + $"V2 certificate download for order '{certResp?.OrderId}' returned a null or empty leaf " + + "certificate PEM while a chain PEM is present; cannot assemble a valid chain without the leaf."); + sb.Append(certResp.CertificatePem.TrimEnd()); + foreach (var intermediate in certResp.ChainPem) + { + if (string.IsNullOrWhiteSpace(intermediate)) continue; + sb.AppendLine(); + sb.Append(intermediate.TrimEnd()); + } + return sb.ToString(); + } + + /// + /// Maps a V2 revoke reason that CERTInext rejects with "Invalid Revoke Reason + /// ID" to an accepted fallback, or null if + /// is not one of the known-rejected values. Of the 9 spec-documented reason strings, + /// only key-compromise, affiliation-changed, superseded, + /// cessation-of-operation, and privilege-withdrawn are actually accepted + /// (the same restriction V1's has + /// always documented) — unspecified, ca-compromise, + /// certificate-hold, and aa-compromise are all rejected. + /// key-compromise is the fallback for the two *-compromise reasons (closest + /// semantic match); cessation-of-operation is the fallback for + /// unspecified and certificate-hold, neither of which implies an actual + /// key compromise — key-compromise there would misrepresent the revoke and + /// trigger the spec's own BR 4.9.1.1 24-hour CRL-turnaround obligation for no reason. + /// + private static string ResolveRejectedRevokeReasonFallback(string rejectedV2Reason) => + rejectedV2Reason switch + { + Constants.RevocationReasonV2.Unspecified => Constants.RevocationReasonV2.CessationOfOperation, + Constants.RevocationReasonV2.CertificateHold => Constants.RevocationReasonV2.CessationOfOperation, + Constants.RevocationReasonV2.CACompromise => Constants.RevocationReasonV2.KeyCompromise, + Constants.RevocationReasonV2.AACompromise => Constants.RevocationReasonV2.KeyCompromise, + _ => null + }; + + /// + /// Revokes a certificate via the V2 REST API. If CERTInext rejects the resolved + /// reason with its "Invalid Revoke Reason ID" 422 and the reason is one of the four + /// known-rejected values (), retries + /// exactly once with an accepted fallback. Any other revoke failure (including a 422 for a + /// reason not in that set) is surfaced as-is, with no retry. + /// + private async Task RevokeV2Async(string caRequestID, string hexSerialNumber, uint revocationReason) + { + _logger.MethodEntry(LogLevel.Debug); + + string v2Reason = StatusMapper.ToV2RevocationReason(revocationReason); + + _logger.LogInformation( + "Revocation V2 attempt started. CARequestID={Id}, HexSerialNumber={Serial}, " + + "ReasonCode={ReasonCode}, V2Reason={V2Reason}", + caRequestID, hexSerialNumber, revocationReason, v2Reason); + + // Pre-flight: resolve which product family owns this order (via TrackOrder, + // which probes families and 404s cleanly per-family) and verify it is revocable. + // This resolves the family definitively before revoke is ever called, so a 404 + // from RevokeOrderV2Async below is unambiguous: revoke's own 404 + // means "not found or not revokable" (per spec). Probing multiple families + // on a revoke 404 instead would produce a misleading "not found in any product + // family" for orders that legitimately exist but simply aren't revokable yet. + V2OrderStatusResponse currentStatus; + string resolvedFamily; + try + { + (resolvedFamily, currentStatus) = await _client.ResolveAndTrackOrderV2WithFamilyAsync(caRequestID); + } + catch (Exception ex) + { + _logger.LogError(ex, + "V2 revocation pre-flight failed. CARequestID={Id}", + caRequestID); + throw; + } + + int disposition = StatusMapper.V2StatusToRequestDisposition(currentStatus.Status); + if (disposition == (int)EndEntityStatus.REVOKED) + { + _logger.LogWarning( + "V2 revocation skipped — already revoked. CARequestID={Id}", + caRequestID); + _logger.MethodExit(LogLevel.Debug); + return (int)EndEntityStatus.REVOKED; + } + + if (disposition != (int)EndEntityStatus.GENERATED) + { + // Compliance finding: a revoke denial must leave an audit record (SOX/SOC2 + // who/what/when/outcome) — mirrors the V1 "Revocation rejected" LogError above. + _logger.LogError( + "V2 revocation rejected — certificate is not in a revocable state. " + + "CARequestID={Id}, Family={Family}, CurrentStatus={Status}", + caRequestID, resolvedFamily, currentStatus.Status); + throw new Exception( + $"V2 certificate '{caRequestID}' cannot be revoked: current status is '{currentStatus.Status}'. " + + "Only issued certificates may be revoked."); + } + + var revokeReq = new V2RevokeRequest + { + Reason = v2Reason, + Note = $"Revoked via Keyfactor Command. CRL reason code: {revocationReason} ({v2Reason})." + }; + + string retriedFromReason = null; + try + { + await _client.RevokeOrderV2Async(resolvedFamily, caRequestID, revokeReq); + } + catch (KeyNotFoundException knf) + { + // Compliance finding: audit the denial (CARequestID, family, HTTP status, EMS + // code) before converting/rethrowing — the client already logged the raw + // HTTP/body; this adds the plugin-level who/what/outcome context. + _logger.LogWarning( + "V2 revocation denied — order not found or not in a revokable state. " + + "CARequestID={Id}, Family={Family}, HttpStatus={HttpStatus}, EmsCode={EmsCode}", + caRequestID, resolvedFamily, 404, ExtractEmsCode(knf.Message) ?? "(none)"); + // The order was already confirmed to live in `resolvedFamily` via TrackOrder + // above, so a 404 here is the spec's other documented meaning — "not in a + // revokable state" — not a genuine family miss. Surface that plainly + // instead of retrying other families. + throw new InvalidOperationException( + $"V2 order '{caRequestID}' (family '{resolvedFamily}') could not be revoked: " + + $"CERTInext reports it as not found or not in a revokable state. {knf.Message}"); + } + catch (InvalidOperationException ioe) when ( + ResolveRejectedRevokeReasonFallback(v2Reason) != null && + ioe.Message.IndexOf("Invalid Revoke Reason ID", StringComparison.OrdinalIgnoreCase) >= 0) + { + // CERTInext's V2 API rejects several of the spec-documented reason values + // outright (422 "Invalid Revoke Reason ID"), independent of + // this plugin. Only 5 of the 9 spec-documented reason strings + // are actually accepted: key-compromise, affiliation-changed, superseded, + // cessation-of-operation, privilege-withdrawn — the same restriction V1's + // ToRevocationReasonId has always been documented against. Retry exactly once + // with the accepted fallback ResolveRejectedRevokeReasonFallback resolved for + // this reason, rather than failing outright on what may be Command's default + // revoke call. + string originalReason = v2Reason; + string fallbackReason = ResolveRejectedRevokeReasonFallback(v2Reason); + _logger.LogWarning( + "V2 revoke rejected reason '{OriginalReason}' as invalid (CARequestID={Id}, Family={Family}, " + + "HttpStatus={HttpStatus}, EmsCode={EmsCode}); retrying once with '{FallbackReason}'.", + originalReason, caRequestID, resolvedFamily, 422, ExtractEmsCode(ioe.Message) ?? "(none)", + fallbackReason); + v2Reason = fallbackReason; + revokeReq = new V2RevokeRequest + { + // CERTInext's "note" field silently rejects a semicolon with the same + // "Invalid Revoke Remarks" 422 — comma/period/slash/parens are all fine; + // only ';' triggers it. Avoid semicolons in this string. + Reason = v2Reason, + Note = $"Revoked via Command, reason {originalReason} rejected, retried as {fallbackReason}." + }; + retriedFromReason = originalReason; + try + { + await _client.RevokeOrderV2Async(resolvedFamily, caRequestID, revokeReq); + } + catch (Exception retryEx) + { + // Compliance finding: the retry attempt is itself a revoke call against the + // CA and must leave an audit record on failure, not just succeed silently or + // vanish into the caller's exception. + _logger.LogError(retryEx, + "V2 revocation retry ({FallbackReason}) failed. CARequestID={Id}, Family={Family}", + fallbackReason, caRequestID, resolvedFamily); + throw; + } + } + catch (InvalidOperationException ioe) + { + // Any 422 not matched by the retry-eligible case above (e.g. a distinct EMS + // code/detail, or a reason not in the known-rejected set) — audit the denial + // and rethrow unchanged. Never more than the one retry above. + _logger.LogWarning( + "V2 revocation denied. CARequestID={Id}, Family={Family}, HttpStatus={HttpStatus}, " + + "EmsCode={EmsCode}, Detail={Detail}", + caRequestID, resolvedFamily, 422, ExtractEmsCode(ioe.Message) ?? "(none)", ioe.Message); + throw; + } + + _logger.LogInformation( + "V2 revocation complete. CARequestID={Id}, HexSerialNumber={Serial}, V2Reason={V2Reason}, " + + "Family={Family}, RetriedFromReason={RetriedFromReason}", + caRequestID, hexSerialNumber, v2Reason, resolvedFamily, retriedFromReason ?? "(none)"); + _logger.MethodExit(LogLevel.Debug); + return (int)EndEntityStatus.REVOKED; + } + + // --------------------------------------------------------------------------- + // V2 private utility + // --------------------------------------------------------------------------- + + /// + /// Pulls the first EMS-NNN code out of an exception message, for audit log + /// lines that want the CA's own error code as a discrete field rather than only the + /// free-text detail. Returns null when no code is present (e.g. a CERTInext + /// detail with no EMS code, such as "Certificate Request still being processed"). + /// + private static string ExtractEmsCode(string message) + { + if (string.IsNullOrEmpty(message)) return null; + var m = System.Text.RegularExpressions.Regex.Match(message, @"\bEMS-\d+\b"); + return m.Success ? m.Value : null; + } + + private static string ExtractCnFromSubject(string subject) + { + if (string.IsNullOrWhiteSpace(subject)) return null; + // subject format: "CN=example.com, O=Org, ..." + foreach (var part in subject.Split(',')) + { + var trimmed = part.Trim(); + if (trimmed.StartsWith("CN=", StringComparison.OrdinalIgnoreCase)) + return trimmed.Substring(3).Trim(); + } + return null; + } + + // --------------------------------------------------------------------------- + // V1 private helpers + // --------------------------------------------------------------------------- + + /// + /// Handles New and Reissue enrollment flows by submitting a fresh certificate + /// request to CERTInext. + /// + private async Task EnrollNewAsync( + string csr, + string subject, + Dictionary san, + EnrollmentParams ep) + { + _logger.MethodEntry(LogLevel.Debug); + var enrollReq = new EnrollCertificateRequest + { + ProfileId = ep.ProfileId, + Csr = csr, + ValidityYears = ep.ValidityYears > 0 ? ep.ValidityYears : (int?)null, + ValidityDays = ep.ValidityDays > 0 ? ep.ValidityDays : (int?)null, + Subject = subject, + Sans = BuildSanList(san, csr, subject), + RequesterName = string.IsNullOrWhiteSpace(ep.RequesterName) ? null : ep.RequesterName, + RequesterEmail = string.IsNullOrWhiteSpace(ep.RequesterEmail) ? null : ep.RequesterEmail, + KeyType = string.IsNullOrWhiteSpace(ep.KeyType) ? null : ep.KeyType, + SignerName = string.IsNullOrWhiteSpace(ep.SignerName) ? null : ep.SignerName, + SignerPlace = string.IsNullOrWhiteSpace(ep.SignerPlace) ? null : ep.SignerPlace, + SignerIp = string.IsNullOrWhiteSpace(ep.SignerIp) ? null : ep.SignerIp, + Comment = "Issued via Keyfactor Command AnyCA REST Gateway." + }; + + var enrollResp = await _client.EnrollCertificateAsync(enrollReq); + + // Whether the DCV block below took ownership of the in-call issuance wait for this + // order. Declared outside the #if so both build flavors compile the pickup gate the + // same way (it simply stays false on the no-DCV build). When true, the synchronous + // pickup poll is skipped: on the DCV build the DCV path already owns the issuance + // decision — it either ran WaitForIssuanceAfterDcvAsync itself, deferred to another + // in-flight caller, or determined the order is terminal / not yet validated — so a + // second stacked poll would either double the wait or burn the budget polling an + // order that can never issue in-call (a cancelled/rejected order + // must not be re-polled here after DCV already short-circuited it). + bool dcvIssuanceWaitRan = false; + +#if SUPPORTS_DCV + // DCV: run domain validation if enabled, the factory was injected, and the + // order was accepted (not immediately failed). + string orderNumber = enrollResp.Id; + if (_domainValidatorFactory != null && _config.DcvEnabled && !string.IsNullOrEmpty(orderNumber)) + { + // DCV owns the in-call issuance wait for this order from here on: every exit from + // this block (duplicate in-flight, DCV-validated + issuance poll, terminal order, + // or challenge-not-yet-exposed) is a decision the pickup poll must not second-guess. + // Set before any await so it holds on every path out of the block. + // + // This is intentionally coarse — keyed on "the DCV subsystem engaged for this order", + // not on "a DCV wait is actively running". The one case it over-defers is an order + // whose pending domains are all assigned to a non-DNS-01 method (HTTP/email): DCV does + // no work, yet pickup is skipped. That is an accepted trade: this plugin only drives + // DNS-01, so such orders depend on out-of-band validation and would not issue within + // the ~55s pickup window anyway — the next sync completes them. Distinguishing that + // sub-case from the terminal/cancelled case (which MUST skip pickup) would require a + // richer PerformDcvIfNeededAsync result and risk polling a terminal order. + dcvIssuanceWaitRan = true; + + // SOX CC7.3: bound the entire DCV flow with a hard timeout so a stuck + // DNS provider or extreme propagation delay cannot hold a gateway worker + // thread indefinitely. Configurable via DcvTimeoutMinutes (config or + // CERTINEXT_DCV_TIMEOUT_MINUTES env var); defaults to 10 minutes. + // Log the resolved limit so an auditor can confirm the configured ceiling. + int dcvTimeoutMinutes = _config.GetEffectiveDcvTimeoutMinutes(); + _logger.LogInformation( + "Starting DCV for order {OrderNumber}. DcvTimeoutMinutes={Timeout}", + orderNumber, dcvTimeoutMinutes); + using var dcvCts = new CancellationTokenSource(TimeSpan.FromMinutes(dcvTimeoutMinutes)); + + // Reserve the in-flight slot before running DCV so that any concurrent + // Synchronize / GetSingleRecord cycle won't try to stage TXT records for the + // same order from the sync-driven retry path. If something else already has + // the slot (the only realistic case: a duplicate Enroll for the same order + // ID), skip our own attempt and fall through to the pending result — the + // other caller will produce the same outcome and we shouldn't double-stage. + bool reserved = _dcvInFlight.TryAdd(orderNumber, 0); + if (!reserved) + { + _logger.LogInformation( + "DCV is already in flight for order {OrderNumber}; Enroll will skip its own DCV attempt " + + "and return the pending enroll response. The other caller will drive issuance.", + orderNumber); + } + else + { + try + { + var dcvOutcome = await PerformDcvIfNeededAsync(orderNumber, dcvCts.Token); + // Only wait for issuance when every pending domain was validated. If any + // domain was skipped (e.g. an IP/email SAN with no DNS provider) the order + // cannot issue, so waiting would just hold the worker for + // DcvWaitForIssuanceSeconds; return pending and let the sync DCV retry path + // pick the order up. + if (dcvOutcome == DcvOutcome.Completed) + { + // Poll GetCertificate until CERTInext finishes generating the cert OR the + // issuance budget expires. CERTInext issuance is async — DCV may verify + // but the cert PEM isn't immediately available. Without this poll, Enroll + // returns a pending result and the cert is picked up on the next sync cycle, + // which is undesirable when the whole thing completes in under a minute. + var postDcv = await WaitForIssuanceAfterDcvAsync(orderNumber, dcvCts.Token); + if (postDcv != null) + { + return BuildEnrollmentResult(new EnrollCertificateResponse + { + Id = postDcv.Id, + Status = postDcv.Status, + Certificate = postDcv.Certificate, + SerialNumber = postDcv.SerialNumber, + Message = $"Post-DCV status: {postDcv.Status}." + }, ep.AutoApprove); + } + } + } + catch (Exception dcvEx) + { + // The order is already placed (and paid for) at CERTInext. A failure of the + // in-call DCV / issuance wait — a TrackOrder or VerifyDcv error, or the + // DcvTimeoutMinutes token firing (Enroll has no caller token, so that + // cancellation is always the internal timeout, never the caller) — must not + // fail the enrollment: Command would never learn the order number and an + // operator retry would place a duplicate paid order. Return the pending + // result instead; the sync-DCV retry path completes the order. + _logger.LogWarning(dcvEx, + "In-call DCV/issuance wait failed after order {OrderNumber} was placed. Returning the " + + "pending result carrying the order number; the next synchronization will retry DCV " + + "and pick up the certificate.", + orderNumber); + } + finally + { + _dcvInFlight.TryRemove(orderNumber, out _); + } + } + } +#endif + + // Synchronous certificate pickup (Sectigo-parity): poll for the issued certificate so + // a fast-issuing order returns GENERATED + PEM in this same call. No-op for the + // already-issued/failed case and for OV/EV orders that CERTInext issues asynchronously + // — those fall back to the pending result and are imported by the next sync. + var newResult = BuildEnrollmentResult(enrollResp, ep.AutoApprove); + newResult = await PickUpEnrolledCertificateAsync(newResult, enrollResp.Id, dcvIssuanceWaitRan); + + _logger.MethodExit(LogLevel.Debug); + return newResult; + } + + /// + /// Handles Renew and RenewOrReissue enrollment flows. + /// Determines whether to renew (API call on existing ID) or fall back to new + /// issuance depending on the certificate's current state. + /// + private async Task RenewOrReissueAsync( + string csr, + string subject, + Dictionary san, + EnrollmentProductInfo productInfo, + EnrollmentParams ep) + { + // Retrieve the prior certificate serial number from the product parameters. + // Command injects "PriorCertSN" for renewal flows. + string priorCertSn = null; + productInfo.ProductParameters?.TryGetValue("PriorCertSN", out priorCertSn); + + // SOC2 CC6.1: a renewal/reissue read against the gateway's certificate + // inventory is a logical-access event and must be logged at Information. + _logger.LogInformation( + "Renewal/reissue probe — read PriorCertSN from EnrollmentProductInfo. " + + "Subject={Subject}, PriorCertSN={PriorCertSN}, RenewalWindowDays={WindowDays}", + LogSanitizer.Strip(subject), string.IsNullOrWhiteSpace(priorCertSn) ? "(none)" : priorCertSn, + ep.RenewalWindowDays); + + if (string.IsNullOrWhiteSpace(priorCertSn)) + { + // SOC2 CC7.2: log policy-relevant decisions at Information so they survive + // production log filters and are available for anomaly detection. + _logger.LogInformation( + "Renewal/reissue has no PriorCertSN — treating as new enrollment. Subject={Subject}", + LogSanitizer.Strip(subject)); + return await EnrollNewAsync(csr, subject, san, ep); + } + + // Resolve the CARequestID for the prior certificate + string priorCaRequestId; + try + { + priorCaRequestId = await _certificateDataReader.GetRequestIDBySerialNumber(priorCertSn); + } + catch (Exception ex) + { + _logger.LogWarning(ex, + "Could not resolve CARequestID for serial '{SN}'. Falling back to new enrollment.", priorCertSn); + return await EnrollNewAsync(csr, subject, san, ep); + } + + if (string.IsNullOrWhiteSpace(priorCaRequestId)) + { + _logger.LogInformation( + "CARequestID for serial '{SN}' is empty — falling back to new enrollment. Subject={Subject}", + priorCertSn, LogSanitizer.Strip(subject)); + return await EnrollNewAsync(csr, subject, san, ep); + } + + // Determine whether this is within the renewal window. + // + // Semantics (Option A — "window before expiry"): + // useRenewalApi = true when the cert expires within the next RenewalWindowDays. + // useRenewalApi = false when the cert expires further away than that (too early → reissue). + // useRenewalApi = false when the cert is already expired (graceful degradation → new order). + // + // This matches operator expectation: "renew when within N days of expiry". + // Certs expiring far in the future should be reissued, not renewed via the CA's + // renew endpoint (which may assume near-expiry context on its side). + bool useRenewalApi = false; + try + { + DateTime? expiry = _certificateDataReader.GetExpirationDateByRequestId(priorCaRequestId); + if (expiry.HasValue) + { + DateTime now = DateTime.UtcNow; + DateTime renewalWindowEnd = now.AddDays(ep.RenewalWindowDays); + // Renew only if the cert is not yet expired AND expires within the window. + useRenewalApi = expiry.Value > now && expiry.Value <= renewalWindowEnd; + + // SOX CC6.2 / SOC2 CC7.2: the renewal window evaluation is a security-relevant + // policy decision (determines whether an existing CA record is reused). Logged + // at Information so it survives production log filters and is not suppressible + // by log-level configuration. + _logger.LogInformation( + "Renewal window evaluation complete. " + + "PriorCARequestID={PriorId}, CertExpiry={Expiry:O}, " + + "RenewalWindowEnd={WindowEnd:O}, RenewalWindowDays={Window}, UseRenewalApi={Use}", + priorCaRequestId, expiry.Value, renewalWindowEnd, ep.RenewalWindowDays, useRenewalApi); + } + } + catch (Exception ex) + { + _logger.LogWarning(ex, + "Could not determine expiry for '{Id}'. Defaulting to new enrollment.", priorCaRequestId); + } + + if (useRenewalApi) + { + // SOX / SOC2 CC7.3: log the renewal attempt at Information so the intent is + // captured before the API call, enabling reconstruction if the call fails. + _logger.LogInformation( + "Renewal via CERTInext renew API started. " + + "PriorCARequestID={PriorId}, Subject={Subject}, ProfileId={ProfileId}", + priorCaRequestId, LogSanitizer.Strip(subject), ep.ProfileId); + + var renewReq = new RenewCertificateRequest + { + Csr = csr, + // Renewals go out as a fresh CERTInext order, so they need the same domain + // set as a new enrollment — otherwise a renewed UCC certificate comes back + // holding only its primary domain. + Subject = subject, + Sans = BuildSanList(san, csr, subject), + ProfileId = ep.ProductCode, + ValidityYears = ep.ValidityYears > 0 ? ep.ValidityYears : (int?)null, + ValidityDays = ep.ValidityDays > 0 ? ep.ValidityDays : (int?)null, + RequesterName = string.IsNullOrWhiteSpace(ep.RequesterName) ? null : ep.RequesterName, + RequesterEmail = string.IsNullOrWhiteSpace(ep.RequesterEmail) ? null : ep.RequesterEmail, + SignerName = string.IsNullOrWhiteSpace(ep.SignerName) ? null : ep.SignerName, + SignerPlace = string.IsNullOrWhiteSpace(ep.SignerPlace) ? null : ep.SignerPlace, + SignerIp = string.IsNullOrWhiteSpace(ep.SignerIp) ? null : ep.SignerIp, + Comment = $"Renewed via Keyfactor Command. Prior ID: {priorCaRequestId}." + }; + + var renewResp = await _client.RenewCertificateAsync(priorCaRequestId, renewReq); + var renewResult = BuildEnrollmentResult(renewResp, ep.AutoApprove); + + // SOX: log the renewal outcome so the new certificate ID and status are + // independently recorded (the outer Enroll method also logs, but this + // ensures the renew path is auditable if the result is further transformed). + _logger.LogInformation( + "Renewal via CERTInext renew API complete. " + + "PriorCARequestID={PriorId}, NewCARequestID={NewId}, Status={Status}", + priorCaRequestId, renewResult.CARequestID, renewResult.Status); + + // Synchronous certificate pickup (Sectigo-parity), same as the new-enrollment path. + // The renew path never runs an in-call DCV, so on a DCV-enabled deployment a renewal + // that is still waiting on DNS-01 validation cannot issue inside the pickup window: + // polling it only holds a gateway worker for a guaranteed miss. Skip pickup for that + // case and return the pending result; the sync-driven DCV retry completes the order. + // Every other renewal (validation reused, no DCV pending, DCV disabled) keeps pickup. + bool awaitsDnsDcv = false; +#if SUPPORTS_DCV + if (renewResult.Status == (int)EndEntityStatus.EXTERNALVALIDATION) + awaitsDnsDcv = await RenewalAwaitsDnsDcvAsync(renewResp.Id); +#endif + if (!awaitsDnsDcv) + renewResult = await PickUpEnrolledCertificateAsync(renewResult, renewResp.Id, dcvIssuanceWaitRan: false); + + return renewResult; + } + else + { + _logger.LogInformation( + "Certificate '{Id}' is outside the renewal window ({Window} days) — issuing new certificate. Subject={Subject}", + priorCaRequestId, ep.RenewalWindowDays, LogSanitizer.Strip(subject)); + return await EnrollNewAsync(csr, subject, san, ep); + } + } + + // --------------------------------------------------------------------------- + // DCV helpers + // --------------------------------------------------------------------------- + +#if SUPPORTS_DCV + /// + /// True when a domain entry is pending validation (dcvStatus="0") and is either not yet + /// assigned a method or assigned to DNS TXT — the only domains this plugin's DCV can complete. + /// Domains assigned to HTTP or e-mail validation are excluded. + /// + private static bool IsPendingDnsDcvEntry(DomainVerificationDetail detail) + { + if (!string.Equals(detail?.DcvStatus, Constants.Dcv.StatusPending, StringComparison.Ordinal)) + return false; + string method = detail?.DcvMethod ?? string.Empty; + return string.IsNullOrEmpty(method) + || string.Equals(method, Constants.Dcv.MethodDnsTxt, StringComparison.Ordinal) + || string.Equals(method, Constants.Dcv.MethodDnsTxtLabel, StringComparison.OrdinalIgnoreCase); + } + + /// + /// Whether a just-placed renewal order is waiting on DNS-01 validation that this call will + /// never perform (the renew path does not run in-call DCV), so the synchronous pickup poll + /// cannot succeed. True only when DCV is enabled with a validator factory and a non-terminal + /// order has at least one pending DNS-01 domain. One TrackOrder call; any failure (including + /// cancellation — Enroll has no caller token) logs a Warning and returns false so the caller + /// falls back to the existing pickup behavior. Never throws: the order already exists at + /// CERTInext, so this check must not fail the renewal. + /// + private async Task RenewalAwaitsDnsDcvAsync(string orderNumber) + { + if (_domainValidatorFactory == null || !_config.DcvEnabled || string.IsNullOrWhiteSpace(orderNumber)) + return false; + + try + { + var track = await _client.TrackOrderAsync(orderNumber); + var details = track?.OrderDetails; + if (details == null) + return false; + + // Terminal orders (issued/revoked, cancelled/rejected) can keep a stale pending + // domain entry; pickup resolves those immediately, so never skip it for them. + if (int.TryParse(details.CertificateStatusId, out int certStatusId)) + { + int disposition = StatusMapper.CertificateStatusIdToRequestDisposition(certStatusId); + if (disposition == (int)EndEntityStatus.GENERATED || disposition == (int)EndEntityStatus.REVOKED) + return false; + } + if (details.OrderStatusId is "4" or "5") + return false; + + int pending = details.DomainVerification?.GetDomainEntries() + .Count(kvp => IsPendingDnsDcvEntry(kvp.Value)) ?? 0; + if (pending == 0) + return false; + + _logger.LogInformation( + "Renewal order {OrderNumber} has {Count} domain(s) pending DNS-01 validation, which the renew " + + "path does not perform in-call; synchronous pickup skipped. Returning the pending result; " + + "the next synchronization completes DCV and imports the certificate.", + orderNumber, pending); + return true; + } + catch (Exception ex) + { + _logger.LogWarning(ex, + "Could not check DCV state for renewal order {OrderNumber}; falling back to the normal " + + "synchronous pickup.", orderNumber); + return false; + } + } +#endif + + /// + /// True when a GetDcv failure is the CERTInext-side "DCV slot is exposed in + /// TrackOrder but the endpoint won't accept calls yet" condition. Surfaces as the + /// API error EMS-956 "Invalid Request for this API" for several hours after + /// enrollment. + /// + /// Detection is intentionally narrow: + /// * If the message contains the literal code EMS-956, treat it as the + /// known not-ready condition. + /// * Otherwise, only fall back to the human-readable phrase match when *no other* + /// EMS-NNN code is present. Without that guard, an upstream proxy or WAF + /// returning a 4xx whose body happens to contain "Invalid Request for this API …" + /// plus a different CERTInext code (e.g. EMS-401) would be silently deferred, + /// masking a real authentication or input-validation failure. + /// + private static bool IsDcvNotYetReady(Exception ex) + { + if (ex == null) return false; + string msg = ex.Message ?? string.Empty; + if (msg.IndexOf("EMS-956", StringComparison.OrdinalIgnoreCase) >= 0) + return true; + bool hasPhrase = msg.IndexOf("Invalid Request for this API", StringComparison.OrdinalIgnoreCase) >= 0; + bool hasOtherEmsCode = System.Text.RegularExpressions.Regex.IsMatch(msg, @"\bEMS-\d+\b"); + return hasPhrase && !hasOtherEmsCode; + } + + /// + /// Strips a leading wildcard label ("*.") so a domain can be used to pick a DNS + /// zone / and to build the + /// DCV TXT record hostname. A literal "*" is not a queryable DNS label, so staging + /// a record at e.g. _emsign-validation.*.example.com for a wildcard domain can never + /// be seen by the CA (a wildcard order with a literal-asterisk TXT host staged stays + /// pending indefinitely). Callers must keep using the + /// ORIGINAL domain string (including "*.") for every CERTInext API call + /// (GetDcv/VerifyDcv/TrackOrder) — that is what the CA itself tracks and reports back + /// per-domain; only the DNS-side hostname/zone-resolution inputs use the base domain. + /// + /// NOTE (unverified): whether CERTInext's own DCV actually accepts a base-domain TXT + /// record as proof for a wildcard domain entry has not been confirmed against the live + /// API — verify before relying on it for a wildcard enrollment. + /// + private static string StripWildcardPrefix(string domain) + { + if (string.IsNullOrEmpty(domain)) + return domain; + return domain.StartsWith("*.", StringComparison.Ordinal) + ? domain.Substring(2) + : domain; + } + + /// + /// Best-effort DCV retry for an order that may still be pending validation. + /// + /// Called from Synchronize and GetSingleRecord so that orders which CERTInext placed + /// into "Pending for Approver"/"Pending System RA" between enrollment and the next + /// gateway cycle (when domainVerification was still null at enroll time) can be + /// driven forward through DCV. Wraps with: + /// * a per-order in-flight guard so overlapping sync cycles or a sync+single + /// refresh do not double-stage TXT records, + /// * a bounded DCV timeout linked to the caller's cancellation token, + /// * swallowing of non-cancellation exceptions so a single bad order does not + /// halt a 12-hour sync — the order will be retried on the next cycle. + /// + /// Uses a single-shot challenge check (waitForChallengeSeconds=0) by default + /// because sync runs periodically: if CERTInext hasn't yet exposed the DCV slot for + /// this order, the next sync cycle will pick it up. Waiting per-order during sync + /// scales poorly — a single pending order's 60s budget becomes minutes of wasted + /// gateway thread time across an account with many orders. See PR #2 discussion. + /// + /// Returns true when DCV actually executed (or DCV is already complete), + /// false when skipped. + /// + private async Task TryRunDcvDuringSyncAsync(string orderNumber, CancellationToken ct, bool fastSync = false) + { + _logger.MethodEntry(LogLevel.Debug); +#if SUPPORTS_DCV + if (_domainValidatorFactory == null || !_config.DcvEnabled || string.IsNullOrEmpty(orderNumber)) + return false; + + if (!_dcvInFlight.TryAdd(orderNumber, 0)) + { + // SOC2 CC7.2: concurrent DCV-attempt collisions are security-relevant + // (they indicate either a normal overlap of two sync cycles OR an attempt + // to interleave operations on the same order). Log at Information so the + // event appears in production logs without verbose-debug being enabled. + _logger.LogInformation( + "DCV already in flight for order {OrderNumber}; skipping concurrent attempt.", + orderNumber); + return false; + } + + try + { + int timeoutMinutes = _config.GetEffectiveDcvTimeoutMinutes(); + using var dcvCts = CancellationTokenSource.CreateLinkedTokenSource(ct); + dcvCts.CancelAfter(TimeSpan.FromMinutes(timeoutMinutes)); + + _logger.LogInformation( + "Attempting deferred DCV during sync/refresh (single-shot challenge check). " + + "OrderNumber={OrderNumber}, DcvTimeoutMinutes={Timeout}", + orderNumber, timeoutMinutes); + + // Any outcome other than NotRun means DCV executed, so sync/refresh callers re-fetch + // the order (a partial run may still have advanced per-domain state). + var outcome = await PerformDcvIfNeededAsync(orderNumber, dcvCts.Token, + waitForChallengeSecondsOverride: 0, + propagationDelaySecondsOverride: fastSync ? Constants.Dcv.SyncPropagationDelaySeconds : (int?)null); + return outcome != DcvOutcome.NotRun; + } + catch (OperationCanceledException) when (ct.IsCancellationRequested) + { + throw; + } + catch (Exception ex) + { + _logger.LogWarning(ex, + "Deferred DCV attempt failed for order {OrderNumber}. Order will be retried on the next sync cycle.", + orderNumber); + return false; + } + finally + { + _dcvInFlight.TryRemove(orderNumber, out _); + } +#else + // DCV is not supported on this build (IAnyCAPlugin 3.2.0). No-op: pending orders + // are reported as EXTERNALVALIDATION and not advanced during sync. + await Task.CompletedTask; + return false; +#endif + } + + /// + /// Runs DNS DCV for any domains on that are still pending + /// validation. Returns when every pending domain was + /// staged and verified, when some were + /// verified but others were skipped (the order cannot issue yet), and + /// when skipped (order already issued, no pending domains, + /// or factory not available). + /// + /// Rule: if the order is already issued we never attempt DCV — it would be a no-op + /// at best and could confuse the CA at worst. + /// + /// lets the sync path force a + /// single-shot challenge check (pass 0) so a sync cycle doesn't spend up to + /// DcvWaitForChallengeSeconds per pending order waiting for CERTInext to + /// expose the DCV slot — sync runs periodically, so unexposed orders are picked up + /// on the next cycle instead. Enroll passes null to keep the full configured + /// budget (user-visible latency benefits from a one-shot end-to-end finish). + /// +#if SUPPORTS_DCV + /// Result of . + private enum DcvOutcome + { + /// No DCV work was done (nothing pending, deferred, or no domain could be staged). + NotRun, + /// All pending domains were staged and verified. + Completed, + /// Staged domains were verified and cleaned up, but at least one domain was skipped. + CompletedWithSkippedDomains + } + + private async Task PerformDcvIfNeededAsync( + string orderNumber, + CancellationToken ct, + int? waitForChallengeSecondsOverride = null, + int? propagationDelaySecondsOverride = null) + { + // Poll TrackOrder until CERTInext exposes the DCV challenge (domainVerification + // populated) OR the cert reaches a terminal state OR the wait budget expires. + // Under concurrent enrollment load CERTInext sometimes takes a few seconds to + // materialize the slot after GenerateOrderSSL returns — without this wait a + // race-condition order skips DCV entirely and waits for the next sync cycle. + int waitBudgetSeconds = waitForChallengeSecondsOverride + ?? _config.GetEffectiveDcvWaitForChallengeSeconds(); + // Challenge-wait poll interval is clamped to [1s, 5s] so it's responsive even + // when an admin has set DcvPropagationDelaySeconds high for slow zones (that + // setting governs how long we wait *after* publishing a TXT record, which is a + // different, slower concern than how often we re-check TrackOrder here). + int challengePollSeconds = Math.Max(1, Math.Min(5, _config.DcvPropagationDelaySeconds > 0 ? _config.DcvPropagationDelaySeconds : 5)); + var waitDeadline = DateTime.UtcNow.AddSeconds(Math.Max(0, waitBudgetSeconds)); + + TrackOrderResponse track = null; + API.TrackOrderDomainVerification domainVerification = null; + int pollAttempts = 0; + + while (true) + { + pollAttempts++; + ct.ThrowIfCancellationRequested(); + track = await _client.TrackOrderAsync(orderNumber, ct); + + // Skip DCV entirely if the certificate is already issued or revoked + if (track.OrderDetails != null + && int.TryParse(track.OrderDetails.CertificateStatusId, out int certStatusId)) + { + int disposition = StatusMapper.CertificateStatusIdToRequestDisposition(certStatusId); + if (disposition == (int)EndEntityStatus.GENERATED || disposition == (int)EndEntityStatus.REVOKED) + { + _logger.LogDebug( + "DCV skipped — order {OrderNumber} is already in terminal state (certificateStatusId={Status}).", + orderNumber, certStatusId); + return DcvOutcome.NotRun; + } + } + + // Skip if the order itself reached a terminal failure state. Without this + // the cached-DCV path below could still return true on a cancelled order + // (domainVerification.Status = "1" survives the cancellation), sending the + // caller into a wasted DcvWaitForIssuanceSeconds-long GetCertificate poll + // that can never resolve. OrderStatusId 4 = cancelled, 5 = rejected. + if (track.OrderDetails?.OrderStatusId is "4" or "5") + { + _logger.LogDebug( + "DCV skipped — order {OrderNumber} is cancelled/rejected " + + "(orderStatusId={OrderStatus}).", + orderNumber, track.OrderDetails.OrderStatusId); + return DcvOutcome.NotRun; + } + + domainVerification = track.OrderDetails?.DomainVerification; + if (domainVerification != null) + break; + + // domainVerification still null — sleep and retry if we have budget left. + if (waitBudgetSeconds <= 0 || DateTime.UtcNow >= waitDeadline) + { + _logger.LogInformation( + "DCV challenge not exposed by CERTInext within {Budget}s for order {OrderNumber} " + + "(attempted {Attempts} TrackOrder polls). Deferring to next sync cycle.", + waitBudgetSeconds, orderNumber, pollAttempts); + return DcvOutcome.NotRun; + } + + try + { + await Task.Delay(TimeSpan.FromSeconds(challengePollSeconds), ct); + } + catch (OperationCanceledException) + { + // Rethrow if the gateway-level token is cancelled so shutdown is not blocked; + // only swallow an internal timeout (e.g. a per-poll deadline CTS). + ct.ThrowIfCancellationRequested(); + return DcvOutcome.NotRun; + } + } + + // If DCV is already validated CERTInext-side, the plugin has no DCV work to + // do — but CERTInext's certificate generation may still be in flight (this + // happens when CERTInext has cached a prior DCV validation for the parent + // domain). Return true so the caller can run the issuance poll and pick up + // the cert directly from Enroll() instead of leaving it for the next sync. + // + // Treat "DCV done" as EITHER the overall aggregate Status flipping to "1" + // OR every individual per-domain dcvStatus being "1": the per-domain field can + // flip before the parent aggregate. + var allDomainEntries = domainVerification.GetDomainEntries(); + bool aggregateValidated = string.Equals( + domainVerification.Status, Constants.Dcv.StatusValidated, StringComparison.Ordinal); + bool everyDomainValidated = allDomainEntries.Count > 0 + && allDomainEntries.All(kvp => string.Equals( + kvp.Value?.DcvStatus, Constants.Dcv.StatusValidated, StringComparison.Ordinal)); + if (aggregateValidated || everyDomainValidated) + { + _logger.LogInformation( + "DCV is already validated for order {OrderNumber} " + + "(aggregateStatus={Aggregate}, perDomainAllValidated={PerDomain}). " + + "Skipping DNS-TXT staging; caller may run the issuance poll.", + orderNumber, aggregateValidated, everyDomainValidated); + return DcvOutcome.Completed; + } + + // Include domains that are pending DCV and either have no method set yet, + // or are already assigned to DNS TXT (numeric "1" from API or label from TrackOrder). + // Domains assigned to HTTP or email DCV are excluded — we must not override them. + var pendingDomains = domainVerification.GetDomainEntries() + .Where(kvp => IsPendingDnsDcvEntry(kvp.Value)) + .ToList(); + + // SOX CC6.1: validate domain names before passing them to the DNS provider plugin + // or the CERTInext API. A malformed domain (empty, whitespace, or containing + // characters outside the FQDN alphabet) could cause log injection or unexpected + // DNS plugin behaviour. Invalid entries are rejected loudly — LogError, so the + // condition is visible in the audit trail — but they are EXCLUDED rather than + // thrown on. + // + // Throwing here would fail the whole order: the exception escapes Enroll (which has + // no catch) after the order was already placed at the CA, so the enrollment reports + // failure with an orphaned order, and no TXT record is staged for the *valid* domains + // on the same order. Worse, it is unrecoverable — every later Synchronize / + // GetSingleRecord retry re-enters here, hits the same undrainable domain, and + // TryRunDcvDuringSyncAsync swallows the exception and returns false, so the order sits + // at EXTERNALVALIDATION forever. + // + // This is reachable in normal operation now that non-DNS SANs are submitted to + // CERTInext (see BuildSanList): the CA registers an email/URI SAN verbatim as an order + // domain, and that key is not an FQDN. One such SAN must not strand the DNS names + // alongside it. Same principle the EMS-956 branch below states explicitly: do not throw + // out of DCV for a condition that leaves the order legitimately pending. + var invalidDomains = new List(); + var validPendingDomains = new List>(); + + foreach (var entry in pendingDomains) + { + string domain = entry.Key; + + // Allow standard FQDN characters plus wildcard prefix (*.example.com). + // + // \A/\z, not ^/$: in .NET's default (non-Multiline) mode, $ matches immediately + // before a single trailing '\n', not only at the true end of the string — so + // "evil.com\n" passes a ^...$ version of this regex. \A and \z are absolute + // start/end-of-string anchors regardless of RegexOptions, so a value with any + // trailing control character is correctly rejected here rather than reaching the + // unsanitized-looking-safe domain this validation exists to guarantee. + bool valid = !string.IsNullOrWhiteSpace(domain) + && System.Text.RegularExpressions.Regex.IsMatch( + domain, @"\A(\*\.)?[a-zA-Z0-9]([a-zA-Z0-9\-\.]*[a-zA-Z0-9])?\z"); + + if (valid) + validPendingDomains.Add(entry); + else + invalidDomains.Add(string.IsNullOrWhiteSpace(domain) ? "(blank)" : domain); + } + + if (invalidDomains.Count > 0) + { + _logger.LogError( + "{Count} domain(s) on order {OrderNumber} are not valid FQDNs and cannot be DNS-01 validated: " + + "[{Domains}]. They are skipped so the remaining {ValidCount} domain(s) can still be validated. " + + "This order cannot be issued by CERTInext until these are removed — they usually come from a " + + "non-DNS SAN (IP address, email, URI) that was requested on the enrollment.", + // An email SAN submitted to V1 comes back verbatim as an order domain; mask it + // unless LogSensitiveRequestData is on. + invalidDomains.Count, orderNumber, + LogSanitizer.FormatUntypedSans(invalidDomains, _config.LogSensitiveRequestData, ", "), + validPendingDomains.Count); + } + + pendingDomains = validPendingDomains; + + if (pendingDomains.Count == 0) + return DcvOutcome.NotRun; + + _logger.LogInformation( + "DCV required for order {OrderNumber}. Pending DNS TXT domains: [{Domains}]", + orderNumber, string.Join(", ", pendingDomains.Select(x => x.Key))); + + var stagedValidations = new List<(string domain, string hostname, Keyfactor.AnyGateway.Extensions.IDomainValidator validator)>(); + + // Every domain that got through staging this pass — whether it freshly published a + // TXT record or shared an already-staged hostname with a sibling (see + // stagedHostnames below). Drives the per-domain CERTInext Verify calls; kept separate + // from stagedValidations (which holds only ONE entry per unique hostname) so a + // wildcard/apex pair sharing a base-domain hostname still each get their own CA-side + // VerifyDcv, without staging — or cleaning up — the shared TXT record twice. + var verifyDomains = new List(); + + // TXT hostname -> the first domain that staged it this pass. A UCC order can list + // both "example.com" and "*.example.com"; StripWildcardPrefix collapses both to the + // same base-domain hostname, so the second domain to reach it must reuse the + // already-staged record instead of publishing (and later cleaning up) a duplicate. + var stagedHostnames = new Dictionary(StringComparer.OrdinalIgnoreCase); + + // Domains this pass could not stage, with why — purely for the summary LogError after + // the loop. Every failure mode below is loud (its own LogError, sanitized) before being + // skipped, so nothing here is silent; this list just avoids repeating that detail twice. + var skippedDomains = new List<(string domain, string reason)>(); + + // Set instead of an immediate `return false` inside the loop below, so a not-yet-ready + // deferral goes through the same cleanup as every other exit path — see the try/catch + // around the loop. + bool deferToNextSyncCycle = false; + + // Removes whatever TXT records were already published before an early exit from the + // staging loop. Nothing else in this method cleans up mid-loop: the try/finally further + // down only runs once every pending domain has been staged, so without this, an early + // exit orphans every TXT record already published for the earlier domains in the *same* + // order — permanently, since nothing else in the codebase calls CleanupValidation for + // them. Kept even though every per-domain failure below is skip-and-continue rather + // than throw: it is the safety net for a genuinely unexpected exception (cancellation, a + // bug, a validator implementation that throws instead of returning a failure result). + // + // Shares its per-entry cleanup logic with the try/finally's own cleanup loop further + // down via CleanupOneStagedValidation — the two call sites differ only in when they run + // (an early exit here vs. always-run-at-the-end there), not in what "clean up one TXT + // record" means. + async Task CleanupPartialStagingAsync() + { + // Concurrent, not sequential: each cleanup call already has its own independent + // CleanupValidationTimeoutSeconds bound (see CleanupOneStagedValidationAsync), but + // running them one after another meant that bound was per-call, not in aggregate — a + // UCC order with N staged domains could hold the calling request open for up to + // N × CleanupValidationTimeoutSeconds if the DNS provider was merely slow (not even + // hung) on every delete, which can exceed DcvTimeoutMinutes itself and defeats the + // "entire DCV flow is hard-timeout-bounded" guarantee for exactly the multi-SAN case + // this diff exists to support. Running them concurrently bounds the wall-clock time + // for the whole batch to the slowest single call, regardless of domain count — these + // are independent per-domain operations (different hostnames/records) with no shared + // mutable state, so there is nothing for concurrent execution to race on. + await Task.WhenAll(stagedValidations.Select(entry => + CleanupOneStagedValidationAsync(entry, " after an early exit from DCV staging"))); + } + + // Shared by CleanupPartialStagingAsync above and the try/finally's own cleanup loop + // below — both mean "remove one already-published TXT record", just at different times + // (an early exit vs. always-run-at-the-end). `context` distinguishes the two in the log + // text without duplicating the try/catch/log structure itself. + async Task CleanupOneStagedValidationAsync( + (string domain, string hostname, Keyfactor.AnyGateway.Extensions.IDomainValidator validator) entry, + string context) + { + var (domain, hostname, validator) = entry; + try + { + // A fresh, independently-bounded token — deliberately neither `ct` nor + // CancellationToken.None. + // + // Not `ct`: this is a best-effort compensating action — removing a TXT record we + // already published — and it must run regardless of WHY we are cleaning up, + // including the case where `ct` itself is the reason (the dominant real trigger + // for the early-exit call site is the shared DcvTimeoutMinutes-bound token firing + // mid-loop, which means `ct` is guaranteed already cancelled there). A + // cooperative IDomainValidator that forwards its token into its own HTTP calls — + // the reference CloudflareDomainValidator in this repo does exactly that — would + // throw immediately on an already-cancelled token and never even attempt the + // delete, silently leaving the record published with only a Warning logged. + // + // Not CancellationToken.None either: this method's own SOX CC7.3 guarantee is + // that the whole DCV flow is hard-timeout-bounded so a stuck DNS provider cannot + // hold a gateway worker thread indefinitely. That bound has to come from + // somewhere for THIS call too — including the routine, always-runs finally-block + // cleanup on the ordinary successful-DCV path, which was never cancellation- + // related to begin with and would otherwise hang forever on a DNS provider + // plugin whose underlying network call stalls. + using var cleanupCts = new CancellationTokenSource( + TimeSpan.FromSeconds(Constants.Dcv.CleanupValidationTimeoutSeconds)); + await validator.CleanupValidation(hostname, cleanupCts.Token); + _logger.LogInformation( + "DNS TXT record cleaned up{Context}. Domain={Domain}, Hostname={Hostname}", + context, LogSanitizer.Strip(domain), LogSanitizer.Strip(hostname)); + } + catch (Exception ex) + { + _logger.LogWarning(ex, + "Failed to clean up DNS TXT record{Context}. Domain={Domain}, Hostname={Hostname}. " + + "May require manual removal.", + context, LogSanitizer.Strip(domain), LogSanitizer.Strip(hostname)); + } + } + + try + { + // Stage DNS TXT records for all pending domains. Every failure below is scoped to + // the one domain that hit it — logged loudly (LogError, so the audit trail carries + // the reason before the domain is dropped) and skipped, never thrown. A throw here + // would abort the WHOLE order after Enroll already placed it at the CA — Enroll has + // no catch around this call, so the exception would escape as a failed enrollment + // with an orphaned CERTInext order, and TryRunDcvDuringSyncAsync would swallow the + // same exception on every later sync retry, leaving the order stuck at + // EXTERNALVALIDATION forever. That is worse than parking the order pending with a + // clear log entry, for EVERY failure shape here — not just the ones distinguishable + // as "bad input" — because nothing downstream ever gets to see or act on the + // exception anyway. Without this guard: a GetDcv error or an empty token for a + // non-DNS SAN (submitted on purpose — see BuildSanList) would abort co-tenant DNS + // domains on the same order; a StageValidation failure on domain N+1 would orphan + // domain N's TXT record; and a misconfiguration-detection throw on an ordinary + // non-DNS Subject CN (which no setting can prevent, since SubmitNonDnsSans only + // filters the SAN list, not the subject) would abort the whole order. There is no + // "this must still throw" case in this loop. + foreach (var (domain, _) in pendingDomains) + { + GetDcvResponse dcvResp; + try + { + dcvResp = await _client.GetDcvAsync(orderNumber, domain, Constants.Dcv.MethodDnsTxt, ct); + } + catch (Exception ex) when (IsDcvNotYetReady(ex)) + { + // CERTInext occasionally exposes the DCV slot in TrackOrder (so + // domainVerification is populated and dcvStatus="0") before the GetDcv + // endpoint will accept calls for that order — surfaces as EMS-956 + // "Invalid Request for this API" for several hours after enrollment. This is + // an order-readiness condition, not a per-domain one, so unlike every other + // case in this loop it defers the whole pass rather than skipping one domain. + _logger.LogInformation( + "GetDcv not yet accepting calls for order {OrderNumber} domain {Domain} ({Error}). " + + "Deferring DCV to the next sync cycle.", + orderNumber, LogSanitizer.Strip(domain), ex.Message); + deferToNextSyncCycle = true; + break; + } + catch (OperationCanceledException) + { + // The shared, DcvTimeoutMinutes-bound cancellation firing mid-loop. This is + // NOT a per-domain CA/DNS-provider failure — it must not be caught by the + // generic clause below, which would mislabel it as "GetDcv failed" for + // whichever domain happened to be in flight and send an operator chasing the + // wrong cause. Propagate to the outer catch, which logs and cleans up. + throw; + } + catch (Exception ex) + { + // Any other GetDcv failure — genuinely unmeasured against the live API for a + // non-DNS order-domain, which is exactly why this must not be allowed to fail + // the whole order on a guess. Skip just this domain. + _logger.LogError(ex, + "GetDcv failed for order {OrderNumber} domain {Domain}; skipping this domain so the " + + "rest of the order can still be validated.", orderNumber, LogSanitizer.Strip(domain)); + skippedDomains.Add((domain, "GetDcv failed")); + continue; + } + + string token = dcvResp.DcvDetails?.Token; + if (string.IsNullOrWhiteSpace(token)) + { + _logger.LogError( + "GetDcv returned no token for order {OrderNumber} domain {Domain}; skipping this " + + "domain so the rest of the order can still be validated.", + orderNumber, LogSanitizer.Strip(domain)); + skippedDomains.Add((domain, "no DCV token returned")); + continue; + } + + string template = string.IsNullOrWhiteSpace(_config.DcvTxtRecordTemplate) + ? Constants.Dcv.DefaultTxtRecordTemplate + : _config.DcvTxtRecordTemplate; + // DCV publishes/looks up the TXT record under the BASE domain — a wildcard's + // "*." label is not a queryable DNS name. CERTInext's own GetDcv/VerifyDcv + // calls above/below still use the original `domain` (including "*."), since + // that is what Track Order reports back per-domain. + string baseDomain = StripWildcardPrefix(domain); + string hostname = string.Format(template, baseDomain); + + if (stagedHostnames.TryGetValue(hostname + "|" + token, out string sharedWithDomain)) + { + // Sibling domain (e.g. the wildcard/apex pair of the same base domain) + // already staged this exact TXT hostname this pass — reuse it instead of + // publishing a second record at the same name. This domain still gets its + // own CA-side GetDcv/VerifyDcv (CERTInext tracks DCV per domain entry); it + // just doesn't need its own TXT record. + _logger.LogInformation( + "DCV hostname {Hostname} for domain {Domain} on order {OrderNumber} is already " + + "staged (shared with {SharedWith}); reusing it instead of publishing a second " + + "TXT record.", + LogSanitizer.Strip(hostname), LogSanitizer.Strip(domain), orderNumber, + LogSanitizer.Strip(sharedWithDomain)); + verifyDomains.Add(domain); + continue; + } + + var validator = DomainValidatorFactory.ResolveDomainValidator(baseDomain, "dns-01"); + if (validator == null) + { + // The canonical case: an IP-literal SAN (or a non-DNS Subject CN) satisfies + // the FQDN regex above but no DNS zone can ever match it. + _logger.LogError( + "No DNS provider plugin resolved for domain '{Domain}' on order {OrderNumber}; " + + "skipping this domain so the rest of the order can still be validated. If this is " + + "a real domain, ensure the appropriate DNS provider plugin is deployed and " + + "configured on the gateway; if it came from a non-DNS SAN (e.g. an IP address) or a " + + "non-DNS Subject CN, remove it from the request.", + LogSanitizer.Strip(domain), orderNumber); + skippedDomains.Add((domain, "no DNS provider resolved")); + continue; + } + + _logger.LogInformation( + "Staging DNS TXT record for DCV. OrderNumber={OrderNumber}, Domain={Domain}, Hostname={Hostname}", + orderNumber, LogSanitizer.Strip(domain), LogSanitizer.Strip(hostname)); + + DomainValidationResult stageResult; + try + { + stageResult = await validator.StageValidation(hostname, token, ct); + } + catch (OperationCanceledException) + { + // Same reasoning as the GetDcv cancellation catch above: not a per-domain + // failure, must reach the outer catch rather than the generic clause below. + throw; + } + catch (Exception ex) + { + _logger.LogError(ex, + "DNS provider plugin threw while staging '{Domain}' for order {OrderNumber}; " + + "skipping this domain so the rest of the order can still be validated.", + LogSanitizer.Strip(domain), orderNumber); + skippedDomains.Add((domain, "DNS provider plugin threw")); + continue; + } + + if (!stageResult.Success) + { + _logger.LogError( + "Failed to stage DNS validation for '{Domain}' on order {OrderNumber}: {Error}. " + + "Skipping this domain so the rest of the order can still be validated.", + LogSanitizer.Strip(domain), orderNumber, LogSanitizer.Strip(stageResult.ErrorMessage)); + skippedDomains.Add((domain, $"stage failed: {stageResult.ErrorMessage}")); + continue; + } + + stagedHostnames[hostname + "|" + token] = domain; + stagedValidations.Add((domain, hostname, validator)); + verifyDomains.Add(domain); + } + } + catch (Exception ex) + { + // Nothing in the loop above throws for a per-domain reason — this is the + // safety net for a genuinely unexpected failure: cancellation (the shared + // DcvTimeoutMinutes-bound token expiring mid-loop — explicitly re-thrown past the + // per-domain catches above rather than mislabeled as a per-domain failure) or a bug. + // Log before rethrowing: neither caller (EnrollNewAsync's try/finally, or Enroll + // itself) adds a catch, so without a log line here an unanticipated failure on the + // synchronous Enroll-time DCV path would leave no plugin-emitted record at all + // identifying the order or cause — only whatever the gateway host's own unhandled- + // exception logging happens to capture. + _logger.LogError(ex, + "Unexpected failure during DCV staging for order {OrderNumber}; cleaning up any " + + "already-staged TXT records before this propagates.", orderNumber); + await CleanupPartialStagingAsync(); + throw; + } + + if (deferToNextSyncCycle) + { + await CleanupPartialStagingAsync(); + return DcvOutcome.NotRun; + } + + if (skippedDomains.Count > 0) + { + _logger.LogError( + "{Count} domain(s) on order {OrderNumber} could not be staged for DCV and were skipped: " + + "[{Domains}]. This order cannot be issued by CERTInext until they are resolved.", + skippedDomains.Count, orderNumber, + LogSanitizer.Strip(string.Join(", ", skippedDomains.Select(d => $"{d.domain} ({d.reason})")))); + } + + if (stagedValidations.Count == 0) + return DcvOutcome.NotRun; + + try + { + // Allow DNS propagation before asking CERTInext to verify. The sync path passes + // a short override so a bounded set of recent pending orders doesn't + // each burn the full configured delay; Enroll uses the full configured value. + int delaySeconds = propagationDelaySecondsOverride + ?? (_config.DcvPropagationDelaySeconds > 0 ? _config.DcvPropagationDelaySeconds : 30); + _logger.LogInformation( + "Waiting {Delay}s for DNS propagation before verifying DCV. OrderNumber={OrderNumber}", + delaySeconds, orderNumber); + await Task.Delay(TimeSpan.FromSeconds(delaySeconds), ct); + + // Every domain that got through staging — including hostname-sharing siblings — + // still gets its own CA-side verify call; CERTInext tracks DCV per domain entry + // even when two domains share one TXT record. + foreach (var domain in verifyDomains) + { + _logger.LogInformation( + "Triggering CERTInext DCV verification. OrderNumber={OrderNumber}, Domain={Domain}", + orderNumber, LogSanitizer.Strip(domain)); + await _client.VerifyDcvAsync(orderNumber, domain, Constants.Dcv.MethodDnsTxt, ct); + } + + // Poll TrackOrder until CERTInext confirms all staged domains are verified + // before removing TXT records — VerifyDcv triggers an async DNS lookup on + // their side, so cleanup must wait for dcvStatus=1 on every domain. + await WaitForDcvVerificationAsync(orderNumber, verifyDomains, ct); + } + finally + { + // Always clean up staged DNS records — even on failure. Concurrent, not sequential + // — see CleanupPartialStagingAsync's comment above for why: sequential cleanup made + // the aggregate wall-clock time for this block scale with the number of staged SAN + // domains, unbounded relative to DcvTimeoutMinutes, on this ordinary success path too. + await Task.WhenAll(stagedValidations.Select(entry => + CleanupOneStagedValidationAsync(entry, ""))); + } + + // A skipped domain (non-FQDN entry filtered above, or one that could not be staged) + // means the order cannot issue yet: tell the caller not to wait for issuance. + return (skippedDomains.Count > 0 || invalidDomains.Count > 0) + ? DcvOutcome.CompletedWithSkippedDomains + : DcvOutcome.Completed; + } + + /// + /// True when the exception's message contains the CERTInext V2 EMS-1080 code + /// ("Domain is already verified"), the spec's documented no-op for both + /// GetDcv and VerifyDcv on a domain that is still within its DCV reuse window. + /// Message-based rather than a typed field because the API's + /// RFC 7807 body carries the EMS code as text embedded in `detail`/`title`, + /// not as a separate structured field (see ). + /// + private static bool IsEms1080DomainAlreadyVerified(Exception ex) => + ex?.Message?.IndexOf("EMS-1080", StringComparison.OrdinalIgnoreCase) >= 0; + + /// + /// Performs DNS-01 DCV for a V2 SSL order using the V2 DCV endpoints. + /// + /// A UCC order's additional SAN domains each carry their own DCV state in + /// Track Order's verifications.domain.domains[] block. This entry point owns the + /// single per-order guard (enrollment + sync overlap + /// protection — one guard entry regardless of how many domains the order has), then + /// dispatches to whichever flow applies: + /// - non-empty → , + /// which loops every domain whose own dcvStatus isn't VERIFIED. + /// - null/empty (single-domain orders, or an older/ + /// simpler response shape that never populated the block) → the + /// single-domain flow in + /// . + /// + /// Returns true when DCV steps were executed for at least one domain, false + /// when skipped entirely (not configured, no domain(s) to act on, or already in flight). + /// + private async Task PerformDcvV2IfNeededAsync( + string orderId, + string domain, + string productFamilySlug, + CancellationToken ct, + IReadOnlyList domainEntries = null) + { + if (_domainValidatorFactory == null || !_config.DcvEnabled) + { + _logger.LogDebug( + "V2 DCV skipped: DCV factory not configured or DcvEnabled=false. OrderId={OrderId}", orderId); + return false; + } + + // Domain control validation exists only for the SSL/TLS family — the + // spec's DCV endpoints live under /ssl-certificates only, the Private PKI folder says + // "No DCV - your CA trusts you", and the Document Signer folder has no DCV step. This + // single gate covers every caller (EnrollV2Async, GetSingleRecordV2Async and V2 + // Synchronize), so a non-SSL order that is merely pending approval/documents is never + // sent to a nonexistent /{family}/{orderId}/dcv endpoint. + if (!string.Equals(productFamilySlug, Constants.ApiV2.FamilySsl, StringComparison.OrdinalIgnoreCase)) + { + _logger.LogDebug( + "V2 DCV skipped: product family '{Family}' has no domain control validation step. OrderId={OrderId}", + productFamilySlug, orderId); + return false; + } + + bool multiDomainMode = domainEntries != null && domainEntries.Count > 0; + + if (!multiDomainMode && string.IsNullOrWhiteSpace(domain)) + { + _logger.LogWarning( + "V2 DCV skipped: no domain name available for order {OrderId}.", orderId); return false; + } - if (!_dcvInFlight.TryAdd(orderNumber, 0)) + // Prevent concurrent DCV staging for the same order (enrollment + sync overlap). + // Mirrors the _dcvInFlight guard in TryRunDcvDuringSyncAsync (V1 path). One guard + // entry per ORDER, not per domain — a UCC order with several pending SANs is still + // a single in-flight unit of work. + if (!_dcvInFlight.TryAdd(orderId, 0)) { - // SOC2 CC7.2: concurrent DCV-attempt collisions are security-relevant - // (they indicate either a normal overlap of two sync cycles OR an attempt - // to interleave operations on the same order). Log at Information so the - // event appears in production logs without verbose-debug being enabled. _logger.LogInformation( - "DCV already in flight for order {OrderNumber}; skipping concurrent attempt.", - orderNumber); + "DCV already in flight for V2 order {OrderId}; skipping concurrent attempt.", orderId); return false; } try { - int timeoutMinutes = _config.GetEffectiveDcvTimeoutMinutes(); - using var dcvCts = CancellationTokenSource.CreateLinkedTokenSource(ct); - dcvCts.CancelAfter(TimeSpan.FromMinutes(timeoutMinutes)); + return multiDomainMode + ? await PerformDcvV2MultiDomainAsync(orderId, domainEntries, productFamilySlug, ct) + : await PerformDcvV2SingleDomainAsync(orderId, domain, productFamilySlug, ct); + } + finally + { + _dcvInFlight.TryRemove(orderId, out _); + } + } - _logger.LogInformation( - "Attempting deferred DCV during sync/refresh (single-shot challenge check). " + - "OrderNumber={OrderNumber}, DcvTimeoutMinutes={Timeout}", - orderNumber, timeoutMinutes); + /// + /// Single-domain V2 DCV flow, used whenever the order has no per-domain + /// verifications.domain.domains[] block to drive from (single-domain orders, or an + /// older/simpler response shape). The _dcvInFlight guard is owned by its caller + /// for the whole call. + /// + /// Flow: + /// 1. GET /ssl-certificates/{orderId}/dcv → retrieve token (token) + /// 2. Publish TXT record at the configured DcvTxtRecordTemplate hostname + /// (default Constants.Dcv.DefaultTxtRecordTemplate) via + /// 3. POST /ssl-certificates/{orderId}/dcv/verify → trigger CA-side verification + /// 4. Poll until status != "pending-dcv" + /// 5. Clean up TXT record + /// + /// EMS-1080 ("Domain is already verified") from either GetDcv or VerifyDcv is + /// treated as DCV already satisfied: publishing is skipped and + /// the flow proceeds straight to step 4. + /// + /// Returns true when DCV steps were executed, false when skipped. + /// + private async Task PerformDcvV2SingleDomainAsync( + string orderId, + string domain, + string productFamilySlug, + CancellationToken ct) + { + _logger.LogInformation( + "V2 DCV starting for order {OrderId}, domain {Domain}.", orderId, LogSanitizer.Strip(domain)); - return await PerformDcvIfNeededAsync(orderNumber, dcvCts.Token, - waitForChallengeSecondsOverride: 0, - propagationDelaySecondsOverride: fastSync ? Constants.Dcv.SyncPropagationDelaySeconds : (int?)null); + // 1. Fetch challenge + V2DcvChallengeResponse challenge = null; + bool dcvAlreadySatisfied = false; + try + { + challenge = await _client.GetDcvV2Async(orderId, productFamilySlug, ct); } - catch (OperationCanceledException) when (ct.IsCancellationRequested) + catch (Exception ex) when (IsEms1080DomainAlreadyVerified(ex)) { - throw; + // EMS-1080 "Domain is already verified" is a documented no-op, + // not a failure: the domain is account-scoped and reusable, so there is no + // fresh challenge to fetch. Treat DCV as already satisfied and skip straight + // to tracking/issuance instead of deferring to the next sync cycle. + _logger.LogInformation( + "V2 DCV already satisfied (EMS-1080 domain already verified) for order {OrderId}; " + + "skipping TXT publish and proceeding to tracking.", orderId); + dcvAlreadySatisfied = true; } catch (Exception ex) { + _dcvInFlight.TryRemove(orderId, out _); _logger.LogWarning(ex, - "Deferred DCV attempt failed for order {OrderNumber}. Order will be retried on the next sync cycle.", - orderNumber); + "V2 GetDcv failed for order {OrderId}; deferring DCV to next sync cycle.", orderId); return false; } + + string token = null; + string hostname = null; + Keyfactor.AnyGateway.Extensions.IDomainValidator validator = null; + + if (!dcvAlreadySatisfied) + { + token = challenge?.Token; + if (string.IsNullOrWhiteSpace(token)) + { + _dcvInFlight.TryRemove(orderId, out _); + _logger.LogWarning( + "V2 GetDcv returned no token for order {OrderId}; deferring DCV.", orderId); + return false; + } + + // TXT record hostname template — config-driven, mirroring V1's + // PerformDcvIfNeededAsync. Falls back to the same + // Constants.Dcv.DefaultTxtRecordTemplate default V1 uses when unconfigured; + // {0} is substituted with the BASE domain name via string.Format, same as V1 — + // a wildcard's "*." label is not a queryable DNS name, so the DNS-side hostname + // and zone resolution use StripWildcardPrefix(domain); the CERTInext calls above + // and below keep using the original `domain` string, since that is what Track + // Order reports back. + string template = string.IsNullOrWhiteSpace(_config.DcvTxtRecordTemplate) + ? Constants.Dcv.DefaultTxtRecordTemplate + : _config.DcvTxtRecordTemplate; + string baseDomain = StripWildcardPrefix(domain); + hostname = string.Format(template, baseDomain); + + validator = DomainValidatorFactory.ResolveDomainValidator(baseDomain, "dns-01"); + if (validator == null) + { + _dcvInFlight.TryRemove(orderId, out _); + _logger.LogError( + "No DNS provider plugin resolved for domain '{Domain}' on V2 order {OrderId}. " + + "Ensure the appropriate DNS provider plugin is deployed and configured.", + LogSanitizer.Strip(domain), orderId); + return false; + } + } + + // staged=true only after a successful StageValidation so the finally only attempts + // cleanup when there is a record to remove (Finding C — cleanup skipped on !Success). + bool staged = false; + try + { + if (!dcvAlreadySatisfied) + { + // 2. Publish TXT record + _logger.LogInformation( + "Staging V2 DNS TXT record. OrderId={OrderId}, Hostname={Hostname}", orderId, LogSanitizer.Strip(hostname)); + + DomainValidationResult stageResult; + try + { + // Non-null here: only reached when !dcvAlreadySatisfied, and + // validator/hostname are always assigned together in that branch above. + stageResult = await validator!.StageValidation(hostname!, token, ct); + } + catch (Exception ex) + { + _logger.LogError(ex, + "V2 DCV: DNS provider threw while staging '{Domain}' for order {OrderId}.", + LogSanitizer.Strip(domain), orderId); + return false; + } + + if (!stageResult.Success) + { + _logger.LogError( + "V2 DCV: Failed to stage DNS TXT for '{Domain}' on order {OrderId}: {Error}.", + LogSanitizer.Strip(domain), orderId, LogSanitizer.Strip(stageResult.ErrorMessage)); + return false; + } + staged = true; + + // Wait for DNS propagation + int delaySeconds = _config.DcvPropagationDelaySeconds > 0 ? _config.DcvPropagationDelaySeconds : 30; + _logger.LogInformation( + "Waiting {Delay}s for DNS propagation before V2 DCV verify. OrderId={OrderId}", delaySeconds, orderId); + await Task.Delay(TimeSpan.FromSeconds(delaySeconds), ct); + + // 3. Trigger CA-side verification + _logger.LogInformation( + "Triggering V2 DCV verification. OrderId={OrderId}, Domain={Domain}", orderId, LogSanitizer.Strip(domain)); + try + { + var verifyResp = await _client.VerifyDcvV2Async(orderId, domain, productFamilySlug, ct); + _logger.LogInformation( + "V2 DCV verify response. OrderId={OrderId}, OverallStatus={Status}", + orderId, verifyResp?.OverallStatus ?? "(null)"); + + if (!string.Equals(verifyResp?.OverallStatus, "VERIFIED", StringComparison.OrdinalIgnoreCase)) + { + _logger.LogWarning( + "V2 DCV verify did not return VERIFIED for order {OrderId}. Status={Status}", + orderId, verifyResp?.OverallStatus); + return false; + } + } + catch (Exception ex) when (IsEms1080DomainAlreadyVerified(ex)) + { + // Same no-op as the GetDcv branch above, but surfaced at Verify time + // instead — the domain became/was already verified between the two + // calls. Treat as verified and continue to tracking rather than + // deferring. + _logger.LogInformation( + "V2 DCV already satisfied (EMS-1080 domain already verified) for order {OrderId} " + + "during VerifyDcv; treating as verified and proceeding to tracking.", orderId); + } + } + + // 4. Poll TrackOrderV2 until status leaves pending-dcv + int timeoutMinutes = _config.GetEffectiveDcvTimeoutMinutes(); + var deadline = DateTime.UtcNow.AddMinutes(timeoutMinutes); + // Fixed short cadence — decoupled from DcvPropagationDelaySeconds (one-shot + // DNS wait), not a poll interval. Reusing it here would yield only ~2 polls + // before the 5-minute timeout. + int pollSeconds = Constants.Dcv.SyncPropagationDelaySeconds; + + while (DateTime.UtcNow < deadline && !ct.IsCancellationRequested) + { + await Task.Delay(TimeSpan.FromSeconds(pollSeconds), ct); + try + { + var trackResp = await _client.TrackOrderV2Async(productFamilySlug, orderId, ct); + _logger.LogDebug( + "V2 DCV poll. OrderId={OrderId}, Status={Status}", orderId, trackResp.Status); + if (!string.Equals(trackResp.Status, "pending-dcv", StringComparison.OrdinalIgnoreCase)) + break; + } + catch (Exception ex) + { + _logger.LogWarning(ex, "V2 DCV: TrackOrderV2 poll failed for order {OrderId}.", orderId); + break; + } + } + + return true; + } finally { - _dcvInFlight.TryRemove(orderNumber, out _); + // Release the in-flight guard regardless of how the staged block exits. + _dcvInFlight.TryRemove(orderId, out _); + + // 5. Clean up TXT record — only when staging succeeded (staged=true). + if (staged) + { + try + { + using var cleanupCts = new CancellationTokenSource( + TimeSpan.FromSeconds(Constants.Dcv.CleanupValidationTimeoutSeconds)); + // Non-null here: staged is only true when !dcvAlreadySatisfied, in + // which case validator/hostname were assigned before staging began. + await validator!.CleanupValidation(hostname!, cleanupCts.Token); + _logger.LogInformation( + "V2 DCV: DNS TXT record cleaned up. OrderId={OrderId}, Hostname={Hostname}", + orderId, LogSanitizer.Strip(hostname)); + } + catch (Exception ex) + { + _logger.LogWarning(ex, + "V2 DCV: Failed to clean up DNS TXT record. OrderId={OrderId}, Hostname={Hostname}. " + + "May require manual removal.", orderId, LogSanitizer.Strip(hostname)); + } + } } -#else - // DCV is not supported on this build (IAnyCAPlugin 3.2.0). No-op: pending orders - // are reported as EXTERNALVALIDATION and not advanced during sync. See issue 0003. - await Task.CompletedTask; - return false; -#endif } /// - /// Runs DNS DCV for any domains on that are still pending - /// validation. Returns true when DCV steps were executed, false when - /// skipped (order already issued, no pending domains, or factory not available). + /// Generalized V2 DCV for orders whose Track Order response surfaced a per-domain + /// verifications.domain.domains[] block — chiefly UCC orders with + /// additional SAN domains. Every entry whose own dcvStatus isn't VERIFIED is + /// processed: stage a TXT record for each pending domain, wait once for DNS propagation + /// (not once per domain), verify each domain individually, poll Track Order until every + /// domain just verified is confirmed (or the shared DCV timeout elapses), then always + /// clean up every staged record regardless of outcome. /// - /// Rule: if the order is already issued we never attempt DCV — it would be a no-op - /// at best and could confuse the CA at worst. + /// Partial failure: a domain that fails GetDcv/staging/verification is logged and + /// skipped — the others keep going. The order is left pending for any domain not + /// resolved this pass; because the caller always re-derives + /// from its own most recent Track Order response, the next sync/GetSingleRecord call + /// naturally retries only whichever domains are still not VERIFIED. /// - /// lets the sync path force a - /// single-shot challenge check (pass 0) so a sync cycle doesn't spend up to - /// DcvWaitForChallengeSeconds per pending order waiting for CERTInext to - /// expose the DCV slot — sync runs periodically, so unexposed orders are picked up - /// on the next cycle instead. Enroll passes null to keep the full configured - /// budget (user-visible latency benefits from a one-shot end-to-end finish). + /// The per-order _dcvInFlight guard is already held by the caller + /// () for the whole call. + /// + /// Returns true when DCV steps were executed for at least one domain (staged, or + /// found already verified via EMS-1080); false only when every domain in + /// was already VERIFIED (nothing to do). /// -#if SUPPORTS_DCV - private async Task PerformDcvIfNeededAsync( - string orderNumber, - CancellationToken ct, - int? waitForChallengeSecondsOverride = null, - int? propagationDelaySecondsOverride = null) + private async Task PerformDcvV2MultiDomainAsync( + string orderId, + IReadOnlyList domainEntries, + string productFamilySlug, + CancellationToken ct) { - // Poll TrackOrder until CERTInext exposes the DCV challenge (domainVerification - // populated) OR the cert reaches a terminal state OR the wait budget expires. - // Under concurrent enrollment load CERTInext sometimes takes a few seconds to - // materialize the slot after GenerateOrderSSL returns — without this wait a - // race-condition order skips DCV entirely and waits for the next sync cycle. - int waitBudgetSeconds = waitForChallengeSecondsOverride - ?? _config.GetEffectiveDcvWaitForChallengeSeconds(); - // Challenge-wait poll interval is clamped to [1s, 5s] so it's responsive even - // when an admin has set DcvPropagationDelaySeconds high for slow zones (that - // setting governs how long we wait *after* publishing a TXT record, which is a - // different, slower concern than how often we re-check TrackOrder here). - int challengePollSeconds = Math.Max(1, Math.Min(5, _config.DcvPropagationDelaySeconds > 0 ? _config.DcvPropagationDelaySeconds : 5)); - var waitDeadline = DateTime.UtcNow.AddSeconds(Math.Max(0, waitBudgetSeconds)); + var pendingDomains = domainEntries + .Where(e => !string.IsNullOrWhiteSpace(e?.Domain) + && !string.Equals(e.DcvStatus, Constants.ApiV2.DcvStatusVerified, StringComparison.OrdinalIgnoreCase)) + .Select(e => e.Domain) + .Distinct(StringComparer.OrdinalIgnoreCase) + .ToList(); - TrackOrderResponse track = null; - API.TrackOrderDomainVerification domainVerification = null; - int pollAttempts = 0; + if (pendingDomains.Count == 0) + { + _logger.LogDebug( + "V2 DCV (multi-domain) skipped: every domain on order {OrderId} is already VERIFIED.", + orderId); + return false; + } - while (true) + _logger.LogInformation( + "V2 DCV (multi-domain) starting for order {OrderId}. PendingDomains=[{Domains}]", + orderId, LogSanitizer.Strip(string.Join(", ", pendingDomains))); + + var staged = new List<(string domain, string hostname, Keyfactor.AnyGateway.Extensions.IDomainValidator validator)>(); + var verifiedDomains = new List(); + var failedDomains = new List<(string domain, string reason)>(); + + // Every domain that got through staging this pass — whether it freshly published a + // TXT record or shared an already-staged hostname with a sibling (see + // stagedHostnames below). Drives the per-domain CA Verify calls in Phase 2; kept + // separate from `staged` (which holds only ONE entry per unique hostname, for + // cleanup) so a wildcard/apex pair sharing a base-domain hostname still each get + // their own VerifyDcv call without staging — or cleaning up — the shared TXT record + // twice. + var verifyCandidates = new List(); + + // TXT hostname -> the first domain that staged it this pass. A UCC order can list + // both "example.com" and "*.example.com"; StripWildcardPrefix collapses both to the + // same base-domain hostname, so the second domain to reach it must reuse the + // already-staged record instead of publishing (and later cleaning up) a duplicate. + var stagedHostnames = new Dictionary(StringComparer.OrdinalIgnoreCase); + + async Task CleanupStagedAsync() { - pollAttempts++; - ct.ThrowIfCancellationRequested(); - track = await _client.TrackOrderAsync(orderNumber, ct); + // Concurrent, not sequential — mirrors the V1 multi-SAN cleanup rationale + // (CleanupPartialStagingAsync above): a UCC order with N staged domains must not + // let the aggregate cleanup time scale with N. + await Task.WhenAll(staged.Select(entry => CleanupOneV2StagedRecordAsync(orderId, entry))); + } - // Skip DCV entirely if the certificate is already issued or revoked - if (track.OrderDetails != null - && int.TryParse(track.OrderDetails.CertificateStatusId, out int certStatusId)) + try + { + // Phase 1: stage a TXT record for every pending domain. Every failure here is + // scoped to the one domain that hit it (logged loudly, then skipped) — never + // thrown — so one bad SAN cannot abort DCV for the co-tenant domains on the same + // order; a partial failure keeps the rest going. + foreach (var d in pendingDomains) { - int disposition = StatusMapper.CertificateStatusIdToRequestDisposition(certStatusId); - if (disposition == (int)EndEntityStatus.GENERATED || disposition == (int)EndEntityStatus.REVOKED) + ct.ThrowIfCancellationRequested(); + + V2DcvChallengeResponse challenge = null; + bool alreadySatisfied = false; + try { - _logger.LogDebug( - "DCV skipped — order {OrderNumber} is already in terminal state (certificateStatusId={Status}).", - orderNumber, certStatusId); - return false; + challenge = await _client.GetDcvV2Async(orderId, d, productFamilySlug, ct); + } + catch (Exception ex) when (IsEms1080DomainAlreadyVerified(ex)) + { + _logger.LogInformation( + "V2 DCV already satisfied (EMS-1080) for domain {Domain} on order {OrderId}; " + + "skipping TXT publish for this domain.", LogSanitizer.Strip(d), orderId); + alreadySatisfied = true; + } + catch (OperationCanceledException) + { + // The shared, DcvTimeoutMinutes-bound cancellation — not a per-domain + // failure. Propagate to the outer catch, which logs and cleans up. + throw; + } + catch (Exception ex) + { + _logger.LogError(ex, + "V2 GetDcv failed for domain {Domain} on order {OrderId}; skipping this domain " + + "so the rest of the order can still be validated.", LogSanitizer.Strip(d), orderId); + failedDomains.Add((d, "GetDcv failed")); + continue; } - } - // Skip if the order itself reached a terminal failure state. Without this - // the cached-DCV path below could still return true on a cancelled order - // (domainVerification.Status = "1" survives the cancellation), sending the - // caller into a wasted DcvWaitForIssuanceSeconds-long GetCertificate poll - // that can never resolve. OrderStatusId 4 = cancelled, 5 = rejected. - if (track.OrderDetails?.OrderStatusId is "4" or "5") - { - _logger.LogDebug( - "DCV skipped — order {OrderNumber} is cancelled/rejected " + - "(orderStatusId={OrderStatus}).", - orderNumber, track.OrderDetails.OrderStatusId); - return false; - } + if (alreadySatisfied) + { + verifiedDomains.Add(d); + continue; + } - domainVerification = track.OrderDetails?.DomainVerification; - if (domainVerification != null) - break; + string token = challenge?.Token; + if (string.IsNullOrWhiteSpace(token)) + { + _logger.LogError( + "V2 GetDcv returned no token for domain {Domain} on order {OrderId}; skipping " + + "this domain so the rest of the order can still be validated.", + LogSanitizer.Strip(d), orderId); + failedDomains.Add((d, "no DCV token returned")); + continue; + } + + string template = string.IsNullOrWhiteSpace(_config.DcvTxtRecordTemplate) + ? Constants.Dcv.DefaultTxtRecordTemplate + : _config.DcvTxtRecordTemplate; + // DCV publishes/looks up the TXT record under the BASE domain — a wildcard's + // "*." label is not a queryable DNS name. CERTInext's own GetDcv/VerifyDcv + // calls keep using the original `d` string, since that is what Track Order + // reports back per-domain. + string baseDomain = StripWildcardPrefix(d); + string hostname = string.Format(template, baseDomain); + + if (stagedHostnames.TryGetValue(hostname + "|" + token, out string sharedWithDomain)) + { + // Sibling domain (e.g. the wildcard/apex pair of the same base domain) + // already staged this exact TXT hostname this pass — reuse it instead of + // publishing a second record at the same name. This domain still gets its + // own CA-side VerifyDcv in Phase 2 below. + _logger.LogInformation( + "V2 DCV hostname {Hostname} for domain {Domain} on order {OrderId} is already " + + "staged (shared with {SharedWith}); reusing it instead of publishing a second " + + "TXT record.", + LogSanitizer.Strip(hostname), LogSanitizer.Strip(d), orderId, + LogSanitizer.Strip(sharedWithDomain)); + verifyCandidates.Add(d); + continue; + } + + var validator = DomainValidatorFactory.ResolveDomainValidator(baseDomain, "dns-01"); + if (validator == null) + { + _logger.LogError( + "No DNS provider plugin resolved for domain '{Domain}' on V2 order {OrderId}; " + + "skipping this domain so the rest of the order can still be validated.", + LogSanitizer.Strip(d), orderId); + failedDomains.Add((d, "no DNS provider resolved")); + continue; + } - // domainVerification still null — sleep and retry if we have budget left. - if (waitBudgetSeconds <= 0 || DateTime.UtcNow >= waitDeadline) - { _logger.LogInformation( - "DCV challenge not exposed by CERTInext within {Budget}s for order {OrderNumber} " + - "(attempted {Attempts} TrackOrder polls). Deferring to next sync cycle.", - waitBudgetSeconds, orderNumber, pollAttempts); - return false; + "Staging V2 DNS TXT record for DCV. OrderId={OrderId}, Domain={Domain}, Hostname={Hostname}", + orderId, LogSanitizer.Strip(d), LogSanitizer.Strip(hostname)); + + DomainValidationResult stageResult; + try + { + stageResult = await validator.StageValidation(hostname, token, ct); + } + catch (OperationCanceledException) + { + throw; + } + catch (Exception ex) + { + _logger.LogError(ex, + "V2 DCV: DNS provider threw while staging '{Domain}' for order {OrderId}; " + + "skipping this domain so the rest of the order can still be validated.", + LogSanitizer.Strip(d), orderId); + failedDomains.Add((d, "DNS provider plugin threw")); + continue; + } + + if (!stageResult.Success) + { + _logger.LogError( + "V2 DCV: Failed to stage DNS TXT for '{Domain}' on order {OrderId}: {Error}. " + + "Skipping this domain so the rest of the order can still be validated.", + LogSanitizer.Strip(d), orderId, LogSanitizer.Strip(stageResult.ErrorMessage)); + failedDomains.Add((d, $"stage failed: {stageResult.ErrorMessage}")); + continue; + } + + stagedHostnames[hostname + "|" + token] = d; + staged.Add((d, hostname, validator)); + verifyCandidates.Add(d); } + } + catch (Exception ex) + { + // Safety net for a genuinely unexpected failure: cancellation (the shared + // DcvTimeoutMinutes-bound token expiring mid-loop, explicitly re-thrown past the + // per-domain catches above) or a bug. Clean up whatever was already staged before + // this propagates — none of the callers add their own cleanup. + _logger.LogError(ex, + "Unexpected failure during V2 DCV staging for order {OrderId}; cleaning up any " + + "already-staged TXT records before this propagates.", orderId); + await CleanupStagedAsync(); + throw; + } + + if (verifyCandidates.Count > 0) + { + try + { + // One propagation wait for the whole batch, not one per domain. + int delaySeconds = _config.DcvPropagationDelaySeconds > 0 ? _config.DcvPropagationDelaySeconds : 30; + _logger.LogInformation( + "Waiting {Delay}s for DNS propagation before V2 DCV verify. OrderId={OrderId}, DomainCount={Count}", + delaySeconds, orderId, verifyCandidates.Count); + await Task.Delay(TimeSpan.FromSeconds(delaySeconds), ct); + + // Phase 2: verify each domain that got through staging individually — the + // spec's Verify DCV body takes a single `domain`, mirroring Get DCV + // Challenges' per-domain shape. + // NOTE (unverified): per-SAN semantics have not been confirmed against the + // live API end-to-end. This includes hostname-sharing siblings + // (verifyCandidates), not just the domains that staged a fresh TXT record + // (staged) — CERTInext tracks DCV per domain entry even when two domains + // share one TXT record. + foreach (var d in verifyCandidates) + { + try + { + _logger.LogInformation( + "Triggering V2 DCV verification. OrderId={OrderId}, Domain={Domain}", + orderId, LogSanitizer.Strip(d)); + var verifyResp = await _client.VerifyDcvV2Async(orderId, d, productFamilySlug, ct); + _logger.LogInformation( + "V2 DCV verify response. OrderId={OrderId}, Domain={Domain}, OverallStatus={Status}", + orderId, LogSanitizer.Strip(d), verifyResp?.OverallStatus ?? "(null)"); + + if (string.Equals(verifyResp?.OverallStatus, "VERIFIED", StringComparison.OrdinalIgnoreCase)) + { + verifiedDomains.Add(d); + } + else + { + _logger.LogWarning( + "V2 DCV verify did not return VERIFIED for domain {Domain} on order {OrderId}. " + + "Status={Status}", LogSanitizer.Strip(d), orderId, verifyResp?.OverallStatus); + failedDomains.Add((d, $"verify returned {verifyResp?.OverallStatus ?? "(null)"}")); + } + } + catch (Exception ex) when (IsEms1080DomainAlreadyVerified(ex)) + { + // Same no-op as the GetDcv branch above, but surfaced at Verify time + // instead — the domain became/was already verified between the two + // calls. Treat as verified rather than deferring. + _logger.LogInformation( + "V2 DCV already satisfied (EMS-1080) for domain {Domain} on order {OrderId} " + + "during VerifyDcv; treating as verified.", LogSanitizer.Strip(d), orderId); + verifiedDomains.Add(d); + } + catch (OperationCanceledException) + { + throw; + } + catch (Exception ex) + { + _logger.LogError(ex, + "V2 DCV verify failed for domain {Domain} on order {OrderId}; skipping this " + + "domain so the rest of the order can still be validated.", + LogSanitizer.Strip(d), orderId); + failedDomains.Add((d, "verify failed")); + } + } - try - { - await Task.Delay(TimeSpan.FromSeconds(challengePollSeconds), ct); + // Phase 3: poll Track Order until every domain just verified this pass is + // confirmed there too, before cleanup — mirrors the V1 rationale + // (WaitForDcvVerificationAsync): VerifyDcv's synchronous response may not yet + // be reflected by the CA's own async DNS lookup. + var stagedDomainNames = new HashSet( + verifyCandidates, StringComparer.OrdinalIgnoreCase); + var justVerifiedStaged = verifiedDomains + .Where(d => stagedDomainNames.Contains(d)) + .ToList(); + if (justVerifiedStaged.Count > 0) + { + await WaitForDomainsVerifiedV2Async(orderId, productFamilySlug, justVerifiedStaged, ct); + } } - catch (OperationCanceledException) + finally { - return false; + await CleanupStagedAsync(); } } - // If DCV is already validated CERTInext-side, the plugin has no DCV work to - // do — but CERTInext's certificate generation may still be in flight (this - // happens when CERTInext has cached a prior DCV validation for the parent - // domain). Return true so the caller can run the issuance poll and pick up - // the cert directly from Enroll() instead of leaving it for the next sync. - // - // Treat "DCV done" as EITHER the overall aggregate Status flipping to "1" - // OR every individual per-domain dcvStatus being "1" — observed in the wild - // that the per-domain field can flip before the parent aggregate. - var allDomainEntries = domainVerification.GetDomainEntries(); - bool aggregateValidated = string.Equals( - domainVerification.Status, Constants.Dcv.StatusValidated, StringComparison.Ordinal); - bool everyDomainValidated = allDomainEntries.Count > 0 - && allDomainEntries.All(kvp => string.Equals( - kvp.Value?.DcvStatus, Constants.Dcv.StatusValidated, StringComparison.Ordinal)); - if (aggregateValidated || everyDomainValidated) + if (failedDomains.Count > 0) { - _logger.LogInformation( - "DCV is already validated for order {OrderNumber} " + - "(aggregateStatus={Aggregate}, perDomainAllValidated={PerDomain}). " + - "Skipping DNS-TXT staging; caller may run the issuance poll.", - orderNumber, aggregateValidated, everyDomainValidated); - return true; + _logger.LogError( + "{FailedCount} domain(s) on V2 order {OrderId} could not be validated this pass and " + + "were skipped: [{Domains}]. The order remains pending; a later sync/GetSingleRecord " + + "retries only the still-unverified domains.", + failedDomains.Count, orderId, + LogSanitizer.Strip(string.Join(", ", failedDomains.Select(f => $"{f.domain} ({f.reason})")))); } - // Include domains that are pending DCV and either have no method set yet, - // or are already assigned to DNS TXT (numeric "1" from API or label from TrackOrder). - // Domains assigned to HTTP or email DCV are excluded — we must not override them. - var pendingDomains = domainVerification.GetDomainEntries() - .Where(kvp => - { - if (!string.Equals(kvp.Value?.DcvStatus, Constants.Dcv.StatusPending, StringComparison.Ordinal)) - return false; - string method = kvp.Value?.DcvMethod ?? string.Empty; - return string.IsNullOrEmpty(method) - || string.Equals(method, Constants.Dcv.MethodDnsTxt, StringComparison.Ordinal) - || string.Equals(method, Constants.Dcv.MethodDnsTxtLabel, StringComparison.OrdinalIgnoreCase); - }) - .ToList(); + _logger.LogInformation( + "V2 DCV (multi-domain) summary. OrderId={OrderId}, PendingCount={Pending}, VerifiedCount={Verified}, FailedCount={Failed}", + orderId, pendingDomains.Count, verifiedDomains.Count, failedDomains.Count); - // SOX CC6.1: validate domain names before passing them to the DNS provider plugin - // or the CERTInext API. A malformed domain (empty, whitespace, or containing - // characters outside the FQDN alphabet) could cause log injection or unexpected - // DNS plugin behaviour. Invalid entries are rejected loudly rather than silently - // skipped so the condition is visible in the audit trail. - foreach (var (domain, _) in pendingDomains) - { - if (string.IsNullOrWhiteSpace(domain)) - throw new InvalidOperationException( - $"TrackOrder returned a blank domain key in domainVerification for order '{orderNumber}'. " + - "Cannot proceed with DCV."); + return true; + } - // Allow standard FQDN characters plus wildcard prefix (*.example.com) - if (!System.Text.RegularExpressions.Regex.IsMatch(domain, @"^(\*\.)?[a-zA-Z0-9]([a-zA-Z0-9\-\.]*[a-zA-Z0-9])?$")) - { - _logger.LogError( - "DCV domain name failed validation and will not be processed. OrderNumber={OrderNumber}, Domain={Domain}", - orderNumber, domain); - throw new InvalidOperationException( - $"TrackOrder returned an invalid domain name '{domain}' in domainVerification for order '{orderNumber}'. " + - "Domain names must conform to FQDN syntax."); - } + /// + /// Removes one already-published V2 DCV TXT record. Shared cleanup logic for + /// 's staged-domain list — mirrors the + /// single-domain V2 path's own inline cleanup (and V1's + /// CleanupOneStagedValidationAsync) in both bound and best-effort behavior: a + /// fresh, independently-bounded token (neither the ambient ct nor + /// ) so a stuck DNS provider cannot hang this + /// best-effort compensating action indefinitely, regardless of why cleanup was + /// triggered. + /// + private async Task CleanupOneV2StagedRecordAsync( + string orderId, + (string domain, string hostname, Keyfactor.AnyGateway.Extensions.IDomainValidator validator) entry) + { + var (domain, hostname, validator) = entry; + try + { + using var cleanupCts = new CancellationTokenSource( + TimeSpan.FromSeconds(Constants.Dcv.CleanupValidationTimeoutSeconds)); + await validator.CleanupValidation(hostname, cleanupCts.Token); + _logger.LogInformation( + "V2 DCV: DNS TXT record cleaned up. OrderId={OrderId}, Domain={Domain}, Hostname={Hostname}", + orderId, LogSanitizer.Strip(domain), LogSanitizer.Strip(hostname)); + } + catch (Exception ex) + { + _logger.LogWarning(ex, + "V2 DCV: Failed to clean up DNS TXT record. OrderId={OrderId}, Domain={Domain}, " + + "Hostname={Hostname}. May require manual removal.", + orderId, LogSanitizer.Strip(domain), LogSanitizer.Strip(hostname)); } + } - if (pendingDomains.Count == 0) - return false; + /// + /// Polls until every domain in + /// reaches a VERIFIED dcvStatus in + /// verifications.domain.domains[], reaches REJECTED (terminal — seen + /// after an order cancellation), or is cancelled / + /// the internal deadline elapses. V2 analogue of . + /// + private async Task WaitForDomainsVerifiedV2Async( + string orderId, string productFamilySlug, IReadOnlyList domains, CancellationToken ct) + { + if (domains.Count == 0) return; - _logger.LogInformation( - "DCV required for order {OrderNumber}. Pending DNS TXT domains: [{Domains}]", - orderNumber, string.Join(", ", pendingDomains.Select(x => x.Key))); + var pending = new HashSet(domains, StringComparer.OrdinalIgnoreCase); + // Fixed short cadence — decoupled from DcvPropagationDelaySeconds (a one-shot DNS + // wait), not a poll interval. + int pollSeconds = Constants.Dcv.SyncPropagationDelaySeconds; - var stagedValidations = new List<(string domain, string hostname, Keyfactor.AnyGateway.Extensions.IDomainValidator validator)>(); + // Defense-in-depth deadline, same rationale as WaitForDcvVerificationAsync: bounded + // even if a future refactor breaks the cancellation chain. + var deadline = DateTime.UtcNow.AddMinutes(_config.GetEffectiveDcvTimeoutMinutes()); - // Stage DNS TXT records for all pending domains - foreach (var (domain, _) in pendingDomains) + while (pending.Count > 0 && !ct.IsCancellationRequested) { - GetDcvResponse dcvResp; + if (DateTime.UtcNow >= deadline) + { + _logger.LogWarning( + "V2 DCV verification poll exceeded its internal deadline ({Minutes}min). " + + "OrderId={OrderId}, StillPendingDomains=[{Pending}]. Exiting and leaving TXT " + + "records for the caller's cleanup.", + _config.GetEffectiveDcvTimeoutMinutes(), orderId, + LogSanitizer.Strip(string.Join(",", pending))); + return; + } + try { - dcvResp = await _client.GetDcvAsync(orderNumber, domain, Constants.Dcv.MethodDnsTxt, ct); + await Task.Delay(TimeSpan.FromSeconds(pollSeconds), ct); } - catch (Exception ex) when (IsDcvNotYetReady(ex)) + catch (OperationCanceledException) { - // CERTInext occasionally exposes the DCV slot in TrackOrder (so - // domainVerification is populated and dcvStatus="0") before the GetDcv - // endpoint will accept calls for that order — observed as EMS-956 - // "Invalid Request for this API" for several hours after enrollment. - // Treat this as "DCV not ready yet": skip the DCV ceremony for now and - // let the sync-driven retry pick it up on a later cycle. We must NOT - // throw, because that would fail the entire Enroll call and prevent the - // gateway from recording the pending order at all. - _logger.LogInformation( - "GetDcv not yet accepting calls for order {OrderNumber} domain {Domain} ({Error}). " + - "Deferring DCV to the next sync cycle.", - orderNumber, domain, ex.Message); - return false; + return; + } + + V2OrderStatusResponse poll; + try + { + poll = await _client.TrackOrderV2Async(productFamilySlug, orderId, ct); } catch (Exception ex) { - _logger.LogError(ex, "GetDcv failed for order {OrderNumber} domain {Domain}", orderNumber, domain); - throw; + _logger.LogWarning(ex, + "V2 TrackOrder polling failed during DCV wait. OrderId={OrderId}", orderId); + return; } - string token = dcvResp.DcvDetails?.Token; - if (string.IsNullOrWhiteSpace(token)) - throw new InvalidOperationException( - $"GetDcv returned no token for order '{orderNumber}' domain '{domain}'."); - - string template = string.IsNullOrWhiteSpace(_config.DcvTxtRecordTemplate) - ? Constants.Dcv.DefaultTxtRecordTemplate - : _config.DcvTxtRecordTemplate; - string hostname = string.Format(template, domain); - - var validator = DomainValidatorFactory.ResolveDomainValidator(domain, "dns-01"); - if (validator == null) - throw new InvalidOperationException( - $"No DNS provider plugin is configured for domain '{domain}'. " + - "Ensure the appropriate DNS provider plugin is deployed and configured on the gateway."); - - _logger.LogInformation( - "Staging DNS TXT record for DCV. OrderNumber={OrderNumber}, Domain={Domain}, Hostname={Hostname}", - orderNumber, domain, hostname); - - var stageResult = await validator.StageValidation(hostname, token, ct); - if (!stageResult.Success) - throw new InvalidOperationException( - $"Failed to stage DNS validation for '{domain}': {stageResult.ErrorMessage}"); - - stagedValidations.Add((domain, hostname, validator)); - } - - if (stagedValidations.Count == 0) - return false; - - try - { - // Allow DNS propagation before asking CERTInext to verify. The sync path passes - // a short override (issue 0002) so a bounded set of recent pending orders doesn't - // each burn the full configured delay; Enroll uses the full configured value. - int delaySeconds = propagationDelaySecondsOverride - ?? (_config.DcvPropagationDelaySeconds > 0 ? _config.DcvPropagationDelaySeconds : 30); - _logger.LogInformation( - "Waiting {Delay}s for DNS propagation before verifying DCV. OrderNumber={OrderNumber}", - delaySeconds, orderNumber); - await Task.Delay(TimeSpan.FromSeconds(delaySeconds), ct); + var entries = poll.Verifications?.Domain?.Domains; + if (entries == null) continue; - foreach (var (domain, hostname, _) in stagedValidations) + foreach (var entry in entries) { - _logger.LogInformation( - "Triggering CERTInext DCV verification. OrderNumber={OrderNumber}, Domain={Domain}", orderNumber, domain); - await _client.VerifyDcvAsync(orderNumber, domain, Constants.Dcv.MethodDnsTxt, ct); - } + if (entry?.Domain == null || !pending.Contains(entry.Domain)) continue; - // Poll TrackOrder until CERTInext confirms all staged domains are verified - // before removing TXT records — VerifyDcv triggers an async DNS lookup on - // their side, so cleanup must wait for dcvStatus=1 on every domain. - await WaitForDcvVerificationAsync(orderNumber, stagedValidations.Select(s => s.domain).ToList(), ct); - } - finally - { - // Always clean up staged DNS records — even on failure - foreach (var (domain, hostname, validator) in stagedValidations) - { - try + if (string.Equals(entry.DcvStatus, Constants.ApiV2.DcvStatusVerified, StringComparison.OrdinalIgnoreCase)) { - await validator.CleanupValidation(hostname, ct); _logger.LogInformation( - "DNS TXT record cleaned up. Domain={Domain}, Hostname={Hostname}", domain, hostname); + "V2 DCV verified by CERTInext. OrderId={OrderId}, Domain={Domain}", + orderId, LogSanitizer.Strip(entry.Domain)); + pending.Remove(entry.Domain); } - catch (Exception ex) + else if (string.Equals(entry.DcvStatus, Constants.ApiV2.DcvStatusRejected, StringComparison.OrdinalIgnoreCase)) { - _logger.LogWarning(ex, - "Failed to clean up DNS TXT record. Domain={Domain}, Hostname={Hostname}", domain, hostname); + _logger.LogWarning( + "V2 DCV rejected by CERTInext. OrderId={OrderId}, Domain={Domain}", + orderId, LogSanitizer.Strip(entry.Domain)); + pending.Remove(entry.Domain); } } } - - return true; } #endif @@ -1782,90 +6010,550 @@ private async Task WaitForIssuanceAfterDcvAsync( return last; } - try - { - await Task.Delay(TimeSpan.FromSeconds(pollIntervalSeconds), ct); - } - catch (OperationCanceledException) - { - return last; + try + { + await Task.Delay(TimeSpan.FromSeconds(pollIntervalSeconds), ct); + } + catch (OperationCanceledException) + { + return last; + } + } + } + + /// + /// Polls until every domain in + /// reaches dcvStatus=1 (verified) or a terminal + /// failure state (rejected/cancelled), or is cancelled. + /// Called after VerifyDcvAsync to ensure CERTInext has completed its async + /// DNS lookup before TXT records are cleaned up. + /// + private async Task WaitForDcvVerificationAsync(string orderNumber, IReadOnlyList domains, CancellationToken ct) + { + if (domains.Count == 0) return; + + var pending = new HashSet(domains, StringComparer.OrdinalIgnoreCase); + // Fixed short cadence — decoupled from DcvPropagationDelaySeconds, which is a + // one-shot DNS propagation wait, not a polling interval. Reusing it here would + // reduce the number of polls to ~2 before the 5-minute timeout. + int pollSeconds = Constants.Dcv.SyncPropagationDelaySeconds; + + // Defense-in-depth deadline: SOX CC7.3 requires every wait to be bounded. + // The caller passes a `ct` derived from a CancellationTokenSource that already + // cancels after `DcvTimeoutMinutes`, so this method is bounded via that path. + // We add an explicit internal deadline so a future refactor breaking the + // cancellation chain (e.g. accidentally passing CancellationToken.None) can't + // make this loop unbounded — it would still exit on the deadline below. + var verificationDeadline = DateTime.UtcNow.AddMinutes(_config.GetEffectiveDcvTimeoutMinutes()); + + while (pending.Count > 0 && !ct.IsCancellationRequested) + { + if (DateTime.UtcNow >= verificationDeadline) + { + _logger.LogWarning( + "DCV verification poll exceeded its internal deadline ({Minutes}min). " + + "OrderNumber={OrderNumber}, StillPendingDomains=[{Pending}]. " + + "Exiting and leaving TXT records for the caller's finally block to clean up.", + _config.GetEffectiveDcvTimeoutMinutes(), orderNumber, + LogSanitizer.Strip(string.Join(",", pending))); + return; + } + + await Task.Delay(TimeSpan.FromSeconds(pollSeconds), ct); + + TrackOrderResponse poll; + try { poll = await _client.TrackOrderAsync(orderNumber, ct); } + catch (Exception ex) + { + _logger.LogWarning(ex, "TrackOrder polling failed during DCV wait. OrderNumber={OrderNumber}", orderNumber); + return; + } + + var entries = poll.OrderDetails?.DomainVerification?.GetDomainEntries() + ?? new Dictionary(); + + // Check for order-level terminal failure (cancelled/rejected) + if (poll.OrderDetails?.OrderStatusId is "4" or "5") + { + _logger.LogWarning( + "Order {OrderNumber} reached terminal failure state (OrderStatusId={Status}) during DCV wait. TXT records will be cleaned up.", + orderNumber, poll.OrderDetails.OrderStatusId); + return; + } + + foreach (var domain in domains) + { + if (!pending.Contains(domain)) continue; + if (!entries.TryGetValue(domain, out var detail)) continue; + + if (string.Equals(detail.DcvStatus, Constants.Dcv.StatusValidated, StringComparison.Ordinal)) + { + _logger.LogInformation("DCV verified by CERTInext. OrderNumber={OrderNumber}, Domain={Domain}", + orderNumber, LogSanitizer.Strip(domain)); + pending.Remove(domain); + } + else if (string.Equals(detail.DcvStatus, Constants.Dcv.StatusRejected, StringComparison.Ordinal)) + { + _logger.LogWarning("DCV rejected by CERTInext. OrderNumber={OrderNumber}, Domain={Domain}", + orderNumber, LogSanitizer.Strip(domain)); + pending.Remove(domain); + } + } + } + } + + /// + /// Synchronous certificate pickup — parity with the legacy Sectigo connector's + /// PickUpEnrolledCertificate. After an order is submitted, polls + /// GetCertificate up to PickupRetries times, PickupDelay seconds + /// apart (after a fixed initial delay), so an order that issues quickly is returned + /// GENERATED + PEM in the same enrollment call instead of waiting for the next + /// synchronization. If the certificate has not issued within the budget, the original + /// pending result is returned unchanged and the order is imported by a later sync. + /// + /// Applies to ALL products. CERTInext issues OV/EV asynchronously (organization + /// verification, minutes to hours; per CERTInext support), so + /// those typically exhaust the budget and fall back to pending; only DV / already-approved + /// orders return in-call. Never throws — any polling error degrades to the pending result. + /// + private async Task PickUpEnrolledCertificateAsync( + EnrollmentResult pendingResult, string orderNumber, bool dcvIssuanceWaitRan, + CancellationToken ct = default) + { + // The DCV path already owns the in-call issuance wait for this order — running a second + // stacked poll here would double the wait budget (when DCV ran WaitForIssuanceAfterDcvAsync) + // or waste it polling an order DCV already found terminal / not-yet-validated. Defer to + // the pending result; a later sync completes it. + if (dcvIssuanceWaitRan) + return pendingResult; + + // Only a still-pending (external-validation) result can benefit from a pickup poll. + // An already issued/failed/revoked result is returned as-is. + if (pendingResult == null + || pendingResult.Status != (int)EndEntityStatus.EXTERNALVALIDATION) + return pendingResult; + + // A pending result with no order number cannot be polled — surface the anomaly rather + // than silently returning, so an un-pollable pending state leaves an audit trace. + if (string.IsNullOrWhiteSpace(orderNumber)) + { + _logger.LogWarning( + "Synchronous pickup skipped: a pending enrollment was returned with no order " + + "number to poll. The certificate can only be reconciled by a later synchronization."); + return pendingResult; + } + + int retries = _config.GetEffectivePickupRetries(); + if (retries <= 0) + { + _logger.LogInformation( + "Synchronous certificate pickup disabled (PickupRetries<=0). Order {OrderNumber} " + + "will be picked up on the next synchronization.", orderNumber); + return pendingResult; + } + + int delaySeconds = _config.GetEffectivePickupDelaySeconds(); + + // Hard ceiling on total in-call occupancy. PickupRetries and PickupDelay are each clamped + // independently, but their product can still reach ~30 min at the extremes — enough to push + // Enroll() past Command's own enrollment timeout. If the configured budget would exceed the + // ceiling, cap the retry count to fit; the remainder is imported by the next synchronization. + int maxPollRetries = ComputeMaxPollRetries(delaySeconds); + if (retries > maxPollRetries) + { + _logger.LogInformation( + "Configured pickup budget (PickupRetries={Configured}, PickupDelaySeconds={Delay}) exceeds the " + + "{MaxTotal}s in-call ceiling; capping to {Capped} attempts. The certificate will be imported by " + + "the next synchronization if it has not issued by then.", + retries, delaySeconds, Constants.Pickup.MaxTotalWaitSeconds, maxPollRetries); + retries = maxPollRetries; + } + + _logger.LogInformation( + "Starting synchronous certificate pickup. OrderNumber={OrderNumber}, PickupRetries={Retries}, " + + "PickupDelaySeconds={Delay} (max ~{Max}s including a {Initial}s initial delay).", + orderNumber, retries, delaySeconds, + Constants.Pickup.InitialDelaySeconds + retries * delaySeconds, Constants.Pickup.InitialDelaySeconds); + + int pollErrors = 0; + try + { + // Small static delay before the first poll — mirrors the Sectigo connector's + // attempt to let a fast order finish issuing before we start polling at all. + await Task.Delay(TimeSpan.FromSeconds(Constants.Pickup.InitialDelaySeconds), ct); + + for (int attempt = 1; attempt <= retries; attempt++) + { + try + { + var cert = await _client.GetCertificateAsync(orderNumber, ct); + int disposition = StatusMapper.ToRequestDisposition(cert.Status); + + // SOC2 CC7.3: record each poll's observed disposition so the issuance + // timeline is reconstructable (how many polls ran, what each returned). + _logger.LogDebug( + "Pickup poll observed status. OrderNumber={OrderNumber}, Attempt={Attempt}/{Retries}, " + + "MappedDisposition={Disposition}, Status='{Status}', BodyPresent={HasBody}.", + orderNumber, attempt, retries, disposition, cert.Status, + !string.IsNullOrWhiteSpace(cert.Certificate)); + + // Issued: only surface GENERATED when the PEM is actually present — never + // hand Command a body-less "issued" record. A body-less issued state keeps + // polling until the body appears or the budget runs out. + if (disposition == (int)EndEntityStatus.GENERATED + && !string.IsNullOrWhiteSpace(cert.Certificate)) + { + _logger.LogInformation( + "Synchronous pickup complete. OrderNumber={OrderNumber}, SerialNumber={Serial}, " + + "Attempt={Attempt}/{Retries}.", + orderNumber, + string.IsNullOrWhiteSpace(cert.SerialNumber) ? "(not provided by CA)" : cert.SerialNumber, + attempt, retries); + return new EnrollmentResult + { + CARequestID = string.IsNullOrWhiteSpace(cert.Id) ? orderNumber : cert.Id, + Certificate = cert.Certificate, + Status = (int)EndEntityStatus.GENERATED, + StatusMessage = $"Certificate issued successfully. CERTInext ID: {orderNumber}." + }; + } + + // Terminal non-issued outcomes carry no body and are surfaced immediately. + if (disposition == (int)EndEntityStatus.REVOKED + || disposition == (int)EndEntityStatus.FAILED) + { + // SOX/SOC2 CC7.2: an issuance FAILURE must cross the error threshold that + // SIEM issuance-failure rules key on (parity with BuildEnrollmentResult's + // enroll-time FAILED handling); a REVOKED terminal state is a warning. + if (disposition == (int)EndEntityStatus.FAILED) + _logger.LogError( + "Order {OrderNumber} reached terminal FAILED status '{Status}' during " + + "synchronous pickup (attempt {Attempt}/{Retries}).", + orderNumber, cert.Status, attempt, retries); + else + _logger.LogWarning( + "Order {OrderNumber} was REVOKED ('{Status}') during synchronous pickup " + + "(attempt {Attempt}/{Retries}).", + orderNumber, cert.Status, attempt, retries); + return new EnrollmentResult + { + CARequestID = string.IsNullOrWhiteSpace(cert.Id) ? orderNumber : cert.Id, + Certificate = cert.Certificate, + Status = disposition, + StatusMessage = $"Order {orderNumber} reached status '{cert.Status}' during enrollment pickup." + }; + } + } + catch (Exception ex) + { + if (ex is OperationCanceledException) throw; + // A transient fetch failure consumes an attempt rather than aborting the + // wait; if it never recovers the pending result is returned below. + pollErrors++; + _logger.LogWarning(ex, + "Pickup GetCertificate failed for order {OrderNumber} (attempt {Attempt}/{Retries}).", + orderNumber, attempt, retries); + } + + // Delay after every attempt (including the last), matching the Sectigo + // connector's pickup cadence so the max-occupancy ceiling is identical. + await Task.Delay(TimeSpan.FromSeconds(delaySeconds), ct); } + + // SOC1 accuracy: don't attribute non-completion to "OV/EV async by design" when the + // real cause was every poll erroring (e.g. a CA-side TrackOrder outage). Distinguish + // the two so the log reflects what actually happened. + if (pollErrors == retries) + _logger.LogWarning( + "Synchronous pickup exhausted {Retries} attempts for order {OrderNumber} — ALL polls " + + "errored (see preceding warnings). Returning pending result; the next synchronization " + + "will re-attempt retrieval.", + retries, orderNumber); + else + _logger.LogInformation( + "Synchronous pickup did not complete within {Retries} attempts for order {OrderNumber} " + + "({Errors} poll error(s); remainder still pending). Returning pending result; the " + + "certificate will be imported by the next synchronization. CERTInext issues OV/EV " + + "asynchronously by design.", + retries, orderNumber, pollErrors); + pendingResult.StatusMessage = + $"{pendingResult.StatusMessage} The certificate was not issued within the enrollment-pickup " + + "window; it will be imported by a later synchronization."; + } + catch (Exception ex) + { + _logger.LogWarning(ex, + "Synchronous pickup failed for order {OrderNumber}. Returning pending result; " + + "sync will pick up the certificate later.", orderNumber); } + + return pendingResult; } /// - /// Polls until every domain in - /// reaches dcvStatus=1 (verified) or a terminal - /// failure state (rejected/cancelled), or is cancelled. - /// Called after VerifyDcvAsync to ensure CERTInext has completed its async - /// DNS lookup before TXT records are cleaned up. + /// Computes the maximum number of pickup poll attempts that fit inside + /// , given the fixed initial delay and a + /// per-attempt delay. Shared by the V1 and V2 pickup paths and kept as a pure, synchronous + /// function so the ceiling clamp can be unit-tested without waiting out real + /// Task.Delay calls. /// - private async Task WaitForDcvVerificationAsync(string orderNumber, IReadOnlyList domains, CancellationToken ct) + internal static int ComputeMaxPollRetries(int delaySeconds) => + Math.Max(1, + (Constants.Pickup.MaxTotalWaitSeconds - Constants.Pickup.InitialDelaySeconds) / delaySeconds); + + /// + /// Synchronous certificate pickup for the V2 API — parity with + /// above: without this poll, a DV order + /// that CERTInext issues within seconds of CSR submission would only ever reach Command + /// via a gateway sync plus a Command full scan. After a V2 + /// order is created and its CSR submitted, polls + /// up to PickupRetries times, PickupDelay seconds apart (after the same + /// fixed initial delay), so a fast-issuing order is returned GENERATED + PEM in this same + /// enrollment call instead of waiting for the next synchronization. Reuses the identical + /// config knobs and wait-budget ceiling as the V1 method (Constants.Pickup, + /// GetEffectivePickupRetries, GetEffectivePickupDelaySeconds) so the two + /// behave identically from an operator's perspective. Never throws — any polling error + /// degrades to the pending result. + /// + /// Also returns the freshest raw CA status string observed while producing the result + /// (falling back to when no fresher poll ran), so + /// 's terminal REVOKED-to-FAILED + /// normalization can log/report the CA's own status text, not just Command's mapped + /// disposition. Note: a REVOKED result reaching that normalization is never "surfaced + /// immediately" as REVOKED — see NormalizeV2RevokedEnrollResult. + /// + private async Task<(EnrollmentResult Result, string RawCaStatus)> PickUpEnrolledCertificateV2Async( + EnrollmentResult pendingResult, string orderId, string productFamilySlug, + bool dcvV2Ran, string lastKnownCaStatus, CancellationToken ct = default, + V2AgreementAcceptContext agreementContext = null) { - if (domains.Count == 0) return; + // The inline V2 DCV path already owns the in-call issuance wait for this order — + // running a second stacked poll here would double the wait budget (when + // PerformDcvV2IfNeededAsync ran its own tracking poll) or waste it re-polling an + // order DCV already left mid-flight. Defer to the pending result; a later sync + // completes it. Mirrors dcvIssuanceWaitRan's role in the V1 method above. + if (dcvV2Ran) + return (pendingResult, lastKnownCaStatus); + + // Only a still-pending (external-validation) result can benefit from a pickup poll. + // An already issued/failed/revoked result is returned unpolled — the caller's own + // terminal normalization (NormalizeV2RevokedEnrollResult) decides what a REVOKED + // disposition here ultimately becomes; this method does not surface it as-is. + if (pendingResult == null + || pendingResult.Status != (int)EndEntityStatus.EXTERNALVALIDATION) + return (pendingResult, lastKnownCaStatus); + + // A pending result with no order id cannot be polled — surface the anomaly rather + // than silently returning, so an un-pollable pending state leaves an audit trace. + if (string.IsNullOrWhiteSpace(orderId)) + { + _logger.LogWarning( + "V2 synchronous pickup skipped: a pending enrollment was returned with no order " + + "id to poll. The certificate can only be reconciled by a later synchronization."); + return (pendingResult, lastKnownCaStatus); + } - var pending = new HashSet(domains, StringComparer.OrdinalIgnoreCase); - int pollSeconds = Math.Max(1, _config.DcvPropagationDelaySeconds); + int retries = _config.GetEffectivePickupRetries(); + if (retries <= 0) + { + _logger.LogInformation( + "V2 synchronous certificate pickup disabled (PickupRetries<=0). Order {OrderId} " + + "will be picked up on the next synchronization.", orderId); + return (pendingResult, lastKnownCaStatus); + } - // Defense-in-depth deadline: SOX CC7.3 requires every wait to be bounded. - // The caller passes a `ct` derived from a CancellationTokenSource that already - // cancels after `DcvTimeoutMinutes`, so this method is bounded via that path. - // We add an explicit internal deadline so a future refactor breaking the - // cancellation chain (e.g. accidentally passing CancellationToken.None) can't - // make this loop unbounded — it would still exit on the deadline below. - var verificationDeadline = DateTime.UtcNow.AddMinutes(_config.GetEffectiveDcvTimeoutMinutes()); + int delaySeconds = _config.GetEffectivePickupDelaySeconds(); - while (pending.Count > 0 && !ct.IsCancellationRequested) + // Hard ceiling on total in-call occupancy — identical rationale to the V1 method: + // PickupRetries and PickupDelay are each clamped independently, but their product can + // still reach ~30 min at the extremes. Cap the retry count to fit; the remainder is + // imported by the next synchronization. + int maxPollRetries = ComputeMaxPollRetries(delaySeconds); + if (retries > maxPollRetries) { - if (DateTime.UtcNow >= verificationDeadline) - { - _logger.LogWarning( - "DCV verification poll exceeded its internal deadline ({Minutes}min). " + - "OrderNumber={OrderNumber}, StillPendingDomains=[{Pending}]. " + - "Exiting and leaving TXT records for the caller's finally block to clean up.", - _config.GetEffectiveDcvTimeoutMinutes(), orderNumber, string.Join(",", pending)); - return; - } + _logger.LogInformation( + "Configured pickup budget (PickupRetries={Configured}, PickupDelaySeconds={Delay}) exceeds the " + + "{MaxTotal}s in-call ceiling; capping to {Capped} attempts. The certificate will be imported by " + + "the next synchronization if it has not issued by then.", + retries, delaySeconds, Constants.Pickup.MaxTotalWaitSeconds, maxPollRetries); + retries = maxPollRetries; + } - await Task.Delay(TimeSpan.FromSeconds(pollSeconds), ct); + _logger.LogInformation( + "Starting V2 synchronous certificate pickup. OrderId={OrderId}, PickupRetries={Retries}, " + + "PickupDelaySeconds={Delay} (max ~{Max}s including a {Initial}s initial delay).", + orderId, retries, delaySeconds, + Constants.Pickup.InitialDelaySeconds + retries * delaySeconds, Constants.Pickup.InitialDelaySeconds); + + int pollErrors = 0; + // Attempts where the order was `issued` but Download Certificate answered 422 EMS-1165 + // ("issued at the CA, certificate not generated yet"). Logged per attempt at Debug and + // summarized once at Info below — not a Warning per attempt, and not a poll error. + int notGeneratedYet = 0; + string lastStates = null; + try + { + // Small static delay before the first poll — mirrors the V1 method's attempt to + // let a fast order finish issuing before we start polling at all. + await Task.Delay(TimeSpan.FromSeconds(Constants.Pickup.InitialDelaySeconds), ct); - TrackOrderResponse poll; - try { poll = await _client.TrackOrderAsync(orderNumber, ct); } - catch (Exception ex) + for (int attempt = 1; attempt <= retries; attempt++) { - _logger.LogWarning(ex, "TrackOrder polling failed during DCV wait. OrderNumber={OrderNumber}", orderNumber); - return; - } + try + { + var tracked = await _client.TrackOrderV2Async(productFamilySlug, orderId, ct); + int disposition = StatusMapper.V2StatusToRequestDisposition(tracked.Status); + lastKnownCaStatus = tracked.Status; - var entries = poll.OrderDetails?.DomainVerification?.GetDomainEntries() - ?? new Dictionary(); + // SOC2 CC7.3: record each poll's observed disposition so the issuance + // timeline is reconstructable (how many polls ran, what each returned). + _logger.LogDebug( + "V2 pickup poll observed status. OrderId={OrderId}, Attempt={Attempt}/{Retries}, " + + "MappedDisposition={Disposition}, Status='{Status}'.", + orderId, attempt, retries, disposition, tracked.Status); - // Check for order-level terminal failure (cancelled/rejected) - if (poll.OrderDetails?.OrderStatusId is "4" or "5") - { - _logger.LogWarning( - "Order {OrderNumber} reached terminal failure state (OrderStatusId={Status}) during DCV wait. TXT records will be cleaned up.", - orderNumber, poll.OrderDetails.OrderStatusId); - return; - } + // An order that reaches pending-agreement mid-poll gets the (at most one) + // acceptance call; the poll then simply continues. + await TryAcceptV2AgreementAsync(tracked, productFamilySlug, orderId, agreementContext, ct); - foreach (var domain in domains) - { - if (!pending.Contains(domain)) continue; - if (!entries.TryGetValue(domain, out var detail)) continue; + if (disposition == (int)EndEntityStatus.GENERATED) + { + // Issued: only surface GENERATED when the certificate body actually + // downloads — never hand Command a body-less "issued" record. A failed + // or empty download keeps polling until the body appears or the budget + // runs out, same invariant the V1 method already enforces. + try + { + var certResp = await _client.DownloadCertificateV2Async(productFamilySlug, orderId, ct); + string fullChain = AssembleV2CertChain(certResp); - if (string.Equals(detail.DcvStatus, Constants.Dcv.StatusValidated, StringComparison.Ordinal)) - { - _logger.LogInformation("DCV verified by CERTInext. OrderNumber={OrderNumber}, Domain={Domain}", orderNumber, domain); - pending.Remove(domain); + if (!string.IsNullOrWhiteSpace(fullChain)) + { + _logger.LogInformation( + "V2 synchronous pickup complete. OrderId={OrderId}, SerialNumber={Serial}, " + + "Attempt={Attempt}/{Retries}.", + orderId, + string.IsNullOrWhiteSpace(certResp.SerialNumber) ? "(not provided by CA)" : certResp.SerialNumber, + attempt, retries); + return (new EnrollmentResult + { + CARequestID = orderId, + Certificate = fullChain, + Status = (int)EndEntityStatus.GENERATED, + StatusMessage = "Certificate issued via V2 API." + }, lastKnownCaStatus); + } + + _logger.LogDebug( + "V2 pickup poll: order {OrderId} reports issued but returned no certificate " + + "body yet (attempt {Attempt}/{Retries}); continuing to poll.", + orderId, attempt, retries); + } + catch (Exception dlEx) + { + if (IsCertificateNotGeneratedYet(dlEx)) + { + // Issued at the CA, certificate not generated yet: keep polling + // (normal generation takes ~20 s), quietly. + notGeneratedYet++; + lastStates = DescribeV2States(tracked); + _logger.LogDebug( + "V2 pickup: order {OrderId} is issued at CERTInext but its certificate is not " + + "generated yet (Download Certificate 422 EMS-1165; attempt {Attempt}/{Retries}). {States}", + orderId, attempt, retries, lastStates); + } + else + { + // Issued but the download itself failed — consume the attempt and + // keep polling rather than aborting; a later attempt (or the next + // sync) may succeed. + pollErrors++; + _logger.LogWarning(dlEx, + "V2 pickup: order {OrderId} is issued but certificate download failed " + + "(attempt {Attempt}/{Retries}).", orderId, attempt, retries); + } + } + } + else if (disposition == (int)EndEntityStatus.REVOKED + || disposition == (int)EndEntityStatus.FAILED) + { + // Terminal non-issued outcomes carry no body and stop the poll + // immediately. The REVOKED case still comes back from this method with + // Status=REVOKED, but EnrollV2Async's terminal + // NormalizeV2RevokedEnrollResult call maps it to FAILED before it ever + // reaches the gateway, since a REVOKED order observed here never has a + // downloadable certificate body. + if (disposition == (int)EndEntityStatus.FAILED) + _logger.LogError( + "V2 order {OrderId} reached terminal FAILED status '{Status}' during " + + "synchronous pickup (attempt {Attempt}/{Retries}).", + orderId, tracked.Status, attempt, retries); + else + _logger.LogWarning( + "V2 order {OrderId} was REVOKED ('{Status}') during synchronous pickup " + + "(attempt {Attempt}/{Retries}).", + orderId, tracked.Status, attempt, retries); + return (new EnrollmentResult + { + CARequestID = orderId, + Certificate = null, + Status = disposition, + StatusMessage = $"Order {orderId} reached status '{tracked.Status}' during enrollment pickup." + }, lastKnownCaStatus); + } } - else if (string.Equals(detail.DcvStatus, Constants.Dcv.StatusRejected, StringComparison.Ordinal)) + catch (Exception ex) { - _logger.LogWarning("DCV rejected by CERTInext. OrderNumber={OrderNumber}, Domain={Domain}", orderNumber, domain); - pending.Remove(domain); + if (ex is OperationCanceledException) throw; + // A transient status-fetch failure consumes an attempt rather than aborting + // the wait; if it never recovers the pending result is returned below. + pollErrors++; + _logger.LogWarning(ex, + "V2 pickup TrackOrderV2Async failed for order {OrderId} (attempt {Attempt}/{Retries}).", + orderId, attempt, retries); } + + // Delay after every attempt (including the last), matching the V1 method's + // pickup cadence so the max-occupancy ceiling is identical. + await Task.Delay(TimeSpan.FromSeconds(delaySeconds), ct); } + + // SOC1 accuracy: don't attribute non-completion to "still validating" when the + // real cause was every poll erroring (e.g. a CA-side TrackOrder outage). Distinguish + // the two so the log reflects what actually happened. + if (pollErrors == retries) + _logger.LogWarning( + "V2 synchronous pickup exhausted {Retries} attempts for order {OrderId} — ALL polls " + + "errored (see preceding warnings). Returning pending result; the next synchronization " + + "will re-attempt retrieval.", + retries, orderId); + else if (notGeneratedYet > 0) + _logger.LogInformation( + "V2 order {OrderId} is issued at CERTInext but its certificate was not generated yet after " + + "{NotGenerated} of {Retries} pickup attempt(s) (Download Certificate answered 422 EMS-1165 each " + + "time; normal generation takes about 20 s). {States}. Returning pending result; the " + + "certificate will be imported by the next synchronization.", + orderId, notGeneratedYet, retries, lastStates); + else + _logger.LogInformation( + "V2 synchronous pickup did not complete within {Retries} attempts for order {OrderId} " + + "({Errors} poll error(s); remainder still pending). Returning pending result; the " + + "certificate will be imported by the next synchronization.", + retries, orderId, pollErrors); + pendingResult.StatusMessage = notGeneratedYet > 0 + ? $"{pendingResult.StatusMessage} The order is issued at CERTInext but its certificate was not " + + "generated yet within the enrollment-pickup window; it will be imported by a later synchronization." + : $"{pendingResult.StatusMessage} The certificate was not issued within the enrollment-pickup " + + "window; it will be imported by a later synchronization."; + } + catch (Exception ex) + { + _logger.LogWarning(ex, + "V2 synchronous pickup failed for order {OrderId}. Returning pending result; " + + "sync will pick up the certificate later.", orderId); } + + return (pendingResult, lastKnownCaStatus); } /// @@ -1878,6 +6566,16 @@ private EnrollmentResult BuildEnrollmentResult(EnrollCertificateResponse resp, b throw new Exception("CERTInext returned a null enrollment response."); int status = StatusMapper.ToRequestDisposition(resp.Status); + + // CertiNext's "auto-approved"/"downloadable" statuses can arrive before the + // certificate bytes are actually generated — GetCertificate right after order + // placement then fails, leaving resp.Certificate null while resp.Status still + // says issued. Never hand Command a GENERATED result with no PEM (it crashes + // CertificateConverterFactory.FromPEM downstream); demote to pending instead, + // matching the same invariant PickUpEnrolledCertificateAsync already enforces. + if (status == (int)EndEntityStatus.GENERATED && string.IsNullOrWhiteSpace(resp.Certificate)) + status = (int)EndEntityStatus.EXTERNALVALIDATION; + string message; switch (status) @@ -1958,46 +6656,479 @@ private static int MapRevocationReasonStringToCode(string reason) } /// - /// Converts the multi-valued SAN dictionary from the AnyCA gateway into the - /// list expected by the CERTInext API. + /// Builds the list submitted to CERTInext: the multi-valued SAN + /// dictionary the AnyCA gateway hands us, falling back to the subjectAltName extension + /// carried inside the CSR itself only when the gateway supplies nothing at all. + /// + /// Fallback, not union, deliberately: Command's SAN dictionary is the channel through + /// which an enrollment pattern's SAN policy is expressed for this request, and a signed + /// CSR — typically generated by the subscriber's own tooling, not by Command — can + /// legitimately carry more names than that policy allows. Unioning them in would + /// re-introduce a name the policy excluded. The CSR is only consulted when the dictionary + /// argument is null — not merely empty or all-empty-arrays. A non-null dictionary, + /// even one that computes to zero names, means Command's enrollment pattern ran and + /// deliberately produced no SANs for this request; only its literal absence means no + /// policy-derived set exists to defer to. + /// + /// The CSR still matters even though CERTInext ignores its subjectAltName extension + /// outright: a CSR carrying two DNS names, submitted with additionalDomains + /// omitted, produces an order with only the CN registered. Production behaves the same way: the customer + /// report that prompted this fix was a production UCC order whose CSR carried the SANs + /// and whose issued certificate held only the CN. So on whichever path populates the + /// gateway dictionary — or, in the fallback case, the CSR — this method is the only way + /// those names reach additionalDomains and therefore the certificate. + /// + /// History (UCC SANs silently dropped): the gateway keys this dictionary + /// dnsname, not dns. did not recognize + /// dnsname, so every DNS SAN was typed "dnsname", filtered out by the + /// DNS-only test in BuildAdditionalDomains, and the order went to CERTInext + /// with no additionalDomains at all. The certificate came back holding only + /// the CN, which reads as the CA stripping SANs supplied on the CSR. + /// + private List BuildSanList(Dictionary san, string csr, string subject) + => BuildSanList(san, csr, subject, dnsOnly: false, out _); + + /// + /// with an explicit + /// DNS-only mode for callers whose wire field cannot carry non-DNS SANs at all — the V2 + /// SSL UCC additionalDomains path. With set, + /// non-DNS entries are removed before any logging, regardless of + /// (a V1-only switch), and handed back via + /// so the caller can log its own accurate message. The + /// V1-worded "DROPPED because SubmitNonDnsSans is false" / "submitted rather than dropped" + /// warnings are only emitted when is false. /// - private static List BuildSanList(Dictionary san) + private List BuildSanList( + Dictionary san, string csr, string subject, + bool dnsOnly, out List excludedNonDns) { - if (san == null || san.Count == 0) + excludedNonDns = new List(); + + // "type|value" keys of entries that came from the CSR fallback, not the gateway + // dictionary — used only to word the provenance log accurately once the final, + // possibly-filtered result is known (see below). + var result = CollectRequestedSanEntries(san, csr, out var fromCsrKeys, out var skippedCsrTags); + + // Email SAN values masked unless LogSensitiveRequestData is on. + string FormatSans(IEnumerable sans) => + LogSanitizer.FormatSans(sans, _config.LogSensitiveRequestData); + + if (skippedCsrTags.Count > 0) + { + // GeneralName types with no domain-name rendering (otherName — e.g. a UPN from a + // Windows-generated CSR — directoryName, x400Address, ediPartyName, registeredID). + // They cannot be expressed in additionalDomains, so they are not forwarded. Warn + // rather than drop silently: the operator needs to know the CSR asked for something + // the certificate will not carry. + _logger.LogWarning( + "{Count} SAN(s) in the CSR use a type that cannot be represented as a domain name " + + "and were not submitted (ASN.1 GeneralName tag(s): {Tags}). CERTInext's " + + "additionalDomains field carries domain names only, so these cannot appear on the " + + "issued certificate. Remove them from the CSR if they are required. Subject={Subject}", + skippedCsrTags.Count, string.Join(", ", skippedCsrTags), LogSanitizer.Strip(subject)); + } + + if (result.Count == 0) + { + _logger.LogDebug( + "No SANs supplied by the gateway and none found in the CSR — submitting the order " + + "with domainName only. Subject={Subject}", LogSanitizer.Strip(subject)); return null; + } + + // CERTInext's certificateInformation.additionalDomains is a domain-name field, and + // non-DNS SANs are submitted into it deliberately rather than discarded: dropping + // them would issue a certificate silently missing names the subscriber asked for, + // which is the worse failure. + // + // Measured on the US sandbox only (product 844): CERTInext did NOT reject these at + // order placement. It accepted the order and registered the value verbatim as an + // order domain — an email address, an IP literal and a URI all came back as + // domainVerification keys. The order then cannot pass domain validation, so it parks + // pending instead of failing fast. + // + // NOTE (unverified): production behavior for this case has not been confirmed and may + // reject the order outright instead. The warning below therefore describes the + // sandbox outcome as the expected one without promising it: either way the operator is + // told which SANs are the problem, which is the part that matters for diagnosis. + // + // This filtering runs BEFORE any of the logging below, and all of that logging is + // computed from `result` as it stands afterward — not from the pre-filter set. Logging + // must reflect what is actually submitted, not what was initially collected: with + // SubmitNonDnsSans=false, logging against the pre-filter set would claim a SAN was + // added to the order when it was in fact dropped — a self-contradicting audit record + // for the same enrollment. + var nonDns = result.Where(s => !string.Equals(s.Type, "dns", StringComparison.OrdinalIgnoreCase)).ToList(); + + if (dnsOnly) + { + // DNS-only caller (V2 SSL UCC additionalDomains): non-DNS SANs can + // never reach the wire there, whatever SubmitNonDnsSans says, so exclude them + // here — before the logging below — and leave the wording to the caller, which + // knows which field they were excluded from. No V1-worded warning is raised. + excludedNonDns = nonDns; + result = result + .Where(s => string.Equals(s.Type, "dns", StringComparison.OrdinalIgnoreCase)) + .ToList(); + nonDns = new List(); + + if (result.Count == 0) + return null; + } + else if (nonDns.Count > 0 && !_config.SubmitNonDnsSans) + { + _logger.LogWarning( + "{Count} requested SAN(s) are not DNS names and are being DROPPED because " + + "SubmitNonDnsSans is false: {Sans}. The order will issue, but the certificate will " + + "NOT contain these names. Set SubmitNonDnsSans back to true to submit them and have " + + "CERTInext surface the problem instead. Subject={Subject}", + nonDns.Count, FormatSans(nonDns), LogSanitizer.Strip(subject)); + + result = result + .Where(s => string.Equals(s.Type, "dns", StringComparison.OrdinalIgnoreCase)) + .ToList(); + nonDns = new List(); + + if (result.Count == 0) + return null; + } + + // Log the final, post-filter resolved set and its provenance at Information. + int fromCsrKept = result.Count(s => fromCsrKeys.Contains($"{s.Type}|{s.Value}")); + // Post-filter, not the pre-filter `fromGateway` snapshot: gateway- and CSR-sourced + // entries are mutually exclusive by construction (the CSR fallback only ever runs when + // the gateway supplied nothing at all), so whatever's left in `result` and isn't + // fromCsrKept must be gateway-sourced. Using the pre-filter count here reproduced the + // exact self-contradicting-audit-trail bug this method was already restructured once to + // fix — with SubmitNonDnsSans=false this line could read e.g. "Resolved 1 SAN(s) ... + // FromGatewayRequest=3", an arithmetic impossibility for anyone reconciling counts. + int fromGatewayKept = result.Count - fromCsrKept; + _logger.LogInformation( + "Resolved {Total} SAN(s) for submission. FromGatewayRequest={FromGateway}, " + + "AddedFromCsrFallback={FromCsr}, Sans={Sans}, Subject={Subject}", + result.Count, fromGatewayKept, fromCsrKept, FormatSans(result), + LogSanitizer.Strip(subject)); + + if (fromCsrKept > 0) + { + // Worth a Warning, not Debug: it means Command handed us no SAN data at all for + // this enrollment, which is a gateway/template wiring smell even though the CSR + // fallback recovers it here. + _logger.LogWarning( + "Command supplied no SAN data for this enrollment; {Count} SAN(s) present in the CSR " + + "have been added to the order instead. Review the enrollment pattern / template SAN " + + "configuration. Subject={Subject}", + fromCsrKept, LogSanitizer.Strip(subject)); + } + + if (nonDns.Count > 0) + { + // Reaching this line means dnsOnly is false and SubmitNonDnsSans is true (both + // other cases emptied nonDns above), so these are being submitted, not dropped. + _logger.LogWarning( + "{Count} requested SAN(s) are not DNS names: {Sans}. CERTInext's additionalDomains " + + "field takes domain names, so this order will either be rejected outright or be " + + "created and then fail domain validation and sit pending — on the US sandbox it was " + + "accepted verbatim and parked pending. They are submitted rather than dropped on " + + "purpose: a visible failure is preferable to a certificate issued without names the " + + "subscriber requested. Remove them from the CSR or the enrollment pattern if the " + + "order should proceed. Subject={Subject}", + nonDns.Count, FormatSans(nonDns), LogSanitizer.Strip(subject)); + } + + return result; + } + /// + /// The SAN source rule shared by and + /// (extracted here so both honour it + /// identically): the gateway-supplied SAN + /// dictionary (types normalized by ), falling back to the CSR's own + /// subjectAltName extension only when the dictionary is itself null — see + /// for why this is a fallback, not a union. Entries are trimmed + /// and de-duplicated by type+value. No filtering and no logging happens here. + /// + /// "type|value" keys of the entries that came from the CSR fallback. + /// GeneralName tags present in the CSR that have no string rendering. + private static List CollectRequestedSanEntries( + Dictionary san, string csr, + out HashSet fromCsrKeys, out List skippedCsrTags) + { var result = new List(); + // Type+value identity, so the same name requested as two different SAN types is + // preserved while an exact repeat across the two sources collapses. + var seen = new HashSet(StringComparer.OrdinalIgnoreCase); + var csrKeys = new HashSet(StringComparer.OrdinalIgnoreCase); - // AnyCA passes SANs keyed by type name (e.g. "Dns", "Ip", "Email", "Uri") - foreach (var kvp in san) + void Add(string type, string value, bool fromCsr = false) { - string sanType = MapSanType(kvp.Key); - if (kvp.Value == null) continue; + if (string.IsNullOrWhiteSpace(value)) return; + string trimmed = value.Trim(); + string key = $"{type}|{trimmed}"; + if (!seen.Add(key)) return; + result.Add(new SanEntry { Type = type, Value = trimmed }); + if (fromCsr) csrKeys.Add(key); + } - foreach (string value in kvp.Value) + // AnyCA passes SANs keyed by type name — the real gateway uses "dnsname", + // "rfc822name", "ipaddress"; MapSanType normalizes the spelling variants. + if (san != null) + { + foreach (var kvp in san) { - if (!string.IsNullOrWhiteSpace(value)) - result.Add(new SanEntry { Type = sanType, Value = value.Trim() }); + string sanType = MapSanType(kvp.Key); + if (kvp.Value == null) continue; + + foreach (string value in kvp.Value) + Add(sanType, value); } } - return result.Count > 0 ? result : null; + // CSR fallback — only when the gateway dictionary is itself absent (san == null), NOT + // merely "computed to zero SAN entries" (i.e. result.Count == 0 at this point). Those + // are different things: + // a non-null dictionary — even an empty one, or one whose keys all map to empty arrays + // — means Command's enrollment pattern ran and deliberately produced no SANs for this + // request, which the CSR fallback must respect rather than override. san == null means + // Command never populated SAN data for this enrollment path at all, which is the one + // case this fallback exists for. Checking "computed to zero" instead of "san is null" + // would let an enrollment pattern that explicitly computes zero SANs still have + // CSR-derived names spliced back in — reopening the policy-reintroduction risk the + // fallback-over-union redesign exists to close. + skippedCsrTags = new List(); + if (san == null) + { + var csrSans = ExtractSanEntriesFromCsr(csr, out skippedCsrTags); + foreach (var csrSan in csrSans) + Add(csrSan.Type, csrSan.Value, fromCsr: true); + } + + fromCsrKeys = csrKeys; + return result; + } + + /// + /// Resolves the additionalHosts list for a V2 private-pki order. Spec + /// ("Private PKI Certificates" -> Create - Intranet SSL): "additionalHosts[] - SAN + /// list (DNS names or IPv4 / IPv6)"; the example body sends + /// ["portal.acme.local", "reports.acme.local", "10.0.0.50"] with the primary host in + /// hostname, not repeated here. + /// + /// - Source: — the same gateway-dictionary-with- + /// CSR-fallback rule the SSL UCC path uses via . + /// - DNS and IP SANs are both submitted. Unlike SSL's FQDN-only additionalDomains, + /// IP literals are native to this field, so the V1-era SubmitNonDnsSans switch + /// (whose purpose is keeping SANs CERTInext cannot validate out of a domain-name field) + /// is deliberately not consulted — dropping a requested IP SAN here would silently issue + /// a certificate without it. + /// - Email/URI SANs (and CSR GeneralName types with no string form) have no place in a + /// host list: excluded with a warning that names only their types (an email SAN value is + /// personal data). + /// - The primary is excluded; duplicates collapse + /// case-insensitively. Returns null (field omitted) when nothing remains. + /// + private List BuildPrivatePkiAdditionalHosts( + Dictionary san, string csr, string subject, string hostname) + { + var requested = CollectRequestedSanEntries(san, csr, out var fromCsrKeys, out var skippedCsrTags); + + if (skippedCsrTags.Count > 0) + { + _logger.LogWarning( + "{Count} SAN(s) in the CSR use a type that cannot be represented as a host name or IP " + + "address and were not submitted (ASN.1 GeneralName tag(s): {Tags}). V2 private-pki " + + "additionalHosts carries DNS names and IPv4/IPv6 addresses only, so these cannot appear " + + "on the issued certificate. Subject={Subject}", + skippedCsrTags.Count, string.Join(", ", skippedCsrTags), LogSanitizer.Strip(subject)); + } + + bool IsHostType(SanEntry s) => + string.Equals(s.Type, "dns", StringComparison.OrdinalIgnoreCase) + || string.Equals(s.Type, "ip", StringComparison.OrdinalIgnoreCase); + + var unsupported = requested.Where(s => !IsHostType(s)).ToList(); + if (unsupported.Count > 0) + { + _logger.LogWarning( + "EnrollV2Async: {Count} requested SAN(s) are neither DNS names nor IP addresses and cannot " + + "be submitted via V2 private-pki additionalHosts (DNS names or IPv4/IPv6 only) — they will " + + "NOT appear on the issued certificate. Types=[{Types}]", + unsupported.Count, string.Join(", ", unsupported.Select(s => s.Type))); + } + + var hosts = requested + .Where(IsHostType) + .Select(s => s.Value?.Trim()) + .Where(v => !string.IsNullOrWhiteSpace(v)) + .Where(v => !string.Equals(v, hostname, StringComparison.OrdinalIgnoreCase)) + .Distinct(StringComparer.OrdinalIgnoreCase) + .ToList(); + + // Gateway- and CSR-sourced entries are mutually exclusive by construction (the CSR is + // only read when the gateway dictionary is null), so when any entry came from the CSR, + // every surviving host did. Same wiring-smell warning BuildSanList raises for SSL. + if (fromCsrKeys.Count > 0 && hosts.Count > 0) + { + _logger.LogWarning( + "Command supplied no SAN data for this enrollment; {Count} SAN(s) present in the CSR " + + "have been added to the private-pki order's additionalHosts instead. Review the " + + "enrollment pattern / template SAN configuration. Subject={Subject}", + hosts.Count, LogSanitizer.Strip(subject)); + } + + return hosts.Count == 0 ? null : hosts; } private static string MapSanType(string anyCAType) { switch (anyCAType?.ToLowerInvariant()) { - case "dns": return "dns"; + // "dnsname" is what the AnyCA REST Gateway actually sends; "dns"/"dnsnames" + // are kept for callers and older hosts that use the shorter spelling. + case "dns": + case "dnsname": + case "dnsnames": return "dns"; case "ip": - case "ipaddress": return "ip"; + case "ipaddress": + case "ipaddresses": return "ip"; case "email": - case "rfc822": return "email"; - case "uri": return "uri"; + case "rfc822": + case "rfc822name": return "email"; + case "uri": + case "uniformresourceidentifier": return "uri"; default: return anyCAType?.ToLowerInvariant() ?? "dns"; } } + /// + /// Extracts the subjectAltName entries from a PEM-encoded PKCS#10 CSR. + /// + /// Implemented with BouncyCastle (per the project's crypto policy: all certificate + /// and key handling goes through BouncyCastle, never BCL System.Security.Cryptography). + /// Never throws — an absent, truncated, or otherwise unparseable CSR returns an empty + /// list so enrollment continues on the gateway-supplied SAN data alone. + /// + /// PEM-encoded PKCS#10 request, or null/garbage. + /// + /// ASN.1 GeneralName tag numbers present in the CSR that have no domain-name rendering and + /// were therefore not returned (otherName, directoryName, x400Address, ediPartyName, + /// registeredID, and any malformed IPAddress). Reported so the caller can warn instead of + /// dropping them silently. + /// + private static List ExtractSanEntriesFromCsr(string csrPem, out List skippedTagNumbers) + { + var result = new List(); + skippedTagNumbers = new List(); + if (string.IsNullOrWhiteSpace(csrPem)) + return result; + + try + { + string b64 = csrPem + .Replace("-----BEGIN CERTIFICATE REQUEST-----", string.Empty) + .Replace("-----END CERTIFICATE REQUEST-----", string.Empty) + .Replace("-----BEGIN NEW CERTIFICATE REQUEST-----", string.Empty) + .Replace("-----END NEW CERTIFICATE REQUEST-----", string.Empty) + .Replace("\r", string.Empty) + .Replace("\n", string.Empty) + .Trim(); + + if (string.IsNullOrWhiteSpace(b64)) + return result; + + var csr = new Org.BouncyCastle.Pkcs.Pkcs10CertificationRequest(Convert.FromBase64String(b64)); + + // SANs live in the PKCS#9 extensionRequest attribute, not the CSR body. + var extensions = csr.GetRequestedExtensions(); + var sanExtension = extensions?.GetExtension( + Org.BouncyCastle.Asn1.X509.X509Extensions.SubjectAlternativeName); + if (sanExtension == null) + return result; + + var names = Org.BouncyCastle.Asn1.X509.GeneralNames.GetInstance(sanExtension.GetParsedValue()); + foreach (var generalName in names.GetNames()) + { + var entry = GeneralNameToSanEntry(generalName); + if (entry != null) + result.Add(entry); + else + skippedTagNumbers.Add(generalName.TagNo); + } + } + catch (Exception ex) + { + // Enrollment must not fail because we could not read the CSR's SANs — the + // gateway-supplied set still applies, and CERTInext validates the CSR itself. + // Debug so an operator diagnosing a missing SAN can see the parse was skipped. + LogHandler.GetClassLogger(typeof(CERTInextCAPlugin)) + .LogDebug(ex, "ExtractSanEntriesFromCsr suppressed CSR parse failure"); + } + + return result; + } + + /// + /// Maps a GeneralName to the this plugin would submit for it, or null + /// for a name whose value cannot be rendered meaningfully — skipped rather than submitted as + /// ASN.1 debris. One switch, not two: a separate tag→type mapping alongside this one would + /// assign a type string ("directoryname", "registeredid", ...) to tags that always return a + /// null value here anyway — the type never reaches a caller with no value to pair it with. + /// + private static SanEntry GeneralNameToSanEntry(Org.BouncyCastle.Asn1.X509.GeneralName generalName) + { + string type; + string value; + + switch (generalName.TagNo) + { + case Org.BouncyCastle.Asn1.X509.GeneralName.DnsName: + type = "dns"; + value = Org.BouncyCastle.Asn1.DerIA5String.GetInstance(generalName.Name).GetString(); + break; + + case Org.BouncyCastle.Asn1.X509.GeneralName.Rfc822Name: + type = "email"; + value = Org.BouncyCastle.Asn1.DerIA5String.GetInstance(generalName.Name).GetString(); + break; + + case Org.BouncyCastle.Asn1.X509.GeneralName.UniformResourceIdentifier: + type = "uri"; + value = Org.BouncyCastle.Asn1.DerIA5String.GetInstance(generalName.Name).GetString(); + break; + + case Org.BouncyCastle.Asn1.X509.GeneralName.IPAddress: + type = "ip"; + // Octet string → dotted-quad / RFC 5952 text, so what we submit and log is + // the address the subscriber asked for rather than its hex encoding. + byte[] octets = Org.BouncyCastle.Asn1.Asn1OctetString.GetInstance(generalName.Name).GetOctets(); + value = octets.Length == 4 || octets.Length == 16 + ? new System.Net.IPAddress(octets).ToString() + : null; + break; + + default: + // otherName, directoryName, x400Address, ediPartyName, registeredID. + // + // Deliberately null, not Name.ToString(). BouncyCastle renders these as an + // ASN.1 dump — a UPN otherName from a Windows-generated CSR stringifies to + // "[1.3.6.1.4.1.311.20.2.3, [CONTEXT 0]svc@corp.example.com]" and a + // directoryName to "CN=host.example.com,O=Acme". Submitting that as an entry in + // additionalDomains is not "forwarding the name the subscriber asked for" — it + // is putting ASN.1 debris in a domain-name field, which cannot become a + // certificate SAN under any circumstances and only breaks the order. That is + // different from a well-formed non-DNS SAN (IP/email/URI), which we do submit + // on purpose so nothing the subscriber requested is dropped silently. + // + // Skipped is not silent: BuildSanList warns with the tag numbers so the + // operator can see a SAN was present and not forwarded. + type = null; + value = null; + break; + } + + return string.IsNullOrWhiteSpace(value) ? null : new SanEntry { Type = type, Value = value }; + } + private static string GetStringValue( Dictionary dict, string key, string defaultValue = "") { @@ -2007,9 +7138,47 @@ private static string GetStringValue( } /// - /// Extracts the X.509 serial number from a PEM-encoded certificate for inclusion - /// in audit log entries. Returns "(parse-error)" rather than throwing, so that a - /// logging failure never suppresses an audit record. + /// Validates that is an absolute URI using https, or http only + /// when the host is loopback (localhost/127.0.0.1/::1). Shared by every config field + /// that receives a credential on every outbound request — currently ApiUrl + /// (, ) and, in V1 OAuth + /// mode, OAuthTokenUrl (same two call sites) — so the http-cleartext rule can + /// never drift between connection-test time and actual startup. Does NOT check for + /// null/empty; callers that need a distinct "is required" message should check that + /// first and only call this helper once the value is known to be non-blank. + /// + /// null when passes; otherwise an actionable + /// error message naming . + private static string ValidateHttpsOrLoopbackUrl(string fieldName, string url) + { + if (!Uri.TryCreate(url, UriKind.Absolute, out Uri parsed)) + return $"'{fieldName}' is not a valid absolute URI."; + + if (!string.Equals(parsed.Scheme, Uri.UriSchemeHttps, StringComparison.OrdinalIgnoreCase) + && !parsed.IsLoopback) + { + return $"'{fieldName}' must use https — credentials (the OAuth client secret or API " + + "key) are sent to this URL on every request, and http would transmit them in " + + "cleartext. http is only allowed for a loopback host (localhost/127.0.0.1/::1)."; + } + + return null; + } + + /// + /// Extracts the X.509 serial number of the *leaf* (first) certificate from a + /// PEM-encoded certificate — or from a PEM chain — for inclusion in audit log + /// entries. Returns "(parse-error)" rather than throwing, so that a logging + /// failure never suppresses an audit record. + /// + /// V2 enrollment/sync pass this a full chain PEM (: + /// leaf followed by intermediate blocks). Decoding that as a single base64 blob is + /// wrong on two counts: each PEM block carries its own base64 padding, so a '=' + /// from the leaf block lands mid-string once concatenated (Convert.FromBase64String + /// throws FormatException), and even if it didn't, the leaf and intermediate DER + /// would be mashed into one invalid ASN.1 structure. Reading block-by-block via + /// BouncyCastle's PemReader and stopping after the first block sidesteps both: + /// it returns exactly the leaf block's own decoded DER bytes, ignoring the rest. /// /// Implemented with BouncyCastle (per the project's crypto policy: all certificate /// and key handling goes through BouncyCastle, never BCL System.Security.Cryptography). @@ -2018,20 +7187,19 @@ private static string ExtractSerialFromPem(string pem) { try { - // Strip PEM headers and decode the DER bytes - string b64 = pem - .Replace("-----BEGIN CERTIFICATE-----", string.Empty) - .Replace("-----END CERTIFICATE-----", string.Empty) - .Replace("\r", string.Empty) - .Replace("\n", string.Empty) - .Trim(); - - if (string.IsNullOrWhiteSpace(b64)) + if (string.IsNullOrWhiteSpace(pem)) return "(empty-pem)"; - byte[] der = Convert.FromBase64String(b64); + using var stringReader = new System.IO.StringReader(pem); + var pemReader = new Org.BouncyCastle.Utilities.IO.Pem.PemReader(stringReader); + var pemObject = pemReader.ReadPemObject(); + if (pemObject == null) + return "(parse-error)"; // no "-----BEGIN"/"-----END" block found at all + if (pemObject.Content == null || pemObject.Content.Length == 0) + return "(empty-pem)"; // block markers present but body is empty + var parser = new Org.BouncyCastle.X509.X509CertificateParser(); - var cert = parser.ReadCertificate(der); + var cert = parser.ReadCertificate(pemObject.Content); if (cert == null) return "(parse-error)"; // Match X509Certificate2.SerialNumber's format precisely: uppercase hex, diff --git a/CERTInext/CERTInextCAPluginConfig.cs b/CERTInext/CERTInextCAPluginConfig.cs index 43d0537..a7eee92 100644 --- a/CERTInext/CERTInextCAPluginConfig.cs +++ b/CERTInext/CERTInextCAPluginConfig.cs @@ -1,4 +1,4 @@ -// Copyright 2024 Keyfactor +// Copyright 2026 Keyfactor // Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. // You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 // Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, @@ -27,17 +27,17 @@ public static Dictionary GetCAConnectorAnnotations() { [Constants.Config.ApiUrl] = new PropertyConfigInfo { - Comments = "REQUIRED: CERTInext API base URL. " + - "Sandbox (US): https://sandbox-us-api.certinext.io/emSignHub-API/ — " + - "Production (US): https://us-api.certinext.io/ — " + - "Production (Global/India): https://api.certinext.io/", + Comments = "REQUIRED: CERTInext API base URL. V1 (default): host plus /emSignHub-API/, e.g. " + + "https://us-api.certinext.io/emSignHub-API/. V2 (UseV2Api=true): bare host, e.g. " + + "https://us-api.certinext.io. Must use https.", Hidden = false, DefaultValue = string.Empty, Type = "String" }, [Constants.Config.AccountNumber] = new PropertyConfigInfo { - Comments = "REQUIRED: Your CERTInext account number (numeric string). " + + Comments = "REQUIRED when UseV2Api is false: your CERTInext account number (numeric string). " + + "Included in the `meta` block of every V1 request. Not used when UseV2Api is true. " + "Available in the CERTInext portal.", Hidden = false, DefaultValue = string.Empty, @@ -45,102 +45,100 @@ public static Dictionary GetCAConnectorAnnotations() }, [Constants.Config.GroupNumber] = new PropertyConfigInfo { - Comments = "OPTIONAL: CERTInext group (delegation) number. " + - "When set, it is included in GetProductDetails requests AND in the " + - "`delegationInformation.groupNumber` field of every SSL order so the order " + - "is routed to the correct account group. Some accounts will queue orders for " + - "additional review when this field is omitted. " + - "Available in the CERTInext portal under Delegation → Groups.", + Comments = "OPTIONAL: CERTInext group (delegation) number. When set, it is included in " + + "product-catalog requests and in the order (`orderDetails.groupNumber` on V1, " + + "`groupNumber` on V2) so the order is routed to the configured account group, and V2 " + + "synchronization is scoped to the group. When blank, CERTInext uses the account's " + + "default group. Available in the CERTInext portal under Delegation → Groups.", Hidden = false, DefaultValue = string.Empty, Type = "String" }, [Constants.Config.OrganizationNumber] = new PropertyConfigInfo { - Comments = "STRONGLY RECOMMENDED for OV/EV and faster DV issuance: numeric " + - "CERTInext organization number for a pre-vetted organization (e.g. " + - "your company's pre-vetted entry). When set, every SSL order is submitted " + - "with `organizationDetails.preVetting=\"1\"` and the configured " + - "`organizationNumber`, telling CERTInext to skip the manual " + - "organization-vetting queue. Without this value, orders are placed without " + - "any organizationDetails block and CERTInext may park them in " + - "`Pending System RA` for extended manual review (observed: tens of hours). " + - "Available in the CERTInext portal under Organizations → " + - "Pre-vetted Organizations.", + Comments = "OPTIONAL: Pre-vetted CERTInext organization number. Required for OV/EV on V2; " + + "recommended for V1 OV/EV and faster DV. Skips CERTInext's manual vetting queue.", Hidden = false, DefaultValue = string.Empty, Type = "String" }, [Constants.Config.TechnicalContactName] = new PropertyConfigInfo { - Comments = "OPTIONAL: Name sent in the `technicalPointOfContact.tpcName` field of every " + - "SSL order. Defaults to the configured RequestorName when blank. " + - "Some product configurations require a TPoC to be present; omitting it can " + - "cause CERTInext to park orders awaiting manual completion of the field.", + Comments = "OPTIONAL: Name sent as the order's technical point of contact (V1 " + + "`technicalPointOfContact.pocFirstName` / `pocLastName`, V2 `technicalPointOfContact.name`). " + + "On V1 the name is split on the first whitespace: the first word is the first name and the " + + "rest is the last name; a single-word name is sent in both. Defaults to the configured " + + "RequestorName when blank. On V1, if no contact name or no email resolves (including from " + + "RequestorName/RequestorEmail), the whole technicalPointOfContact block is omitted from the " + + "order and a Warning is logged, since CERTInext requires both inside the block.", Hidden = false, DefaultValue = string.Empty, Type = "String" }, [Constants.Config.TechnicalContactEmail] = new PropertyConfigInfo { - Comments = "OPTIONAL: Email sent in the `technicalPointOfContact.tpcEmail` field of every " + - "SSL order. Defaults to the configured RequestorEmail when blank.", + Comments = "OPTIONAL: Email sent as the order's technical point of contact (V1 " + + "`technicalPointOfContact.pocEmail`, V2 `email`). Defaults to the configured RequestorEmail " + + "when blank. On V1, if no contact name or no email resolves (including from " + + "RequestorName/RequestorEmail), the whole technicalPointOfContact block is omitted from the " + + "order and a Warning is logged, since CERTInext requires both inside the block.", Hidden = false, DefaultValue = string.Empty, Type = "String" }, [Constants.Config.TechnicalContactIsdCode] = new PropertyConfigInfo { - Comments = "OPTIONAL: International dialing code for the TPoC phone number. " + - "Defaults to the configured RequestorIsdCode when blank.", + Comments = "OPTIONAL: International dialing code for the technical contact phone number. Defaults to " + + "the configured RequestorIsdCode when blank.", Hidden = false, DefaultValue = string.Empty, Type = "String" }, [Constants.Config.TechnicalContactMobileNumber] = new PropertyConfigInfo { - Comments = "OPTIONAL: Mobile number for the TPoC (digits only). " + - "Defaults to the configured RequestorMobileNumber when blank.", + Comments = "OPTIONAL: Mobile number for the technical contact (digits only). Defaults to the " + + "configured RequestorMobileNumber when blank.", Hidden = false, DefaultValue = string.Empty, Type = "String" }, [Constants.Config.AuthMode] = new PropertyConfigInfo { - Comments = "REQUIRED: Authentication mode. " + - "'AccessKey' (default) — uses authKey = SHA256(accessKey + ts + txn) in every request body. " + - "'OAuth' — uses an OAuth2 bearer token (requires OAuthTokenUrl, OAuthClientId, OAuthClientSecret).", + Comments = "OPTIONAL, legacy (V1 only): leave as 'AccessKey' (default). V1 does not honor OAuth " + + "tokens, so 'OAuth' is unsupported. Ignored when UseV2Api is true.", Hidden = false, DefaultValue = Constants.Config.AuthModeAccessKey, Type = "String" }, [Constants.Config.ApiKey] = new PropertyConfigInfo { - Comments = "REQUIRED when AuthMode is 'AccessKey': the REST API Access Key generated in the " + - "CERTInext portal under Integrations → APIs. " + - "This value is used to compute authKey = SHA256(accessKey + ts + txn); " + - "it is never transmitted directly.", + Comments = "REQUIRED when UseV2Api is false: the REST API Access Key generated in the CERTInext " + + "portal under Integrations → APIs. Used to compute authKey = SHA256(accessKey + ts + " + + "txn); never transmitted directly. Not used when UseV2Api is true.", Hidden = true, DefaultValue = string.Empty, Type = "String" }, [Constants.Config.OAuth2TokenUrl] = new PropertyConfigInfo { - Comments = "OAuth token endpoint URL. Required when AuthMode is 'OAuth'.", + Comments = "Legacy / unsupported (V1): V1 does not honor OAuth tokens; leave blank. Ignored when " + + "UseV2Api is true — V2 requests its token from {ApiUrl}/oauth/token.", Hidden = false, DefaultValue = string.Empty, Type = "String" }, [Constants.Config.OAuth2ClientId] = new PropertyConfigInfo { - Comments = "OAuth client ID. Required when AuthMode is 'OAuth'.", + Comments = "OAuth client ID. REQUIRED when UseV2Api is true: V2 authenticates with " + + "client_credentials against {ApiUrl}/oauth/token. The key must be generated in OAuth mode " + + "in the CERTInext portal. Not used on V1.", Hidden = false, DefaultValue = string.Empty, Type = "String" }, [Constants.Config.OAuth2ClientSecret] = new PropertyConfigInfo { - Comments = "OAuth client secret. Required when AuthMode is 'OAuth'.", + Comments = "OAuth client secret. REQUIRED when UseV2Api is true (see OAuthClientId). Not used on V1.", Hidden = true, DefaultValue = string.Empty, Type = "String" @@ -175,42 +173,61 @@ public static Dictionary GetCAConnectorAnnotations() DefaultValue = string.Empty, Type = "String" }, + [Constants.Config.RequestorDesignation] = new PropertyConfigInfo + { + Comments = "OPTIONAL: Job title / role of the requestor (e.g. 'IT Administrator'). Sent as " + + "requestorInformation.requestorDesignation (V1) and requestor.designation (V2). Free " + + "text. Omitted when blank.", + Hidden = false, + DefaultValue = string.Empty, + Type = "String" + }, [Constants.Config.SignerPlace] = new PropertyConfigInfo { - Comments = "City or location of the subscriber agreement signer. Required by CERTInext for all orders.", + Comments = "City or location of the subscriber agreement signer (e.g. 'San Francisco, CA'). " + + "REQUIRED when UseV2Api is on: the V2 Subscriber Agreement sent with every SSL order " + + "requires it, so the connector cannot be saved with it blank. A per-template " + + "SignerPlace enrollment parameter overrides it. On V1, if neither is set, the " + + "placeholder \"Gateway\" is sent and a Warning is logged; set it so the agreement audit " + + "record is accurate.", Hidden = false, DefaultValue = string.Empty, Type = "String" }, [Constants.Config.SignerIp] = new PropertyConfigInfo { - Comments = "IP address of the subscriber agreement signer. Required by CERTInext for all orders.", + Comments = "V1 ONLY: IP address of the subscriber agreement signer. A template-level SignerIp " + + "enrollment parameter overrides it. If neither is set, the placeholder 127.0.0.1 is sent " + + "and a Warning is logged, and a value that is not an IP address is still sent unchanged, " + + "with a Warning. Ignored on V2: the V2 agreement block has no signer IP field, so it is " + + "never sent.", Hidden = false, DefaultValue = string.Empty, Type = "String" }, ["DefaultProductCode"] = new PropertyConfigInfo { - Comments = "OPTIONAL: Default numeric product code used when not specified at template level. " + - "Product codes are provided by eMudhra (e.g. the SSL DV 1-year code for your account). " + - "Retrieve available codes from Integrations → APIs → GetProductDetails.", + Comments = "OPTIONAL: Default numeric product code. V1 only: used for renewals when the template " + + "supplies none. Not used on V2, where the product is resolved by CERTInext (set the " + + "template's ProductCode to override). Get codes via GetProductDetails.", Hidden = false, DefaultValue = string.Empty, Type = "String" }, [Constants.Config.AccountingModel] = new PropertyConfigInfo { - Comments = "OPTIONAL: CERTInext billing model sent in `orderDetails.accountingModel`. " + - "\"2\" = credit-based (most accounts, default). \"1\" = cash model.", + Comments = "OPTIONAL: CERTInext billing model sent in `orderDetails.accountingModel` on V1 orders. " + + "\"2\" = credit-based (most accounts, default). \"1\" = cash model. Not used by V2.", Hidden = false, DefaultValue = "2", Type = "String" }, [Constants.Config.EmailNotifications] = new PropertyConfigInfo { - Comments = "OPTIONAL: Whether CERTInext sends lifecycle-event emails to the requestor. " + - "\"1\" = enabled, \"0\" = silent (recommended for gateway-driven orders so end users " + - "aren't surprised by CA emails). Default: \"0\".", + Comments = "OPTIONAL: Lifecycle emails to the requestor. \"1\" = full set (V2: \"all\"), \"0\" = silent " + + "(V1: \"0\"; V2: \"consent-only\", the quietest value the V2 API accepts). " + + "Blank: silent on V1, omitted on V2 (CA default applies). Other values fail V2 " + + "enrollment. Default: \"0\".", Hidden = false, DefaultValue = "0", Type = "String" @@ -218,7 +235,9 @@ public static Dictionary GetCAConnectorAnnotations() [Constants.Config.SubscriptionValidityYears] = new PropertyConfigInfo { Comments = "OPTIONAL: Default validity in years for SSL orders. \"1\", \"2\", or \"3\". " + - "Override per template via the ValidityYears product parameter. Default: \"1\".", + "Used when the template sets no ValidityYears (and, on V1, no ValidityDays); a template " + + "term (on V1 the larger of ValidityYears and ValidityDays in years) overrides it. " + + "Default: \"1\".", Hidden = false, DefaultValue = "1", Type = "String" @@ -242,24 +261,36 @@ public static Dictionary GetCAConnectorAnnotations() }, [Constants.Config.AutoSecureWww] = new PropertyConfigInfo { - Comments = "OPTIONAL: If \"1\", CERTInext automatically adds the `www.` variant of the " + - "primary domain as an additional SAN. \"0\" = use only the CN/SANs supplied " + - "with the CSR. Default: \"0\".", + Comments = "OPTIONAL: Sent as `orderDetails.autoSecureWWW` on every V1 SSL order (new and " + + "renewal) and as `autoSecureWww` on V2 SSL orders. If \"1\", CERTInext automatically adds " + + "the `www.` variant of the primary domain as an additional SAN, which must also pass " + + "domain validation. \"0\" = use only the CN/SANs supplied with the CSR. Default: \"0\".", Hidden = false, DefaultValue = "0", Type = "String" }, [Constants.Config.IgnoreExpired] = new PropertyConfigInfo { - Comments = "If true, expired certificates will be skipped during synchronization. Default: false.", + Comments = "If true, expired certificates are skipped during synchronization. V2 only: the V1 sync " + + "does not currently apply it. Default: false.", Hidden = false, DefaultValue = false, Type = "Boolean" }, + [Constants.Config.SubmitNonDnsSans] = new PropertyConfigInfo + { + Comments = "OPTIONAL (V1 only): If true (default), non-DNS SANs (IP, email, URI) are submitted, but " + + "CERTInext cannot validate them, so the order won't issue. If false, only DNS names are " + + "submitted.", + Hidden = false, + DefaultValue = true, + Type = "Boolean" + }, [Constants.Config.PageSize] = new PropertyConfigInfo { - Comments = "Number of orders to fetch per page during synchronization. " + - $"Default: {Constants.Api.DefaultPageSize}, max: {Constants.Api.MaxPageSize}.", + Comments = $"Number of orders to fetch per page during synchronization (1 or higher). Default: " + + $"{Constants.Api.DefaultPageSize}, max: {Constants.Api.MaxPageSize} (V2 `/reports/orders` " + + $"pages are capped at {Constants.ApiV2.OrdersReportMaxPageSize}).", Hidden = false, DefaultValue = Constants.Api.DefaultPageSize, Type = "Number" @@ -272,16 +303,51 @@ public static Dictionary GetCAConnectorAnnotations() DefaultValue = true, Type = "Boolean" }, - [Constants.Config.DcvEnabled] = new PropertyConfigInfo + [Constants.Config.LogSensitiveRequestData] = new PropertyConfigInfo { - Comments = "OPTIONAL: When true, the gateway will perform DNS-based Domain Control Validation (DCV) " + - "during enrollment for orders that require it, using the configured DNS provider plugin. " + - "Requires a DNS provider plugin (e.g. azure-azuredns-dnsplugin) to be deployed on the gateway. " + - "Default: false.", + Comments = "OPTIONAL temporary diagnostic switch. When true, requestor personal data (name, email, " + + "phone) and full CA payloads are logged. Credentials are always redacted. Turn off after " + + "verifying. Default: false.", Hidden = false, DefaultValue = false, Type = "Boolean" }, + [Constants.Config.PickupRetries] = new PropertyConfigInfo + { + Comments = $"OPTIONAL: Times Enroll() polls CERTInext for the certificate after order submission " + + $"(0-{Constants.Pickup.MaxRetries}; 0 disables the wait). Unissued orders are picked up by " + + $"sync. Default: {Constants.Pickup.DefaultRetries}.", + Hidden = false, + DefaultValue = Constants.Pickup.DefaultRetries, + Type = "Number" + }, + [Constants.Config.PickupDelay] = new PropertyConfigInfo + { + Comments = $"OPTIONAL: Seconds between certificate-pickup polls " + + $"(1-{Constants.Pickup.MaxDelaySeconds}). Total wait is " + + $"{Constants.Pickup.InitialDelaySeconds} s + PickupRetries x this value. Command's own " + + $"enrollment call into the gateway is bounded at roughly " + + $"{Constants.Pickup.CommandEnrollmentBudgetSeconds} s, so the plugin caps the total at " + + $"{Constants.Pickup.MaxTotalWaitSeconds} s regardless of how PickupRetries/PickupDelay " + + $"are set, reducing the retry count to fit. Keep your configured total well under that " + + $"ceiling. Default: {Constants.Pickup.DefaultDelaySeconds} " + + $"(~{Constants.Pickup.InitialDelaySeconds + Constants.Pickup.DefaultRetries * Constants.Pickup.DefaultDelaySeconds} " + + $"s with default retries).", + Hidden = false, + DefaultValue = Constants.Pickup.DefaultDelaySeconds, + Type = "Number" + }, + [Constants.Config.DcvEnabled] = new PropertyConfigInfo + { + Comments = "OPTIONAL: When true, the plugin performs DNS-based Domain Control Validation (DCV) " + + "during enrollment and synchronization for orders that require it, using the DNS provider " + + "plugin deployed on the gateway (e.g. azure-azuredns-dnsplugin). Without a DNS provider " + + "plugin, orders that need validation stay pending and the plugin logs why. Set to false " + + "to skip DCV. Default: true.", + Hidden = false, + DefaultValue = true, + Type = "Boolean" + }, [Constants.Config.DcvTxtRecordTemplate] = new PropertyConfigInfo { Comments = "OPTIONAL: Format string for the DNS TXT record hostname used during DCV. " + @@ -310,54 +376,113 @@ public static Dictionary GetCAConnectorAnnotations() }, [Constants.Config.DcvWaitForChallengeSeconds] = new PropertyConfigInfo { - Comments = "OPTIONAL: How long (seconds) the plugin will wait inside Enroll() for CERTInext to " + - "expose the DCV challenge (i.e. populate `domainVerification` in TrackOrder). Under " + - "concurrent load CERTInext sometimes takes a few seconds after GenerateOrderSSL " + - "before the slot appears. Without this wait, the plugin's initial TrackOrder check " + - "sees null and skips DCV — the order then has to wait for the next gateway sync " + - "cycle to be picked up. Setting to 0 disables the wait (single-check behaviour). " + - $"Can also be set via the {Constants.Config.DcvWaitForChallengeSecondsEnvVar} " + - "environment variable; the env var takes precedence when both are set. Default: 60.", + Comments = "OPTIONAL (V1 only): Seconds Enroll() waits for CERTInext to expose the DCV challenge. 0 " + + "disables the wait. CERTINEXT_DCV_WAIT_FOR_CHALLENGE_SECONDS overrides it. Default: 60.", Hidden = false, DefaultValue = 60, Type = "Number" }, [Constants.Config.DcvWaitForIssuanceSeconds] = new PropertyConfigInfo { - Comments = "OPTIONAL: How long (seconds) the plugin will wait inside Enroll() after DCV " + - "verifies for CERTInext to finish generating the certificate. CERTInext issuance " + - "is async — DCV may be verified but the cert PEM isn't yet available for download. " + - "Without this wait, Enroll() returns a pending result and the issued cert is " + - "picked up by the next sync cycle. Setting to 0 disables the wait (single-fetch " + - "behaviour). " + - $"Can also be set via the {Constants.Config.DcvWaitForIssuanceSecondsEnvVar} " + - "environment variable; the env var takes precedence when both are set. Default: 60.", + Comments = "OPTIONAL (V1 only): Seconds Enroll() waits for issuance after DCV verifies. 0 disables " + + "the wait. CERTINEXT_DCV_WAIT_FOR_ISSUANCE_SECONDS overrides it. Default: 60.", Hidden = false, DefaultValue = 60, Type = "Number" }, [Constants.Config.DcvSyncMaxOrderAgeHours] = new PropertyConfigInfo { - Comments = "OPTIONAL: During synchronization, only pending DV orders younger than this many hours " + - "are eligible to be driven through DCV. This keeps a sync pass fast when there is a " + - "large backlog of old, never-completing pending orders (e.g. abandoned orders or domains " + - "outside the configured DNS provider's zone): they age out and are simply reported as " + - "pending rather than retried every pass. Recently-placed orders (the ones that legitimately " + - "deferred DCV) are always within the window and complete via the normal scan cadence. " + - $"Set to 0 to disable the age filter (attempt DCV for all pending). Default: {Constants.Dcv.DefaultSyncMaxOrderAgeHours}.", + Comments = $"OPTIONAL: During synchronization, only pending DV orders younger than this many hours " + + $"are driven through DCV. 0 disables the filter. Default: " + + $"{Constants.Dcv.DefaultSyncMaxOrderAgeHours}.", Hidden = false, DefaultValue = Constants.Dcv.DefaultSyncMaxOrderAgeHours, Type = "Number" }, [Constants.Config.DcvSyncMaxPerPass] = new PropertyConfigInfo { - Comments = "OPTIONAL: Maximum number of pending DV orders the plugin will attempt to drive through DCV " + - "in a single synchronization pass. Bounds the per-pass cost regardless of backlog size; " + - "remaining pending orders are reported as-is and picked up on a later pass (the per-minute " + - $"incremental scan keeps recent orders moving). Set to 0 to disable the cap. Default: {Constants.Dcv.DefaultSyncMaxPerPass}.", + Comments = $"OPTIONAL: Maximum pending DV orders driven through DCV per synchronization pass. 0 " + + $"disables the cap. Default: {Constants.Dcv.DefaultSyncMaxPerPass}.", Hidden = false, DefaultValue = Constants.Dcv.DefaultSyncMaxPerPass, Type = "Number" + }, + + // ----------------------------------------------------------------------- + // V2 API settings — only required when UseV2Api = true + // ----------------------------------------------------------------------- + + [Constants.ConfigV2.UseV2Api] = new PropertyConfigInfo + { + Comments = "OPTIONAL: When true, the plugin routes Ping / Enroll / GetSingleRecord / Revoke / " + + "Synchronize through the CERTInext V2 REST API (/api/certinext/v2/), including V2 " + + "/reports/orders for Synchronize. Requires ApiUrl (the V2 base URL in this mode), " + + "OAuthClientId, OAuthClientSecret, and SignerPlace. V1 credentials " + + "(ApiKey/AccountNumber/AuthMode) are not required when this is true. Default: false (V1 " + + "API).", + Hidden = false, + DefaultValue = false, + Type = "Boolean" + }, + [Constants.Config.V2SyncLookbackHours] = new PropertyConfigInfo + { + Comments = $"OPTIONAL (V2 only): Hours subtracted from the last-sync time on incremental sync, so an " + + $"order created earlier but issued later is not missed. Default: " + + $"{Constants.ApiV2.DefaultSyncLookbackHours}.", + Hidden = false, + DefaultValue = Constants.ApiV2.DefaultSyncLookbackHours, + Type = "Number" + }, + [Constants.Config.SyncRecentOrderGraceSeconds] = new PropertyConfigInfo + { + Comments = "OPTIONAL: during a Synchronize (full or incremental, in both V1 and V2 modes), a pending or issued " + + "order created less than this many seconds ago (plus a small clock margin) is not emitted to " + + "the gateway; the next incremental pass imports it. This stops the sync from inserting a " + + "gateway row for an order whose enrollment is still in flight, which would make the " + + "enrollment's own save fail with a duplicate key. Revoked and failed orders are never held " + + "back. 0 disables the hold; a negative value uses the default. " + + $"Default: {Constants.Api.DefaultSyncRecentOrderGraceSeconds}.", + Hidden = false, + DefaultValue = Constants.Api.DefaultSyncRecentOrderGraceSeconds, + Type = "Number" + }, + [Constants.Config.V2InlineCsr] = new PropertyConfigInfo + { + Comments = "OPTIONAL (V2 mode only): when true (the default), SSL/TLS enrollment sends the CSR inline in " + + "the order create call (a single POST /ssl-certificates), as a direct API integration " + + "does. When false, the plugin creates the order and then submits the CSR (PUT .../csr); " + + "that two-call flow fails for a domain the account has already validated, because " + + "CERTInext approves the order at create and then rejects the CSR. A create that times " + + "out or returns a 5xx can leave an order that still issues; it is not cancelled and the " + + "next synchronization imports it, so do not resubmit. Private PKI orders ignore this " + + "setting and always use the two-call flow (the CA rejects an inline CSR on Private PKI " + + "create). Ignored when UseV2Api is false. Default: true (single call).", + Hidden = false, + DefaultValue = true, + Type = "Boolean" + }, + [Constants.Config.SslComSubmitOrganization] = new PropertyConfigInfo + { + Comments = "OPTIONAL (V2 mode only): before an OV or EV SSL/TLS order, the plugin checks " + + "whether SSL.com has validated the organization (OrganizationNumber) at that level, " + + "refreshing the status once if not. When this is true and the organization is still " + + "unvalidated and ready to submit, the plugin also SUBMITS it to SSL.com for validation. " + + "WARNING: enabling this ACCEPTS SSL.COM'S SUBSCRIBER AGREEMENT ON THE ORGANIZATION'S " + + "BEHALF; each acceptance is audit-logged. Leave false unless you are authorized to do " + + "that. Whatever the outcome, the order is placed anyway and a not-validated organization " + + "only logs a warning. Default: false.", + Hidden = false, + DefaultValue = false, + Type = "Boolean" + }, + [Constants.Config.SslComAdminEmail] = new PropertyConfigInfo + { + Comments = "OPTIONAL (V2 mode only): administrator email sent as adminEmail when the plugin " + + "submits an organization to SSL.com (only used when SslComSubmitOrganization is true). " + + "Blank omits it and SSL.com uses the organization's own contact.", + Hidden = false, + DefaultValue = string.Empty, + Type = "String" } }; } @@ -372,9 +497,12 @@ public static Dictionary GetTemplateParameterAnnotat { [Constants.EnrollmentParam.ProductCode] = new PropertyConfigInfo { - Comments = "OPTIONAL: Override the numeric CERTInext product code for this template. " + - "When omitted, the default production code for the selected product is used automatically " + - "(e.g. DV SSL → 838). Set this explicitly when targeting sandbox or a non-standard code.", + Comments = "OPTIONAL: Override the numeric CERTInext product code for this template. When omitted: " + + "on V1, the default production code for the selected product is used (e.g. DV SSL → 838); " + + "on V2, no X-Product-Code header is sent and CERTInext resolves the product from the " + + "variant, the wildcard shape of the domain and any additional domains. On V2 an explicit " + + "value is an override, sent as X-Product-Code to choose between several matching " + + "catalog products (for example different CA profiles for the same variant).", Hidden = false, DefaultValue = string.Empty, Type = "String" @@ -389,7 +517,13 @@ public static Dictionary GetTemplateParameterAnnotat }, [Constants.EnrollmentParam.ValidityYears] = new PropertyConfigInfo { - Comments = "OPTIONAL: Subscription validity in years: 1, 2, or 3. Default: 1. " + + Comments = "OPTIONAL: Subscription term in years: 1, 2, or 3. On V1 the order's term is the " + + "larger of ValidityYears and ValidityDays rounded up to whole years (365 days = 1 year); " + + "a field left at its default (1 year) never overrides the other. On V2 only " + + "ValidityYears is used. A template value overrides the connector's " + + "SubscriptionValidityYears. Because the larger value wins on V1, a stale larger " + + "ValidityDays cannot be shortened with ValidityYears alone; set ValidityDays back to " + + "365. Default: 1. " + "Note: CERTInext validates per 390-day certificate within the subscription; " + "the 'validity' field in the order is the subscription term, not certificate lifetime.", Hidden = false, @@ -398,56 +532,63 @@ public static Dictionary GetTemplateParameterAnnotat }, [Constants.EnrollmentParam.ValidityDays] = new PropertyConfigInfo { - Comments = "DEPRECATED: Use ValidityYears instead. " + - "If set, value is divided by 365 and rounded up to get the subscription year count.", + Comments = "OPTIONAL: V1 only (ignored on V2, which uses ValidityYears). Requested validity in " + + "days. CERTInext's order API takes whole subscription years, so days are converted to " + + "years, rounded up (365 days = 1 year). The order's term is the larger of this and " + + "ValidityYears; a field left at its default (365 days = 1 year) never overrides the " + + "other. Kept because certificate lifetimes are shrinking and days is the unit that will " + + "matter if CERTInext adds a lifetime field. To shorten a template with a larger value, " + + "set this back to 365. Default: 365.", Hidden = false, DefaultValue = 365, Type = "Number" }, [Constants.EnrollmentParam.AutoApprove] = new PropertyConfigInfo { - Comments = "OPTIONAL: If true, the gateway will attempt automatic approval of certificates " + - "that are returned in a pending-approval state. Default: false.", + Comments = "Currently has no effect — reserved for future use. The plugin does not call " + + "any approval endpoint against CERTInext regardless of this setting.", Hidden = false, DefaultValue = false, Type = "Boolean" }, [Constants.EnrollmentParam.RequesterName] = new PropertyConfigInfo { - Comments = "OPTIONAL: Default requester name to include in the enrollment request. " + - "Used when no requester name can be derived from the subject.", + Comments = "OPTIONAL: Overrides the connector RequestorName for this template when non-blank. Never " + + "derived from the certificate subject.", Hidden = false, DefaultValue = string.Empty, Type = "String" }, [Constants.EnrollmentParam.RequesterEmail] = new PropertyConfigInfo { - Comments = "OPTIONAL: Default requester email address. " + - "Used when no email can be derived from the subject.", + Comments = "OPTIONAL: Overrides the connector RequestorEmail for this template when non-blank. Never " + + "derived from the certificate subject.", Hidden = false, DefaultValue = string.Empty, Type = "String" }, [Constants.EnrollmentParam.RenewalWindowDays] = new PropertyConfigInfo { - Comments = "OPTIONAL: Number of days before certificate expiration within which a renewal is " + - "triggered. Certificates expiring further than this window are reissued instead. " + - "Certificates that have already expired also fall back to reissue. Default: 90.", + Comments = "OPTIONAL: V1 only. Number of days before certificate expiration within which a renewal " + + "is triggered. Certificates expiring further than this window are reissued instead. " + + "Certificates that have already expired also fall back to reissue. V2 places a new order " + + "for every renewal and reissue. Default: 90.", Hidden = false, DefaultValue = 90, Type = "Number" }, [Constants.EnrollmentParam.KeyType] = new PropertyConfigInfo { - Comments = "OPTIONAL: Key algorithm to request (e.g. 'RSA2048', 'RSA4096', 'EC256', 'EC384'). " + - "If omitted, the profile default is used.", + Comments = "OPTIONAL: Informational. The key algorithm is determined by the submitted CSR; CERTInext " + + "accepts RSA 2048/3072/4096 and ECC P-256/P-384 and rejects larger RSA, ECC P-521, and " + + "Ed25519/Ed448.", Hidden = false, DefaultValue = string.Empty, Type = "String" }, [Constants.EnrollmentParam.DomainName] = new PropertyConfigInfo { - Comments = "OPTIONAL: Primary domain for SSL/TLS orders. " + + Comments = "OPTIONAL: Primary domain for SSL/TLS orders (for V2 private-pki orders, the primary hostname). " + "Derived from the CSR CN if omitted.", Hidden = false, DefaultValue = string.Empty, @@ -455,27 +596,56 @@ public static Dictionary GetTemplateParameterAnnotat }, [Constants.EnrollmentParam.SignerName] = new PropertyConfigInfo { - Comments = "OPTIONAL: Per-template subscriber agreement signer name. " + - "Falls back to the connector-level RequestorName if omitted.", + Comments = "OPTIONAL: Per-template subscriber agreement signer name. Falls back to the " + + "connector-level RequestorName if omitted (V2: the requestor name). If no name resolves, " + + "V1 sends the placeholder \"Keyfactor Gateway\" and logs a Warning.", Hidden = false, DefaultValue = string.Empty, Type = "String" }, [Constants.EnrollmentParam.SignerPlace] = new PropertyConfigInfo { - Comments = "OPTIONAL: Per-template signer city/location. " + - "Falls back to the connector-level SignerPlace if omitted.", + Comments = "OPTIONAL: Per-template signer city/location. Falls back to the connector-level " + + "SignerPlace if omitted. If neither is set, V1 sends the placeholder \"Gateway\" and logs " + + "a Warning.", Hidden = false, DefaultValue = string.Empty, Type = "String" }, [Constants.EnrollmentParam.SignerIp] = new PropertyConfigInfo { - Comments = "OPTIONAL: Per-template signer IP address. " + - "Falls back to the connector-level SignerIp if omitted.", + Comments = "V1 ONLY, OPTIONAL: Per-template signer IP address. Falls back to the connector-level " + + "SignerIp if omitted. If neither is set, V1 sends the placeholder 127.0.0.1 and logs a " + + "Warning; a V1 value that is not an IP address is sent unchanged, with a Warning. " + + "Ignored on V2 (the V2 agreement block has no signer IP field).", Hidden = false, DefaultValue = string.Empty, Type = "String" + }, + + // ----------------------------------------------------------------------- + // V2 API enrollment parameters (only used when UseV2Api = true) + // ----------------------------------------------------------------------- + + [Constants.EnrollmentParam.ProductFamily] = new PropertyConfigInfo + { + Comments = "V2 ONLY: Product family for this template. Accepted values: 'ssl' (default) or " + + "'private-pki'. 'private-pki' requires a Private PKI ProductVariant. 'signature' " + + "(Document Signer) is accepted by the parameter, but Document " + + "Signer enrollment is not supported.", + Hidden = false, + DefaultValue = "ssl", + Type = "String" + }, + [Constants.EnrollmentParam.ProductVariant] = new PropertyConfigInfo + { + Comments = "V2 ONLY: Product variant sent in the V2 order body. ProductFamily 'ssl': 'dv', 'ov', or " + + "'ev' — if omitted, derived from the selected product; an explicit value that contradicts " + + "the product fails enrollment. ProductFamily 'private-pki': 'intranet-ssl' or 'igtf-host' " + + "(required; no default).", + Hidden = false, + DefaultValue = "dv", + Type = "String" } }; } @@ -492,8 +662,9 @@ public class CERTInextConfig // ----------------------------------------------------------------------- /// - /// CERTInext API base URL, e.g. "https://us-api.certinext.io/emSignHub-API/". - /// Must end with a trailing slash or the endpoint path segment. + /// CERTInext API base URL. V1 (default): host plus the /emSignHub-API/ path, e.g. + /// "https://us-api.certinext.io/emSignHub-API/". V2 (UseV2Api=true): the bare host, e.g. + /// "https://us-api.certinext.io". A trailing slash is optional; the client trims and re-adds it. /// [JsonPropertyName("ApiUrl")] public string ApiUrl { get; set; } = string.Empty; @@ -507,9 +678,9 @@ public class CERTInextConfig /// /// Optional CERTInext group (delegation) number. When set, it is passed in /// the productDetails.groupNumber field of GetProductDetails - /// requests AND in the delegationInformation.groupNumber field of every - /// SSL order body so the order is routed to the correct account group. Some - /// accounts queue orders for extra review when this field is omitted. + /// requests AND in the orderDetails.groupNumber field of every + /// SSL order body (new and renewal) so the order is routed to the configured account + /// group. When blank, CERTInext uses the account's default group. /// [JsonPropertyName("GroupNumber")] public string GroupNumber { get; set; } = string.Empty; @@ -533,7 +704,8 @@ public class CERTInextConfig // ----------------------------------------------------------------------- /// - /// Authentication mode: "AccessKey" (default) or "OAuth". + /// Legacy. "AccessKey" (default). V1 does not honor OAuth tokens, so "OAuth" is unsupported; + /// the field is kept so connectors saved with it keep loading. Ignored when UseV2Api is true. /// [JsonPropertyName("AuthMode")] public string AuthMode { get; set; } = Constants.Config.AuthModeAccessKey; @@ -541,21 +713,21 @@ public class CERTInextConfig /// /// Raw REST API Access Key generated in CERTInext portal (Integrations → APIs). /// Used to compute authKey = SHA256(accessKey + ts + txn). - /// Required when AuthMode is "AccessKey". + /// Required on V1 (AccessKey); not used on V2. /// NEVER logged or transmitted directly — only the derived authKey is sent. /// [JsonPropertyName("ApiKey")] public string ApiKey { get; set; } = string.Empty; - /// OAuth token endpoint URL. Required when AuthMode is "OAuth". + /// Legacy / unsupported: V1 does not honor OAuth tokens. Ignored on V2, which uses {ApiUrl}/oauth/token. [JsonPropertyName("OAuthTokenUrl")] public string OAuthTokenUrl { get; set; } = string.Empty; - /// OAuth client ID. Required when AuthMode is "OAuth". + /// OAuth client ID. Required when UseV2Api is true; not used on V1. [JsonPropertyName("OAuthClientId")] public string OAuthClientId { get; set; } = string.Empty; - /// OAuth client secret. Required when AuthMode is "OAuth". + /// OAuth client secret. Required when UseV2Api is true; not used on V1. [JsonPropertyName("OAuthClientSecret")] public string OAuthClientSecret { get; set; } = string.Empty; @@ -594,16 +766,24 @@ public class CERTInextConfig [JsonPropertyName("RequestorMobileNumber")] public string RequestorMobileNumber { get; set; } = string.Empty; + /// + /// Default requestor job title / role. Blank by default; when blank, the V2 order's + /// requestor.designation field is omitted rather than sent with any default value. + /// + [JsonPropertyName("RequestorDesignation")] + public string RequestorDesignation { get; set; } = string.Empty; + /// Subscriber agreement signer place (city/location). Required by CERTInext. [JsonPropertyName("SignerPlace")] public string SignerPlace { get; set; } = string.Empty; - /// Subscriber agreement signer IP address. Required by CERTInext. + /// Subscriber agreement signer IP address (V1 only; the V2 agreement block has no such field). [JsonPropertyName("SignerIp")] public string SignerIp { get; set; } = string.Empty; /// - /// Default product code used when the template-level ProductCode is not specified. + /// Default product code used when the template-level ProductCode is not specified (V1 only: + /// renewals). Ignored on V2, which sends X-Product-Code only for an explicit template ProductCode. /// Product codes are numeric strings provided by eMudhra (e.g. "844" for DV SSL 1-year). /// [JsonPropertyName("DefaultProductCode")] @@ -639,7 +819,12 @@ public class CERTInextConfig [JsonPropertyName("AccountingModel")] public string AccountingModel { get; set; } = "2"; - /// "1" = enable lifecycle emails to requestor, "0" = silent (default). + /// + /// "1" = full notification set (V1 sends it as-is; V2 maps to "all"). "0" = silent on + /// both V1 and V2 (default). Blank stays silent on V1 (sent + /// as "0") but is omitted on V2, letting the CA's own default ("all") apply instead. Any + /// other value fails V2 enrollment before any CA call. + /// [JsonPropertyName("EmailNotifications")] public string EmailNotifications { get; set; } = "0"; @@ -666,12 +851,46 @@ public class CERTInextConfig [JsonPropertyName("IgnoreExpired")] public bool IgnoreExpired { get; set; } = false; + /// + /// Whether non-DNS SANs (IP address, email, URI) are submitted to CERTInext. + /// + /// Defaults to true: nothing the subscriber requested is dropped silently. CERTInext + /// registers such values verbatim as order domains, and they cannot pass domain validation, + /// so the order will not issue until they are removed — a visible failure, deliberately + /// preferred over a certificate quietly missing requested names. + /// + /// Set to false to submit DNS names only, restoring the pre-1.0.1 behaviour where the + /// order issues but the non-DNS names are absent from the certificate. This exists as an + /// upgrade escape hatch: on a host that was issuing certificates for requests carrying an IP + /// or email SAN, the default flips those enrollments from "issues (incomplete)" to "parks + /// pending", and an operator needs a way back that does not involve downgrading the plugin. + /// + [JsonPropertyName("SubmitNonDnsSans")] + public bool SubmitNonDnsSans { get; set; } = true; + [JsonPropertyName("PageSize")] public int PageSize { get; set; } = Constants.Api.DefaultPageSize; [JsonPropertyName("Enabled")] public bool Enabled { get; set; } = true; + /// + /// OPTIONAL diagnostic escape hatch. When true, full CA request/response payloads are + /// logged at Trace (beyond the credential scrubbing that always applies), and the + /// enrollment-attempt Information log line includes the requestor's name and email in + /// full. This writes personal data belonging to whoever placed the order — name, email, + /// phone, and other organization contact fields — plus complete CA request/response + /// bodies into the gateway's log files. Intended only for temporary use while verifying + /// a new deployment (confirming exactly what was sent to the CA and that the order + /// succeeded); turn it back off once verification is complete. When false (default), + /// personal-data fields are replaced with "***REDACTED***" (email values are masked but + /// keep their domain, e.g. "j***@example.com") and the enrollment log line omits the + /// requester name entirely. Credentials (API keys, OAuth secrets, tokens) are always + /// redacted regardless of this setting. Default: false. + /// + [JsonPropertyName("LogSensitiveRequestData")] + public bool LogSensitiveRequestData { get; set; } = false; + // ----------------------------------------------------------------------- // DCV — domain control validation via DNS provider plugins // ----------------------------------------------------------------------- @@ -679,10 +898,10 @@ public class CERTInextConfig /// /// When true, the plugin will run DNS DCV for orders that require it during enrollment. /// Requires IDomainValidatorFactory to be injected by the gateway (available from - /// IAnyCAPlugin 3.3.0-prerelease). Default: false. + /// IAnyCAPlugin 3.3.0). Default: true. /// [JsonPropertyName("DcvEnabled")] - public bool DcvEnabled { get; set; } = false; + public bool DcvEnabled { get; set; } = true; /// /// Format string for the TXT record hostname. {0} is replaced with the domain. @@ -695,6 +914,23 @@ public class CERTInextConfig /// Seconds to wait after publishing the DNS TXT record before calling VerifyDcv. /// Default: 30. /// + /// + /// Number of GetCertificate poll attempts inside Enroll() after an order is + /// submitted, before falling back to a pending result (picked up by the next sync). + /// Mirrors the legacy Sectigo connector's PickupRetries. Set to 0 to disable. + /// Default: 5. + /// + [JsonPropertyName("PickupRetries")] + public int PickupRetries { get; set; } = Constants.Pickup.DefaultRetries; + + /// + /// Seconds between certificate-pickup retries. PickupRetries * PickupDelay (plus a + /// short initial delay) bounds the time an enrollment call occupies a Command worker + /// thread. Mirrors the legacy Sectigo connector's PickupDelay. Default: 10. + /// + [JsonPropertyName("PickupDelay")] + public int PickupDelayInSeconds { get; set; } = Constants.Pickup.DefaultDelaySeconds; + [JsonPropertyName("DcvPropagationDelaySeconds")] public int DcvPropagationDelaySeconds { get; set; } = 30; @@ -746,6 +982,67 @@ public class CERTInextConfig [JsonPropertyName("DcvSyncMaxPerPass")] public int DcvSyncMaxPerPass { get; set; } = Constants.Dcv.DefaultSyncMaxPerPass; + // ----------------------------------------------------------------------- + // V2 API settings + // ----------------------------------------------------------------------- + + /// + /// When true, Enroll / GetSingleRecord / Revoke / Synchronize use the CERTInext V2 REST + /// API. In this mode is the V2 base URL (e.g. + /// https://sandbox-us-api.certinext.io, no trailing path suffix) and V2 OAuth2 auth reuses + /// / . V1-only credentials + /// (, , ) are not + /// required when this is true. Default: false. + /// + [JsonPropertyName("UseV2Api")] + public bool UseV2Api { get; set; } = false; + + /// + /// V2 mode only: during an incremental Synchronize, query V2 /reports/orders with a + /// 'from' date of (lastSync minus this many hours) rather than exactly lastSync — see + /// (the + /// from/to filter's order-date-vs-issue-date semantics are not documented). + /// Ignored when is false. Default: 72. + /// + [JsonPropertyName("V2SyncLookbackHours")] + public int V2SyncLookbackHours { get; set; } = Constants.ApiV2.DefaultSyncLookbackHours; + + /// + /// During a Synchronize (full or incremental, V1 and V2 modes), pending and issued orders created + /// less than this many seconds ago (plus ) + /// are not emitted, so the sync cannot create the gateway row an in-flight enrollment is about to + /// save (issue 0090). 0 disables; a negative value falls back to the default. Revoked and failed + /// orders are never held back. Default: 120. + /// + [JsonPropertyName("SyncRecentOrderGraceSeconds")] + public int SyncRecentOrderGraceSeconds { get; set; } = Constants.Api.DefaultSyncRecentOrderGraceSeconds; + + /// + /// OPTIONAL (V2 mode only), default true. When true, SSL/TLS orders carry the CSR inline in the + /// create call (single call, no PUT .../csr). When false, the plugin creates the order + /// without a CSR and then submits it; that two-call flow fails for an already-validated domain, + /// where CERTInext approves the order at create and then rejects the CSR. Private PKI ignores this and always uses the two-call + /// flow. Ignored when is false. + /// + [JsonPropertyName("V2InlineCsr")] + public bool V2InlineCsr { get; set; } = true; + + /// + /// V2 only. When true, an OV/EV SSL/TLS enrollment whose organization SSL.com has not + /// validated (and that is ready to submit) submits it to SSL.com, which accepts SSL.com's + /// subscriber agreement on the organization's behalf. Default false: the plugin only reads + /// the status and warns. The order is placed regardless. + /// + [JsonPropertyName("SslComSubmitOrganization")] + public bool SslComSubmitOrganization { get; set; } = false; + + /// + /// V2 only. Optional adminEmail sent on an SSL.com organization submission (only used + /// when is true). + /// + [JsonPropertyName("SslComAdminEmail")] + public string SslComAdminEmail { get; set; } = string.Empty; + /// /// Returns the effective DCV timeout, preferring the environment variable over the /// config field so operators can adjust the ceiling without a connector reconfiguration. @@ -782,5 +1079,22 @@ public int GetEffectiveDcvWaitForIssuanceSeconds() return envVal; return DcvWaitForIssuanceSeconds >= 0 ? DcvWaitForIssuanceSeconds : 60; } + + /// + /// Effective number of certificate-pickup retries, clamped to + /// [0, ]. 0 disables the synchronous pickup. + /// + public int GetEffectivePickupRetries() + => System.Math.Max(0, System.Math.Min(PickupRetries, Constants.Pickup.MaxRetries)); + + /// + /// Effective seconds between pickup retries, clamped to + /// [1, ]. A non-positive configured value + /// falls back to the default rather than producing a tight busy-loop. + /// + public int GetEffectivePickupDelaySeconds() + => System.Math.Max(1, System.Math.Min( + PickupDelayInSeconds > 0 ? PickupDelayInSeconds : Constants.Pickup.DefaultDelaySeconds, + Constants.Pickup.MaxDelaySeconds)); } } diff --git a/CERTInext/Client/CERTInextClient.cs b/CERTInext/Client/CERTInextClient.cs index 255b65a..66d5a98 100644 --- a/CERTInext/Client/CERTInextClient.cs +++ b/CERTInext/Client/CERTInextClient.cs @@ -1,4 +1,4 @@ -// Copyright 2024 Keyfactor +// Copyright 2026 Keyfactor // Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. // You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 // Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, @@ -7,6 +7,7 @@ using System; using System.Collections.Generic; +using System.Linq; using System.Net; using System.Runtime.CompilerServices; using System.Text; @@ -14,6 +15,7 @@ using System.Threading; using System.Threading.Tasks; using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; using Keyfactor.Extensions.CAPlugin.CERTInext.Models; using Keyfactor.Logging; using Microsoft.Extensions.Logging; @@ -36,16 +38,49 @@ namespace Keyfactor.Extensions.CAPlugin.CERTInext.Client /// public class CERTInextClient : ICERTInextClient, IDisposable { - private static readonly ILogger Logger = LogHandler.GetClassLogger(); + // Not readonly only so unit tests can capture the client's log output through + // OverrideLoggerForTests. Production code never reassigns it. + private static ILogger Logger = LogHandler.GetClassLogger(); + + /// + /// Test seam: swaps the class-wide logger so a unit test can assert exactly what the client + /// logs (request/response payload dumps, warnings). The logger is static and resolved once + /// per process, so swapping LogHandler.Factory cannot reach it. Dispose the returned + /// handle to restore the previous logger. + /// + internal static IDisposable OverrideLoggerForTests(ILogger logger) + { + var prior = Logger; + Logger = logger ?? throw new ArgumentNullException(nameof(logger)); + return new LoggerOverride(prior); + } + + private sealed class LoggerOverride : IDisposable + { + private ILogger _prior; + public LoggerOverride(ILogger prior) => _prior = prior; + public void Dispose() + { + if (_prior == null) return; + Logger = _prior; + _prior = null; + } + } private readonly CERTInextConfig _config; private readonly RestClient _http; - // OAuth2 token cache — refreshed when expired + // OAuth2 token cache — refreshed when expired (V1) private string _cachedToken; private DateTime _tokenExpiry = DateTime.MinValue; private readonly SemaphoreSlim _tokenLock = new SemaphoreSlim(1, 1); + // V2 API HTTP client and token cache + private readonly RestClient _httpV2; + private string _v2Token; + private DateTime _v2TokenExpiry = DateTime.MinValue; + private readonly SemaphoreSlim _v2TokenLock = new SemaphoreSlim(1, 1); + // --------------------------------------------------------------------------- // Construction // --------------------------------------------------------------------------- @@ -67,6 +102,20 @@ public CERTInextClient(CERTInextConfig config) }; _http = new RestClient(options); + + // V2 client — only constructed when V2 is enabled and ApiUrl is set. A single ApiUrl + // serves both modes (its meaning follows UseV2Api); + // in V2 mode it is the V2 base URL (no trailing path suffix). + // No authenticator: tokens are injected per-request via BuildV2RequestAsync. + if (config.UseV2Api && !string.IsNullOrWhiteSpace(config.ApiUrl)) + { + var v2Options = new RestClientOptions(config.ApiUrl.TrimEnd('/')) + { + ThrowOnAnyError = false, + Timeout = TimeSpan.FromSeconds(120) + }; + _httpV2 = new RestClient(v2Options); + } } // --------------------------------------------------------------------------- @@ -77,6 +126,8 @@ public void Dispose() { _http?.Dispose(); _tokenLock?.Dispose(); + _httpV2?.Dispose(); + _v2TokenLock?.Dispose(); } // --------------------------------------------------------------------------- @@ -167,7 +218,7 @@ public async Task PingAsync(CancellationToken ct = default) result.Meta.ErrorCode, result.Meta.ErrorMessage, level: LogLevel.Error); throw new Exception( - $"CERTInext credential validation failed: {result.Meta.ErrorMessage ?? result.Meta.ErrorCode}. " + + $"CERTInext credential validation failed: {MaskCaText(result.Meta.ErrorMessage) ?? result.Meta.ErrorCode}. " + "See gateway logs for details."); } @@ -186,9 +237,20 @@ public async Task PlaceOrderAsync( if (request.Meta == null) request.Meta = await BuildMetaAsync(ct); + // The domain set is logged here, at the wire, not just where Command hands it to us. + // A UCC order that silently lost its SANs upstream of this point is otherwise + // indistinguishable in the gateway log from one the CA stripped — reconciling the + // enrollment-start "SANs=" line against this one localizes the loss immediately. + var certInfo = request.OrderDetails?.CertificateInformation; Logger.LogInformation( - "Submitting order to CERTInext. ProductCode={ProductCode}", - request.OrderDetails?.ProductCode); + "Submitting order to CERTInext. ProductCode={ProductCode}, DomainName={DomainName}, " + + "AdditionalDomainCount={AdditionalDomainCount}, AdditionalDomains={AdditionalDomains}", + request.OrderDetails?.ProductCode, + LogSanitizer.Strip(certInfo?.DomainName), + certInfo?.AdditionalDomains?.Count ?? 0, + // Untyped by now: an email SAN submitted here is masked unless + // LogSensitiveRequestData is on. + LogSanitizer.FormatUntypedSans(certInfo?.AdditionalDomains, _config.LogSensitiveRequestData)); GenerateOrderResponse result = null; RestResponse resp = null; @@ -213,10 +275,19 @@ public async Task PlaceOrderAsync( request.Meta = await BuildMetaAsync(ct); var req = new RestRequest(Constants.Api.GenerateOrderSslPath, Method.Post); - req.AddJsonBody(JsonSerializer.Serialize(request, GetJsonOptions())); + string jsonBody = JsonSerializer.Serialize(request, GetJsonOptions()); + // Guarded: redaction is a regex + JSON-reader pass that must not run when Trace is off. + if (Logger.IsEnabled(LogLevel.Trace)) + Logger.LogTrace("PlaceOrderAsync request payload: {Payload}", + ApplyLoggingRedaction(jsonBody, _config.LogSensitiveRequestData)); + req.AddJsonBody(jsonBody); var sw = System.Diagnostics.Stopwatch.StartNew(); - resp = await ExecuteWithRetryAsync(req, ct); + // idempotent:false — order submission is non-idempotent. A network-level + // timeout may occur after CERTInext already created the order, so re-sending the + // same requestTxn would be rejected as EMS-947 and orphan the created order + // Rate-limit retries are still handled below (with a fresh txn). + resp = await ExecuteWithRetryAsync(req, ct, idempotent: false); sw.Stop(); Logger.LogInformation( @@ -232,6 +303,26 @@ public async Task PlaceOrderAsync( $"Authentication failure during certificate order. HTTP {(int)resp.StatusCode}. See gateway logs for details."); } + // Transient/network failure (5xx or no HTTP status) on a non-idempotent submit: + // CERTInext may have already created the order (the response just didn't reach us). + // We deliberately did not retry (see idempotent:false above). Fail clearly instead + // of deserializing an empty body; if the order was created, the next sync imports it. + bool transientFailure = !resp.IsSuccessful + && !((int)resp.StatusCode >= 400 && (int)resp.StatusCode < 500); + if (transientFailure) + { + Logger.LogWarning( + "PlaceOrder received no usable response (DomainName={Domain}, HttpStatus={Status}, LatencyMs={Latency}). " + + "Not retrying to avoid a duplicate order (EMS-947). If CERTInext created the order it " + + "will be imported by the next synchronization.", + LogSanitizer.Strip(request.OrderDetails?.CertificateInformation?.DomainName), + (int)resp.StatusCode, sw.ElapsedMilliseconds); + throw new Exception( + "CERTInext did not return a usable response to the order submission. If the order was " + + "created it will be imported by the next synchronization — do not resubmit immediately. " + + "See gateway logs for details."); + } + result = DeserializeOrThrow(resp, "place order"); if (result.Meta != null && !result.Meta.IsSuccess) @@ -247,7 +338,7 @@ public async Task PlaceOrderAsync( Logger.LogWarning( "PlaceOrder hit rate-limit-shaped error \"{ErrorMessage}\" (attempt {Attempt}/{Max}). " + "Backing off {WaitSeconds:F1}s before retrying. See Troubleshooting in README for context.", - result.Meta.ErrorMessage, attempt, RateLimitMaxAttempts, waitSeconds); + MaskCaText(result.Meta.ErrorMessage), attempt, RateLimitMaxAttempts, waitSeconds); try { await Task.Delay(TimeSpan.FromSeconds(waitSeconds), ct); @@ -259,8 +350,33 @@ public async Task PlaceOrderAsync( continue; // retry } + // EMS-947 "Duplicate requestTxn": CERTInext already received an order for this + // transaction. The non-idempotent-retry handling above means this should not be + // caused by our own retry, but if it still surfaces the order exists on the CA + // side and will be imported by the next sync — say so, not a generic failure. + bool isDuplicateTxn = + string.Equals(result.Meta.ErrorCode, "EMS-947", StringComparison.OrdinalIgnoreCase) + || (result.Meta.ErrorMessage?.IndexOf("Duplicate requestTxn", StringComparison.OrdinalIgnoreCase) >= 0); + if (isDuplicateTxn) + { + // Log the classification decision itself (parity with the transient-failure + // branch above) so an auditor sees the plugin deliberately treated this as a + // benign duplicate rather than a hard failure. + Logger.LogWarning( + "PlaceOrder classified {ErrorCode} as a duplicate transaction (not a hard failure). " + + "DomainName={Domain}, Path={Path}, HttpStatus={Status}, LatencyMs={Latency}. If an order exists " + + "for this transaction it will be imported by the next synchronization.", + result.Meta.ErrorCode, + LogSanitizer.Strip(request.OrderDetails?.CertificateInformation?.DomainName), + Constants.Api.GenerateOrderSslPath, (int)resp.StatusCode, sw.ElapsedMilliseconds); + throw new Exception( + "CERTInext reported a duplicate order transaction (EMS-947). If an order was created " + + "for this transaction it will be imported by the next synchronization — do not resubmit " + + "immediately. See gateway logs for details."); + } + throw new Exception( - $"CERTInext order failed: {result.Meta.ErrorMessage ?? result.Meta.ErrorCode}. " + + $"CERTInext order failed: {MaskCaText(result.Meta.ErrorMessage) ?? result.Meta.ErrorCode}. " + "See gateway logs for details."); } @@ -300,7 +416,9 @@ public async Task SubmitCsrAsync(SubmitCsrRequest request, CancellationToken ct req.AddJsonBody(JsonSerializer.Serialize(request, GetJsonOptions())); var sw = System.Diagnostics.Stopwatch.StartNew(); - var resp = await ExecuteWithRetryAsync(req, ct); + // idempotent:false — submitting a CSR is non-idempotent; do not resend on a network + // timeout (the first attempt may have been received). See PlaceOrderAsync. + var resp = await ExecuteWithRetryAsync(req, ct, idempotent: false); sw.Stop(); Logger.LogInformation( @@ -310,6 +428,23 @@ public async Task SubmitCsrAsync(SubmitCsrRequest request, CancellationToken ct if (!resp.IsSuccessful) { LogApiFailure(Constants.Api.SubmitCsrPath, resp); + // Parity with PlaceOrderAsync: a transient/network failure on this non-idempotent + // submit was NOT retried, so record that decision (the CSR may already have been + // received). 4xx client errors fall through to the generic failure below. + bool transientFailure = !((int)resp.StatusCode >= 400 && (int)resp.StatusCode < 500); + if (transientFailure) + { + Logger.LogWarning( + "SubmitCSR received no usable response (OrderNumber={OrderNumber}, HttpStatus={Status}, " + + "LatencyMs={Latency}); not retrying (non-idempotent). If CERTInext already received the CSR, " + + "do not resubmit immediately.", + request.OrderDetails?.OrderNumber, (int)resp.StatusCode, sw.ElapsedMilliseconds); + // Parity with PlaceOrderAsync: carry the actionable guidance into the surfaced + // exception, not only the log line. + throw new Exception( + "CERTInext did not return a usable response to the CSR submission. If the CSR was received " + + "it will take effect — do not resubmit immediately. See gateway logs for details."); + } throw new Exception($"CERTInext SubmitCSR failed. HTTP {(int)resp.StatusCode}. See gateway logs for details."); } @@ -354,6 +489,10 @@ public async Task TrackOrderAsync(string orderNumber, Cancel } var result = DeserializeOrThrow(resp, $"track order {orderNumber}"); + // Guarded: full syncs call TrackOrder thousands of times; skip redaction when Trace is off. + if (Logger.IsEnabled(LogLevel.Trace)) + Logger.LogTrace("TrackOrderAsync response payload (Order={OrderNumber}): {Payload}", + orderNumber, ApplyLoggingRedaction(resp.Content, _config.LogSensitiveRequestData)); // A meta status of "0" with errorCode EMS-913 or similar means the order was not found if (result.Meta != null && !result.Meta.IsSuccess) @@ -363,10 +502,10 @@ public async Task TrackOrderAsync(string orderNumber, Cancel if (result.Meta.ErrorCode != null && (result.Meta.ErrorCode.StartsWith("EMS-9") || result.Meta.ErrorMessage?.Contains("not found", StringComparison.OrdinalIgnoreCase) == true)) { - throw new KeyNotFoundException($"Order '{orderNumber}' was not found in CERTInext. Error: {result.Meta.ErrorMessage}"); + throw new KeyNotFoundException($"Order '{orderNumber}' was not found in CERTInext. Error: {MaskCaText(result.Meta.ErrorMessage)}"); } throw new Exception( - $"CERTInext TrackOrder failed for order '{orderNumber}': {result.Meta.ErrorMessage ?? result.Meta.ErrorCode}."); + $"CERTInext TrackOrder failed for order '{orderNumber}': {MaskCaText(result.Meta.ErrorMessage) ?? result.Meta.ErrorCode}."); } Logger.MethodExit(LogLevel.Trace); @@ -415,7 +554,7 @@ public async Task DownloadCertificateAsync(string orderN LogApiFailure($"{Constants.Api.GetCertificatePath} {orderNumber}", resp, result.Meta.ErrorCode, result.Meta.ErrorMessage); throw new Exception( - $"CERTInext GetCertificate failed for order '{orderNumber}': {result.Meta.ErrorMessage ?? result.Meta.ErrorCode}."); + $"CERTInext GetCertificate failed for order '{orderNumber}': {MaskCaText(result.Meta.ErrorMessage) ?? result.Meta.ErrorCode}."); } Logger.MethodExit(LogLevel.Trace); @@ -458,7 +597,8 @@ public async Task RevokeOrderAsync(RevokeOrderRequest request, CancellationToken } string errMsg = ExtractErrorMessage(resp.Content, - $"revoke order {request.RevocationDetails?.OrderNumber}"); + $"revoke order {request.RevocationDetails?.OrderNumber}", + logSensitiveRequestData: _config.LogSensitiveRequestData); Logger.LogError( "RevokeOrder API call failed. OrderNumber={OrderNumber}, HttpStatus={Status}, Error={Error}", request.RevocationDetails?.OrderNumber, (int)resp.StatusCode, errMsg); @@ -478,7 +618,7 @@ public async Task RevokeOrderAsync(RevokeOrderRequest request, CancellationToken resp, revResp.Meta.ErrorCode, revResp.Meta.ErrorMessage); throw new Exception( $"CERTInext RevokeOrder returned failure for order " + - $"'{request.RevocationDetails?.OrderNumber}': {revResp.Meta.ErrorMessage ?? revResp.Meta.ErrorCode}."); + $"'{request.RevocationDetails?.OrderNumber}': {MaskCaText(revResp.Meta.ErrorMessage) ?? revResp.Meta.ErrorCode}."); } } catch (JsonException) @@ -647,9 +787,11 @@ public async Task EnrollCertificateAsync( // If the CSR was provided in the legacy request, submit it now if not already included in the order // (The real API accepts CSR inline in GenerateOrderSSL; the legacy flow may not have set it) - // Poll TrackOrder to get the current status - var trackResp = await TrackOrderAsync(orderNumber, ct); - string certStatusId = trackResp.OrderDetails?.CertificateStatusId ?? "1"; + // Poll TrackOrder to get the current status. The order already exists at CERTInext + // (and is paid for), so a failure here must not fail the enrollment — see + // TryTrackOrderAfterPlacementAsync. + var trackResp = await TryTrackOrderAfterPlacementAsync(orderNumber, "enrollment", ct); + string certStatusId = trackResp?.OrderDetails?.CertificateStatusId ?? "1"; // Try to download the certificate if the order is fulfilled string pemCert = null; @@ -678,7 +820,7 @@ public async Task EnrollCertificateAsync( Certificate = pemCert, SerialNumber = serialNumber, ProfileId = request.ProfileId, - Message = trackResp.OrderDetails?.CertificateStatus + Message = trackResp?.OrderDetails?.CertificateStatus }; Logger.LogInformation( @@ -710,30 +852,57 @@ public async Task RenewCertificateAsync( throw new KeyNotFoundException($"Cannot renew: prior order '{certificateId}' was not found in CERTInext."); } - // We don't have the product code from TrackOrder — build an order using - // the config defaults and the CSR from the renewal request. + // Primary domain for the renewal order. Prefer the CN of the subject Command gave + // us; the prior order's requestorName is only a last resort and is not a domain — + // it is retained solely so an old caller that sets no Subject still gets a domain. + // Hoisted: the same parse drives both the domain and the "did we get a CN?" warning, + // mirroring BuildOrderRequestFromLegacyEnrollRequest. + string subjectCn = ExtractCnFromSubject(request.Subject); + + string renewalDomainName = + subjectCn + ?? priorTrack.OrderDetails?.RequestorInformation?.RequestorName + ?? "unknown"; + + if (subjectCn == null) + { + Logger.LogWarning( + "Renewal of order {PriorId} has no usable CN in its subject; falling back to " + + "DomainName='{DomainName}' from the prior order. Verify the renewed certificate's " + + "primary domain.", + certificateId, LogSanitizer.Strip(renewalDomainName)); + } + + // Prefer the template's own product code (threaded through via request.ProfileId); + // only fall back to the connector-level default when the caller didn't supply one. + // EnrollmentParams.ProductCode never returns null (it returns string.Empty when it + // can't resolve a code), so this must be a blank check, not a null-coalesce — a + // null-coalesce here would make the DefaultProductCode fallback unreachable, the + // same dead-fallback bug that made DefaultProductCode a no-op for new enrollments. + string renewalProductCode = string.IsNullOrWhiteSpace(request.ProfileId) + ? (_config.DefaultProductCode ?? string.Empty) + : request.ProfileId; + + // Same order-details builder as new enrollment, so a renewal sends every field a new + // order does (groupNumber, autoSecureWWW, technicalPointOfContact, organizationDetails, + // remarks) and follows the connector's validity / autoRenew / emailNotifications / + // accountingModel settings plus the ValidityYears/Days/Comment the plugin passes. var orderReq = new GenerateOrderSslRequest { Meta = await BuildMetaAsync(ct), - OrderDetails = new SslOrderDetails - { - ProductCode = _config.DefaultProductCode ?? string.Empty, - SaveAndHold = "0", - RequestorInformation = new RequestorInformation - { - RequestorName = request.RequesterName ?? _config.RequestorName, - RequestorEmail = request.RequesterEmail ?? _config.RequestorEmail, - RequestorIsdCode = _config.RequestorIsdCode ?? "1", - RequestorMobileNumber = _config.RequestorMobileNumber ?? string.Empty - }, - SubscriptionDetails = new SubscriptionDetails { Validity = "1" }, - CertificateInformation = new CertificateInformation - { - DomainName = priorTrack.OrderDetails?.RequestorInformation?.RequestorName ?? "unknown" - }, - Csr = request.Csr, - AgreementDetails = BuildDefaultAgreementDetails() - } + OrderDetails = BuildSslOrderDetails( + productCode: renewalProductCode, + domainName: renewalDomainName, + sans: request.Sans, + csr: request.Csr, + validityYears: request.ValidityYears, + validityDays: request.ValidityDays, + requesterName: request.RequesterName, + requesterEmail: request.RequesterEmail, + comment: request.Comment, + signerName: request.SignerName, + signerPlace: request.SignerPlace, + signerIp: request.SignerIp) }; var orderResp = await PlaceOrderAsync(orderReq, ct); @@ -742,8 +911,10 @@ public async Task RenewCertificateAsync( if (string.IsNullOrWhiteSpace(newOrderNumber)) throw new Exception("CERTInext renewal order placement succeeded but returned no orderNumber."); - var trackResp = await TrackOrderAsync(newOrderNumber, ct); - string certStatusId = trackResp.OrderDetails?.CertificateStatusId ?? "1"; + // Same post-placement rule as enrollment: the renewal order exists, so a TrackOrder + // failure degrades to a pending result instead of failing the renewal. + var trackResp = await TryTrackOrderAfterPlacementAsync(newOrderNumber, "renewal", ct); + string certStatusId = trackResp?.OrderDetails?.CertificateStatusId ?? "1"; string pemCert = null; string serialNumber = null; @@ -767,7 +938,7 @@ public async Task RenewCertificateAsync( Status = MapCertStatusIdToLegacyString(certStatusId), Certificate = pemCert, SerialNumber = serialNumber, - Message = trackResp.OrderDetails?.CertificateStatus + Message = trackResp?.OrderDetails?.CertificateStatus }; Logger.LogInformation( @@ -777,6 +948,44 @@ public async Task RenewCertificateAsync( return legacyResp; } + /// + /// Looks up the status of an order that GenerateOrderSSL has just placed. The order + /// already exists at CERTInext (and is paid for), so a failure here — a transient 5xx, a + /// timeout, or an EMS-9xx "not found" during propagation lag surfacing as + /// — must not fail the enrollment/renewal: that would hide + /// the order number from Command and let an operator retry place a duplicate paid order. + /// On failure this logs a Warning naming the order and returns null; the callers then + /// treat the status as unknown (pending), so sync and pickup finish the order later. + /// A genuine cancellation ( cancelled) still propagates; an + /// with a live token (an HTTP-timeout + /// ) is treated like any other failure. + /// + private async Task TryTrackOrderAfterPlacementAsync( + string orderNumber, string operation, CancellationToken ct) + { + try + { + return await TrackOrderAsync(orderNumber, ct); + } + catch (OperationCanceledException) when (ct.IsCancellationRequested) + { + Logger.LogWarning( + "CERTInext {Operation} was cancelled after order {OrderNumber} was placed. The order exists at " + + "CERTInext and will be imported by the next synchronization.", + operation, orderNumber); + throw; + } + catch (Exception ex) + { + Logger.LogWarning(ex, + "TrackOrder failed after order {OrderNumber} was placed ({Operation}); the order exists at " + + "CERTInext. Returning a pending result carrying the order number; the certificate will be " + + "retrieved during next synchronization.", + orderNumber, operation); + return null; + } + } + /// public async Task GetCertificateAsync( string certificateId, @@ -967,7 +1176,7 @@ public async Task GetDcvAsync( $"{Constants.Api.GetDcvPath} {orderNumber}/{domainName}", resp, result.Meta.ErrorCode, result.Meta.ErrorMessage); throw new Exception( - $"CERTInext GetDcv failed for order '{orderNumber}' domain '{domainName}': {result.Meta.ErrorMessage ?? result.Meta.ErrorCode}."); + $"CERTInext GetDcv failed for order '{orderNumber}' domain '{domainName}': {MaskCaText(result.Meta.ErrorMessage) ?? result.Meta.ErrorCode}."); } // SOX CC7.3: log token presence (never value) so each DCV step is independently @@ -1040,7 +1249,7 @@ public async Task VerifyDcvAsync( $"{Constants.Api.VerifyDcvPath} {orderNumber}/{domainName}", resp, verifyResp.Meta.ErrorCode, verifyResp.Meta.ErrorMessage); throw new Exception( - $"CERTInext VerifyDcv returned failure for order '{orderNumber}' domain '{domainName}': {verifyResp.Meta.ErrorMessage ?? verifyResp.Meta.ErrorCode}."); + $"CERTInext VerifyDcv returned failure for order '{orderNumber}' domain '{domainName}': {MaskCaText(verifyResp.Meta.ErrorMessage) ?? verifyResp.Meta.ErrorCode}."); } } catch (JsonException) { /* non-JSON 200 body is acceptable */ } @@ -1143,258 +1352,1470 @@ private static string GenerateTxnId() /// /// Returns a valid OAuth2 access token, refreshing it if expired. Thread-safe. /// - private async Task GetOrRefreshTokenAsync(CancellationToken ct) - { - if (!string.IsNullOrEmpty(_cachedToken) && DateTime.UtcNow < _tokenExpiry) - return _cachedToken; - - await _tokenLock.WaitAsync(ct); - try - { - if (!string.IsNullOrEmpty(_cachedToken) && DateTime.UtcNow < _tokenExpiry) - return _cachedToken; - - Logger.LogInformation( - "OAuth2 token acquisition attempt started. TokenUrl={TokenUrl}, ClientId={ClientId}", - _config.OAuthTokenUrl, _config.OAuthClientId); - - using var tokenClient = new RestClient(_config.OAuthTokenUrl); - var tokenReq = new RestRequest(string.Empty, Method.Post); - tokenReq.AddHeader("Content-Type", "application/x-www-form-urlencoded"); - tokenReq.AddParameter("grant_type", "client_credentials"); - tokenReq.AddParameter("client_id", _config.OAuthClientId); - tokenReq.AddParameter("client_secret", _config.OAuthClientSecret); - - var tokenResp = await tokenClient.ExecuteAsync(tokenReq, ct); - if (!tokenResp.IsSuccessful || string.IsNullOrWhiteSpace(tokenResp.Content)) - { - // SOX CC6.1 (credential confidentiality): NEVER log tokenResp.Content, - // tokenResp.ErrorMessage, or tokenResp.ErrorException — RestSharp's - // failure paths can echo the original request including the - // `client_secret` form value. Only StatusCode + non-secret config - // identifiers are safe to log here. - Logger.LogError( - "OAuth2 token acquisition failed. TokenUrl={TokenUrl}, ClientId={ClientId}, HttpStatus={Status}", - _config.OAuthTokenUrl, _config.OAuthClientId, (int)tokenResp.StatusCode); - throw new Exception( - $"Failed to obtain OAuth2 token from CERTInext. HTTP {(int)tokenResp.StatusCode}. See gateway logs for details."); - } - - var tokenPayload = JsonSerializer.Deserialize(tokenResp.Content, GetJsonOptions()); + // --------------------------------------------------------------------------- + // ICERTInextClient — V2 REST API methods + // --------------------------------------------------------------------------- - if (tokenPayload == null || string.IsNullOrEmpty(tokenPayload.AccessToken)) - { - Logger.LogError( - "OAuth2 token acquisition failed — response did not contain access_token. TokenUrl={TokenUrl}", - _config.OAuthTokenUrl); - throw new Exception("OAuth2 token response from CERTInext did not contain an access_token."); - } + /// + public async Task GetAuthMeV2Async(CancellationToken ct = default) + { + Logger.MethodEntry(LogLevel.Trace); + EnsureV2Client(); + var req = await BuildV2RequestAsync(Constants.ApiV2.AuthMePath, Method.Get, ct); + var resp = await _httpV2.ExecuteAsync(req, ct); + ThrowOnV2Failure(resp, "auth/me"); + var result = DeserializeV2OrThrow(resp, "auth/me"); + Logger.MethodExit(LogLevel.Trace); + return result; + } - _cachedToken = tokenPayload.AccessToken; - _tokenExpiry = DateTime.UtcNow.AddSeconds(Math.Max(tokenPayload.ExpiresIn - 60, 30)); + /// + public async Task PingV2Async(CancellationToken ct = default) + { + Logger.MethodEntry(LogLevel.Trace); + var me = await GetAuthMeV2Async(ct); + Logger.LogInformation( + "CERTInext V2 ping successful. AccountNumber={AccountNumber}, AuthType={AuthType}", + me.AccountNumber, me.AuthType); + Logger.MethodExit(LogLevel.Trace); + } - Logger.LogInformation( - "OAuth2 token acquired. TokenUrl={TokenUrl}, ClientId={ClientId}, ExpiresAt={Expiry:u}", - _config.OAuthTokenUrl, _config.OAuthClientId, _tokenExpiry); - return _cachedToken; - } - finally - { - _tokenLock.Release(); - } + /// + public async Task PlaceOrderV2Async( + string productFamilySlug, + string productCode, + V2CreateSslOrderRequest request, + CancellationToken ct = default) + { + // The SSL-shaped body must only ever go to the SSL endpoint: substituting the slug + // into the URL unchecked would let a private-pki/signature template silently send + // this body to the wrong family's create endpoint. + if (!string.Equals(productFamilySlug, Constants.ApiV2.FamilySsl, StringComparison.OrdinalIgnoreCase)) + throw new ArgumentException( + $"A V2 SSL/TLS order body can only be sent to the '{Constants.ApiV2.FamilySsl}' family, " + + $"not '{productFamilySlug}'. Use the Private PKI or Document Signer PlaceOrderV2Async overload.", + nameof(productFamilySlug)); + + return await PlaceOrderV2CoreAsync(Constants.ApiV2.SslCertificatesPath, productCode, request, ct); } - // --------------------------------------------------------------------------- - // Retry helper - // --------------------------------------------------------------------------- + /// + public Task PlaceOrderV2Async( + string productCode, + V2CreatePrivatePkiOrderRequest request, + CancellationToken ct = default) + => PlaceOrderV2CoreAsync(Constants.ApiV2.PrivatePkiCertificatesPath, productCode, request, ct); + + /// + public Task PlaceOrderV2Async( + string productCode, + V2CreateSignatureOrderRequest request, + CancellationToken ct = default) + => PlaceOrderV2CoreAsync(Constants.ApiV2.SignatureCertificatesPath, productCode, request, ct); /// - /// Executes a with up to - /// attempts, retrying on HTTP 5xx and network-level failures (no status code). - /// 4xx responses are returned immediately — client errors will not be resolved - /// by retrying. + /// Shared V2 create-order transport for every product family: POSTs the + /// family-specific body to with the X-Product-Code and + /// Idempotency-Key headers. Request and response bodies are only ever logged (Trace) + /// through , so credentials are always scrubbed and + /// requestor/subject PII is scrubbed unless LogSensitiveRequestData is on. + /// X-Product-Code is the spec's "Optional override" on SSL, Private PKI and Document Signer + /// create: when it is absent the CERTInext wrapper resolves the catalog product itself + /// (from productVariant/variant, the wildcard shape of certificate.domain + /// and whether additionalDomains is non-empty). A null/blank + /// therefore omits the header entirely rather than sending it + /// empty, which is not itself a valid override value. /// - private async Task ExecuteWithRetryAsync( - RestRequest req, - CancellationToken ct, - int maxAttempts = 3) + private async Task PlaceOrderV2CoreAsync( + string path, + string productCode, + TRequest request, + CancellationToken ct) { - RestResponse resp = null; - for (int attempt = 1; attempt <= maxAttempts; attempt++) + Logger.MethodEntry(LogLevel.Trace); + EnsureV2Client(); + string idempotencyKey = Guid.NewGuid().ToString(); + var req = await BuildV2RequestAsync(path, Method.Post, ct, idempotencyKey); + if (!string.IsNullOrWhiteSpace(productCode)) + req.AddHeader("X-Product-Code", productCode); + string json = JsonSerializer.Serialize(request, GetJsonOptions()); + if (Logger.IsEnabled(LogLevel.Trace)) + Logger.LogTrace("PlaceOrderV2Async request payload: {Payload}", + ApplyLoggingRedaction(json, _config.LogSensitiveRequestData)); + req.AddJsonBody(json); + var sw = System.Diagnostics.Stopwatch.StartNew(); + var resp = await _httpV2.ExecuteAsync(req, ct); + sw.Stop(); + Logger.LogInformation( + "CERTInext V2 API call: Method=POST, Path={Path}, HttpStatus={Status}, LatencyMs={Latency}", + path, (int)resp.StatusCode, sw.ElapsedMilliseconds); + if (Logger.IsEnabled(LogLevel.Trace)) + Logger.LogTrace("PlaceOrderV2Async response: {Body}", + ApplyLoggingRedaction(resp.Content, _config.LogSensitiveRequestData)); + + // Transient/network failure (5xx or no HTTP status) on a non-idempotent create: the + // order may exist at the CA (with V2InlineCsr it carries the CSR and may even issue). + // Never retried (a replay could duplicate the order). Same wording as V1's + // PlaceOrderAsync so operators see one message for "created but we never heard back". + // 401/403 and 4xx keep their dedicated handling in ThrowOnV2Failure below. + // Only for an inline-CSR SSL create: in the two-call flow an order created behind a lost + // response has no CSR, never issues, and resubmitting is the right move (af036ae behaviour). + bool inlineCsrCreate = _config.V2InlineCsr + && string.Equals(path, Constants.ApiV2.SslCertificatesPath, StringComparison.Ordinal); + int createStatus = (int)resp.StatusCode; + if (inlineCsrCreate && !resp.IsSuccessful && (createStatus == 0 || createStatus >= 500)) { - resp = await _http.ExecuteAsync(req, ct); - - // Success or 4xx client error — return immediately - bool isClientError = (int)resp.StatusCode >= 400 && (int)resp.StatusCode < 500; - if (resp.IsSuccessful || isClientError) - return resp; - - if (attempt < maxAttempts) - { - Logger.LogWarning( - "CERTInext API returned {Status} on attempt {Attempt}/{Max} — retrying...", - (int)resp.StatusCode, attempt, maxAttempts); - } + LogV2ApiFailure("V2 place order", resp, LogLevel.Warning); + Logger.LogWarning( + "V2 place order received no usable response (Path={Path}, HttpStatus={Status}, LatencyMs={Latency}). " + + "Not retrying to avoid a duplicate order. If CERTInext created the order it will be imported by " + + "the next synchronization.", + path, createStatus, sw.ElapsedMilliseconds); + throw new Exception( + "CERTInext did not return a usable response to the V2 order create " + + (createStatus == 0 ? "(no HTTP response)" : $"(HTTP {createStatus})") + + ". If the order was created it will be imported by the next synchronization — do not " + + "resubmit immediately. See gateway logs for details."); } - - // Return the last response (caller handles the error) - return resp; - } - - // --------------------------------------------------------------------------- - // Legacy helper — maps legacy reason string to CRL code - // --------------------------------------------------------------------------- - - private static uint MapLegacyReasonStringToCrlCode(string reason) - { - switch (reason?.ToLowerInvariant()) + ThrowOnV2Failure(resp, "V2 place order"); + V2CreateOrderResponse result; + try { - case "keycompromise": return 1; - case "cacompromise": return 2; - case "affiliationchanged": return 3; - case "superseded": return 4; - case "cessationofoperation": return 5; - case "certificatehold": return 6; - case "removefromcrl": return 8; - case "privilegewithdrawn": return 9; - case "aacompromise": return 10; - default: return 0; // unspecified -> maps to KeyCompromise in ToRevocationReasonId + result = DeserializeV2OrThrow(resp, "V2 place order"); + } + catch (Exception deserEx) when (inlineCsrCreate) + { + // A 2xx whose body is empty/unparseable: the CA accepted the create but we cannot read + // the order id, so the order exists and the next sync imports it. + Logger.LogWarning(deserEx, + "V2 place order returned HTTP {Status} but the body could not be read; the order may exist. " + + "Not retrying to avoid a duplicate order.", (int)resp.StatusCode); + throw new Exception( + "CERTInext accepted the V2 order create but returned no readable order id. The order was " + + "most likely created and will be imported by the next synchronization — do not resubmit " + + "immediately. See gateway logs for details.", deserEx); } + Logger.MethodExit(LogLevel.Trace); + return result; } - private static bool IsCertificateDownloadable(string certStatusId) + /// + public async Task SubmitCsrV2Async( + string productFamilySlug, + string orderId, + string csrPem, + CancellationToken ct = default) { - if (!int.TryParse(certStatusId, out int id)) return false; - return id == Constants.CertificateStatusId.CertificateGenerated || - id == Constants.CertificateStatusId.CertificateDownloaded || - id == Constants.CertificateStatusId.OrderAutoApproved || - id == Constants.CertificateStatusId.RekeyApproved || - id == Constants.CertificateStatusId.ApprovedBySecondApprover; + Logger.MethodEntry(LogLevel.Trace); + EnsureV2Client(); + string path = BuildV2OrderPath(productFamilySlug, orderId) + "/csr"; + var req = await BuildV2RequestAsync(path, Method.Put, ct); + var body = new V2SubmitCsrRequest { Csr = csrPem }; + req.AddJsonBody(JsonSerializer.Serialize(body, GetJsonOptions())); + var resp = await _httpV2.ExecuteAsync(req, ct); + ThrowOnV2Failure(resp, "V2 submit CSR"); + Logger.MethodExit(LogLevel.Trace); } - private static string MapCertStatusIdToLegacyString(string certStatusId) + /// + public async Task TrackOrderV2Async( + string productFamilySlug, + string orderId, + CancellationToken ct = default) { - if (!int.TryParse(certStatusId, out int id)) return "pending"; - int disposition = StatusMapper.CertificateStatusIdToRequestDisposition(id); - switch (disposition) + Logger.MethodEntry(LogLevel.Trace); + EnsureV2Client(); + string path = BuildV2OrderPath(productFamilySlug, orderId); + var req = await BuildV2RequestAsync(path, Method.Get, ct); + var resp = await _httpV2.ExecuteAsync(req, ct); + if (resp.StatusCode == HttpStatusCode.NotFound) { - case (int)Keyfactor.PKI.Enums.EJBCA.EndEntityStatus.GENERATED: return "issued"; - case (int)Keyfactor.PKI.Enums.EJBCA.EndEntityStatus.REVOKED: return "revoked"; - case (int)Keyfactor.PKI.Enums.EJBCA.EndEntityStatus.EXTERNALVALIDATION: return "pending_approval"; - case (int)Keyfactor.PKI.Enums.EJBCA.EndEntityStatus.FAILED: return "failed"; - default: return "pending"; + Logger.MethodExit(LogLevel.Trace); + throw new KeyNotFoundException($"V2 order '{orderId}' not found in family '{productFamilySlug}'."); } + ThrowOnV2Failure(resp, "V2 track order"); + var result = DeserializeV2OrThrow(resp, "V2 track order"); + Logger.MethodExit(LogLevel.Trace); + return result; } - private static LegacyGetCertificateResponse MapOrderReportEntryToLegacy(OrderReportEntry entry) + /// + public async Task DownloadCertificateV2Async( + string productFamilySlug, + string orderId, + CancellationToken ct = default) { - // Note: GetOrderReport does not return requestor name/email in the ordersArray. - // Those fields are only available via TrackOrder on individual orders. - System.DateTime? orderDate = null; - if (!string.IsNullOrWhiteSpace(entry.OrderDate) - && System.DateTime.TryParse(entry.OrderDate, - System.Globalization.CultureInfo.InvariantCulture, - System.Globalization.DateTimeStyles.AssumeUniversal | System.Globalization.DateTimeStyles.AdjustToUniversal, - out var parsed)) + Logger.MethodEntry(LogLevel.Trace); + EnsureV2Client(); + string path = BuildV2OrderPath(productFamilySlug, orderId) + "/certificate"; + var req = await BuildV2RequestAsync(path, Method.Get, ct); + var resp = await _httpV2.ExecuteAsync(req, ct); + if (resp.StatusCode == HttpStatusCode.NotFound) { - orderDate = parsed; + Logger.MethodExit(LogLevel.Trace); + throw new KeyNotFoundException($"V2 certificate for order '{orderId}' not found in family '{productFamilySlug}'."); } - - return new LegacyGetCertificateResponse + if (resp.StatusCode == (HttpStatusCode)422 + && resp.Content != null + && resp.Content.IndexOf("EMS-1165", StringComparison.OrdinalIgnoreCase) >= 0) { - Id = string.IsNullOrWhiteSpace(entry.OrderNumber) ? entry.RequestNumber : entry.OrderNumber, - Status = MapCertStatusIdToLegacyString(entry.CertificateStatusId), - Subject = entry.DomainName, - ProfileId = entry.ProductCode, - OrderDate = orderDate - }; + // 422 EMS-1165 ("Invalid request status") right after Track Order reports `issued` is + // the "issued at the CA, certificate not generated yet" window (normally ~20 s), and + // callers poll through it, so it is logged at Debug here (one line per attempt) instead + // of the Warning every other failure gets. The same code also means "never + // downloadable" for a revoked order; whether it is transient is the caller's call. + LogV2ApiFailure("V2 download certificate", resp, LogLevel.Debug); + string detail = ExtractV2ErrorMessage(resp.Content, "V2 download certificate", _config.LogSensitiveRequestData); + Logger.MethodExit(LogLevel.Trace); + throw new V2CertificateNotGeneratedException( + $"CERTInext V2 API error during 'V2 download certificate'. HTTP 422. {detail}"); + } + ThrowOnV2Failure(resp, "V2 download certificate"); + var result = DeserializeV2OrThrow(resp, "V2 download certificate"); + Logger.MethodExit(LogLevel.Trace); + return result; } - private GenerateOrderSslRequest BuildOrderRequestFromLegacyEnrollRequest(EnrollCertificateRequest request) + /// + public async Task RevokeOrderV2Async( + string productFamilySlug, + string orderId, + V2RevokeRequest request, + CancellationToken ct = default) { - // Map ValidityDays → CERTInext's year-based validity. Default 1. - string validityYears = request.ValidityDays.HasValue - ? Math.Ceiling(request.ValidityDays.Value / 365.0).ToString("0") - : (string.IsNullOrWhiteSpace(_config.SubscriptionValidityYears) - ? "1" - : _config.SubscriptionValidityYears); - - string requestorName = request.RequesterName ?? _config.RequestorName ?? "Keyfactor Gateway"; - string requestorEmail = request.RequesterEmail ?? _config.RequestorEmail ?? string.Empty; - string requestorIsd = string.IsNullOrWhiteSpace(_config.RequestorIsdCode) ? "1" : _config.RequestorIsdCode; - string requestorMobile = _config.RequestorMobileNumber ?? string.Empty; - - return new GenerateOrderSslRequest + Logger.MethodEntry(LogLevel.Trace); + EnsureV2Client(); + string idempotencyKey = Guid.NewGuid().ToString(); + string path = BuildV2OrderPath(productFamilySlug, orderId) + "/revoke"; + var req = await BuildV2RequestAsync(path, Method.Post, ct, idempotencyKey); + req.AddJsonBody(JsonSerializer.Serialize(request, GetJsonOptions())); + var resp = await _httpV2.ExecuteAsync(req, ct); + if (resp.StatusCode == HttpStatusCode.NotFound) { - // Meta will be set by PlaceOrderAsync - OrderDetails = new SslOrderDetails - { - ProductCode = request.ProfileId ?? _config.DefaultProductCode ?? string.Empty, - AccountingModel = string.IsNullOrWhiteSpace(_config.AccountingModel) ? "2" : _config.AccountingModel, - SaveAndHold = "0", - EmailNotifications = string.IsNullOrWhiteSpace(_config.EmailNotifications) ? "0" : _config.EmailNotifications, - - // delegationInformation — routes the order to the configured account group. - // Omitted entirely when GroupNumber is blank (the model JsonIgnore-WhenNull - // handles property absence further down). - DelegationInformation = !string.IsNullOrWhiteSpace(_config.GroupNumber) - ? new DelegationInformation { GroupNumber = _config.GroupNumber } - : null, - - // organizationDetails — declares pre-vetted org when configured. This is the - // single biggest factor in how quickly CERTInext releases an order from - // Pending System RA. When OrganizationNumber is blank we omit the whole - // block (the model is JsonIgnore-WhenNull) so the order falls back to the - // unvetted path — same behavior as the prior plugin builds. - OrganizationDetails = !string.IsNullOrWhiteSpace(_config.OrganizationNumber) - ? new OrganizationDetails + // Compliance finding: a revoke denial must leave an audit trail (SOX/SOC2 + // who/what/when/outcome) even though this branch returns before + // ThrowOnV2Failure/LogV2ApiFailure would otherwise run it. Log explicitly with + // the order/family identity plus the usual HTTP-status+redacted-body line. + Logger.LogWarning( + "V2 revoke denied — order not found or not in a revokable state. " + + "OrderId={OrderId}, ProductFamily={Family}, HttpStatus={HttpStatus}", + orderId, productFamilySlug, (int)resp.StatusCode); + LogV2ApiFailure("V2 revoke order", resp, LogLevel.Warning); + Logger.MethodExit(LogLevel.Trace); + // Per the V2 spec ("Revoke Certificate", 404 response): "Order not found + // or not in a revokable state." This is deliberately ambiguous on the + // wire — callers that have already confirmed the order lives in + // `productFamilySlug` (e.g. via TrackOrderV2Async) should treat a 404 + // here as "not revokable", not as a family miss. + throw new KeyNotFoundException( + $"V2 order '{orderId}' in family '{productFamilySlug}' not found or not in a revokable state."); + } + if (resp.StatusCode == (HttpStatusCode)422) + { + // Label by whatever EMS code/detail CERTInext actually returned rather + // than presuming "not in issued state" — 422s here cover multiple + // distinct conditions (EMS-969 revoke reason ID missing, sandbox-timing + // "Certificate Request still being processed", etc.). + string detail = ExtractV2ErrorMessage(resp.Content, "V2 revoke", _config.LogSensitiveRequestData); + // Compliance finding: same audit-trail requirement as the 404 branch above — + // this also returns before ThrowOnV2Failure would otherwise log it. + Logger.LogWarning( + "V2 revoke rejected. OrderId={OrderId}, ProductFamily={Family}, HttpStatus={HttpStatus}, " + + "Detail={Detail}", + orderId, productFamilySlug, (int)resp.StatusCode, detail); + LogV2ApiFailure("V2 revoke order", resp, LogLevel.Warning); + throw new InvalidOperationException($"V2 revoke rejected. {detail}"); + } + ThrowOnV2Failure(resp, "V2 revoke order"); + Logger.MethodExit(LogLevel.Trace); + } + + /// + public async Task AcceptAgreementV2Async( + string productFamilySlug, + string orderId, + V2AgreementParams agreement, + CancellationToken ct = default) + { + Logger.MethodEntry(LogLevel.Trace); + // The accept-agreement endpoint is documented for the SSL/TLS family only (Private PKI has + // "no Subscriber Agreement"); never send it to another family's path. + if (!string.Equals(productFamilySlug, Constants.ApiV2.FamilySsl, StringComparison.OrdinalIgnoreCase)) + throw new ArgumentException( + $"Accepting a Subscriber Agreement is only supported for the '{Constants.ApiV2.FamilySsl}' " + + $"family, not '{productFamilySlug}'.", nameof(productFamilySlug)); + if (agreement == null) throw new ArgumentNullException(nameof(agreement)); + EnsureV2Client(); + string path = BuildV2OrderPath(productFamilySlug, orderId) + "/agreement"; + var req = await BuildV2RequestAsync(path, Method.Post, ct); + req.AddJsonBody(JsonSerializer.Serialize(new V2AcceptAgreementRequest { Agreement = agreement }, GetJsonOptions())); + var sw = System.Diagnostics.Stopwatch.StartNew(); + var resp = await _httpV2.ExecuteAsync(req, ct); + sw.Stop(); + Logger.LogInformation( + "CERTInext V2 API call: Method=POST, Path={Path}, HttpStatus={Status}, LatencyMs={Latency}", + path, (int)resp.StatusCode, sw.ElapsedMilliseconds); + ThrowOnV2Failure(resp, "V2 accept agreement"); + Logger.MethodExit(LogLevel.Trace); + } + + // --------------------------------------------------------------------------- + // SSL.com organization validation (V2) + // --------------------------------------------------------------------------- + + private static string BuildSslComValidationPath(string organizationNumber) + { + if (string.IsNullOrWhiteSpace(organizationNumber)) + throw new ArgumentException("An organization number is required.", nameof(organizationNumber)); + return $"{Constants.ApiV2.OrganizationsPath}/{Uri.EscapeDataString(organizationNumber.Trim())}/" + + Constants.ApiV2.SslComValidationSuffix; + } + + /// + /// Executes one SSL.com validation call and parses the body. The body carries the SSL.com + /// contact (personal data), so it is only ever logged, at Trace, through + /// . + /// + private async Task ExecuteSslComValidationAsync( + string path, Method method, object body, string operation, bool bodyOptional, CancellationToken ct) + { + EnsureV2Client(); + var req = await BuildV2RequestAsync(path, method, ct); + if (body != null) + req.AddJsonBody(JsonSerializer.Serialize(body, GetJsonOptions())); + var sw = System.Diagnostics.Stopwatch.StartNew(); + var resp = await _httpV2.ExecuteAsync(req, ct); + sw.Stop(); + Logger.LogInformation( + "CERTInext V2 API call: Method={Method}, Path={Path}, HttpStatus={Status}, LatencyMs={Latency}", + method, path, (int)resp.StatusCode, sw.ElapsedMilliseconds); + if (Logger.IsEnabled(LogLevel.Trace)) + Logger.LogTrace("{Operation} response: {Body}", operation, + ApplyLoggingRedaction(resp.Content, _config.LogSensitiveRequestData)); + ThrowOnV2Failure(resp, operation); + if (bodyOptional && string.IsNullOrWhiteSpace(resp.Content)) + return null; + return DeserializeV2OrThrow(resp, operation); + } + + /// + public async Task GetSslComValidationAsync(string organizationNumber, CancellationToken ct = default) + { + Logger.MethodEntry(LogLevel.Trace); + var result = await ExecuteSslComValidationAsync( + BuildSslComValidationPath(organizationNumber), Method.Get, null, "V2 SSL.com validation status", false, ct); + Logger.MethodExit(LogLevel.Trace); + return result; + } + + /// + public async Task SyncSslComValidationAsync(string organizationNumber, CancellationToken ct = default) + { + Logger.MethodEntry(LogLevel.Trace); + var result = await ExecuteSslComValidationAsync( + BuildSslComValidationPath(organizationNumber) + "/sync", Method.Post, null, "V2 SSL.com validation sync", false, ct); + Logger.MethodExit(LogLevel.Trace); + return result; + } + + /// + public async Task SubmitSslComValidationAsync( + string organizationNumber, V2SslComSubmitRequest request, CancellationToken ct = default) + { + Logger.MethodEntry(LogLevel.Trace); + if (request == null) throw new ArgumentNullException(nameof(request)); + var result = await ExecuteSslComValidationAsync( + BuildSslComValidationPath(organizationNumber), Method.Post, request, "V2 SSL.com validation submit", true, ct); + Logger.MethodExit(LogLevel.Trace); + return result; + } + + /// + public async Task CancelOrderV2Async( + string productFamilySlug, + string orderId, + string reason, + CancellationToken ct = default) + { + Logger.MethodEntry(LogLevel.Trace); + if (string.IsNullOrWhiteSpace(reason)) + throw new ArgumentException( + "A cancel reason is required (CERTInext rejects an empty one with EMS-984).", nameof(reason)); + EnsureV2Client(); + string idempotencyKey = Guid.NewGuid().ToString(); + string path = BuildV2OrderPath(productFamilySlug, orderId) + "/cancel"; + var req = await BuildV2RequestAsync(path, Method.Post, ct, idempotencyKey); + req.AddJsonBody(JsonSerializer.Serialize(new V2CancelOrderRequest { Reason = reason }, GetJsonOptions())); + var sw = System.Diagnostics.Stopwatch.StartNew(); + var resp = await _httpV2.ExecuteAsync(req, ct); + sw.Stop(); + Logger.LogInformation( + "CERTInext V2 API call: Method=POST, Path={Path}, HttpStatus={Status}, LatencyMs={Latency}", + path, (int)resp.StatusCode, sw.ElapsedMilliseconds); + if (resp.StatusCode == (HttpStatusCode)422) + { + // Spec "Cancel Order" 422: "order already in a terminal state" (e.g. already + // issued — use /revoke). Not an exception: the caller reports it as "not cancelled". + LogV2ApiFailure("V2 cancel order", resp, LogLevel.Warning); + Logger.MethodExit(LogLevel.Trace); + return V2CancelOrderOutcome.AlreadyTerminal; + } + ThrowOnV2Failure(resp, "V2 cancel order"); + Logger.MethodExit(LogLevel.Trace); + return V2CancelOrderOutcome.Cancelled; + } + + /// + public async Task ResolveAndTrackOrderV2Async( + string orderId, + CancellationToken ct = default) + { + Logger.MethodEntry(LogLevel.Trace); + var (_, status) = await ResolveV2OrderFamilyAsync(orderId, ct); + Logger.MethodExit(LogLevel.Trace); + return status; + } + + /// + public async Task<(string family, V2OrderStatusResponse status)> ResolveAndTrackOrderV2WithFamilyAsync( + string orderId, + CancellationToken ct = default) + { + Logger.MethodEntry(LogLevel.Trace); + var result = await ResolveV2OrderFamilyAsync(orderId, ct); + Logger.MethodExit(LogLevel.Trace); + return result; + } + + /// + public async Task ResolveAndDownloadCertificateV2Async( + string orderId, + CancellationToken ct = default) + { + Logger.MethodEntry(LogLevel.Trace); + var (family, _) = await ResolveV2OrderFamilyAsync(orderId, ct); + var cert = await DownloadCertificateV2Async(family, orderId, ct); + Logger.MethodExit(LogLevel.Trace); + return cert; + } + + /// + public async Task GetDcvV2Async(string orderId, string familySlug, CancellationToken ct = default) + { + Logger.MethodEntry(LogLevel.Trace); + EnsureV2Client(); + string path = $"/api/certinext/v2/{familySlug}/{orderId}/dcv"; + var req = await BuildV2RequestAsync(path, Method.Get, ct); + var resp = await _httpV2.ExecuteAsync(req, ct); + Logger.LogInformation( + "CERTInext V2 API call: Method=GET, Path={Path}, HttpStatus={Status}", + path, (int)resp.StatusCode); + ThrowOnV2Failure(resp, "V2 get DCV challenge"); + var result = DeserializeV2OrThrow(resp, "V2 get DCV challenge"); + Logger.MethodExit(LogLevel.Trace); + return result; + } + + /// + public async Task GetDcvV2Async( + string orderId, string domain, string familySlug, CancellationToken ct = default) + { + Logger.MethodEntry(LogLevel.Trace); + EnsureV2Client(); + // Per-domain scope: returns a distinct token per SAN on a UCC order. + string path = $"/api/certinext/v2/{familySlug}/{orderId}/dcv?domain=" + Uri.EscapeDataString(domain); + var req = await BuildV2RequestAsync(path, Method.Get, ct); + var resp = await _httpV2.ExecuteAsync(req, ct); + Logger.LogInformation( + "CERTInext V2 API call: Method=GET, Path={Path}, HttpStatus={Status}", + path, (int)resp.StatusCode); + ThrowOnV2Failure(resp, "V2 get DCV challenge (per-domain)"); + var result = DeserializeV2OrThrow(resp, "V2 get DCV challenge (per-domain)"); + Logger.MethodExit(LogLevel.Trace); + return result; + } + + /// + public async Task VerifyDcvV2Async(string orderId, string domain, string familySlug, CancellationToken ct = default) + { + Logger.MethodEntry(LogLevel.Trace); + EnsureV2Client(); + string path = $"/api/certinext/v2/{familySlug}/{orderId}/dcv/verify"; + var req = await BuildV2RequestAsync(path, Method.Post, ct); + var body = new V2DcvVerifyRequest { Domain = domain, Method = "dns-txt" }; + req.AddJsonBody(JsonSerializer.Serialize(body, GetJsonOptions())); + var resp = await _httpV2.ExecuteAsync(req, ct); + Logger.LogInformation( + "CERTInext V2 API call: Method=POST, Path={Path}, HttpStatus={Status}", + path, (int)resp.StatusCode); + + if (resp.StatusCode == (HttpStatusCode)422) + { + string detail = ExtractV2ErrorMessage(resp.Content, "V2 verify DCV", _config.LogSensitiveRequestData); + throw new InvalidOperationException( + $"V2 DCV verification failed for order '{orderId}', domain '{domain}'. {detail}"); + } + + // 204 No Content is a valid success — return an empty verified response + if (resp.StatusCode == System.Net.HttpStatusCode.NoContent || string.IsNullOrWhiteSpace(resp.Content)) + { + Logger.MethodExit(LogLevel.Trace); + return new V2DcvVerifyResponse { OverallStatus = "VERIFIED" }; + } + + ThrowOnV2Failure(resp, "V2 verify DCV"); + var result = DeserializeV2OrThrow(resp, "V2 verify DCV"); + Logger.MethodExit(LogLevel.Trace); + return result; + } + + /// + public async Task> GetProductDetailsV2Async(CancellationToken ct = default) + { + Logger.MethodEntry(LogLevel.Trace); + EnsureV2Client(); + + // Scope the catalog to the connector's configured billing group, mirroring V1's + // GetProductDetailsAsync (ProductDetailsFilter.GroupNumber). Omitted entirely when + // unconfigured so the account's default group is used, same as V1. + string path = Constants.ApiV2.CatalogProductsPath; + if (!string.IsNullOrWhiteSpace(_config.GroupNumber)) + path += "?groupNumber=" + Uri.EscapeDataString(_config.GroupNumber); + + var req = await BuildV2RequestAsync(path, Method.Get, ct); + var resp = await _httpV2.ExecuteAsync(req, ct); + Logger.LogInformation( + "CERTInext V2 API call: Method=GET, Path={Path}, HttpStatus={Status}", + Constants.ApiV2.CatalogProductsPath, (int)resp.StatusCode); + ThrowOnV2Failure(resp, "V2 get product details"); + var result = ParseProductDetailsV2Response(resp.Content); + Logger.MethodExit(LogLevel.Trace); + return result; + } + + /// + public async IAsyncEnumerable ListOrdersV2Async( + string from = null, + string to = null, + int pageSize = Constants.Api.DefaultPageSize, + [EnumeratorCancellation] CancellationToken ct = default) + { + Logger.MethodEntry(LogLevel.Trace); + EnsureV2Client(); + + // Server clamps size to 100 and treats page=0 as page 1; the client always sends + // 1-based pages itself so that quirk never surfaces here. + int size = pageSize <= 0 + ? Constants.Api.DefaultPageSize + : Math.Min(pageSize, Constants.ApiV2.OrdersReportMaxPageSize); + + int page = 1; + int totalPages = int.MaxValue; // sentinel until the first response tells us + + while (true) + { + ct.ThrowIfCancellationRequested(); + + var query = new StringBuilder(); + query.Append(Constants.ApiV2.OrdersReportPath) + .Append("?page=").Append(page) + .Append("&size=").Append(size); + if (!string.IsNullOrWhiteSpace(from)) + query.Append("&from=").Append(Uri.EscapeDataString(from)); + if (!string.IsNullOrWhiteSpace(to)) + query.Append("&to=").Append(Uri.EscapeDataString(to)); + // Scope the orders report to the connector's configured billing group, mirroring + // V1's SslOrderDetails.GroupNumber. Omitted entirely when unconfigured so + // the account's default group is used, same as V1. + if (!string.IsNullOrWhiteSpace(_config.GroupNumber)) + query.Append("&groupNumber=").Append(Uri.EscapeDataString(_config.GroupNumber)); + + var req = await BuildV2RequestAsync(query.ToString(), Method.Get, ct); + + var sw = System.Diagnostics.Stopwatch.StartNew(); + var resp = await _httpV2.ExecuteAsync(req, ct); + sw.Stop(); + + Logger.LogInformation( + "CERTInext V2 API call: Method=GET, Path={Path}, Page={Page}, HttpStatus={Status}, LatencyMs={Latency}", + Constants.ApiV2.OrdersReportPath, page, (int)resp.StatusCode, sw.ElapsedMilliseconds); + + ThrowOnV2Failure(resp, "V2 list orders"); + var listResp = DeserializeV2OrThrow(resp, $"V2 list orders page {page}"); + + var rows = listResp.Content; + if (rows == null || rows.Count == 0) + break; + + if (page == 1) + totalPages = listResp.TotalPages > 0 ? listResp.TotalPages : 1; + + Logger.LogDebug( + "V2 orders report: fetched page {Page}/{TotalPages} with {Count} rows (totalElements={Total}).", + page, totalPages, rows.Count, listResp.TotalElements); + + foreach (var row in rows) + yield return row; + + if (page >= totalPages) + break; + + page++; + } + + Logger.MethodExit(LogLevel.Trace); + } + + /// + /// Minimal, read-only escape hatch for probing V2 endpoints that don't yet have a + /// typed client method (e.g. /reports/orders, /domains during discovery). + /// Issues a GET against the V2 base URL using the same token/header machinery as the + /// typed V2 methods, and returns the raw status/content instead of throwing on + /// non-success so callers can inspect 4xx/5xx bodies directly. Intended for + /// integration-test spikes — prefer a typed method once the response shape is known. + /// + public async Task<(int StatusCode, string ContentType, string Content)> ProbeV2GetAsync( + string pathAndQuery, CancellationToken ct = default) + { + Logger.MethodEntry(LogLevel.Trace); + EnsureV2Client(); + var req = await BuildV2RequestAsync(pathAndQuery, Method.Get, ct); + var resp = await _httpV2.ExecuteAsync(req, ct); + Logger.LogInformation( + "CERTInext V2 probe call: Method=GET, Path={Path}, HttpStatus={Status}", + pathAndQuery, (int)resp.StatusCode); + Logger.MethodExit(LogLevel.Trace); + return ((int)resp.StatusCode, resp.ContentType, resp.Content); + } + + // --------------------------------------------------------------------------- + // V2 private helpers + // --------------------------------------------------------------------------- + + /// + /// Parses the GET /api/certinext/v2/catalog/products response into a flat + /// list. The endpoint may return a bare JSON array + /// or a JSON object that wraps the list under a known property name + /// ("products", "data", "items", or "catalog"). The sandbox account returns the SAME + /// nested category-envelope shape as V1's GetProductDetails — each top-level array element + /// is a category ("categoryName"/"categoryID"/"currencyType") containing its own + /// nested "products" array of {productCode, productName, productTypeID, ...}. The + /// spec's flat "productId" example shape is also handled as a fallback in case a + /// different account/API version returns it. Per-element, not per-response, so a + /// mixed response (unlikely but not contractually excluded) is still flattened. + /// + private List ParseProductDetailsV2Response(string content) + { + if (string.IsNullOrWhiteSpace(content)) + return new List(); + + using var doc = JsonDocument.Parse(content); + var root = doc.RootElement; + + JsonElement arr; + if (root.ValueKind == JsonValueKind.Array) + { + arr = root; + } + else if (root.ValueKind == JsonValueKind.Object) + { + // Log the top-level property names so the actual schema is visible in test output. + var keys = string.Join(", ", root.EnumerateObject().Select(p => p.Name)); + Logger.LogInformation( + "GetProductDetailsV2Async: response is a JSON object with top-level keys: [{Keys}]", keys); + + JsonElement? found = null; + foreach (string candidate in new[] { "products", "data", "items", "catalog" }) + { + if (root.TryGetProperty(candidate, out JsonElement candidateArr) && candidateArr.ValueKind == JsonValueKind.Array) + { + found = candidateArr; + break; + } + } + + if (found == null) + { + // No recognised array property found — surface the object keys in the exception + // so the caller/test can see the actual schema and create a proper DTO. + throw new InvalidOperationException( + $"V2 catalog/products returned an unexpected JSON object. Top-level keys: [{keys}]. " + + "Update ParseProductDetailsV2Response with the correct property name."); + } + + arr = found.Value; + } + else + { + throw new InvalidOperationException( + $"V2 catalog/products returned unexpected JSON kind: {root.ValueKind}."); + } + + var result = new List(); + foreach (var element in arr.EnumerateArray()) + { + if (element.ValueKind != JsonValueKind.Object) + continue; + + if (element.TryGetProperty("products", out JsonElement nestedProducts) + && nestedProducts.ValueKind == JsonValueKind.Array) + { + // Nested category envelope — mirror V1's GetProductDetailsResponse.FlattenProducts(). + string categoryName = element.TryGetProperty("categoryName", out var cn) && cn.ValueKind == JsonValueKind.String + ? cn.GetString() + : null; + + foreach (var product in nestedProducts.EnumerateArray()) + { + if (product.ValueKind != JsonValueKind.Object) + continue; + + result.Add(new ProductDetail { - PreVetting = "1", - OrganizationNumber = _config.OrganizationNumber - } - : null, + ProductCode = product.TryGetProperty("productCode", out var pc) && pc.ValueKind == JsonValueKind.String ? pc.GetString() : null, + ProductName = product.TryGetProperty("productName", out var pn) && pn.ValueKind == JsonValueKind.String ? pn.GetString() : null, + ProductType = categoryName, + ProductTypeId = product.TryGetProperty("productTypeID", out var pt) + ? (pt.ValueKind == JsonValueKind.String ? pt.GetString() : pt.ToString()) + : null, + Active = true // the API only returns products available on the account + }); + } + } + else if (element.TryGetProperty("productCode", out _)) + { + // Flat row already shaped like ProductDetail. + result.Add(JsonSerializer.Deserialize(element.GetRawText(), GetJsonOptions())); + } + else if (element.TryGetProperty("productId", out var pid)) + { + // Flat row using the spec example's "productId" key instead of "productCode". + result.Add(new ProductDetail + { + ProductCode = pid.ValueKind == JsonValueKind.String ? pid.GetString() : pid.ToString(), + ProductName = element.TryGetProperty("productName", out var pn2) && pn2.ValueKind == JsonValueKind.String ? pn2.GetString() : null, + ProductType = element.TryGetProperty("masterProductName", out var mpn) && mpn.ValueKind == JsonValueKind.String ? mpn.GetString() : null, + ProductTypeId = element.TryGetProperty("productTypeID", out var pt2) + ? (pt2.ValueKind == JsonValueKind.String ? pt2.GetString() : pt2.ToString()) + : null, + Active = true + }); + } + else + { + Logger.LogWarning( + "GetProductDetailsV2Async: skipping catalog element with unrecognised shape. Keys: [{Keys}]", + string.Join(", ", element.EnumerateObject().Select(p => p.Name))); + } + } + + return result; + } + + private void EnsureV2Client() + { + if (_httpV2 == null) + throw new InvalidOperationException( + "V2 API client is not initialised. Ensure UseV2Api=true and ApiUrl is set in the connector configuration."); + } + + private static string BuildV2OrderPath(string productFamilySlug, string orderId) + => $"/api/certinext/v2/{productFamilySlug}/{orderId}"; + + /// + /// Probes all three V2 product families (SSL → Private PKI → Signature) to find + /// which one owns the given order ID. Returns the matching family slug and the + /// TrackOrder response. Throws if not found. + /// + private async Task<(string family, V2OrderStatusResponse status)> ResolveV2OrderFamilyAsync( + string orderId, + CancellationToken ct) + { + foreach (var family in new[] + { + Constants.ApiV2.FamilySsl, + Constants.ApiV2.FamilyPrivatePki, + Constants.ApiV2.FamilySignature + }) + { + try + { + var status = await TrackOrderV2Async(family, orderId, ct); + return (family, status); + } + catch (KeyNotFoundException) + { + // Not in this family — try the next one + } + } + throw new KeyNotFoundException($"V2 order '{orderId}' not found in any product family."); + } + + /// + /// Fetches or returns the cached V2 OAuth2 bearer token. + /// Uses standard client_credentials grant with form-encoded body. + /// Token is cached until 60 seconds before its expiry. + /// + private async Task GetOrRefreshV2TokenAsync(CancellationToken ct) + { + if (!string.IsNullOrEmpty(_v2Token) && DateTime.UtcNow < _v2TokenExpiry) + return _v2Token; + + await _v2TokenLock.WaitAsync(ct); + try + { + if (!string.IsNullOrEmpty(_v2Token) && DateTime.UtcNow < _v2TokenExpiry) + return _v2Token; + + Logger.LogInformation( + "V2 OAuth2 token acquisition started. ApiUrl={ApiUrl}, ClientId={ClientId}", + _config.ApiUrl, _config.OAuthClientId); + + string tokenUrl = _config.ApiUrl.TrimEnd('/') + Constants.ApiV2.TokenPath; + using var tokenClient = new RestClient(tokenUrl); + var tokenReq = new RestRequest(string.Empty, Method.Post); + tokenReq.AddHeader("Content-Type", "application/x-www-form-urlencoded"); + tokenReq.AddParameter("grant_type", "client_credentials"); + tokenReq.AddParameter("client_id", _config.OAuthClientId); + tokenReq.AddParameter("client_secret", _config.OAuthClientSecret); + + var tokenResp = await tokenClient.ExecuteAsync(tokenReq, ct); + if (!tokenResp.IsSuccessful || string.IsNullOrWhiteSpace(tokenResp.Content)) + { + // SOX CC6.1: never log tokenResp.Content — may contain client_secret. + // Per the V2 spec's OAuth2 error table: 401 invalid_client = wrong client_id / + // client_secret (or a revoked key); 403 unauthorized_client = the key exists but + // was never generated in OAuth mode in the portal. These are distinct failure + // modes with distinct fixes, so each gets its own hint rather than sharing one. + if ((int)tokenResp.StatusCode == 401) + { + Logger.LogError( + "V2 OAuth2 token acquisition failed with 401 Unauthorized (invalid_client). " + + "ApiUrl={ApiUrl}, ClientId={ClientId}. " + + "Hint: the OAuthClientId or OAuthClientSecret is wrong, or the key was revoked in the portal.", + _config.ApiUrl, _config.OAuthClientId); + throw new Exception( + "V2 OAuth2 token request denied (401 Unauthorized, invalid_client). " + + "The OAuthClientId or OAuthClientSecret is incorrect, or the key was revoked. " + + "Regenerate the client secret in the CERTInext portal (Integration → REST APIs → OAuth2) " + + "and update the connector config. See gateway logs for details."); + } + if ((int)tokenResp.StatusCode == 403) + { + Logger.LogError( + "V2 OAuth2 token acquisition failed with 403 Forbidden (unauthorized_client). " + + "ApiUrl={ApiUrl}, ClientId={ClientId}. " + + "Hint: the access key exists but was not generated in OAuth mode in the portal.", + _config.ApiUrl, _config.OAuthClientId); + throw new Exception( + "V2 OAuth2 token request denied (403 Forbidden, unauthorized_client). " + + "The access key was not generated in OAuth mode. Recreate the key in the CERTInext " + + "portal (Integration → REST APIs → OAuth2) with the OAuth radio button selected. " + + "See gateway logs for details."); + } + Logger.LogError( + "V2 OAuth2 token acquisition failed. ApiUrl={ApiUrl}, ClientId={ClientId}, HttpStatus={Status}", + _config.ApiUrl, _config.OAuthClientId, (int)tokenResp.StatusCode); + throw new Exception( + $"Failed to obtain V2 OAuth2 token. HTTP {(int)tokenResp.StatusCode}. See gateway logs for details."); + } + + var tokenPayload = JsonSerializer.Deserialize(tokenResp.Content, GetJsonOptions()); + if (tokenPayload == null || string.IsNullOrEmpty(tokenPayload.AccessToken)) + { + Logger.LogError( + "V2 OAuth2 token response did not contain access_token. ApiUrl={ApiUrl}", + _config.ApiUrl); + throw new Exception("V2 OAuth2 token response did not contain an access_token."); + } + + _v2Token = tokenPayload.AccessToken; + _v2TokenExpiry = DateTime.UtcNow.AddSeconds(Math.Max(tokenPayload.ExpiresIn - 60, 30)); + + Logger.LogInformation( + "V2 OAuth2 token acquired. ApiUrl={ApiUrl}, ClientId={ClientId}, ExpiresAt={Expiry:u}", + _config.ApiUrl, _config.OAuthClientId, _v2TokenExpiry); + return _v2Token; + } + finally + { + _v2TokenLock.Release(); + } + } + + /// + /// Builds a V2 REST request with the Authorization: Bearer header populated from + /// the cached/refreshed V2 token. Optionally adds an Idempotency-Key header. + /// + private async Task BuildV2RequestAsync( + string path, + Method method, + CancellationToken ct, + string idempotencyKey = null) + { + string token = await GetOrRefreshV2TokenAsync(ct); + var req = new RestRequest(path, method); + req.AddHeader("Authorization", $"Bearer {token}"); + req.AddHeader("Accept", "application/json"); + if (!string.IsNullOrEmpty(idempotencyKey)) + req.AddHeader("Idempotency-Key", idempotencyKey); + return req; + } + + /// + /// Throws an appropriate exception for V2 API non-success responses. + /// Handles RFC 7807 problem+json and plain HTTP errors. + /// + // Instance (not static) — calls LogV2ApiFailure, which needs _config.LogSensitiveRequestData. + private void ThrowOnV2Failure(RestResponse resp, string operation) + { + if (resp.IsSuccessful) return; + + if (resp.StatusCode == HttpStatusCode.Unauthorized) + { + LogV2ApiFailure(operation, resp, LogLevel.Error); + throw new Exception($"V2 authentication failure during '{operation}'. HTTP 401. See gateway logs for details."); + } + + if (resp.StatusCode == HttpStatusCode.Forbidden) + { + LogV2ApiFailure(operation, resp, LogLevel.Error); + string hint = ExtractV2ErrorMessage(resp.Content, operation, _config.LogSensitiveRequestData); + throw new Exception( + $"V2 access denied during '{operation}'. HTTP 403. {hint} " + + "If error code is EMS-2022, ensure OAuth2 is enabled in the CERTInext portal."); + } + + LogV2ApiFailure(operation, resp, LogLevel.Warning); + string msg = ExtractV2ErrorMessage(resp.Content, operation, _config.LogSensitiveRequestData); + throw new Exception($"CERTInext V2 API error during '{operation}'. HTTP {(int)resp.StatusCode}. {msg}"); + } + + /// + /// Writes a structured log for a V2 API non-success response — matching the V1 + /// pattern but adapted for V2's RFC 7807 error shape. + /// Call immediately before throwing so the exception's "See gateway logs for details" + /// message has a corresponding structured entry in the gateway log. + /// + // Instance (not static) so it can read _config.LogSensitiveRequestData. + private void LogV2ApiFailure(string operation, RestResponse resp, LogLevel level = LogLevel.Warning) + { + // Skip the redaction passes entirely when this level is disabled. + if (!Logger.IsEnabled(level)) return; + string sanitizedBody = Truncate( + ApplyLoggingRedaction(resp?.Content, _config.LogSensitiveRequestData) ?? "(empty)", + LoggedResponseBodyCapBytes); + Logger.Log( + level, + "CERTInext V2 API non-success. Operation={Operation}, Method={Method}, Path={Path}, " + + "HttpStatus={HttpStatus}, ResponseBody={ResponseBody}", + operation, + resp?.Request?.Method.ToString() ?? "(unknown)", + resp?.Request?.Resource ?? "(unknown)", + (int?)resp?.StatusCode ?? 0, + sanitizedBody); + } + + /// + /// Parses an RFC 7807 problem+json body and returns a human-readable message. + /// Falls back to a generic message on parse failure. The CA-supplied text (title, + /// detail, per-field errors[]) goes through + /// because it can echo a submitted value such as an email address; + /// defaults to false so a caller that omits + /// it fails closed. + /// + private static string ExtractV2ErrorMessage(string content, string operation, bool logSensitiveRequestData = false) + { + if (string.IsNullOrWhiteSpace(content)) + return $"CERTInext V2 returned no body for '{operation}'."; + + string capped = content.Length > MaxErrorBodyBytes + ? content.Substring(0, MaxErrorBodyBytes) + : content; + + try + { + var problem = JsonSerializer.Deserialize(capped, GetJsonOptions()); + if (problem != null && (!string.IsNullOrWhiteSpace(problem.Detail) || !string.IsNullOrWhiteSpace(problem.Title) + || (problem.Errors != null && problem.Errors.Count > 0))) + { + string msg = $"{problem.Title}: {problem.Detail}".Trim(':').Trim(); + + // RFC 7807 per-field validation errors (spec's "errors[]", e.g. a 400 on + // order create naming exactly which field failed) — fold them into the + // message so the operator doesn't have to go dig the raw response out of + // the gateway log to find out which field CERTInext rejected. + if (problem.Errors != null && problem.Errors.Count > 0) + { + string fieldErrors = string.Join("; ", problem.Errors + .Where(e => !string.IsNullOrWhiteSpace(e?.Field) || !string.IsNullOrWhiteSpace(e?.Message)) + .Select(e => $"{e.Field}: {e.Message}".Trim(':').Trim())); + if (!string.IsNullOrWhiteSpace(fieldErrors)) + msg = string.IsNullOrWhiteSpace(msg) ? fieldErrors : $"{msg} [{fieldErrors}]"; + } + + if (!string.IsNullOrWhiteSpace(msg)) + return LogSanitizer.SanitizeCaText(msg, logSensitiveRequestData); + } + } + catch + { + // Not a problem+json body — fall through + } + + return $"See gateway logs for raw response. Operation='{operation}'."; + } + + private static T DeserializeV2OrThrow(RestResponse resp, string operation) where T : class + { + if (string.IsNullOrWhiteSpace(resp.Content)) + throw new Exception($"CERTInext V2 returned an empty body for '{operation}'."); + var result = JsonSerializer.Deserialize(resp.Content, GetJsonOptions()); + if (result == null) + throw new Exception($"CERTInext V2 returned a null/unrecognised body for '{operation}'."); + return result; + } + + // --------------------------------------------------------------------------- + // V1 token helper (unchanged) + // --------------------------------------------------------------------------- + + private async Task GetOrRefreshTokenAsync(CancellationToken ct) + { + if (!string.IsNullOrEmpty(_cachedToken) && DateTime.UtcNow < _tokenExpiry) + return _cachedToken; + + await _tokenLock.WaitAsync(ct); + try + { + if (!string.IsNullOrEmpty(_cachedToken) && DateTime.UtcNow < _tokenExpiry) + return _cachedToken; + + Logger.LogInformation( + "OAuth2 token acquisition attempt started. TokenUrl={TokenUrl}, ClientId={ClientId}", + _config.OAuthTokenUrl, _config.OAuthClientId); + + using var tokenClient = new RestClient(_config.OAuthTokenUrl); + var tokenReq = new RestRequest(string.Empty, Method.Post); + tokenReq.AddHeader("Content-Type", "application/x-www-form-urlencoded"); + tokenReq.AddParameter("grant_type", "client_credentials"); + tokenReq.AddParameter("client_id", _config.OAuthClientId); + tokenReq.AddParameter("client_secret", _config.OAuthClientSecret); + + var tokenResp = await tokenClient.ExecuteAsync(tokenReq, ct); + if (!tokenResp.IsSuccessful || string.IsNullOrWhiteSpace(tokenResp.Content)) + { + // SOX CC6.1 (credential confidentiality): NEVER log tokenResp.Content, + // tokenResp.ErrorMessage, or tokenResp.ErrorException — RestSharp's + // failure paths can echo the original request including the + // `client_secret` form value. Only StatusCode + non-secret config + // identifiers are safe to log here. + Logger.LogError( + "OAuth2 token acquisition failed. TokenUrl={TokenUrl}, ClientId={ClientId}, HttpStatus={Status}", + _config.OAuthTokenUrl, _config.OAuthClientId, (int)tokenResp.StatusCode); + throw new Exception( + $"Failed to obtain OAuth2 token from CERTInext. HTTP {(int)tokenResp.StatusCode}. See gateway logs for details."); + } + + var tokenPayload = JsonSerializer.Deserialize(tokenResp.Content, GetJsonOptions()); + + if (tokenPayload == null || string.IsNullOrEmpty(tokenPayload.AccessToken)) + { + Logger.LogError( + "OAuth2 token acquisition failed — response did not contain access_token. TokenUrl={TokenUrl}", + _config.OAuthTokenUrl); + throw new Exception("OAuth2 token response from CERTInext did not contain an access_token."); + } + + _cachedToken = tokenPayload.AccessToken; + _tokenExpiry = DateTime.UtcNow.AddSeconds(Math.Max(tokenPayload.ExpiresIn - 60, 30)); + + Logger.LogInformation( + "OAuth2 token acquired. TokenUrl={TokenUrl}, ClientId={ClientId}, ExpiresAt={Expiry:u}", + _config.OAuthTokenUrl, _config.OAuthClientId, _tokenExpiry); + return _cachedToken; + } + finally + { + _tokenLock.Release(); + } + } + + // --------------------------------------------------------------------------- + // Retry helper + // --------------------------------------------------------------------------- + + /// + /// Executes a with up to + /// attempts, retrying on HTTP 5xx and network-level failures (no status code). + /// 4xx responses are returned immediately — client errors will not be resolved + /// by retrying. + /// + /// When is false the request is sent exactly + /// once and transient failures are NOT retried. This is required for non-idempotent + /// order-submission calls: a network-level timeout can occur *after* CERTInext has + /// already received and created the order, so re-sending the same body (same + /// requestTxn) is rejected as "Duplicate requestTxn" (EMS-947) and orphans the + /// order the first attempt actually created. + /// + private async Task ExecuteWithRetryAsync( + RestRequest req, + CancellationToken ct, + int maxAttempts = 3, + bool idempotent = true) + { + int attempts = idempotent ? maxAttempts : 1; + RestResponse resp = null; + var sw = System.Diagnostics.Stopwatch.StartNew(); + for (int attempt = 1; attempt <= attempts; attempt++) + { + resp = await _http.ExecuteAsync(req, ct); + + // Success or 4xx client error — return immediately, checked BEFORE the + // cancellation check below. `_http.ExecuteAsync` already ran to completion by the + // time control reaches this line; whether `ct` has *since* flipped to cancelled is + // a separate, unsynchronized fact (a check-after-await race, not a fabricated one — + // a CancellationTokenSource(TimeSpan) callback and this awaited Task's completion + // are not mutually exclusive events). A deadline (the shared DcvTimeoutMinutes + // budget) firing at essentially the same instant a call genuinely succeeded must not + // discard that success: for VerifyDcv specifically, discarding it here would abort + // PerformDcvIfNeededAsync's loop before WaitForDcvVerificationAsync ever ran, and + // its finally block would delete the just-staged TXT record even though CERTInext + // had genuinely received the verify trigger — turning a real CA-side success into a + // self-inflicted DCV failure. + bool isClientError = (int)resp.StatusCode >= 400 && (int)resp.StatusCode < 500; + if (resp.IsSuccessful || isClientError) + return resp; - RequestorInformation = new RequestorInformation - { - RequestorName = requestorName, - RequestorEmail = requestorEmail, - RequestorIsdCode = requestorIsd, - RequestorMobileNumber = requestorMobile - }, - SubscriptionDetails = new SubscriptionDetails - { - Validity = validityYears, - AutoRenew = string.IsNullOrWhiteSpace(_config.SubscriptionAutoRenew) ? "0" : _config.SubscriptionAutoRenew, - RenewCriteria = string.IsNullOrWhiteSpace(_config.SubscriptionRenewCriteriaDays) ? "30" : _config.SubscriptionRenewCriteriaDays - }, - CertificateInformation = new CertificateInformation - { - DomainName = ExtractCnFromSubject(request.Subject) ?? "unknown", - AdditionalDomains = BuildAdditionalDomains(request.Sans), - AutoSecureWww = string.IsNullOrWhiteSpace(_config.AutoSecureWww) ? "0" : _config.AutoSecureWww - }, - - // technicalPointOfContact — each field falls back to the requestor default - // when its TechnicalContact* counterpart is blank. - TechnicalPointOfContact = new TechnicalPointOfContact - { - TpcName = string.IsNullOrWhiteSpace(_config.TechnicalContactName) ? requestorName : _config.TechnicalContactName, - TpcEmail = string.IsNullOrWhiteSpace(_config.TechnicalContactEmail) ? requestorEmail : _config.TechnicalContactEmail, - TpcIsdCode = string.IsNullOrWhiteSpace(_config.TechnicalContactIsdCode) ? requestorIsd : _config.TechnicalContactIsdCode, - TpcMobileNumber = string.IsNullOrWhiteSpace(_config.TechnicalContactMobileNumber) ? requestorMobile : _config.TechnicalContactMobileNumber - }, - - Csr = request.Csr, - AgreementDetails = BuildDefaultAgreementDetails(), - AdditionalInformation = new AdditionalInformation + // Only for a call that did NOT succeed: this client is built with + // ThrowOnAnyError=false (see the constructor), so a cancelled ct does not surface as + // OperationCanceledException from ExecuteAsync — RestSharp catches + // HttpClient.SendAsync's cancellation internally and returns a non-throwing, + // unsuccessful RestResponse instead. Left unchecked, that response reaches + // DeserializeOrThrow and becomes a plain Exception indistinguishable from a genuine + // API failure — which is exactly how a caller such as PerformDcvIfNeededAsync's + // shared DCV-timeout cancellation was still landing in a generic "GetDcv failed" + // per-domain catch instead of the cancellation-specific one, even after that method + // was hardened to re-throw a real OperationCanceledException past its per-domain + // catches. Surface the true cancellation here, at the one place in the client that + // actually holds `ct`, before any retry or error-wrapping logic sees the response. + // + // Throwing here means every caller's own per-call audit line (Method/Path/HttpStatus/ + // LatencyMs, logged after ExecuteWithRetryAsync returns) never executes for the + // cancelled call — that specific attempt would otherwise vanish from the audit trail + // entirely, leaving only a coarser, order-level "unexpected failure" log with no + // domain/endpoint/status/latency. Log that record here instead, at the one place that + // reliably sees every cancellation regardless of which of ExecuteWithRetryAsync's ~10 + // callers is in flight. + if (ct.IsCancellationRequested) + { + Logger.LogWarning( + "CERTInext API call cancelled: Method={Method}, Path={Path}, HttpStatus={Status}, " + + "ResponseStatus={ResponseStatus}, LatencyMs={Latency}, Attempt={Attempt}/{Max}.", + req.Method, req.Resource, (int)resp.StatusCode, resp.ResponseStatus, + sw.ElapsedMilliseconds, attempt, attempts); + } + ct.ThrowIfCancellationRequested(); + + if (attempt < attempts) + { + Logger.LogWarning( + "CERTInext API returned {Status} on attempt {Attempt}/{Max} — retrying...", + (int)resp.StatusCode, attempt, attempts); + } + } + + // Return the last response (caller handles the error) + return resp; + } + + // --------------------------------------------------------------------------- + // Legacy helper — maps legacy reason string to CRL code + // --------------------------------------------------------------------------- + + private static uint MapLegacyReasonStringToCrlCode(string reason) + { + switch (reason?.ToLowerInvariant()) + { + case "keycompromise": return 1; + case "cacompromise": return 2; + case "affiliationchanged": return 3; + case "superseded": return 4; + case "cessationofoperation": return 5; + case "certificatehold": return 6; + case "removefromcrl": return 8; + case "privilegewithdrawn": return 9; + case "aacompromise": return 10; + default: return 0; // unspecified -> maps to KeyCompromise in ToRevocationReasonId + } + } + + private static bool IsCertificateDownloadable(string certStatusId) + { + if (!int.TryParse(certStatusId, out int id)) return false; + return id == Constants.CertificateStatusId.CertificateGenerated || + id == Constants.CertificateStatusId.CertificateDownloaded || + id == Constants.CertificateStatusId.OrderAutoApproved || + id == Constants.CertificateStatusId.RekeyApproved || + id == Constants.CertificateStatusId.ApprovedBySecondApprover; + } + + private static string MapCertStatusIdToLegacyString(string certStatusId) + { + if (!int.TryParse(certStatusId, out int id)) return "pending"; + int disposition = StatusMapper.CertificateStatusIdToRequestDisposition(id); + switch (disposition) + { + case (int)Keyfactor.PKI.Enums.EJBCA.EndEntityStatus.GENERATED: return "issued"; + case (int)Keyfactor.PKI.Enums.EJBCA.EndEntityStatus.REVOKED: return "revoked"; + case (int)Keyfactor.PKI.Enums.EJBCA.EndEntityStatus.EXTERNALVALIDATION: return "pending_approval"; + case (int)Keyfactor.PKI.Enums.EJBCA.EndEntityStatus.FAILED: return "failed"; + default: return "pending"; + } + } + + private static LegacyGetCertificateResponse MapOrderReportEntryToLegacy(OrderReportEntry entry) + { + // Note: GetOrderReport does not return requestor name/email in the ordersArray. + // Those fields are only available via TrackOrder on individual orders. + System.DateTime? orderDate = null; + if (!string.IsNullOrWhiteSpace(entry.OrderDate) + && System.DateTime.TryParse(entry.OrderDate, + System.Globalization.CultureInfo.InvariantCulture, + System.Globalization.DateTimeStyles.AssumeUniversal | System.Globalization.DateTimeStyles.AdjustToUniversal, + out var parsed)) + { + orderDate = parsed; + } + + return new LegacyGetCertificateResponse + { + Id = string.IsNullOrWhiteSpace(entry.OrderNumber) ? entry.RequestNumber : entry.OrderNumber, + Status = MapCertStatusIdToLegacyString(entry.CertificateStatusId), + Subject = entry.DomainName, + ProfileId = entry.ProductCode, + OrderDate = orderDate + }; + } + + private GenerateOrderSslRequest BuildOrderRequestFromLegacyEnrollRequest(EnrollCertificateRequest request) + { + // Hoisted: additionalDomains is de-duplicated against the primary domain, so both + // fields have to be built from the same value. + string domainName = ExtractCnFromSubject(request.Subject) ?? "unknown"; + + return new GenerateOrderSslRequest + { + // Meta will be set by PlaceOrderAsync + OrderDetails = BuildSslOrderDetails( + // Blank (not just null) ProfileId must fall back: the template ProductCode + // resolves to "" when unset, so a null-coalesce would never fire. + productCode: string.IsNullOrWhiteSpace(request.ProfileId) + ? (_config.DefaultProductCode ?? string.Empty) + : request.ProfileId, + domainName: domainName, + sans: request.Sans, + csr: request.Csr, + validityYears: request.ValidityYears, + validityDays: request.ValidityDays, + requesterName: request.RequesterName, + requesterEmail: request.RequesterEmail, + comment: request.Comment, + signerName: request.SignerName, + signerPlace: request.SignerPlace, + signerIp: request.SignerIp) + }; + } + + /// + /// Builds the orderDetails block of a V1 GenerateOrderSSL body. Shared by new + /// enrollment and renewal so both send the same field set, in the locations CERTInext + /// reads them (orderDetails.groupNumber, orderDetails.autoSecureWWW, + /// orderDetails.technicalPointOfContact.poc*), and both honor the connector's + /// validity / autoRenew / emailNotifications / accountingModel settings. + /// Callers resolve the product code and primary domain themselves (renewal derives them + /// differently from new enrollment). + /// + private SslOrderDetails BuildSslOrderDetails( + string productCode, + string domainName, + List sans, + string csr, + int? validityYears, + int? validityDays, + string requesterName, + string requesterEmail, + string comment, + string signerName, + string signerPlace, + string signerIp) + { + string requestorName = requesterName ?? _config.RequestorName ?? "Keyfactor Gateway"; + string requestorEmail = requesterEmail ?? _config.RequestorEmail ?? string.Empty; + string requestorIsd = string.IsNullOrWhiteSpace(_config.RequestorIsdCode) ? "1" : _config.RequestorIsdCode; + string requestorMobile = _config.RequestorMobileNumber ?? string.Empty; + + return new SslOrderDetails + { + ProductCode = productCode, + AccountingModel = string.IsNullOrWhiteSpace(_config.AccountingModel) ? "2" : _config.AccountingModel, + SaveAndHold = "0", + EmailNotifications = string.IsNullOrWhiteSpace(_config.EmailNotifications) ? "0" : _config.EmailNotifications, + + // orderDetails.groupNumber — routes the order to the configured account group. + // Omitted (JsonIgnore-WhenNull) when GroupNumber is blank. + GroupNumber = string.IsNullOrWhiteSpace(_config.GroupNumber) ? null : _config.GroupNumber, + + // orderDetails.autoSecureWWW — always sent so CERTInext's own default ("1", which + // adds www. and a second DCV) never applies silently. + AutoSecureWww = string.IsNullOrWhiteSpace(_config.AutoSecureWww) ? "0" : _config.AutoSecureWww, + + // organizationDetails — declares pre-vetted org when configured. This is the + // single biggest factor in how quickly CERTInext releases an order from + // Pending System RA. When OrganizationNumber is blank we omit the whole + // block (the model is JsonIgnore-WhenNull) so the order falls back to the + // unvetted path — same behavior as the prior plugin builds. + OrganizationDetails = !string.IsNullOrWhiteSpace(_config.OrganizationNumber) + ? new OrganizationDetails { - Remarks = request.Comment ?? "Issued via Keyfactor Command AnyCA REST Gateway." + PreVetting = "1", + OrganizationNumber = _config.OrganizationNumber } + : null, + + RequestorInformation = new RequestorInformation + { + RequestorName = requestorName, + RequestorEmail = requestorEmail, + RequestorIsdCode = requestorIsd, + RequestorMobileNumber = requestorMobile, + RequestorDesignation = string.IsNullOrWhiteSpace(_config.RequestorDesignation) ? null : _config.RequestorDesignation.Trim() + }, + SubscriptionDetails = new SubscriptionDetails + { + Validity = ResolveValidityYears(validityYears, validityDays), + AutoRenew = string.IsNullOrWhiteSpace(_config.SubscriptionAutoRenew) ? "0" : _config.SubscriptionAutoRenew, + RenewCriteria = string.IsNullOrWhiteSpace(_config.SubscriptionRenewCriteriaDays) ? "30" : _config.SubscriptionRenewCriteriaDays + }, + CertificateInformation = new CertificateInformation + { + DomainName = domainName, + AdditionalDomains = BuildAdditionalDomains(sans, domainName) + }, + + TechnicalPointOfContact = BuildTechnicalPointOfContact( + requestorName, requestorEmail, requestorIsd, requestorMobile), + + Csr = csr, + AgreementDetails = BuildAgreementDetails(signerName, signerPlace, signerIp), + AdditionalInformation = new AdditionalInformation + { + Remarks = comment ?? "Issued via Keyfactor Command AnyCA REST Gateway." } }; } - private AgreementDetails BuildDefaultAgreementDetails() + /// + /// Resolves subscriptionDetails.validity (whole subscription years). The term is + /// max(ValidityYears, ceil(ValidityDays / 365)), counting each only when it is set + /// (> 0). Both template fields default to one year, so a field left at its default can + /// never override an explicit value in the other; this keeps templates saved with only + /// ValidityDays (the sole working knob in 1.0.0) on the same term. When neither is set the + /// connector's SubscriptionValidityYears (default "1") applies. + /// + private string ResolveValidityYears(int? validityYears, int? validityDays) + { + int years = Math.Max(validityYears ?? 0, 0); + int days = Math.Max(validityDays ?? 0, 0); + int daysAsYears = (int)Math.Ceiling(days / 365.0); + int term = Math.Max(years, daysAsYears); + if (term > 0) + return term.ToString(System.Globalization.CultureInfo.InvariantCulture); + return string.IsNullOrWhiteSpace(_config.SubscriptionValidityYears) ? "1" : _config.SubscriptionValidityYears; + } + + /// + /// Builds technicalPointOfContact. Each TechnicalContact* field falls back to the + /// matching resolved requestor value when blank; the name is split into + /// pocFirstName/pocLastName via . + /// Returns null (block omitted, Warning logged) when no email resolves or when the resolved + /// name yields a blank first name — CERTInext's spec marks the block optional but requires + /// the name and email inside it, and it validates them now that they reach it, so an empty + /// POC email or name must not start rejecting orders that previously went through. + /// + private TechnicalPointOfContact BuildTechnicalPointOfContact( + string requestorName, string requestorEmail, string requestorIsd, string requestorMobile) + { + string email = string.IsNullOrWhiteSpace(_config.TechnicalContactEmail) + ? requestorEmail + : _config.TechnicalContactEmail; + + if (string.IsNullOrWhiteSpace(email)) + { + Logger.LogWarning( + "Omitting technicalPointOfContact from the SSL order: neither TechnicalContactEmail " + + "nor RequestorEmail resolved to a value. Set TechnicalContactEmail (or RequestorEmail) " + + "in the connector configuration to send a technical point of contact."); + return null; + } + + string name = string.IsNullOrWhiteSpace(_config.TechnicalContactName) + ? requestorName + : _config.TechnicalContactName; + var (first, last) = SplitContactName(name); + + if (string.IsNullOrWhiteSpace(first)) + { + Logger.LogWarning( + "Omitting technicalPointOfContact from the SSL order: neither TechnicalContactName " + + "nor RequestorName resolved to a value. Set TechnicalContactName (or RequestorName) " + + "in the connector configuration to send a technical point of contact."); + return null; + } + + return new TechnicalPointOfContact + { + PocFirstName = first, + PocLastName = last, + PocEmail = email, + PocIsdCode = string.IsNullOrWhiteSpace(_config.TechnicalContactIsdCode) ? requestorIsd : _config.TechnicalContactIsdCode, + PocMobileNumber = string.IsNullOrWhiteSpace(_config.TechnicalContactMobileNumber) ? requestorMobile : _config.TechnicalContactMobileNumber + }; + } + + /// + /// Splits a single contact-name string into first/last name for + /// pocFirstName/pocLastName. The name is trimmed and split on the first run + /// of whitespace: the first token is the first name, the remainder (internal spacing + /// preserved) is the last name. A single-token name is placed in both fields (pending + /// CERTInext guidance on single-name contacts). Null/blank input yields two empty strings. + /// + internal static (string First, string Last) SplitContactName(string name) + { + string trimmed = name?.Trim(); + if (string.IsNullOrEmpty(trimmed)) + return (string.Empty, string.Empty); + + int ws = -1; + for (int i = 0; i < trimmed.Length; i++) + { + if (char.IsWhiteSpace(trimmed[i])) { ws = i; break; } + } + if (ws < 0) + return (trimmed, trimmed); + + string first = trimmed.Substring(0, ws); + string last = trimmed.Substring(ws).TrimStart(); + return (first, last); + } + + /// + /// Builds agreementDetails. Each signer value resolves template value, then + /// connector value, then built-in default, using blank (not just null) checks because + /// both the template parameters and the connector config default to "". + /// + private AgreementDetails BuildAgreementDetails( + string templateSignerName, string templateSignerPlace, string templateSignerIp) { // SOC1 accuracy-of-processing: the subscriber agreement is a legal artefact // and the SignerIp it carries is part of the audit record CERTInext stores. @@ -1402,24 +2823,68 @@ private AgreementDetails BuildDefaultAgreementDetails() // don't break existing deployments (and our enrollment never fails just // because SignerIp is blank), but a missing value emits a Warning so an // auditor sees the misrepresentation as an actionable signal in the gateway log. - string signerIp = _config.SignerIp; - if (string.IsNullOrWhiteSpace(signerIp)) + string signerIp = FirstNonBlank(templateSignerIp, _config.SignerIp); + WarnIfSignerIpNotAnAddress(signerIp, source: string.IsNullOrWhiteSpace(templateSignerIp) ? "connector" : "template"); + if (signerIp == null) { Logger.LogWarning( - "Connector config SignerIp is empty — falling back to 127.0.0.1 for the " + - "subscriber agreement. Set the SignerIp config field to the gateway host's " + - "actual public-routable IP so the audit record is accurate."); + "Neither the template SignerIp parameter nor the connector SignerIp config is set — " + + "falling back to 127.0.0.1 for the subscriber agreement. Set SignerIp to the " + + "gateway host's actual public-routable IP so the audit record is accurate."); signerIp = "127.0.0.1"; } + // Same SOC1 rationale as SignerIp: placeholder SignerName/SignerPlace values land in + // the legal agreement record, so a fallback is surfaced as a Warning (values unchanged). + string signerName = FirstNonBlank(templateSignerName, _config.RequestorName); + if (signerName == null) + { + Logger.LogWarning( + "Neither the template SignerName parameter nor the connector RequestorName config is set — " + + "falling back to \"Keyfactor Gateway\" for the subscriber agreement. Set SignerName on the " + + "template or RequestorName on the connector to the actual signer so the audit record is accurate."); + signerName = "Keyfactor Gateway"; + } + string signerPlace = FirstNonBlank(templateSignerPlace, _config.SignerPlace); + if (signerPlace == null) + { + Logger.LogWarning( + "Neither the template SignerPlace parameter nor the connector SignerPlace config is set — " + + "falling back to \"Gateway\" for the subscriber agreement. Set SignerPlace on the " + + "template or connector to the signer's actual location so the audit record is accurate."); + signerPlace = "Gateway"; + } return new AgreementDetails { AcceptAgreement = "1", - SignerName = _config.RequestorName ?? "Keyfactor Gateway", - SignerPlace = _config.SignerPlace ?? "Gateway", + SignerName = signerName, + SignerPlace = signerPlace, SignerIp = signerIp }; } + /// + /// Warn-only check: the resolved SignerIp is sent as agreementDetails.signerIP (part of + /// the subscriber-agreement audit record), so a value that is not an IP literal (for example + /// a host name) is flagged. The value is still sent unchanged; enrollment never fails here. + /// + private static void WarnIfSignerIpNotAnAddress(string signerIp, string source) + { + if (string.IsNullOrWhiteSpace(signerIp) || IPAddress.TryParse(signerIp, out _)) + return; + + string shown = LogSanitizer.Strip(signerIp.Length > 64 ? signerIp.Substring(0, 64) + "..." : signerIp); + Logger.LogWarning( + "The SignerIp value from the {Source} ('{SignerIp}') is not a valid IPv4/IPv6 address but is " + + "being sent unchanged as agreementDetails.signerIP in the subscriber agreement audit record. " + + "Set SignerIp to the gateway host's actual IP address.", + source, shown); + } + + private static string FirstNonBlank(string first, string second) + => !string.IsNullOrWhiteSpace(first) ? first + : !string.IsNullOrWhiteSpace(second) ? second + : null; + private static string ExtractCnFromSubject(string subject) { if (string.IsNullOrWhiteSpace(subject)) return null; @@ -1432,16 +2897,57 @@ private static string ExtractCnFromSubject(string subject) return null; } - private static List BuildAdditionalDomains(System.Collections.Generic.List sans) + /// + /// Projects the resolved SAN list onto certificateInformation.additionalDomains. + /// + /// Every requested SAN is submitted regardless of type. Filtering to DNS-only (the + /// original behaviour) issued certificates quietly missing names the subscriber had + /// requested, which is the worse failure; the caller warns about the non-DNS entries + /// before we get here. + /// + /// is the value already going out as the order's primary + /// domain, and Command normally includes the CN in the SAN set as well. On the US + /// sandbox CERTInext collapses that repetition itself (a CN submitted twice is + /// registered once), but that is undocumented and not verified against production — + /// which is exactly why we exclude it + /// here rather than relying on CA-side de-duplication. It also keeps the submitted body + /// matching what we log. + /// + private List BuildAdditionalDomains( + System.Collections.Generic.List sans, + string domainName) { if (sans == null || sans.Count == 0) return null; + var domains = new List(); + var seen = new HashSet(StringComparer.OrdinalIgnoreCase); + + bool haveDomainName = !string.IsNullOrWhiteSpace(domainName); + if (haveDomainName) + seen.Add(domainName.Trim()); + + int duplicates = 0; foreach (var san in sans) { - if (string.Equals(san.Type, "dns", StringComparison.OrdinalIgnoreCase) && - !string.IsNullOrWhiteSpace(san.Value)) - domains.Add(san.Value); + if (san == null || string.IsNullOrWhiteSpace(san.Value)) continue; + + string value = san.Value.Trim(); + if (!seen.Add(value)) + { + duplicates++; + continue; + } + domains.Add(value); + } + + if (duplicates > 0) + { + Logger.LogDebug( + "Collapsed {Count} duplicate SAN value(s) out of additionalDomains " + + "(already submitted as domainName '{DomainName}', or repeated in the SAN set).", + duplicates, LogSanitizer.Strip(domainName)); } + return domains.Count > 0 ? domains : null; } @@ -1449,14 +2955,18 @@ private static List BuildAdditionalDomains(System.Collections.Generic.Li // Deserialization helpers // --------------------------------------------------------------------------- - private static T DeserializeOrThrow(RestResponse resp, string operation) where T : class + // Instance (not static) — calls LogApiFailure, which needs _config.LogSensitiveRequestData. + private T DeserializeOrThrow(RestResponse resp, string operation) where T : class { if (!resp.IsSuccessful) { - string errMsg = ExtractErrorMessage(resp.Content, operation); - Logger.LogError( - "CERTInext API error during '{Operation}': HttpStatus={Status}, Error={Error}", - operation, (int)resp.StatusCode, errMsg); + // V1 documents errors only as HTTP-200 meta envelopes, so a non-2xx + // body here is usually not from the V1 application at all (e.g. ApiUrl missing the + // /emSignHub-API/ segment). Log the redacted body and put the HTTP status in the + // message so "See gateway logs for details" has something to point at. + string errMsg = ExtractErrorMessage( + resp.Content, operation, (int)resp.StatusCode, _config.LogSensitiveRequestData); + LogApiFailure(operation, resp, errorMessage: errMsg, level: LogLevel.Error); throw new Exception(errMsg); } @@ -1597,13 +3107,16 @@ internal static string RedactCredentials(string body) // but the field name is a common one and the cost of redacting it is zero). body = System.Text.RegularExpressions.Regex.Replace( body, - @"(?i)""(authKey|client_secret|apiKey|accessKey|password)""\s*:\s*""[^""]*""", + @"(?i)""(authKey|client_secret|apiKey|accessKey|password)""\s*:\s*""[^""\\]*(?:\\.[^""\\]*)*""", @"""$1"":""***REDACTED***"""); - // Form-urlencoded: client_secret=... or authKey=... (before any & or end) + // The JSON value pattern above is escape-aware: a value such as "ab\"cd" is matched whole. + // Form-urlencoded: client_secret=... or authKey=... (before any & or end). + // A backslash-escaped char (e.g. \") is consumed as part of the value so a form value + // embedded in a JSON-escaped string cannot leak the text after the escape. body = System.Text.RegularExpressions.Regex.Replace( body, - @"(?i)\b(authKey|client_secret|apiKey|accessKey|password)=([^&\s""]+)", + @"(?i)\b(authKey|client_secret|apiKey|accessKey|password)=(?:\\.|[^&\s""])+", "$1=***REDACTED***"); // Authorization header lines if a header dump ever ends up in body shape. @@ -1617,6 +3130,259 @@ internal static string RedactCredentials(string body) return body; } + // Exact JSON key names that carry a person's email address across the V1 and V2 wire + // shapes (see CERTInext/API/CertificateRequest.cs and CERTInext/API/V2/CertificateRequestV2.cs). + // Every one of these is a full, exact key — never a substring of an unrelated key (e.g. + // "domainName"/"organizationName" do not end in a bare "email" key) — so matching the key + // by exact name cannot cross-contaminate unrelated fields. "pocEmail" is the + // technicalPointOfContact email on the current V1 order shape; the legacy "tpcEmail" is not + // emitted by any V1 model today and is kept as defence in depth for CA error/response + // bodies that may echo older field names. + private static readonly string[] PersonalEmailFieldNames = + { + "requestorEmail", "requesterEmail", "pocEmail", "tpcEmail", "requestorEmailId", "dcvEmail", "email", + // V2 SSL.com organization-validation submit body (optional admin contact). + "adminEmail" + }; + + // Exact JSON key names carrying other person/contact data (name, phone/ISD/mobile, + // designation, signer place/IP). The V1 technicalPointOfContact keys are the poc* family + // (pocFirstName/pocLastName/pocIsdCode/pocMobileNumber); the legacy tpc* names are kept as + // defence in depth for CA bodies echoing the old names. "name" is bare only inside the V2 requestor / + // technicalPointOfContact blocks in every currently-logged body — it is never used as an + // exact top-level key anywhere else on the CERTInext wire shapes this plugin logs raw. + // + // The V2 Document Signer (signature) body's `subject` block and its create + // response add a natural person's name, identity-document and street-address fields + // (firstName, lastName, identityDocumentType, identificationNumber, streetAddress1/2, + // locality, postalCode) and a `subjectDisplayName` (full name for natural/legal person). + // subject.email / subject.phone / subject.designation are already covered by the bare + // "email"/"phone"/"designation" keys. Deliberately NOT added: organizationName, + // organizationUnit, organizationIdentificationNumber, businessCategory, state, + // countryCode — organization or coarse-location data, and "organizationName" is also a + // V1 order/report key whose value is an OV organization, not a person. The V2 + // private-pki body adds no new personal keys: its requestor / + // technicalPointOfContact blocks reuse the bare keys above, and hostname / + // additionalHosts are host names / IP literals, not personal data. + private static readonly string[] PersonalOtherFieldNames = + { + "requestorName", "requesterName", "signerName", "name", + "requestorIsdCode", "requestorMobileNumber", "requestorDesignation", + "pocFirstName", "pocLastName", "pocIsdCode", "pocMobileNumber", + "tpcName", "tpcIsdCode", "tpcMobileNumber", "signerPlace", "signedPlace", "signerip", "phone", "designation", + "firstName", "lastName", "subjectDisplayName", "identityDocumentType", "identificationNumber", + "streetAddress1", "streetAddress2", "locality", "postalCode", + // The V2 SSL create body carries the PKCS#10 CSR inline ("csr") when V2InlineCsr is on; its + // subject is requester data. + "csr" + }; + + /// + /// Scrubs known person/contact-bearing keys out of a JSON-ish body before it goes into a + /// log line, when LogSensitiveRequestData is off. Covers the V1 + /// requestorInformation / technicalPointOfContact / agreementDetails + /// shapes (requestorName, requestorEmail, requestorIsdCode, + /// requestorMobileNumber, requestorDesignation, pocFirstName, + /// pocLastName, pocEmail, pocIsdCode, pocMobileNumber, the + /// legacy tpcName/tpcEmail/tpcIsdCode/tpcMobileNumber (defence + /// in depth for CA bodies echoing the old names), signerName, + /// signerPlace, signerIP/signerIp, the legacy requesterName/ + /// requesterEmail aliases, and the requestorEmailId search filter) and the + /// V2 nested requestor / technicalPointOfContact shapes (bare name/ + /// email/phone/designation), plus the V2 Document Signer + /// subject block's person fields and subjectDisplayName (see + /// PersonalOtherFieldNames for the exact list and what is deliberately excluded). + /// + /// Email values are masked via so the domain stays + /// visible (e.g. "j***@example.com") while the local part is hidden. Every other + /// matched field is replaced outright with "***REDACTED***". Fields that are + /// already blank/empty on the wire are left untouched — there is nothing to redact. + /// + /// Conservative substring/regex pass, same style as — + /// tolerant of whitespace around the JSON key : value separator (including + /// pretty-printed bodies), and anchored on the opening/closing quote of the key so it + /// cannot match a key name as a substring of a longer one. Email SANs inside SAN arrays + /// (additionalDomains/additionalHosts) and domainVerification keys are + /// masked afterwards by . Exposed internal + /// for unit testing. + /// + internal static string RedactPersonalData(string body) + { + if (string.IsNullOrEmpty(body)) return body; + + foreach (var key in PersonalEmailFieldNames) + body = RedactJsonField(body, key, LogSanitizer.MaskEmail); + + foreach (var key in PersonalOtherFieldNames) + body = RedactJsonField(body, key, _ => "***REDACTED***"); + + return MaskEmailsInSanContainers(body); + } + + // Exact JSON keys whose value is an array of SAN strings. V1 additionalDomains carries every + // requested SAN regardless of type, emails included. + // V2 SSL additionalDomains and private-pki additionalHosts are filtered to DNS / IP before + // submission, so they are covered only as defence in depth: a DNS name or IP literal never + // contains '@', so masking there can only ever touch a mis-typed email. + private static readonly string[] SanArrayFieldNames = { "additionalDomains", "additionalHosts" }; + + // Exact JSON keys whose value is an object keyed by SAN value. The V1 TrackOrder + // domainVerification block is { "": { ... }, "status": "..." }, and an email + // submitted in additionalDomains comes back as one of those keys. + private static readonly string[] SanKeyedObjectFieldNames = { "domainVerification" }; + + /// + /// Masks email addresses in the two SAN-bearing container shapes the + /// key/value regex in cannot reach: string elements of a + /// array, and property names directly inside a + /// object. Only values containing @ are masked, + /// with . DNS / IP values, every other key, and anything + /// nested deeper inside those containers are left alone. Keys match exactly and + /// case-insensitively, the same as . + /// + /// Uses to find the exact token spans, then splices masked + /// tokens into the original bytes. The rest of the body stays byte-for-byte as it was, with + /// its whitespace and escaping unchanged. A regex cannot follow nesting depth or escaped + /// quotes reliably, and a DOM re-serialize would reformat the whole logged body. Never + /// throws: a body that does not start with {/[ is returned unchanged, and on + /// malformed or truncated JSON the masks found before the fault are still applied. + /// + internal static string MaskEmailsInSanContainers(string body) + { + if (string.IsNullOrEmpty(body)) return body; + if (body.IndexOf('@') < 0 && body.IndexOf("\\u0040", StringComparison.OrdinalIgnoreCase) < 0) + return body; + + int first = 0; + while (first < body.Length && char.IsWhiteSpace(body[first])) first++; + if (first == body.Length || (body[first] != '{' && body[first] != '[')) return body; + + byte[] utf8 = Encoding.UTF8.GetBytes(body); + var edits = new List<(int Start, int Length, string Replacement)>(); + + try + { + var reader = new Utf8JsonReader(utf8, new JsonReaderOptions + { + CommentHandling = JsonCommentHandling.Skip, + AllowTrailingCommas = true + }); + + string pendingProperty = null; + int containerDepth = -1; // CurrentDepth of tokens directly inside the targeted container + bool containerIsArray = false; + + while (reader.Read()) + { + if (containerDepth >= 0) + { + if (reader.CurrentDepth < containerDepth) + { + containerDepth = -1; // the container's own End token + continue; + } + + bool candidate = reader.CurrentDepth == containerDepth && + (containerIsArray + ? reader.TokenType == JsonTokenType.String + : reader.TokenType == JsonTokenType.PropertyName); + if (candidate) + { + string value = reader.GetString(); + if (value != null && value.IndexOf('@') >= 0) + { + // TokenStartIndex is the opening quote; ValueSpan is the raw content. + string masked = reader.ValueIsEscaped + ? JsonSerializer.Serialize(LogSanitizer.MaskEmail(value)) + : "\"" + LogSanitizer.MaskEmail(Encoding.UTF8.GetString(reader.ValueSpan)) + "\""; + edits.Add(((int)reader.TokenStartIndex, reader.ValueSpan.Length + 2, masked)); + } + } + continue; + } + + if (reader.TokenType == JsonTokenType.PropertyName) + { + pendingProperty = reader.GetString(); + continue; + } + + if (pendingProperty != null) + { + if (reader.TokenType == JsonTokenType.StartArray && MatchesAny(SanArrayFieldNames, pendingProperty)) + { + containerDepth = reader.CurrentDepth + 1; + containerIsArray = true; + } + else if (reader.TokenType == JsonTokenType.StartObject && MatchesAny(SanKeyedObjectFieldNames, pendingProperty)) + { + containerDepth = reader.CurrentDepth + 1; + containerIsArray = false; + } + } + pendingProperty = null; + } + } + catch (JsonException) + { + // Malformed or truncated body: keep the masks collected before the fault. Everything + // up to that point was well-formed, so those spans are correct. + } + + if (edits.Count == 0) return body; + + var output = new System.IO.MemoryStream(utf8.Length); + int cursor = 0; + foreach (var (start, length, replacement) in edits) + { + output.Write(utf8, cursor, start - cursor); + byte[] replacementBytes = Encoding.UTF8.GetBytes(replacement); + output.Write(replacementBytes, 0, replacementBytes.Length); + cursor = start + length; + } + output.Write(utf8, cursor, utf8.Length - cursor); + return Encoding.UTF8.GetString(output.GetBuffer(), 0, (int)output.Length); + + static bool MatchesAny(string[] keys, string name) + { + foreach (var key in keys) + if (string.Equals(key, name, StringComparison.OrdinalIgnoreCase)) return true; + return false; + } + } + + /// + /// Replaces the value of every occurrence of a JSON string field named + /// (case-insensitive, exact key match) with applied to the + /// original value. Leaves already-empty values untouched. Whitespace around the colon and + /// around the key's own quotes is tolerated. The value match is escape-aware (\" and + /// \\ do not end the string), so nothing after an escaped quote is left unredacted. + /// + private static string RedactJsonField(string body, string keyName, Func transform) + { + return System.Text.RegularExpressions.Regex.Replace( + body, + $@"(?i)(""{System.Text.RegularExpressions.Regex.Escape(keyName)}""\s*:\s*"")([^""\\]*(?:\\.[^""\\]*)*)("")", + m => string.IsNullOrEmpty(m.Groups[2].Value) + ? m.Value + : m.Groups[1].Value + transform(m.Groups[2].Value) + m.Groups[3].Value); + } + + /// + /// Applies the standard logging redaction pipeline to a request/response body before it + /// is written to a log line: credentials are always scrubbed via + /// , and personal-data fields are additionally scrubbed via + /// unless is + /// true. Centralizing this here keeps all six raw-body log sites in this + /// class (and LogApiFailure/LogV2ApiFailure) consistent and gives the on/off + /// behavior one place to unit-test. + /// + internal static string ApplyLoggingRedaction(string body, bool logSensitiveRequestData) + { + string redacted = RedactCredentials(body); + return logSensitiveRequestData ? redacted : RedactPersonalData(redacted); + } + /// /// Writes a structured log capturing every diagnostic field available for a /// non-success CERTInext API response — HTTP status, the CERTInext-side error @@ -1644,14 +3410,19 @@ internal static string RedactCredentials(string body) /// so SOX-loggable authentication events match /// the SIEM-alert level convention. /// - private static void LogApiFailure( + // Instance (not static) so it can read _config.LogSensitiveRequestData. + // The errorMessage argument is CA-supplied text and is masked here (idempotently), so callers + // may pass it raw or already masked. + private void LogApiFailure( string operationContext, RestResponse resp, string errorCode = null, string errorMessage = null, LogLevel level = LogLevel.Warning) { - string sanitizedBody = RedactCredentials(resp?.Content) ?? "(empty)"; + // Skip the redaction passes entirely when this level is disabled. + if (!Logger.IsEnabled(level)) return; + string sanitizedBody = ApplyLoggingRedaction(resp?.Content, _config.LogSensitiveRequestData) ?? "(empty)"; Logger.Log( level, "CERTInext API non-success. Operation={Operation}, HttpStatus={HttpStatus}, " + @@ -1659,14 +3430,30 @@ private static void LogApiFailure( operationContext, (int?)resp?.StatusCode ?? 0, errorCode ?? "(none)", - errorMessage ?? "(none)", + MaskCaText(errorMessage) ?? "(none)", Truncate(sanitizedBody, LoggedResponseBodyCapBytes)); } - private static string ExtractErrorMessage(string content, string operation) + /// + /// Masks email-shaped tokens in, and strips CR/LF from, CA-supplied error text unless + /// LogSensitiveRequestData is on. Use for every CA message that reaches a log line or + /// an exception message; feed the raw text instead. + /// + private string MaskCaText(string text) => LogSanitizer.SanitizeCaText(text, _config.LogSensitiveRequestData); + + /// + /// Builds the exception/log message for a non-success CERTInext body. CA-supplied text + /// (meta.errorMessage, meta.errorCode, legacy message) goes through + /// ; + /// defaults to false so a caller that omits it fails closed. + /// + internal static string ExtractErrorMessage( + string content, string operation, int? httpStatus = null, bool logSensitiveRequestData = false) { + string status = httpStatus.HasValue ? $" (HTTP {httpStatus.Value})" : string.Empty; + if (string.IsNullOrWhiteSpace(content)) - return $"CERTInext returned no body for operation '{operation}'."; + return $"CERTInext returned no body{status} for operation '{operation}'."; if (content.Length > MaxErrorBodyBytes) { @@ -1685,22 +3472,24 @@ private static string ExtractErrorMessage(string content, string operation) { string errMsg = null; string errCode = null; - if (meta.TryGetProperty("errorMessage", out var em)) errMsg = em.GetString(); - if (meta.TryGetProperty("errorCode", out var ec)) errCode = ec.GetString(); + if (meta.TryGetProperty("errorMessage", out var em)) + errMsg = LogSanitizer.SanitizeCaText(em.GetString(), logSensitiveRequestData); + if (meta.TryGetProperty("errorCode", out var ec)) + errCode = LogSanitizer.SanitizeCaText(ec.GetString(), logSensitiveRequestData); if (!string.IsNullOrWhiteSpace(errMsg) || !string.IsNullOrWhiteSpace(errCode)) - return $"CERTInext error during '{operation}': {errMsg ?? errCode} [{errCode}]"; + return $"CERTInext error during '{operation}'{status}: {errMsg ?? errCode} [{errCode}]"; } // Fall back to legacy ApiErrorResponse shape if (doc.RootElement.TryGetProperty("message", out var legacyMsg)) - return $"CERTInext error during '{operation}': {legacyMsg.GetString()}"; + return $"CERTInext error during '{operation}'{status}: {LogSanitizer.SanitizeCaText(legacyMsg.GetString(), logSensitiveRequestData)}"; } catch { // Fall through to safe generic message } - return $"CERTInext returned an unrecognised error body for operation '{operation}'. " + + return $"CERTInext returned an unrecognised error body{status} for operation '{operation}'. " + "See gateway logs for details."; } diff --git a/CERTInext/Client/ICERTInextClient.cs b/CERTInext/Client/ICERTInextClient.cs index cbba099..b4cd8fe 100644 --- a/CERTInext/Client/ICERTInextClient.cs +++ b/CERTInext/Client/ICERTInextClient.cs @@ -1,4 +1,4 @@ -// Copyright 2024 Keyfactor +// Copyright 2026 Keyfactor // Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. // You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 // Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, @@ -10,6 +10,7 @@ using System.Threading; using System.Threading.Tasks; using Keyfactor.Extensions.CAPlugin.CERTInext.API; +using Keyfactor.Extensions.CAPlugin.CERTInext.API.V2; namespace Keyfactor.Extensions.CAPlugin.CERTInext.Client { @@ -172,5 +173,232 @@ Task VerifyDcvAsync( string domainName, string dcvMethod, CancellationToken ct = default); + + // ----------------------------------------------------------------------- + // V2 REST API methods — only active when UseV2Api = true + // ----------------------------------------------------------------------- + + /// + /// V2 connectivity check via GET /api/certinext/v2/auth/me. + /// Throws if the V2 endpoint is unreachable or credentials are invalid. + /// + Task PingV2Async(CancellationToken ct = default); + + /// + /// Places a new SSL/TLS order via POST /api/certinext/v2/{productFamilySlug}. + /// A non-blank product code is sent as the X-Product-Code header (the spec's optional + /// override); null/blank omits it and CERTInext resolves the product itself. + /// An Idempotency-Key is generated automatically. + /// must be ssl-certificates: this body is the + /// SSL/TLS shape, and sending it to another family's endpoint would send the wrong body + /// shape to that family's create endpoint — any other slug throws + /// before a request is made. Use + /// the / + /// overloads for the other families. + /// + Task PlaceOrderV2Async( + string productFamilySlug, + string productCode, + V2CreateSslOrderRequest request, + CancellationToken ct = default); + + /// + /// Places a new Private PKI order via POST /api/certinext/v2/private-pki-certificates. + /// Same X-Product-Code / Idempotency-Key handling as the SSL overload. + /// + /// A distinct overload rather than a shared base type on the SSL overload's request + /// parameter, deliberately: every existing Moq Setup/Callback is typed to + /// , and widening that parameter would break the + /// typed callbacks at runtime. The family is implied by the request type, so there is no + /// slug parameter that could be mismatched with the body. + /// + Task PlaceOrderV2Async( + string productCode, + V2CreatePrivatePkiOrderRequest request, + CancellationToken ct = default); + + /// + /// Places a new Document Signer order via POST /api/certinext/v2/signature-certificates. + /// Same X-Product-Code / Idempotency-Key handling as the SSL overload. Not + /// yet called by EnrollV2Async — see . + /// + Task PlaceOrderV2Async( + string productCode, + V2CreateSignatureOrderRequest request, + CancellationToken ct = default); + + /// + /// Submits a CSR to an existing V2 order via PUT /api/certinext/v2/{family}/{orderId}/csr. + /// Used by the two-call flow (the default for SSL/TLS, and always for Private PKI). With + /// V2InlineCsr the SSL/TLS create carries the CSR and this is never called (a PUT after an + /// inline CSR is rejected 422). + /// + Task SubmitCsrV2Async( + string productFamilySlug, + string orderId, + string csrPem, + CancellationToken ct = default); + + /// + /// Returns the current status of a V2 order via GET /api/certinext/v2/{family}/{orderId}. + /// Throws when the order does not exist in that family. + /// + Task TrackOrderV2Async( + string productFamilySlug, + string orderId, + CancellationToken ct = default); + + /// + /// Downloads the issued certificate for a V2 order. + /// GET /api/certinext/v2/{family}/{orderId}/certificate + /// + Task DownloadCertificateV2Async( + string productFamilySlug, + string orderId, + CancellationToken ct = default); + + /// + /// Revokes a V2 certificate via POST /api/certinext/v2/{family}/{orderId}/revoke. + /// An Idempotency-Key is generated automatically. + /// + Task RevokeOrderV2Async( + string productFamilySlug, + string orderId, + V2RevokeRequest request, + CancellationToken ct = default); + + /// + /// Accepts the Subscriber Agreement of an SSL/TLS order that is waiting at + /// pending-agreement, via POST /api/certinext/v2/ssl-certificates/{orderId}/agreement + /// with body { "agreement": { signerName, signerPlace, accepted } } (spec: "the CA will + /// not release the certificate until this is done"). SSL/TLS only: any other + /// throws before a + /// request is made. Not an idempotent call as far as the spec says, so it is never retried. + /// + Task AcceptAgreementV2Async( + string productFamilySlug, + string orderId, + V2AgreementParams agreement, + CancellationToken ct = default); + + /// + /// Cancels a not-yet-issued V2 order via POST /api/certinext/v2/{family}/{orderId}/cancel + /// with body { "reason": ... }. An Idempotency-Key is generated + /// automatically. Returns on 2xx (spec: 204) + /// and on 422 (spec: "order already in + /// a terminal state"); throws on any other failure. Never retries. + /// + /// One of the Constants.ApiV2.Family* slugs. + /// The V2 order ID. + /// Required free-text reason (the CA rejects an empty one with EMS-984). + Task CancelOrderV2Async( + string productFamilySlug, + string orderId, + string reason, + CancellationToken ct = default); + + /// + /// Returns V2 auth/me response (accountNumber, authType). + /// + Task GetAuthMeV2Async(CancellationToken ct = default); + + /// + /// Resolves the product-family slug for the given V2 order ID by probing all three + /// families (ssl → private-pki → signature), then returns the track response. + /// Throws if the order is not found in any family. + /// + Task ResolveAndTrackOrderV2Async( + string orderId, + CancellationToken ct = default); + + /// + /// Resolves the product-family slug for the given V2 order ID and downloads the certificate. + /// Throws if the order is not found in any family. + /// + Task ResolveAndDownloadCertificateV2Async( + string orderId, + CancellationToken ct = default); + + /// + /// Returns the DCV challenge details for a V2 order. + /// GET /api/certinext/v2/{familySlug}/{orderId}/dcv + /// + Task GetDcvV2Async(string orderId, string familySlug, CancellationToken ct = default); + + /// + /// Returns the DCV challenge details for one specific domain on a V2 order. + /// GET /api/certinext/v2/{familySlug}/{orderId}/dcv?domain={domain} + /// + /// A distinct overload rather than an optional parameter on + /// deliberately: Moq (and any other expression-tree-based mocking) cannot omit an + /// argument on a mocked call — every existing 3-argument Setup/Verify for the no-domain + /// overload would otherwise fail to compile. Parameter order mirrors + /// 's established (orderId, domain, familySlug, ct) + /// convention. Returns a distinct token per SAN on a UCC order. + /// + Task GetDcvV2Async(string orderId, string domain, string familySlug, CancellationToken ct = default); + + /// + /// Asks CERTInext to verify the DNS TXT record for the given domain on a V2 order. + /// POST /api/certinext/v2/{familySlug}/{orderId}/dcv/verify + /// Both 200 OK and 204 No Content are treated as success. + /// Throws on 422 (verification failed). + /// + Task VerifyDcvV2Async(string orderId, string domain, string familySlug, CancellationToken ct = default); + + /// + /// Resolves the product-family slug for the given V2 order ID by probing all three + /// families (ssl → private-pki → signature), then returns both the resolved slug and the + /// track response. Use this when the caller needs to pass the family slug to downstream + /// operations such as DCV. + /// Throws if the order is not found in any family. + /// + Task<(string family, V2OrderStatusResponse status)> ResolveAndTrackOrderV2WithFamilyAsync( + string orderId, + CancellationToken ct = default); + + /// + /// Returns the list of products available in the V2 catalog. + /// GET /api/certinext/v2/catalog/products + /// + Task> GetProductDetailsV2Async(CancellationToken ct = default); + + /// + /// Pages through all orders via GET /api/certinext/v2/reports/orders. Used for V2-mode + /// Synchronize. Paging is 1-based; is clamped + /// to (100) server-side. + /// + /// Optional inclusive start date filter (YYYY-MM-DD). + /// Optional inclusive end date filter (YYYY-MM-DD). + /// Page size requested; server clamps to 100. + IAsyncEnumerable ListOrdersV2Async( + string from = null, + string to = null, + int pageSize = Constants.Api.DefaultPageSize, + CancellationToken ct = default); + + /// + /// Reads an organization's SSL.com validation status via + /// GET /api/certinext/v2/organizations/{orgNumber}/ca-validations/sslcom: status per level + /// (OV, EV) with validTill, what is still missing before submission, and the SSL.com contact. + /// + Task GetSslComValidationAsync(string organizationNumber, CancellationToken ct = default); + + /// + /// Re-reads the organization from SSL.com via + /// POST /api/certinext/v2/organizations/{orgNumber}/ca-validations/sslcom/sync and returns the + /// same body as the GET. + /// + Task SyncSslComValidationAsync(string organizationNumber, CancellationToken ct = default); + + /// + /// Submits an organization to SSL.com for validation via + /// POST /api/certinext/v2/organizations/{orgNumber}/ca-validations/sslcom. The body's + /// subscriberAgreementAccepted must be true, i.e. calling this accepts SSL.com's + /// subscriber agreement on the organization's behalf. Spec: "Safe to repeat: a level already + /// requested is skipped." Returns the response body, or null when the CA answers with none. + /// + Task SubmitSslComValidationAsync( + string organizationNumber, V2SslComSubmitRequest request, CancellationToken ct = default); } } diff --git a/CERTInext/Client/V2CertificateNotGeneratedException.cs b/CERTInext/Client/V2CertificateNotGeneratedException.cs new file mode 100644 index 0000000..a11ed58 --- /dev/null +++ b/CERTInext/Client/V2CertificateNotGeneratedException.cs @@ -0,0 +1,25 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Client +{ + /// + /// Thrown by DownloadCertificateV2Async when CERTInext answers HTTP 422 with + /// EMS-1165 Invalid request status.. The same code also means "never downloadable" for a + /// revoked order, so the response alone can't distinguish the cases; a caller that already knows + /// the order is issued (Track Order, or the report row) treats it as "issued at the CA, + /// certificate not generated yet" - normally resolved within about 20 seconds - and keeps + /// waiting instead of reporting a download failure. Carries the same message text the generic + /// V2 failure would have had, so existing message-based handling is unaffected. + /// + public sealed class V2CertificateNotGeneratedException : Exception + { + public V2CertificateNotGeneratedException(string message) : base(message) { } + } +} diff --git a/CERTInext/Constants.cs b/CERTInext/Constants.cs index 83e6929..bd2ec54 100644 --- a/CERTInext/Constants.cs +++ b/CERTInext/Constants.cs @@ -1,4 +1,4 @@ -// Copyright 2024 Keyfactor +// Copyright 2026 Keyfactor // Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. // You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 // Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, @@ -20,15 +20,31 @@ public static class Config public const string AuthMode = "AuthMode"; public const string Enabled = "Enabled"; public const string IgnoreExpired = "IgnoreExpired"; + public const string SubmitNonDnsSans = "SubmitNonDnsSans"; public const string PageSize = "PageSize"; + + // Diagnostic escape hatch — see CERTInextConfig.LogSensitiveRequestData. Off by + // default; only meant for temporary use while verifying a new deployment. + public const string LogSensitiveRequestData = "LogSensitiveRequestData"; + + // Synchronous certificate pickup (parity with the legacy Sectigo connector). + // After submitting an order, Enroll() polls GetCertificate up to PickupRetries + // times, PickupDelay seconds apart (after a fixed initial delay), so a fast-issuing + // order returns the issued certificate in the same enrollment call instead of + // waiting for the next synchronization. On timeout the order is returned pending and + // imported by a later sync. + public const string PickupRetries = "PickupRetries"; + public const string PickupDelay = "PickupDelay"; + public const string RequestorName = "RequestorName"; public const string RequestorEmail = "RequestorEmail"; public const string RequestorIsdCode = "RequestorIsdCode"; public const string RequestorMobileNumber = "RequestorMobileNumber"; + public const string RequestorDesignation = "RequestorDesignation"; public const string SignerPlace = "SignerPlace"; public const string SignerIp = "SignerIp"; - // Technical point-of-contact defaults (TpcName/Email default to Requestor* when blank) + // Technical point-of-contact (each poc* field defaults to its Requestor* value when blank) public const string TechnicalContactName = "TechnicalContactName"; public const string TechnicalContactEmail = "TechnicalContactEmail"; public const string TechnicalContactIsdCode = "TechnicalContactIsdCode"; @@ -63,13 +79,23 @@ public static class Config public const string DcvWaitForIssuanceSeconds = "DcvWaitForIssuanceSeconds"; // Bounds on DCV-during-sync so a large pending backlog can't make a sync pass - // slow (issue 0002). Only pending orders younger than DcvSyncMaxOrderAgeHours + // slow. Only pending orders younger than DcvSyncMaxOrderAgeHours // are eligible for DCV completion during sync, and at most DcvSyncMaxPerPass // orders are attempted per pass; the rest are emitted as pending and revisited // on a later pass (the per-minute incremental cadence keeps recent orders moving). public const string DcvSyncMaxOrderAgeHours = "DcvSyncMaxOrderAgeHours"; public const string DcvSyncMaxPerPass = "DcvSyncMaxPerPass"; + // V2 mode only: incremental-sync lookback window for /reports/orders. + public const string V2SyncLookbackHours = "V2SyncLookbackHours"; + // V1 and V2: sync does not emit pending or issued orders younger than this (issue 0090). + public const string SyncRecentOrderGraceSeconds = "SyncRecentOrderGraceSeconds"; + public const string V2InlineCsr = "V2InlineCsr"; // opt-in: SSL/TLS sends the CSR inline on create (V2 only) + // V2 OV/EV orders: opt-in submission of the organization to SSL.com for validation, which + // accepts SSL.com's subscriber agreement on the organization's behalf (default off). + public const string SslComSubmitOrganization = "SslComSubmitOrganization"; + public const string SslComAdminEmail = "SslComAdminEmail"; + // Environment variable that overrides DcvTimeoutMinutes when set. public const string DcvTimeoutMinutesEnvVar = "CERTINEXT_DCV_TIMEOUT_MINUTES"; public const string DcvWaitForChallengeSecondsEnvVar = "CERTINEXT_DCV_WAIT_FOR_CHALLENGE_SECONDS"; @@ -99,7 +125,7 @@ public static class EnrollmentParam public const string ProductCode = "ProductCode"; // CERTInext numeric product code public const string ProfileId = "ProfileId"; // alias for ProductCode (kept for back-compat) public const string ValidityYears = "ValidityYears"; // 1, 2, or 3 - public const string ValidityDays = "ValidityDays"; // legacy; mapped to years if set + public const string ValidityDays = "ValidityDays"; // V1: converted to whole years (rounded up); larger of years/days wins public const string AutoApprove = "AutoApprove"; public const string RequesterName = "RequesterName"; public const string RequesterEmail = "RequesterEmail"; @@ -111,6 +137,10 @@ public static class EnrollmentParam public const string SignerIp = "SignerIp"; public const string DomainName = "DomainName"; // primary domain for SSL/TLS orders public const string KeyType = "KeyType"; + + // V2 API enrollment parameters + public const string ProductFamily = "ProductFamily"; // V2: "ssl", "private-pki", or "signature" + public const string ProductVariant = "ProductVariant"; // V2: ssl "dv"/"ov"/"ev"; private-pki "intranet-ssl"/"igtf-host" } public static class Products @@ -126,9 +156,16 @@ public static class Products public const string EvSsl = "EV SSL"; public const string EvSslUcc = "EV SSL Multi-Domain (UCC)"; - // Default production numeric codes. These are the standard codes for the - // CERTInext production environment. Sandbox codes differ — set ProductCode - // explicitly on the template to override when targeting sandbox. + // V1-ONLY. Default production numeric codes for the CERTInext V1 (legacy) API. + // These are the standard codes for the CERTInext production environment under V1. + // Sandbox codes differ — set ProductCode explicitly on the template to override + // when targeting sandbox. + // + // Do NOT reuse this table for V2 dispatch: its numbering does not match the live + // V2 catalog — e.g. this table's "842" is OV SSL, but the live V2 + // catalog's "842" is DV SSL, a flat +4 offset across all 10 codes. V2 resolves the + // product code live from the Catalog response instead — see ProductTypeIdsV2 below + // and EnrollV2Async/ValidateProductInfo in CERTInextCAPlugin.cs. public static readonly System.Collections.Generic.Dictionary DefaultProductCodes = new System.Collections.Generic.Dictionary(System.StringComparer.OrdinalIgnoreCase) { @@ -143,6 +180,69 @@ public static class Products [EvSsl] = "846", [EvSslUcc] = "847", }; + + // V2-ONLY. Maps each product name (ProductId, as advertised by GetProductIds()) to + // the CERTInext V2 catalog's stable numeric productTypeID value (spec: + // "Get Product Details" field vocabulary). productTypeID is the CA's own documented mechanism + // for "programmatic routing" (its docs explicitly say productName is "for display" + // only) — unlike productCode (V1-era table above, wrong numbering for V2) or + // productName (varies by account/catalog version: the live catalog, the V1 spec + // table, and the V2 spec table each use different spellings/suffixes for the same + // product), productTypeID is a small, stable, CERTInext-documented + // enum. + // NOTE: 15/18/20/21/22 match the real V2 sandbox catalog; the other five + // (13/14/16/17/19) are spec-documented but have not been checked against it. + // + // Used by EnrollV2Async/ValidateProductInfo to resolve/validate the real V2 product + // code from the live catalog when no explicit ProductCode override is configured. + // Never used for V1. + public static readonly System.Collections.Generic.Dictionary ProductTypeIdsV2 = + new System.Collections.Generic.Dictionary(System.StringComparer.OrdinalIgnoreCase) + { + [DvSsl] = "13", + [DvSslWildcard] = "14", + [DvSslUcc] = "15", + [DvSslWildcardUcc] = "21", + [OvSsl] = "16", + [OvSslWildcard] = "17", + [OvSslUcc] = "18", + [OvSslWildcardUcc] = "22", + [EvSsl] = "19", + [EvSslUcc] = "20", + }; + + // V2-ONLY. Maps each SSL product name (ProductId) to the V2 create body's + // productVariant value ("dv"/"ov"/"ev"). Grouped by the same + // productTypeID assurance level ProductTypeIdsV2 above already documents (13-15 and + // 21 -> dv, 16-18 and 22 -> ov, 19-20 -> ev); kept as its own ProductId-keyed table + // (rather than a second indirection through ProductTypeIdsV2) so it reads the same way + // as DefaultProductCodes/ProductTypeIdsV2 above. + // + // Used by CERTInextCAPlugin.ResolveSslProductVariant (EnrollV2Async/ValidateProductInfo) + // to derive productVariant when the template's ProductVariant enrollment parameter is + // not set explicitly, and to reject an explicit ProductVariant that contradicts the + // selected product (e.g. "dv" configured for "OV SSL" — the bug this table fixes: the + // plugin was sending productVariant:"dv" for every product regardless of ProductId, + // which skips the OV/EV organization block CERTInext requires). + // + // All 10 SSL ProductIds are covered; there is no "unmapped" case today. private-pki + // and signature families are unrelated (private-pki's variant enum is intranet-ssl / + // igtf-host — Constants.ApiV2.PrivatePkiVariants — and signature enrollment is not yet + // supported) and must not consult this table. + public static readonly System.Collections.Generic.Dictionary ProductVariantsV2 = + new System.Collections.Generic.Dictionary(System.StringComparer.OrdinalIgnoreCase) + { + [DvSsl] = ApiV2.ProductVariantDv, + [DvSslWildcard] = ApiV2.ProductVariantDv, + [DvSslUcc] = ApiV2.ProductVariantDv, + [DvSslWildcardUcc] = ApiV2.ProductVariantDv, + [OvSsl] = ApiV2.ProductVariantOv, + [OvSslWildcard] = ApiV2.ProductVariantOv, + [OvSslUcc] = ApiV2.ProductVariantOv, + [OvSslWildcardUcc] = ApiV2.ProductVariantOv, + [EvSsl] = ApiV2.ProductVariantEv, + [EvSslUcc] = ApiV2.ProductVariantEv, + }; } public static class CertificateStatusId @@ -232,6 +332,31 @@ public static class Api public const int DefaultPageSize = 100; public const int MaxPageSize = 500; + // Enroll/sync race mitigation (issue 0090), shared by the V1 and V2 syncs. A sync that + // emits a row for an order whose enrollment has not saved yet makes the gateway insert a + // row with that CARequestID, and the enrollment's own save then fails on the unique + // (CA, CARequestID) index. So a sync (full or incremental) withholds pending and issued + // orders younger than this; the next incremental pass imports them (V2: the lookback + // re-lists them; V1: GetSyncIssuedAfter moves the listing start back). + // 120 s is the longest an enrollment normally runs before it gives up. + public const int DefaultSyncRecentOrderGraceSeconds = 120; + + // Added to the grace window when comparing against orderDate. Both listings carry + // orderDate as whole seconds, UTC, truncated (verified live 2026-10-15: V1 GetOrderReport + // rows are "yyyy-MM-dd HH:mm:ss", stamps 0.95-2.4 s before the gateway's UTC log clock; V2 + // /reports/orders rows are yyyy-MM-ddTHH:mm:ssZ, 0.8-1.4 s before the create response). + // Truncation makes an order look up to 1 s older than it is, and CA/gateway clock skew is + // not bounded by anything we control, so leave a few seconds of slack. + public const int SyncRecentOrderClockMarginSeconds = 5; + + // V1 only: the incremental listing filters orderDateFrom by UTC calendar day + // (CERTInextClient.ListCertificatesAsync). A held-back order is re-listed on the next pass + // only if its day is not before the day of the issuedAfter we send. Looking back by the + // hold window plus this slack (for the gateway's lastSync being the previous pass's end + // rather than its start) keeps an order created just before UTC midnight in the next + // pass's listing. + public const int SyncRecentOrderLookbackSlackSeconds = 300; + // Legacy path constants — kept so CERTInextClient can still reference them // without breaking existing callers while being replaced. // These do NOT exist in the real API. @@ -268,6 +393,41 @@ public static class RevocationReasonId public const int Default = KeyCompromise; } + public static class Pickup + { + // Defaults mirror the legacy Sectigo connector's PickUpEnrolledCertificate: + // a 5-second initial delay, then up to 5 poll attempts 10 seconds apart, so the + // maximum time an enrollment call occupies a Command worker thread is + // InitialDelaySeconds + DefaultRetries * DefaultDelaySeconds = 5 + 5*10 = 55 seconds. + // Set PickupRetries to 0 to disable the wait entirely (immediate pending return). + public const int DefaultRetries = 5; + public const int DefaultDelaySeconds = 10; + + // Small static delay before the first poll — gives a fast order a chance to finish + // issuing before we poll at all, avoiding a guaranteed-miss first attempt. + public const int InitialDelaySeconds = 5; + + // Per-factor safety clamps so a single mis-typed value cannot produce a tight busy-loop + // or an absurd per-attempt delay. These bound each knob independently; the *product* + // (retries * delay) is bounded separately by MaxTotalWaitSeconds below. + public const int MaxRetries = 30; + public const int MaxDelaySeconds = 60; + + // Command's observed enrollment-call timeout: the stock .NET HttpClient default of 100 + // seconds, confirmed in the field (Command_API_Log.txt: EJBCAWebClient.CertificateRequestEnroll + // aborted with "HttpClient.Timeout of 100 seconds elapsing"). Enroll() is called synchronously + // on this budget, so any in-call pickup wait must fit comfortably inside it. + public const int CommandEnrollmentBudgetSeconds = 100; + + // Hard ceiling on total in-call pickup occupancy (initial delay + retries * delay). + // The per-factor clamps above still permit a ~1805s product at the extremes, which would + // push Enroll() past CommandEnrollmentBudgetSeconds; the pickup paths cap the effective + // retry count (ComputeMaxPollRetries) so the total never exceeds this. Set to 75s - 25s of + // headroom inside the 100s Command budget for the order submit (plus DCV/CSR calls on V2) + // and per-poll round-trips, which also consume that budget but aren't counted in this ceiling. + public const int MaxTotalWaitSeconds = 75; + } + public static class Dcv { // CERTInext dcvMethod values (dcvDetails.dcvMethod in GetDcv / VerifyDcv) @@ -285,6 +445,17 @@ public static class Dcv // Override via the DcvTxtRecordTemplate connector config field. public const string DefaultTxtRecordTemplate = "_emsign-validation.{0}"; + // Independent bound for a single CleanupValidation (TXT-record removal) call. This is + // deliberately its own fixed ceiling, not a fraction of DcvTimeoutMinutes and not the + // ambient DCV-flow cancellation token: cleanup is a best-effort compensating action that + // must get a real chance to run even when the operation it's cleaning up after was + // itself cancelled (the ambient token would already be cancelled at that point), but it + // still must not be allowed to hang the calling gateway request forever if a DNS + // provider plugin's underlying network call stalls. 60s comfortably covers a single + // DELETE-shaped call under normal conditions (the reference CloudflareDomainValidator's + // HttpClient default alone is 100s) without risking an indefinite hang. + public const int CleanupValidationTimeoutSeconds = 60; + // Defaults for the DCV-during-sync bounds (issue 0002). public const int DefaultSyncMaxOrderAgeHours = 24; public const int DefaultSyncMaxPerPass = 50; @@ -297,7 +468,161 @@ public static class Dcv public const int SyncPropagationDelaySeconds = 3; } + /// + /// V2 REST API constants — all paths, status strings, and family slugs for the + /// /api/certinext/v2/ surface. Auth is OAuth2 client_credentials. The plugin sends + /// an Idempotency-Key header on order-create/revoke, but the spec only documents + /// this header (as "parsed today, enforced in a future release") on Verify DCV and Domains + /// endpoints, not order-create/revoke. + /// + public static class ApiV2 + { + // Auth / connectivity + public const string TokenPath = "/oauth/token"; + public const string AuthMePath = "/api/certinext/v2/auth/me"; + + // Product-family resource paths (appended to base URL) + public const string SslCertificatesPath = "/api/certinext/v2/ssl-certificates"; + public const string PrivatePkiCertificatesPath = "/api/certinext/v2/private-pki-certificates"; + public const string SignatureCertificatesPath = "/api/certinext/v2/signature-certificates"; + public const string CatalogProductsPath = "/api/certinext/v2/catalog/products"; + + // SSL.com organization validation: {OrganizationsPath}/{orgNumber}/{SslComValidationSuffix} + // (GET status, POST submit) and .../{SslComValidationSuffix}/sync (POST refresh). + public const string OrganizationsPath = "/api/certinext/v2/organizations"; + public const string SslComValidationSuffix = "ca-validations/sslcom"; + + // Order status strings (V2 REST — NOT numeric IDs) + public const string StatusPendingDcv = "pending-dcv"; + public const string StatusPendingCsr = "pending-csr"; + public const string StatusPendingAgreement = "pending-agreement"; + public const string StatusPendingOrganizationVerification = "pending-organization-verification"; + public const string StatusPendingDocuments = "pending-documents"; + public const string StatusPendingApproval = "pending-approval"; + public const string StatusIssued = "issued"; + public const string StatusCancelled = "cancelled"; + public const string StatusRevoked = "revoked"; + public const string StatusRejected = "rejected"; + public const string StatusExpired = "expired"; + // Spec-documented V2 status — CERTInext can't say where the order is; not terminal. + public const string StatusUnknown = "unknown"; + + // Per-domain dcvStatus values on Track Order's verifications.domain.domains[] + // block: PENDING while a SAN's DCV is outstanding, VERIFIED once confirmed, + // REJECTED after the parent + // order is cancelled. Uppercase — distinct from the V1 Dcv class's numeric "0"/"1" + // dcvStatus values, which belong to a different API generation entirely. + public const string DcvStatusPending = "PENDING"; + public const string DcvStatusVerified = "VERIFIED"; + public const string DcvStatusRejected = "REJECTED"; + + // Product-family slugs (used as URL path segments) + public const string FamilySsl = "ssl-certificates"; + public const string FamilyPrivatePki = "private-pki-certificates"; + public const string FamilySignature = "signature-certificates"; + + // productVariant values that require an organization block — every + // other value (dv and its wildcard/UCC combinations) omits it entirely. + public const string ProductVariantOv = "ov"; + public const string ProductVariantEv = "ev"; + + // The SSL family's own "no assurance vetting" variant. Given its own named constant + // so Constants.Products.ProductVariantsV2 below doesn't repeat the "dv" + // literal that EnrollmentParams.ProductVariant/V2CreateSslOrderRequest.ProductVariant + // also default to. + public const string ProductVariantDv = "dv"; + + // Private PKI create-body `variant` enum. Spec, "Private PKI + // Certificates" field table: "`variant` | **Mandatory** (`intranet-ssl` / + // `igtf-host`)". Sourced from the ProductVariant template parameter (the same + // "variant within the family" parameter the SSL body's productVariant uses). + // Note: the spec's create-*response* table echoes a wider enum (`intranet-ssl` / + // `igtf-host` / `igtf-personal` / `device` / `vpn`) — only the two documented + // create values are accepted here. + public const string PrivatePkiVariantIntranetSsl = "intranet-ssl"; + public const string PrivatePkiVariantIgtfHost = "igtf-host"; + public static readonly System.Collections.Generic.HashSet PrivatePkiVariants = + new System.Collections.Generic.HashSet(System.StringComparer.OrdinalIgnoreCase) + { + PrivatePkiVariantIntranetSsl, + PrivatePkiVariantIgtfHost + }; + + // Create-body `emailNotifications` silent value. The spec's enum is + // `consent-only | all` (it used to accept "0"); "consent-only" is the quietest setting. + // The connector's EmailNotifications=0 maps to it and =1 maps to "all". + public const string EmailNotificationsConsentOnly = "consent-only"; + + // Catalog productTypeID for Private PKI products. Spec, Catalog -> List Products + // "productTypeID values": `"39"` | Private PKI | Private PKI (`8`). Also observed live + // on the sandbox catalog (product 149, "Sandbox emSign Intranet SSL 1 Year"). + public const string PrivatePkiProductTypeId = "39"; + + // Document Signer create-body `subjectType` enum. Spec, "Document + // Signer Certificates" field table: "`subjectType` | **Mandatory** + // (`natural-person` / `legal-person` / `legal-entity`)". Not yet sourced by + // EnrollV2Async — signature enrollment is still an open design decision. + public static readonly System.Collections.Generic.HashSet SignatureSubjectTypes = + new System.Collections.Generic.HashSet(System.StringComparer.OrdinalIgnoreCase) + { + "natural-person", + "legal-person", + "legal-entity" + }; + + // Fixed designation sent on technicalPointOfContact.designation. The + // spec documents this as free text with no enum (examples: "Technical Contact", + // "IT Administrator", "PKI Manager", "Authorized Signer") and there is no connector + // config field for it — deliberately out of scope for + // RequestorDesignation (Config.RequestorDesignation), which only covers + // requestor.designation. No existing generic designation/title config field was + // found to reuse for this one, so this remains a fixed default. + public const string DefaultTechnicalContactDesignation = "Technical Contact"; + + // UCC (multi-SAN) product family detection — from the live Catalog response's + // productTypeID field: 15=DV SSL UCC, 18=OV SSL UCC, 20=EV SSL UCC, + // 21=DV SSL Wildcard UCC, 22=OV SSL Wildcard UCC. + // Deliberately NOT derived from Constants.Products.DefaultProductCodes — that table's + // numbering disagrees with the live/spec numbering. + public static readonly System.Collections.Generic.HashSet UccProductTypeIds = + new System.Collections.Generic.HashSet { "15", "18", "20", "21", "22" }; + + // Non-UCC wildcard product family detection — from the live Catalog response's + // productTypeID field: 14=DV SSL Wildcard, 17=OV SSL Wildcard + // (Constants.Products.ProductTypeIdsV2). Deliberately excludes the UCC wildcard + // type IDs (21/22, in UccProductTypeIds above) — those are already exempt from + // the single-domain SAN guard by virtue of being UCC, and their additionalDomains + // handling is unrelated to the apex-SAN exemption this set is used for (the V2 + // single-domain enrollment guard in EnrollV2Async). + public static readonly System.Collections.Generic.HashSet WildcardProductTypeIds = + new System.Collections.Generic.HashSet { "14", "17" }; + + // Orders report (Synchronize, V2 mode) — GET /api/certinext/v2/reports/orders. + // Spring-style page envelope: content/page/size/totalPages/totalElements. + // Paging is 1-based; size is clamped to 100 server-side; page=0 is treated as + // page 1. + public const string OrdersReportPath = "/api/certinext/v2/reports/orders"; + public const int OrdersReportMaxPageSize = 100; + + // Default lookback window: whether /reports/orders' from/to filter brackets order + // date or issue date is not documented. + // An incremental sync re-requests from (lastSync - this window) rather than + // exactly lastSync, so an order created before lastSync but issued after it + // (e.g. a slow-DCV order) still surfaces. See CERTInextConfig.V2SyncLookbackHours. + public const int DefaultSyncLookbackHours = 72; + } + + // V2 config key constants (added here alongside existing Config constants) + public static class ConfigV2 + { + public const string UseV2Api = "UseV2Api"; + } + // Legacy string revocation reasons — retained so StatusMapper still compiles. + // V1 never puts these on the wire (RevokeOrderRequest sends a numeric + // revokeReasonId — see CERTInextClient.RevokeCertificateAsync / + // MapLegacyReasonStringToCrlCode), so this class is intentionally left + // untouched by the V2 kebab-case fix; see RevocationReasonV2 below. public static class RevocationReason { public const string Unspecified = "unspecified"; @@ -311,5 +636,27 @@ public static class RevocationReason public const string PrivilegeWithdrawn = "privilegeWithdrawn"; public const string AACompromise = "aACompromise"; } + + // V2 API revocation reason strings. These must match the CERTInext V2 spec's + // kebab-case `reason` enum exactly ("Revoke Certificate" in the + // V2 spec). Sending camelCase (the + // values shared with the legacy RevocationReason class above) gets + // HTTP 400. `AACompromise` is accepted on the + // signature-certificates / private-pki-certificates revoke endpoints per spec, + // but is not documented on ssl-certificates; kept here as the RFC 5280 code-10 + // mapping for those other families. There is no V2 equivalent of the RFC 5280 + // CRL-only "removeFromCRL" (code 8) reason, so it is intentionally absent here. + public static class RevocationReasonV2 + { + public const string Unspecified = "unspecified"; + public const string KeyCompromise = "key-compromise"; + public const string CACompromise = "ca-compromise"; + public const string AffiliationChanged = "affiliation-changed"; + public const string Superseded = "superseded"; + public const string CessationOfOperation = "cessation-of-operation"; + public const string CertificateHold = "certificate-hold"; + public const string PrivilegeWithdrawn = "privilege-withdrawn"; + public const string AACompromise = "aa-compromise"; + } } } diff --git a/CERTInext/Models/EnrollmentParams.cs b/CERTInext/Models/EnrollmentParams.cs index 69b662f..5cc2373 100644 --- a/CERTInext/Models/EnrollmentParams.cs +++ b/CERTInext/Models/EnrollmentParams.cs @@ -1,4 +1,4 @@ -// Copyright 2024 Keyfactor +// Copyright 2026 Keyfactor // Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. // You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 // Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, @@ -33,14 +33,18 @@ public EnrollmentParams(EnrollmentProductInfo productInfo) /// Resolution order: /// 1. ProductCode template parameter (explicit override — use for sandbox or non-standard codes) /// 2. ProfileId template parameter (deprecated alias for ProductCode) - /// 3. Default production code looked up from the selected product name (ProductId) + /// 3. V1-ONLY fallback: default production code looked up from the selected product + /// name (ProductId) via Constants.Products.DefaultProductCodes. + /// V2 callers must check before using this value: + /// when false, this getter's fallback (step 3) is the V1-era table, whose numbering does + /// not match the live V2 catalog — resolve the V2 code from the live catalog + /// by ProductTypeId instead (see EnrollV2Async / ValidateProductInfo). /// public string ProductCode { get { - var explicit_ = GetString(Constants.EnrollmentParam.ProductCode, - GetString(Constants.EnrollmentParam.ProfileId, string.Empty)); + var explicit_ = GetExplicitProductCode(); if (!string.IsNullOrEmpty(explicit_)) return explicit_; @@ -52,7 +56,24 @@ public string ProductCode /// Alias for ProductCode — kept for backward compat. public string ProfileId => ProductCode; - /// Requested validity in days; 0 means "use profile default". + /// + /// True when an explicit ProductCode or ProfileId override was configured on the + /// template. False means 's getter falls back to the V1-only + /// Constants.Products.DefaultProductCodes table — V2 callers must not use that fallback + /// value; resolve the code from the live catalog by ProductTypeId instead. + /// + public bool HasExplicitProductCode => !string.IsNullOrEmpty(GetExplicitProductCode()); + + private string GetExplicitProductCode() + { + return GetString(Constants.EnrollmentParam.ProductCode, + GetString(Constants.EnrollmentParam.ProfileId, string.Empty)); + } + + /// Requested subscription validity in years (1, 2, or 3). On V1 the order uses the larger of this and ValidityDays in years; V2 uses only this. + public int ValidityYears => GetInt(Constants.EnrollmentParam.ValidityYears, 0); + + /// Requested validity in days (V1 only), converted to whole years (rounded up); 0 means unset. public int ValidityDays => GetInt(Constants.EnrollmentParam.ValidityDays, 0); /// Whether to auto-approve pending-approval certificates. @@ -73,8 +94,8 @@ public string ProductCode public string KeyType => GetString(Constants.EnrollmentParam.KeyType, string.Empty); /// - /// Primary domain name for SSL/TLS orders. - /// Derived from the CSR CN by the client if omitted here. + /// Primary domain name for SSL/TLS orders (and the hostname of a V2 private-pki + /// order). Derived from the CSR CN by the client if omitted here. /// public string DomainName => GetString(Constants.EnrollmentParam.DomainName, string.Empty); @@ -96,6 +117,46 @@ public string ProductCode /// public string SignerIp => GetString(Constants.EnrollmentParam.SignerIp, string.Empty); + // ------------------------------------------------------------------ + // V2 API parameters + // ------------------------------------------------------------------ + + /// + /// V2 product family. Accepted values: "ssl" (default), "private-pki", "signature". + /// Used to select the correct V2 resource path. + /// + public string ProductFamily => GetString(Constants.EnrollmentParam.ProductFamily, "ssl"); + + /// + /// V2 product family as the REST path slug used in V2 URL construction. + /// Maps "ssl" → "ssl-certificates", "private-pki" → "private-pki-certificates", + /// "signature" → "signature-certificates". + /// + public string ProductFamilySlug => ProductFamily.ToLowerInvariant() switch + { + "ssl" => Constants.ApiV2.FamilySsl, + "private-pki" => Constants.ApiV2.FamilyPrivatePki, + "signature" => Constants.ApiV2.FamilySignature, + _ => Constants.ApiV2.FamilySsl + }; + + /// + /// V2 product variant within the family, sent in the order body. For the SSL family this + /// is the productVariant field ("dv", "ov", "ev"); for the private-pki family it + /// is the variant field ("intranet-ssl", "igtf-host"). + /// Default: "dv" (SSL-only; private-pki enrollment rejects it — see + /// ). + /// + public string ProductVariant => GetString(Constants.EnrollmentParam.ProductVariant, "dv"); + + /// + /// True when the ProductVariant template parameter is actually set (non-blank), as + /// opposed to falling back to its SSL-only "dv" default. + /// Used only to word the private-pki validation error accurately. + /// + public bool HasExplicitProductVariant => + !string.IsNullOrEmpty(GetString(Constants.EnrollmentParam.ProductVariant, string.Empty)); + // ------------------------------------------------------------------ // Helpers // ------------------------------------------------------------------ diff --git a/CERTInext/Models/LogSanitizer.cs b/CERTInext/Models/LogSanitizer.cs new file mode 100644 index 0000000..3cc1611 --- /dev/null +++ b/CERTInext/Models/LogSanitizer.cs @@ -0,0 +1,196 @@ +// Copyright 2026 Keyfactor +// Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. +// You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 +// Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions +// and limitations under the License. + +using System; +using System.Collections.Generic; +using System.Linq; +using System.Text.RegularExpressions; + +namespace Keyfactor.Extensions.CAPlugin.CERTInext.Models +{ + /// + /// Neutralizes control characters before a requester-controlled value is interpolated into a + /// log message. + /// + /// SAN values reach the log from the CSR and from Command's SAN dictionary, i.e. from the + /// requester. Structured message templates stop format-string abuse but not embedded newlines, + /// and NLog's text layout does not escape them — so an unsanitized value can forge additional, + /// well-formed-looking records in the gateway log (CWE-117). That matters here specifically + /// because these log lines exist to make the submitted SAN set auditable; a forged line could + /// assert a different SAN set than the one actually sent. + /// + /// Shared between CERTInextCAPlugin and Client.CERTInextClient — both sanitize the + /// same kind of value at their respective log sinks, so a single shared definition keeps + /// them identical. + /// + internal static class LogSanitizer + { + internal static string Strip(string value) + { + if (string.IsNullOrEmpty(value)) return value; + return value + .Replace("\r", "\\r") + .Replace("\n", "\\n") + .Replace("\t", "\\t"); + } + + /// + /// Masks the local part of an email address for logging while preserving the domain + /// (e.g. "j***@example.com"), so an operator can still tell which organization + /// an order came from without seeing exactly who submitted it. Used by both + /// CERTInextCAPlugin and Client.CERTInextClient when + /// LogSensitiveRequestData is off. Values with no @ (blank, + /// malformed, or not actually an email) fall back to a full "***REDACTED***". + /// + internal static string MaskEmail(string value) + { + if (string.IsNullOrEmpty(value)) return value; + int at = value.IndexOf('@'); + if (at <= 0) return "***REDACTED***"; + string domain = value.Substring(at + 1); + return value.Substring(0, 1) + "***@" + domain; + } + + // Email-shaped token inside free text. The lookbehind restricts match starts to token + // boundaries so scanning stays linear on long runs of local-part characters (error bodies + // can be up to 64 KB). Already-masked output ("j***@example.com") does not re-match, so + // masking is idempotent. A trailing '.' is left out of the domain ("a@b.com." -> "a@b.com"). + private static readonly Regex EmailInText = new Regex( + @"(? + /// Prepares CA-supplied error text (V1 meta.errorMessage / legacy message, V2 + /// problem+json title/detail/errors[]) for a log line or an exception + /// message. With on the text is returned + /// unchanged. Off, email-shaped tokens are masked via (CERTInext may + /// echo a submitted request value in its error text) and CR/LF/tab are neutralized via + /// ; everything else (codes, field names, reasons) is kept word for word. + /// Names and phone numbers in free text are not detected. Null passes through. + /// Rate-limit detection must be given the raw text, not this output. + /// + internal static string SanitizeCaText(string text, bool logSensitiveRequestData) + { + if (logSensitiveRequestData || string.IsNullOrEmpty(text)) return text; + try + { + return Strip(EmailInText.Replace(text, m => MaskEmail(m.Value))); + } + catch (RegexMatchTimeoutException) + { + return "(CA error text withheld: could not be safely masked)"; + } + } + + // SAN type spellings (case-insensitive) whose values are email addresses: the gateway's + // "rfc822name" plus the variants CERTInextCAPlugin.MapSanType normalizes to "email". + private static readonly HashSet EmailSanTypes = + new HashSet(StringComparer.OrdinalIgnoreCase) { "email", "rfc822", "rfc822name" }; + + // SAN types logged verbatim even with LogSensitiveRequestData off: host names and IP + // literals are audit fields, not personal data. + private static readonly HashSet VerbatimSanTypes = + new HashSet(StringComparer.OrdinalIgnoreCase) + { + "dns", "dnsname", "dnsnames", + "ip", "ipaddress", "ipaddresses" + }; + + // URI SAN type spellings. Logged verbatim unless the value carries an '@' (see MaskUri). + private static readonly HashSet UriSanTypes = + new HashSet(StringComparer.OrdinalIgnoreCase) { "uri", "uniformresourceidentifier" }; + + /// + /// Masks the personal part of a URI SAN for logging. A URI without @ is returned + /// unchanged. For a hierarchical URI (scheme://) the userinfo before the last + /// @ of the authority is replaced with *** (https://user:pw@host/ becomes + /// https://***@host/); an @ after the authority (path, query, fragment) is left + /// alone. For an opaque URI (mailto:, sip:, ...) the part after the scheme is + /// masked with (mailto:jane@example.com becomes + /// mailto:j***@example.com). Anything unparseable falls back to . + /// + internal static string MaskUri(string value) + { + if (string.IsNullOrEmpty(value) || value.IndexOf('@') < 0) return value; + + int schemeEnd = value.IndexOf(':'); + if (schemeEnd <= 0) return MaskEmail(value); + + int authStart = schemeEnd + 1; + if (string.CompareOrdinal(value, authStart, "//", 0, 2) == 0) + { + authStart += 2; + int authEnd = value.IndexOfAny(new[] { '/', '?', '#' }, authStart); + if (authEnd < 0) authEnd = value.Length; + string authority = value.Substring(authStart, authEnd - authStart); + int at = authority.LastIndexOf('@'); + return at < 0 ? value : value.Substring(0, authStart) + "***" + value.Substring(authStart + at); + } + + return value.Substring(0, authStart) + MaskEmail(value.Substring(authStart)); + } + + /// + /// Returns a single SAN value as it should appear in a log line. + /// With on, the value is returned as-is. Off, + /// an email-type SAN (rfc822name and its spelling variants) is masked with + /// , and so is any value containing @ whose type is unknown + /// or null (untyped host lists). URI values go through , so userinfo + /// and mailto: addresses are masked. DNS and IP values are always returned as-is. + /// Does not ; callers strip the formatted line. + /// + internal static string FormatSanValue(string sanType, string value, bool logSensitiveRequestData) + { + if (logSensitiveRequestData || string.IsNullOrEmpty(value)) return value; + if (sanType != null && EmailSanTypes.Contains(sanType)) return MaskEmail(value); + if (sanType != null && VerbatimSanTypes.Contains(sanType)) return value; + if (sanType != null && UriSanTypes.Contains(sanType)) return MaskUri(value); + return value.IndexOf('@') >= 0 ? MaskEmail(value) : value; + } + + /// + /// Formats typed SAN entries as "type:value; type:value" for a log line, applying + /// to each value and to the result. + /// Returns "(none)" for a null or empty collection. + /// + internal static string FormatSans( + IEnumerable> sans, bool logSensitiveRequestData) + { + var parts = sans? + .Select(s => $"{s.Key}:{FormatSanValue(s.Key, s.Value, logSensitiveRequestData)}") + .ToList(); + return parts == null || parts.Count == 0 ? "(none)" : Strip(string.Join("; ", parts)); + } + + /// Gateway SAN dictionary overload of . + internal static string FormatSans(Dictionary san, bool logSensitiveRequestData) + => FormatSans( + san?.SelectMany(kvp => (kvp.Value ?? Array.Empty()) + .Select(v => new KeyValuePair(kvp.Key, v))), + logSensitiveRequestData); + + /// Resolved overload of . + internal static string FormatSans(IEnumerable sans, bool logSensitiveRequestData) + => FormatSans( + sans?.Where(s => s != null).Select(s => new KeyValuePair(s.Type, s.Value)), + logSensitiveRequestData); + + /// + /// Formats an untyped list of SAN-derived names (e.g. V1 additionalDomains, or order + /// domains echoed back by the CA) joined by . With no type to go + /// on, any value containing @ is masked when + /// is off. The result is ped; "(none)" for a null or empty list. + /// + internal static string FormatUntypedSans( + IEnumerable values, bool logSensitiveRequestData, string separator = "; ") + { + var parts = values?.Select(v => FormatSanValue(null, v, logSensitiveRequestData)).ToList(); + return parts == null || parts.Count == 0 ? "(none)" : Strip(string.Join(separator, parts)); + } + } +} diff --git a/CERTInext/Models/StatusMapper.cs b/CERTInext/Models/StatusMapper.cs index 59795f8..1594ab2 100644 --- a/CERTInext/Models/StatusMapper.cs +++ b/CERTInext/Models/StatusMapper.cs @@ -1,11 +1,13 @@ -// Copyright 2024 Keyfactor +// Copyright 2026 Keyfactor // Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. // You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 // Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions // and limitations under the License. +using Keyfactor.Logging; using Keyfactor.PKI.Enums.EJBCA; +using Microsoft.Extensions.Logging; namespace Keyfactor.Extensions.CAPlugin.CERTInext.Models { @@ -19,6 +21,8 @@ namespace Keyfactor.Extensions.CAPlugin.CERTInext.Models /// internal static class StatusMapper { + private static readonly ILogger Logger = LogHandler.GetClassLogger(typeof(StatusMapper)); + // ----------------------------------------------------------------------- // Certificate status ID mapping (TrackOrder.orderDetails.certificateStatusId) // ----------------------------------------------------------------------- @@ -191,6 +195,136 @@ public static string ToRevocationReason(uint crlReason) } } + // ----------------------------------------------------------------------- + // V2 API status mapping + // ----------------------------------------------------------------------- + + /// + /// Maps a V2 REST API order status string to the Keyfactor + /// integer code expected by the gateway. + /// + /// Covers the status values documented by the V2 spec's /reports/orders + /// status filter. pending-organization-verification, + /// pending-documents, and pending-approval join the existing + /// pending-* values as EXTERNALVALIDATION — they are OV/EV/DV orders still + /// actively progressing toward issuance, not failures. rejected is a + /// terminal negative outcome mapped to FAILED deliberately, same as the + /// pre-existing cancelled. expired maps to GENERATED instead — + /// an expired-but-not-revoked certificate remains issued inventory, mirroring + /// 's V1 convention and the sync/report path's + /// own "expired" case (CERTInextCAPlugin.TryMapV2ReportDisplayStatus). The + /// spec-documented unknown maps to + /// EXTERNALVALIDATION: the order may still be live. Any value not in this list falls + /// through to the default arm, which also returns FAILED but logs a warning, + /// so "deliberately FAILED" and "unmapped, degrading to + /// FAILED" stay distinguishable in the logs even though the return value + /// is the same today. + /// + /// Status string from the V2 order response. + public static int V2StatusToRequestDisposition(string v2Status) + { + switch (v2Status?.ToLowerInvariant()) + { + case Constants.ApiV2.StatusIssued: + // Expired-but-not-revoked certs remain in inventory as GENERATED — + // mirrors StatusMapper.ToRequestDisposition's V1 convention and the + // sync/report path's own "expired" case. + case Constants.ApiV2.StatusExpired: + return (int)EndEntityStatus.GENERATED; + + case Constants.ApiV2.StatusPendingDcv: + case Constants.ApiV2.StatusPendingCsr: + case Constants.ApiV2.StatusPendingAgreement: + case Constants.ApiV2.StatusPendingOrganizationVerification: + case Constants.ApiV2.StatusPendingDocuments: + case Constants.ApiV2.StatusPendingApproval: + return (int)EndEntityStatus.EXTERNALVALIDATION; + + case Constants.ApiV2.StatusRevoked: + return (int)EndEntityStatus.REVOKED; + + case Constants.ApiV2.StatusCancelled: + case Constants.ApiV2.StatusRejected: + return (int)EndEntityStatus.FAILED; + + case Constants.ApiV2.StatusUnknown: + // `unknown` is in the spec's documented status list, so it is NOT + // the "status we've never heard of" case below — CERTInext is saying it can't + // currently report where the order is, not that the order is dead. Treat it as + // pending so Command keeps the order and sync/pickup keep re-checking it, rather + // than dropping a possibly-live order as FAILED. Warn so an order stuck here is + // visible to operators. + Logger.LogWarning( + "V2StatusToRequestDisposition: CERTInext reported V2 order status 'unknown' — " + + "treating the order as pending (EXTERNALVALIDATION) rather than FAILED; it will be " + + "re-checked on the next status poll or sync. If an order stays 'unknown', raise it with CERTInext."); + return (int)EndEntityStatus.EXTERNALVALIDATION; + + default: + // Distinct from the deliberate cancelled/rejected/expired -> FAILED + // mappings above: this status string isn't recognized at all. Log so + // an operator can tell "legitimately + // failed" apart from "gateway doesn't know this status yet" — degrade + // to FAILED rather than guessing EXTERNALVALIDATION, since an + // unrecognized value could just as easily be a new terminal state. + Logger.LogWarning( + "V2StatusToRequestDisposition: unmapped V2 order status '{V2Status}' — " + + "defaulting to FAILED. This is not one of the V2 spec's documented status " + + "values; if CERTInext has added a new status, StatusMapper needs updating.", + v2Status); + return (int)EndEntityStatus.FAILED; + } + } + + /// + /// Converts an RFC 5280 CRL reason code to the V2 API revocation reason string. + /// Values are the CERTInext V2 spec's kebab-case `reason` enum (see + /// — sending the + /// legacy camelCase strings gets HTTP 400). Codes without a direct V2 + /// equivalent (e.g. RFC 5280 code 8, "removeFromCRL", which is CRL-only and + /// not a valid revocation request reason) are mapped to "unspecified". + /// + /// RFC 5280 CRL reason code from the gateway. + public static string ToV2RevocationReason(uint crlReason) => + crlReason switch + { + 1 => Constants.RevocationReasonV2.KeyCompromise, // RFC: keyCompromise + 2 => Constants.RevocationReasonV2.CACompromise, // RFC: cACompromise + 3 => Constants.RevocationReasonV2.AffiliationChanged, // RFC: affiliationChanged + 4 => Constants.RevocationReasonV2.Superseded, // RFC: superseded + 5 => Constants.RevocationReasonV2.CessationOfOperation,// RFC: cessationOfOperation + 6 => Constants.RevocationReasonV2.CertificateHold, // RFC: certificateHold + 9 => Constants.RevocationReasonV2.PrivilegeWithdrawn, // RFC: privilegeWithdrawn + 10 => Constants.RevocationReasonV2.AACompromise, // RFC: aACompromise + _ => Constants.RevocationReasonV2.Unspecified + }; + + /// + /// Converts a V2 API revocation reason string (the CERTInext V2 spec's kebab-case + /// reason enum on the Track Order response's nested revocation object, + /// e.g. "cessation-of-operation") back to the RFC 5280 CRL reason code for storage in + /// the Keyfactor Command database. Inverse of + /// . Unrecognized or null input (including the + /// not-revoked case, where the caller should not invoke this at all) falls back to 0 + /// (unspecified), mirroring 's V1 default. + /// + /// Raw revocation.reason string from the V2 Track Order response. + public static int V2RevocationReasonToCrlCode(string v2Reason) + { + switch (v2Reason?.ToLowerInvariant()) + { + case Constants.RevocationReasonV2.KeyCompromise: return 1; + case Constants.RevocationReasonV2.CACompromise: return 2; + case Constants.RevocationReasonV2.AffiliationChanged: return 3; + case Constants.RevocationReasonV2.Superseded: return 4; + case Constants.RevocationReasonV2.CessationOfOperation: return 5; + case Constants.RevocationReasonV2.CertificateHold: return 6; + case Constants.RevocationReasonV2.PrivilegeWithdrawn: return 9; + case Constants.RevocationReasonV2.AACompromise: return 10; + default: return 0; + } + } + /// /// Converts a CERTInext revokeReasonId integer back to the RFC 5280 CRL /// reason code for storage in the Keyfactor Command database. diff --git a/CHANGELOG.md b/CHANGELOG.md index 6065cb2..78cac3c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,17 +1,127 @@ +# 2.0.0 + +## Features +- feat(v2): Opt-in CERTInext V2 REST API via `UseV2Api` (default `false`), authenticated with OAuth2 `client_credentials`. +- feat(v2): Enroll, renew, reissue, revoke, and synchronize SSL/TLS and Private PKI products, selected with the `ProductFamily` and `ProductVariant` template parameters. +- feat(v2): A template's `ProductCode` is validated against the V2 catalog when saved. +- feat(v2): Multi-domain (UCC) and wildcard SSL/TLS enrollment, with extra SANs sent as `additionalDomains`. +- feat(v2): V2 OV and EV SSL/TLS orders check the organization's SSL.com validation first (status read, one refresh, and an optional submission). New settings `SslComSubmitOrganization` (default `false`; enabling it accepts SSL.com's subscriber agreement on the organization's behalf, audit-logged) and `SslComAdminEmail`. A not-validated organization or a failed SSL.com call only warns, and the order is placed anyway. +- feat(v2): An SSL/TLS order that Track Order shows at `pending-agreement` gets the Subscriber Agreement accepted via `POST /ssl-certificates/{orderId}/agreement`, using the same signer values as create: at most once per order per enroll call or sync pass, audit-logged first, and a failure only warns. +- feat(v2): The create call no longer sends `X-Product-Code` unless the template sets `ProductCode` (SSL/TLS and Private PKI): CERTInext resolves the product from the variant, wildcard shape and `additionalDomains`, and the response's `resolvedProductCode` is logged. An ambiguous catalog match is no longer an error, Private PKI no longer needs `ProductCode`, and without one a wildcard is detected from the `*.` domain and a UCC order from the template's product or extra DNS SANs. +- feat(v2): V2 SSL/TLS enrollment sends the CSR inline in one create call (`V2InlineCsr`, default `true`). Setting it to `false` selects create + Submit CSR, which fails for a domain the account has already validated; Private PKI stays two-call. +- feat(v2): Synchronize reads `/reports/orders` and honors `IgnoreExpired`. +- feat(v2): Incremental syncs look back `V2SyncLookbackHours` (default 72). +- feat(dcv): DNS-01 domain validation for V2 SSL/TLS orders, including every SAN on a UCC order. +- feat(dcv): `DcvEnabled` now defaults to `true`; it needs a DNS provider plugin, or set it to `false`. +- feat(enroll): V2 orders also return a quickly issued certificate in the same `Enroll` call, using the `PickupRetries` and `PickupDelay` settings V1 gained in 1.0.1. +- feat(config): New settings `RequestorDesignation` and `V2SyncLookbackHours`. +- feat(config): V2 orders honor `GroupNumber`, `OrganizationNumber`, `TechnicalContact*`, `EmailNotifications`, and the subscription renewal settings. + +## Bug Fixes +- fix(v2): A 422 `EMS-1165` from Download Certificate on an order CERTInext reports as `issued` is treated as "certificate not generated yet": the enrollment pickup keeps polling and returns pending, logging per attempt at Debug and one Information summary instead of a warning each time. `GetSingleRecord` and Synchronize log it quietly too (the sync summary gains `IssuedNotGeneratedYet`), and the log lines include CERTInext's `orderState` and `certificateState`. Other download errors still warn. +- fix(v2): `EmailNotifications=0` (silent) is sent as `consent-only` on V2 order create, the quietest value in the spec's `consent-only | all` enum; the old `"0"` isn't a member of it. +- fix(v2): Order create no longer sends `agreement.signerIp`, which isn't in the V2 spec's `Agreement` schema; the `SignerIp` settings now apply to V1 only. +- fix(enroll): V2 UCC and renewal orders keep their SANs and primary domain, and renewals use the template's product code, as V1 does from 1.0.1. +- fix(enroll): A V2 order auto-approved before it finishes issuing returns pending, not an issued result with no certificate. +- fix(dcv): Wildcard TXT records are published at the base domain and shared with the apex. +- fix(config): `ApiUrl` must use https (loopback hosts excepted), checked on save and at startup. +- fix(logging): V2 requestor personal data, email SANs, and request/response payloads are redacted unless `LogSensitiveRequestData` is on. +- fix(logging): Email addresses in CERTInext V2 error text (the problem+json `title`, `detail`, and `errors[]` that end up in exception messages and logs) are masked unless `LogSensitiveRequestData` is on, as V1 error text is. +- fix(logging): V2 payload dumps no longer run redaction when Trace logging is off. +- fix(enroll): V2 order and CSR submissions are never auto-retried after a timeout, which could create duplicate orders (V1 since 1.0.1). +- fix(sync): The V2 sync also holds back pending and issued orders created in the last 120 s (`SyncRecentOrderGraceSeconds`, `0` disables), so an in-flight enrollment no longer fails with a duplicate key (V1 since 1.0.1). +- fix(enroll): The in-call pickup wait is now capped at 75 s (it was 180 s) for V1 and V2, inside Command's roughly 100 s enrollment-call timeout, so a pickup that used its whole budget is no longer abandoned by Command. The 55 s default (`PickupRetries` 5, `PickupDelay` 10) is unaffected. +- fix(logging): Log redaction no longer leaks the rest of a value after an escaped quote, CERTInext error text has email addresses masked unless `LogSensitiveRequestData` is on, and `mailto:` and userinfo are masked in URI SANs in enrollment logs (V1 and V2). + +## Chores +- chore(compat): Requires AnyCA Gateway REST 26.2.0 or later; built against `IAnyCAPlugin` 3.3.0 with DNS-01 DCV included. +- chore(compat): The plugin targets both `net8.0` and `net10.0`. + +## Upgrade Notes +- AnyCA Gateway REST 25.5.x isn't supported; upgrade the gateway to 26.2.0 or later (Command 25.5 or later works with it). +- `DcvEnabled` now defaults to `true`, so without a DNS provider plugin, orders needing validation stay pending; set it to `false` if you validate domains another way. +- Connectors saved with an `http` `ApiUrl` fail to start until the URL uses https. +- V2 no longer sends `X-Product-Code` unless the template sets `ProductCode`, and `DefaultProductCode` no longer applies to V2 orders. A template that needs a specific one of several matching catalog products must set `ProductCode`. +- V2 connectors require `SignerPlace`, and V2 OV/EV orders require `OrganizationNumber`. +- `V2InlineCsr` now defaults to `true`. A connector that already has `V2InlineCsr = false` saved, as connectors created with an earlier 2.0 build do, keeps the two-call flow, which fails for already-validated domains. Set it to `true` on those connectors. +- `SignerIp` (connector and template) is V1 only: V2 no longer sends `agreement.signerIp`, which the V2 spec's agreement schema doesn't define. +- V2 `ProductVariant` is derived from the selected product when unset. +- V2 revoke reasons CERTInext rejects are retried with a substitute (see Revocation Reason Codes in the README). +- V2 `expired` orders are reported as issued, and revoking one is sent to the CA. +- V2 renew and reissue place a new order and don't revoke the original. +- Upgrading from 1.0.0 also brings the changes in 1.0.1 and 1.0.2 above. For example, V1 now submits non-DNS SANs; set `SubmitNonDnsSans` to `false` to drop them. + +## Known Limitations +- OV and OV UCC order placement under V2 can exceed the fixed 120s request timeout, and the order may still be created. +- EV orders under V2 aren't validated end to end. +- Document Signer (`ProductFamily=signature`) enrollment isn't supported under V2. +- Per-SAN DCV on UCC orders, DCV for a never-validated domain, and wildcard DCV aren't validated end to end against the CA. +- Rolling a connector back to V1 after it has issued V2 certificates isn't validated. +- V1 `IgnoreExpired` isn't applied yet; it works on V2. +- V1 `AuthMode=OAuth` isn't supported: the live V1 API ignores the bearer token, so V1 needs an access key. +- The V2 incremental sync doesn't yet skip orders the gateway already holds unchanged, as the V1 incremental sync does from 1.0.2, so it re-reads each order listed. +- Without a template `ProductCode`, the product CERTInext resolves depends on the account's catalog. Where several products match a variant, CERTInext may pick one that rejects a client CSR. On the sandbox, plain DV resolves to `917` "SSL DV 1 month" instead of `842`. Set `ProductCode` on the template to choose the product. +- DCV for domains validated by SSL.com (after the issuing-CA change) isn't supported yet: SSL.com supplies the record name and value through the domain-level DCV endpoints, and the plugin still publishes `DcvTxtRecordTemplate` records through the order-level endpoint. +- Command's enrollment workflow can give up at 60 s, before the 75 s pickup ceiling. When it does, Command records the enrollment as failed even though the order continues at CERTInext, so the certificate can only arrive through a later sync. + +# 1.0.2 + +## Bug Fixes +- fix(sync): `Synchronize` and `GetSingleRecord` no longer send the gateway a revoked record without a certificate unless the gateway already stores that certificate. Such a record made the gateway's revoked-certificate search fail, which stopped every Command scan of the CA. A revoked order the gateway has without a certificate is now reported as failed; one the gateway has never seen is skipped. Rows already stored this way must be repaired in the gateway database. +- fix(sync): Incremental sync no longer re-downloads every issued or revoked order placed that day on every pass. An order the gateway already stores with the same status and its certificate is skipped; new orders, status changes and orders stored without a certificate are fetched as before. Full sync is unchanged. On a day with many orders, incremental passes previously made two API calls per order and could run longer than the sync interval. + +## Documentation +- docs: Added steps for the change of issuing CA after eMudhra's exit from public TLS (SSL.com for InCommon members, Sectigo offered by eMudhra), with the emSign G1 distrust dates. No plugin change is needed; Command, gateway and orchestrator trust stores and the gateway's CA certificate need the new chain. + +# 1.0.1 + +## Bug Fixes +- fix(enroll): Pickup now waits briefly and returns the issued certificate in-band when the CA issues fast, otherwise returning pending as before (`PickupRetries` default 5, `0` disables; `PickupDelay` default 10s). +- fix(enroll): SANs are now read from every key the gateway sends (including `dnsname`), and from the CSR when it sends none, so UCC certificates return all domains. +- fix(enroll): Renewal SANs now come from the renewal request (subject CN, request SANs or CSR), not the prior order. +- fix(enroll): Orders auto-approved by CERTInext before issuance completes now return pending; the next sync picks up the certificate. +- fix(enroll): Renewals now use the template's product code instead of always using `DefaultProductCode`. +- fix(enroll): A blank `RequestorName` or `SignerPlace` now sends the placeholders `Keyfactor Gateway` and `Gateway` instead of an empty subscriber agreement signer. +- fix(enroll): `SignerName`, `SignerPlace`, and `SignerIp` template parameters now override connector values for the subscriber agreement on new orders and renewals. +- fix(enroll): A `SignerIp` that is not a valid IP address now logs a Warning naming whether it came from the template or the connector; the value is still sent unchanged. +- fix(enroll): A Warning is now logged when `SignerName` or `SignerPlace` fall back to their placeholders, naming what to set. +- fix(enroll): `GroupNumber`, `AutoSecureWww`, and the technical contact now send in the correct request fields CERTInext reads. +- fix(enroll): Renewals no longer fail with `EMS-918: Additional Information cannot be empty`; the renewal order now sends `additionalInformation.remarks`. +- fix(enroll): Renewals now send the full order details (group, `AutoSecureWww`, technical contact, organization, remarks), matching a new enrollment. +- fix(enroll): A failed status check or DCV step after placing an order now returns pending with the order number so sync can finish the order and a retry cannot place a duplicate. +- fix(enroll): Non-DNS SANs (IP, email, URI) are now submitted instead of silently dropped; set `SubmitNonDnsSans` to `false` to restore the old behavior. +- fix(enroll): Order/CSR submissions no longer auto-retry after a timeout so a timeout cannot create a duplicate order; if the CA did create one, the next sync imports it. +- fix(enroll): `www.` is no longer added to orders by default because `AutoSecureWww` (default `0`) is now honored; set it to `1` to keep the old behavior. +- fix(enroll): Orders now route to the configured `GroupNumber`, which previously was not applied to orders. +- fix(enroll): Renewals now follow the connector's `SubscriptionAutoRenew`, `EmailNotifications`, and validity settings instead of fixed 1-year validity with auto-renew and notifications on. +- fix(enroll): The `ValidityYears` template parameter now takes effect, and the order term is the larger of `ValidityYears` and `ValidityDays` (rounded up to years) so templates saved with only `ValidityDays` keep their term. +- fix(enroll): The technical contact is omitted, with a Warning, when no contact name or email resolves, since CERTInext requires both once the block is sent. +- fix(logging): The V1 API error log line now reads `CERTInext API non-success. Operation=...` instead of `CERTInext API error during ...`; update any log alerts keyed on the old text. +- fix(dcv): A DV order that cannot issue (IP or email SAN, no DNS provider) now returns pending immediately; sync finishes the order. +- fix(dcv): A DV renewal waiting on DNS-01 validation now returns pending immediately instead of blocking a gateway worker for the pickup wait. +- fix(config): Connector and template validation no longer leaks an HTTP client per check. +- fix(sync): Sync holds back pending or issued orders created in the last 120 s (`SyncRecentOrderGraceSeconds`, `0` disables), making a duplicate-key failure on an in-flight enrollment's save much less likely; enrollments longer than about 2 minutes can still race. + +## Chores +- chore(logging): Startup log now shows whether `OrganizationNumber`, `DefaultProductCode`, `GroupNumber`, `SubmitNonDnsSans`, and `LogSensitiveRequestData` are set, and warns when `LogSensitiveRequestData` is on. +- chore(config): Field descriptions and configuration docs now match the code for `DefaultProductCode`, `ValidityYears`, signer fallbacks, `LogSensitiveRequestData`, and the pickup clamps. +- chore(config): Corrected the `AutoApprove` template setting's description, which previously implied the plugin attempts automatic approval of pending certificates. +- chore(tests): Opt-in live sandbox test that renews through `plugin.Enroll(RenewOrReissue)` end to end (`CERTINEXT_RENEWAL_E2E=1`). + # 1.0.0 -Initial release of the CERTInext (emSign Hub) AnyCA REST Gateway plugin. +Initial release of the CERTInext (emSign Hub) AnyCA Gateway REST plugin. ## Features - feat(enroll): Certificate enrollment for CERTInext SSL products — DV, OV, and EV SSL, including Wildcard and Multi-Domain (UCC) variants — with connector- and template-level overrides for product code, requestor identity, organization/group, and validity. -- feat(dcv): End-to-end DNS-01 domain validation for DV SSL through a pluggable `IDomainValidatorFactory` (Cloudflare provider included). Publishes the TXT challenge, asks CERTInext to verify, waits for issuance, and returns the issued certificate directly from `Enroll`. (DCV build — AnyCA Gateway 26.x.) +- feat(dcv): End-to-end DNS-01 domain validation for DV SSL through a pluggable `IDomainValidatorFactory` (Cloudflare provider included). Publishes the TXT challenge, asks CERTInext to verify, waits for issuance, and returns the issued certificate directly from `Enroll`. (DCV build, AnyCA Gateway 26.x; in 2.0.0 DCV is part of the default build.) - feat(sync): Full and incremental CA synchronization via paginated `GetOrderReport`. Issued certificates carry their full PEM body; revoked certificates carry revocation metadata. - feat(sync): Sync-driven DCV retry drives orders left pending validation to completion on later sync passes, bounded by configurable `DcvSyncMaxOrderAgeHours` and `DcvSyncMaxPerPass` caps so large accounts stay fast. - feat(revoke): Certificate revocation via `RevokeOrder` with RFC 5280 reason-code mapping. -- feat(auth): AccessKey (HMAC-SHA256) and OAuth client-credentials authentication modes. -- feat(build): Single `DcvSupport` MSBuild flag selects the host-matched build from one codebase — default no-DCV (IAnyCAPlugin `3.2.0`, AnyCA Gateway 25.5.x) or `-p:DcvSupport=true` for the DCV build (IAnyCAPlugin `3.3.0-PRERELEASE`, 26.x). Records persist only when the build matches the host's IAnyCAPlugin version. +- feat(auth): AccessKey authentication (a SHA-256 `authKey`) and an OAuth client-credentials mode (not supported by the live V1 API; see 2.0.0). +- feat(build): Single `DcvSupport` MSBuild flag selects the host-matched build from one codebase — default no-DCV (IAnyCAPlugin `3.2.0`, AnyCA Gateway 25.5.x) or `-p:DcvSupport=true` for the DCV build (IAnyCAPlugin `3.3.0-PRERELEASE`, 26.x). Records persist only when the build matches the host's IAnyCAPlugin version. (In 2.0.0 the default is the DCV build.) - feat(config): Connector-level configuration for pre-vetted organization/group/technical-contact injection, DCV timing knobs (challenge/issuance waits), and SSL order defaults. -- feat(sync): `IgnoreExpired` flag to exclude expired certificates from synchronization. +- feat(sync): `IgnoreExpired` flag to exclude expired certificates from synchronization (not applied on V1 yet; see 2.0.0). ## Bug Fixes - fix(sync): Issued certificates now synchronize with their full PEM body — the `GetOrderReport` listing carries no body, so the plugin refetches the full certificate for issued/revoked records. Previously issued certs synced empty and never appeared in Command. diff --git a/Makefile b/Makefile index c2a726f..1be4305 100644 --- a/Makefile +++ b/Makefile @@ -3,10 +3,12 @@ COVERAGE_DIR := /tmp/certinext-coverage REPORT_DIR := /tmp/certinext-coverage-report # --------------------------------------------------------------------------- -# V2 API credentials — set CERTINEXT_V2_API_URL in ~/.env_certinext. -# For the sandbox environment this is the same host as V1 but without the +# V2 API credentials — CERTINEXT_API_URL / CERTINEXT_CLIENT_ID / +# CERTINEXT_CLIENT_SECRET in ~/.env_certinext_v2 (override the path with +# CERTINEXT_V2_ENV_FILE). CERTINEXT_API_URL is the V2 base URL, without the # /emSignHub-API/ suffix, e.g.: -# CERTINEXT_V2_API_URL=https://sandbox-us.certinext.io +# CERTINEXT_API_URL=https://sandbox-us.certinext.io +# See scripts/v2/README.md. # --------------------------------------------------------------------------- .PHONY: build test integration-test coverage coverage-report open-coverage clean \ @@ -138,11 +140,11 @@ generate-test-csr: # --------------------------------------------------------------------------- # probe-products — places saveAndHold=1 draft orders for every SSL/TLS -# product code known to be provisioned on this sandbox account and reports -# which codes are accepted by GenerateOrderSSL. +# product code in the list below and reports which codes are accepted by +# GenerateOrderSSL for the configured account. # -# Product codes exercised (all SSL/TLS from GetProductDetails for this -# sandbox account with groupNumber=2171775848): +# Product codes exercised (sandbox SSL/TLS codes; production codes differ — +# see docsource/configuration.md): # 842 DV SSL Certificate # 843 DV SSL Certificate Wildcard # 844 DV SSL Certificate UCC @@ -167,7 +169,7 @@ probe-products: generate-test-csr # Aliases: orders # Optional overrides: PAGE (default 1), PAGE_SIZE (default 10) # -# Response shape (live API, verified 2026-04): +# Response shape: # { "orderDetails": { "ordersArray": [...], "noOfPages": N, # "totalNoOfResults": N, "pageSize": N, "currentPage": "1" }, # "meta": { "status": "1", ... } } @@ -285,17 +287,11 @@ submit-csr: # --------------------------------------------------------------------------- # list-cas — Sub-CA listing via API # -# The CERTInext REST API does NOT expose a Sub-CA listing endpoint. -# All 18 candidate endpoint names return HTTP 404. +# The CERTInext REST API does not expose a Sub-CA listing endpoint. +# Sub-CA information is available in the CERTInext portal UI +# (https://sandbox-us.certinext.io for the sandbox environment). # -# Sub-CA information must be obtained via the sandbox portal UI at -# https://sandbox-us.certinext.io. Active Sub-CAs for this account: -# Name : emSign Issuing Sand box CA IGTF - C6 -# Type : Subordinate CA -# Status : Active -# (Backed by emSign Trusted Sandbox Root CA - C6) -# -# See analysis/certinext-caplugin/postman-api-findings.md for full details. +# See analysis/certinext-caplugin/postman-api-findings.md for details. # --------------------------------------------------------------------------- list-cas: @@ -319,8 +315,8 @@ list-cas: # make register-import # 05 import templates into Command [CHECK=1] # make register-enrollment # 06 enrollment patterns + template KeyRetention # -# Stages 01 and 06 are VERIFIED live; 02-05 are built from docs/reference -# captures — validate against a live gateway/Command before relying on them. +# Stages 02-05 are modeled on the captured JSON in docs/reference — validate +# them against your gateway/Command before relying on them. # Auth (cookie/token/OAuth), env vars, and gotchas: scripts/register/README.md. # NOTE: stage 04 (and stage 02's CA-connection PUT) touch the CA config, which # is fragile — leave it alone unless explicitly required. @@ -349,14 +345,11 @@ register-enrollment: # --------------------------------------------------------------------------- # create-product — Create a custom product via API # -# The CERTInext REST API does NOT expose a product creation or configuration -# endpoint. All 8 candidate endpoint names return HTTP 404. -# -# Products must be created via the sandbox portal UI at -# https://sandbox-us.certinext.io under: +# The CERTInext REST API does not expose a product creation or configuration +# endpoint. Products are created in the CERTInext portal UI under: # Account → Products → Configure Product # -# See analysis/certinext-caplugin/postman-api-findings.md for full details. +# See analysis/certinext-caplugin/postman-api-findings.md for details. # --------------------------------------------------------------------------- create-product: @@ -365,9 +358,10 @@ create-product: # --------------------------------------------------------------------------- # generate-order-igtf — Place a Private PKI order using product 149 # -# Product 149 (Sandbox emSign Intranet SSL 1 Year) is the only Private PKI -# product provisioned on this sandbox account. Product 108 (IGTF Host -# Certificate) is NOT provisioned here — GetFieldDetails returns EMS-1269. +# Product 149 (Sandbox emSign Intranet SSL 1 Year) is a Private PKI product +# available on sandbox accounts with the Private PKI entitlement. Product 108 +# (IGTF Host Certificate) requires separate provisioning — GetFieldDetails +# returns EMS-1269 when it is not provisioned. # # Uses GenerateOrderPrivatePKI. # Required: CSR at /tmp/certinext-igtf-test.csr (run generate-test-csr first) @@ -413,7 +407,7 @@ generate-order-private-pki: generate-test-csr # reports whether they exist (non-404) or not (404). Wraps # scripts/probe_endpoints.py. # -# Result (confirmed 2026-04): ALL 18 candidates return HTTP 404. +# None of the candidate endpoints exist (all return HTTP 404). # --------------------------------------------------------------------------- probe-endpoints: @@ -453,7 +447,7 @@ get-field-details: FILTER ?= show-postman-bodies: - @python3 /Users/sbailey/RiderProjects/certinext-caplugin/scripts/extract_postman_bodies.py \ + @python3 scripts/extract_postman_bodies.py \ --filter "$(FILTER)" # --------------------------------------------------------------------------- @@ -465,7 +459,7 @@ show-postman-bodies: # --------------------------------------------------------------------------- show-postman-variables: - @python3 /Users/sbailey/RiderProjects/certinext-caplugin/scripts/extract_postman_variables.py + @python3 scripts/extract_postman_variables.py # --------------------------------------------------------------------------- # probe-private-pki-payloads — Try three payload variants for @@ -479,24 +473,28 @@ show-postman-variables: # --------------------------------------------------------------------------- probe-private-pki-payloads: generate-test-csr - @python3 /Users/sbailey/RiderProjects/certinext-caplugin/scripts/order_private_pki_minimal.py \ + @python3 scripts/order_private_pki_minimal.py \ --csr /tmp/certinext-test.csr \ --domain "$(IGTF_DOMAIN)" \ --product "$(PRIVATE_PKI_CODE)" \ --save-and-hold "$(SAVE_AND_HOLD)" # --------------------------------------------------------------------------- -# V2 API targets (credentials + CERTINEXT_V2_API_URL from ~/.env_certinext) +# V2 API targets (credentials from ~/.env_certinext_v2) # -# Auth: scripts/lib/certinext-v2-auth.sh exchanges SHA256(accessKey+ts+txn) -# for a short-lived Bearer JWT at POST {v2BaseURL}/oauth/token. All V2 -# scripts source that lib automatically — no manual token step needed. +# Auth: scripts/lib/certinext-v2-auth.sh fetches an OAuth2 client_credentials +# token at POST {CERTINEXT_API_URL}/oauth/token (same as the plugin's V2 mode). +# The env file is parsed, not sourced; the secret/token never hit argv, disk, +# or output. # -# Scripts live in scripts/v2/. Each script sources ~/.env_certinext and -# scripts/lib/certinext-v2-auth.sh; jq is used for JSON construction and -# pretty-printing. +# Mutating targets (create/verify-dcv/submit-csr/accept/cancel/revoke) only +# PREVIEW the request unless you pass V2_ARGS=--yes-mutate, e.g.: +# make v2-revoke-ssl ORDER_ID=123 V2_ARGS=--yes-mutate +# Full details: scripts/v2/README.md. # --------------------------------------------------------------------------- +V2_ARGS ?= + # --------------------------------------------------------------------------- # v2-ping — GET /api/certinext/v2/auth/me # Connectivity + auth check; returns the account context the token resolves to. @@ -575,7 +573,7 @@ V2_VARIANT ?= dv v2-create-ssl-order: @echo "V2 create SSL order — POST /api/certinext/v2/ssl-certificates" - @PRODUCT_CODE=$(V2_PRODUCT_CODE) DOMAIN=$(V2_DOMAIN) VARIANT=$(V2_VARIANT) scripts/v2/create-ssl-order.sh + @PRODUCT_CODE=$(V2_PRODUCT_CODE) DOMAIN=$(V2_DOMAIN) VARIANT=$(V2_VARIANT) scripts/v2/create-ssl-order.sh $(V2_ARGS) # --------------------------------------------------------------------------- # v2-track-order — GET /api/certinext/v2/ssl-certificates/{orderId} @@ -613,7 +611,7 @@ V2_DCV_METHOD ?= http-url v2-verify-dcv: @echo "V2 verify DCV — POST /api/certinext/v2/ssl-certificates/$(ORDER_ID)/dcv/verify" - @ORDER_ID=$(ORDER_ID) DOMAIN=$(V2_DOMAIN) METHOD=$(V2_DCV_METHOD) scripts/v2/verify-dcv.sh + @ORDER_ID=$(ORDER_ID) DOMAIN=$(V2_DOMAIN) METHOD=$(V2_DCV_METHOD) scripts/v2/verify-dcv.sh $(V2_ARGS) # --------------------------------------------------------------------------- # v2-submit-csr — PUT /api/certinext/v2/ssl-certificates/{orderId}/csr @@ -625,7 +623,7 @@ V2_CSR_FILE ?= v2-submit-csr: @echo "V2 submit CSR (SSL) — PUT /api/certinext/v2/ssl-certificates/$(ORDER_ID)/csr" - @ORDER_ID=$(ORDER_ID) CSR_FILE=$(V2_CSR_FILE) scripts/v2/submit-csr.sh + @ORDER_ID=$(ORDER_ID) CSR_FILE=$(V2_CSR_FILE) scripts/v2/submit-csr.sh $(V2_ARGS) # --------------------------------------------------------------------------- # v2-accept-agreement — POST /api/certinext/v2/ssl-certificates/{orderId}/agreement @@ -635,7 +633,7 @@ v2-submit-csr: v2-accept-agreement: @echo "V2 accept agreement — POST /api/certinext/v2/ssl-certificates/$(ORDER_ID)/agreement" - @ORDER_ID=$(ORDER_ID) scripts/v2/accept-agreement.sh + @ORDER_ID=$(ORDER_ID) scripts/v2/accept-agreement.sh $(V2_ARGS) # --------------------------------------------------------------------------- # v2-download-certificate — GET /api/certinext/v2/ssl-certificates/{orderId}/certificate @@ -661,7 +659,7 @@ V2_REASON ?= superseded v2-revoke-ssl: @echo "V2 revoke SSL — POST /api/certinext/v2/ssl-certificates/$(ORDER_ID)/revoke" - @ORDER_ID=$(ORDER_ID) REASON=$(V2_REASON) scripts/v2/revoke-ssl.sh + @ORDER_ID=$(ORDER_ID) REASON=$(V2_REASON) scripts/v2/revoke-ssl.sh $(V2_ARGS) # --------------------------------------------------------------------------- # v2-cancel-ssl-order — POST /api/certinext/v2/ssl-certificates/{orderId}/cancel @@ -671,12 +669,14 @@ v2-revoke-ssl: v2-cancel-ssl-order: @echo "V2 cancel SSL order — POST /api/certinext/v2/ssl-certificates/$(ORDER_ID)/cancel" - @ORDER_ID=$(ORDER_ID) scripts/v2/cancel-ssl-order.sh + @ORDER_ID=$(ORDER_ID) scripts/v2/cancel-ssl-order.sh $(V2_ARGS) # --------------------------------------------------------------------------- # v2-create-private-pki-order — POST /api/certinext/v2/private-pki-certificates # Creates a Private PKI certificate order against a customer-owned CA. -# Required: PRODUCT_CODE= HOSTNAME= CA_PROFILE_ID= MASTER_PRODUCT_ID= +# Required: V2_HOSTNAME= V2_CA_PROFILE_ID= V2_MASTER_PRODUCT_ID= +# Optional: V2_PRODUCT_CODE= +# (the script input is CERT_HOSTNAME; bash always sets HOSTNAME to the local machine name) # # Prints orderId on success. Use orderId with v2-track-private-pki, # v2-submit-csr-private-pki, v2-download-certificate-private-pki, and @@ -689,7 +689,7 @@ V2_MASTER_PRODUCT_ID ?= v2-create-private-pki-order: @echo "V2 create Private PKI order — POST /api/certinext/v2/private-pki-certificates" - @PRODUCT_CODE=$(V2_PRODUCT_CODE) HOSTNAME=$(V2_HOSTNAME) CA_PROFILE_ID=$(V2_CA_PROFILE_ID) MASTER_PRODUCT_ID=$(V2_MASTER_PRODUCT_ID) scripts/v2/create-private-pki-order.sh + @PRODUCT_CODE=$(V2_PRODUCT_CODE) CERT_HOSTNAME=$(V2_HOSTNAME) CA_PROFILE_ID=$(V2_CA_PROFILE_ID) MASTER_PRODUCT_ID=$(V2_MASTER_PRODUCT_ID) scripts/v2/create-private-pki-order.sh $(V2_ARGS) # --------------------------------------------------------------------------- # v2-track-private-pki — GET /api/certinext/v2/private-pki-certificates/{orderId} @@ -711,7 +711,7 @@ v2-track-private-pki: v2-submit-csr-private-pki: @echo "V2 submit CSR (Private PKI) — PUT /api/certinext/v2/private-pki-certificates/$(ORDER_ID)/csr" - @ORDER_ID=$(ORDER_ID) CSR_FILE=$(V2_CSR_FILE) scripts/v2/submit-csr-private-pki.sh + @ORDER_ID=$(ORDER_ID) CSR_FILE=$(V2_CSR_FILE) scripts/v2/submit-csr-private-pki.sh $(V2_ARGS) # --------------------------------------------------------------------------- # v2-download-certificate-private-pki — GET /api/certinext/v2/private-pki-certificates/{orderId}/certificate @@ -735,18 +735,20 @@ v2-download-certificate-private-pki: v2-revoke-private-pki: @echo "V2 revoke Private PKI — POST /api/certinext/v2/private-pki-certificates/$(ORDER_ID)/revoke" - @ORDER_ID=$(ORDER_ID) REASON=$(V2_REASON) scripts/v2/revoke-private-pki.sh + @ORDER_ID=$(ORDER_ID) REASON=$(V2_REASON) scripts/v2/revoke-private-pki.sh $(V2_ARGS) # --------------------------------------------------------------------------- -# v2-orders-report — GET /api/certinext/v2/reports/orders?page=0&size=50 -# Paginated order history across all product types. -# NOTE: currently returns 501 Not Implemented. -# Use v1 make get-order-report (POST /emSignHub-API/GetOrderReport) meanwhile. +# v2-orders-report — GET /api/certinext/v2/reports/orders?page=1&size=100 +# One page of order history (the endpoint V2 Synchronize pages through). +# Optional: V2_PAGE=1 (1-based) V2_SIZE=100 (server clamps to 100) # --------------------------------------------------------------------------- +V2_PAGE ?= 1 +V2_SIZE ?= 100 + v2-orders-report: - @echo "V2 orders report — GET /api/certinext/v2/reports/orders (NOTE: currently 501)" - @scripts/v2/orders-report.sh + @echo "V2 orders report — GET /api/certinext/v2/reports/orders?page=$(V2_PAGE)&size=$(V2_SIZE)" + @PAGE=$(V2_PAGE) SIZE=$(V2_SIZE) scripts/v2/orders-report.sh # --------------------------------------------------------------------------- # Help @@ -775,7 +777,7 @@ api-help: @echo "" @echo " make probe-products [PROBE_DOMAIN=test-integration.example.com]" @echo " Place saveAndHold=1 draft orders for all SSL/TLS product codes" - @echo " provisioned on the sandbox account (842–851, 149) and report which" + @echo " in the sandbox product list (842–851, 149) and report which" @echo " codes are accepted. A code returning a requestNumber is valid." @echo " Depends on generate-test-csr (called automatically)." @echo "" @@ -813,9 +815,8 @@ api-help: @echo "" @echo " make generate-order-igtf [IGTF_CSR_FILE=/tmp/certinext-igtf-test.csr]" @echo " GenerateOrderPrivatePKI — place a Private PKI order using product 149" - @echo " (Sandbox emSign Intranet SSL, the only active Private PKI product on this" - @echo " sandbox account). Uses saveAndHold=1 by default." - @echo " NOTE: product 108 (IGTF Host) is not provisioned on this account." + @echo " (Sandbox emSign Intranet SSL). Uses saveAndHold=1 by default." + @echo " NOTE: product 108 (IGTF Host) requires separate provisioning." @echo "" @echo " make generate-order-private-pki [PRIVATE_PKI_CSR=...] [PRIVATE_PKI_DOMAIN=...] [PRIVATE_PKI_CODE=149]" @echo " GenerateOrderPrivatePKI — place a Private PKI order for any product code." diff --git a/QUICKSTART.md b/QUICKSTART.md index 40b8292..5de5c32 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -5,6 +5,11 @@ the Keyfactor AnyCA REST Gateway. Walks an operator from "plugin DLL is on the gateway pod" to "Keyfactor Command can enroll an end-entity certificate through the plugin" with copy-pasteable scripts. +> **This is a V1 / AccessKey guide.** The V1 API authenticates with an +> access key only. The V2 API authenticates with OAuth2 only; for V2 +> connector settings, see the +> [V1 to V2 migration guide](docsource/migration-v1-to-v2.md). + Each step is shown twice: a Bash + curl block and a PowerShell block. Use whichever fits your shell. Variables flow forward through the doc, so set them once and reuse them. @@ -24,8 +29,10 @@ so set them once and reuse them. 6. **Enroll a test certificate** end-to-end The CERTInext sandbox returns orders in `EXTERNAL_VALIDATION` status -(pending DCV or manual review), so the final enrollment test reports a -pending result by design — that's success. +(pending DCV or manual review), so the final enrollment test normally +reports a pending result by design — that's success. If DCV is operational +(see [Prerequisites](#prerequisites)), a DV order can instead be issued +within the same enrollment call. ### Data model & dependency order @@ -63,7 +70,7 @@ again inline in each step's intro: | Step | Reference file | |---|---| | 2 — gateway profiles | [`docs/reference/gateway/certificate-profiles.json`](docs/reference/gateway/certificate-profiles.json) | -| 3 — gateway CA config | not GET-able (HTTP 405); see [`docs/reference/gateway/claims.json`](docs/reference/gateway/claims.json) for the authz table this step seeds | +| 3 — gateway CA config | not GET-able (HTTP 405); see [`docs/reference/gateway/claims.json`](docs/reference/gateway/claims.json) for the related authorization table | | 4 — Command CA | [`docs/reference/command/certificate-authority.json`](docs/reference/command/certificate-authority.json) | | 5 — Command templates | [`docs/reference/command/templates-certinext.json`](docs/reference/command/templates-certinext.json) | @@ -73,8 +80,9 @@ again inline in each step's intro: | Component | Required state | |---|---| -| Keyfactor Command | Deployed and reachable at `${COMMAND_URL}` | -| AnyCA REST Gateway | Deployed and reachable at `${GATEWAY_URL}` | +| Keyfactor Command | 25.5 or later, deployed and reachable at `${COMMAND_URL}` | +| AnyCA Gateway REST | 26.2.0 or later (provides `IAnyCAPlugin` 3.3.0), deployed and reachable at `${GATEWAY_URL}` | +| DNS provider plugin | Required for DV auto-issuance. DCV is on by default (`DcvEnabled` defaults to `true`), so a DNS provider plugin must be deployed on the gateway for DV orders to complete | | CERTInext plugin DLL | Already staged at `/app/Extensions/certinext-caplugin/` on the gateway pod; gateway has been restarted since | | Identity Provider | OIDC client credentials issued for both the gateway and Command (Authentik, Keycloak, Entra, etc.) | | CERTInext sandbox account | AccessKey, AccountNumber, GroupNumber, OrganizationNumber, registered requestor email | @@ -216,9 +224,11 @@ if (-not $CmdToken) { throw "command token mint failed" } > **Reference state after this step:** see > [`docs/reference/gateway/certificate-profiles.json`](docs/reference/gateway/certificate-profiles.json) -> for the final 8-profile shape (one per sandbox product) the gateway -> returns from `GET /AnyGatewayREST/config/certificateprofile` after -> all profiles are in place. +> for the final 8-profile shape (eight of the ten advertised products; +> the two EV products are not included) the gateway returns from +> `GET /AnyGatewayREST/config/certificateprofile` after all profiles are +> in place. That capture is deliberately broader than the policy used +> below; see [Key algorithm policy](#key-algorithm-policy). A **certificate profile** on the gateway is a top-level resource: a named key-algorithm policy that's independent of any CA. CA @@ -228,22 +238,22 @@ through their `Templates[]` array, so the profile must exist first. The profile sets the key constraints (allowed algorithms, sizes, curves) the gateway enforces on incoming CSRs / key generations for any ProductID bound to it. One profile can be shared by many CA configs; -in this guide we use a 1-to-1 profile-per-ProductID convention because -the `WirePlugin` code path in `kfclab` does the same. +in this guide we use a 1-to-1 profile-per-ProductID convention, which is +also what `scripts/register/01-gateway-profiles.sh` does. Without an explicit `key_algs` block the gateway uses an empty default that Command interprets as "no key types allowed" — PFX enrollment then fails with `0xA0110004` ("Key type 'RSA' is unsupported or disallowed by -policy"). The body below is the canonical "permit everything we care -about" payload. +policy"). This cause is reported from the field; it is not verified in +this repo. The body below permits exactly the key types CERTInext accepts +(see [Key algorithm policy](#key-algorithm-policy)). ### Bash ```bash KEY_ALGS='{ - "rsa": {"bit_lengths":[2048,3072,4096]}, - "ecdsa": {"curves":["1.2.840.10045.3.1.7","1.3.132.0.34","1.3.132.0.35"]}, - "ed25519": {"bit_lengths":[255]} + "rsa": {"bit_lengths":[2048,3072,4096]}, + "ecdsa": {"curves":["1.2.840.10045.3.1.7","1.3.132.0.34"]} }' PROFILE_BODY=$(jq -n \ @@ -279,13 +289,11 @@ curl -sk -X PUT "${GATEWAY_URL}/AnyGatewayREST/config/certificateprofile" \ ```powershell $KeyAlgs = @{ - rsa = @{ bit_lengths = @(2048, 3072, 4096) } - ecdsa = @{ curves = @( + rsa = @{ bit_lengths = @(2048, 3072, 4096) } + ecdsa = @{ curves = @( "1.2.840.10045.3.1.7", # secp256r1 (P-256) - "1.3.132.0.34", # secp384r1 (P-384) - "1.3.132.0.35" # secp521r1 (P-521) + "1.3.132.0.34" # secp384r1 (P-384) ) } - ed25519 = @{ bit_lengths = @(255) } } $ProfileBody = @{ @@ -322,15 +330,45 @@ try { } ``` -> **Note on CERTInext key algorithm restrictions:** The gateway profile's `key_algs` block defines what Command *allows* — it does not reflect what CERTInext will accept. CERTInext additionally restricts enrollments to RSA 2048/3072/4096 and ECC P-256/P-384. Orders submitted with P-521, Ed25519, Ed448, or RSA larger than 4096 bits are accepted by Command and the gateway but rejected by CERTInext with `Invalid key size`. Configure your profiles and templates to only permit the key types CERTInext supports. +### Key algorithm policy + +The gateway profile's `key_algs` block defines what Command *allows*. It +does not reflect what CERTInext accepts. CERTInext rejects unsupported +keys with `Invalid key size` even though Command and the gateway accept +them, so permit only the supported types in your profiles: + +| Key type | CERTInext | +|---|---| +| RSA 2048, 3072, 4096 | Accepted | +| ECC P-256, P-384 | Accepted | +| RSA 6144 / 8192 | Rejected (`Invalid key size`) | +| ECC P-521 | Rejected | +| Ed25519, Ed448 | Rejected | + +The reference capture in [`docs/reference/`](docs/reference/README.md) +permits all of the rejected types too; it records one lab's state and is +not a recommended policy. + +### All eight non-EV products + +To register all eight non-EV sandbox products, loop Steps 2 and 3 over the +(ProductID, ProductCode) pairs: -> **Doing this for all 8 non-EV sandbox products?** Wrap Steps 2 and 3 in a -> loop over the (ProductID, ProductCode) pairs. The sandbox non-EV product -> codes are 842 (DV SSL), 843 (DV Wildcard), 844 (DV UCC), 845 (DV -> Wildcard UCC), 846 (OV SSL), 847 (OV Wildcard), 848 (OV UCC), 849 -> (OV Wildcard UCC). EV SSL (850) and EV UCC (851) require additional -> `contractSignerInfo`, `certificateApproverInfo`, and org/contract fields -> beyond the base product set. +| ProductID | Sandbox ProductCode | +|---|---| +| `DV SSL` | 842 | +| `DV SSL Wildcard` | 843 | +| `DV SSL Multi-Domain (UCC)` | 844 | +| `DV SSL Wildcard Multi-Domain (UCC)` | 845 | +| `OV SSL` | 846 | +| `OV SSL Wildcard` | 847 | +| `OV SSL Multi-Domain (UCC)` | 848 | +| `OV SSL Wildcard Multi-Domain (UCC)` | 849 | + +The plugin also advertises `EV SSL` (850) and `EV SSL Multi-Domain (UCC)` +(851). They need extra `contractSignerInfo`, `certificateApproverInfo`, and +organization/contract fields beyond the base product set, so they are not +covered here. --- @@ -338,9 +376,10 @@ try { > **Reference state after this step:** > [`docs/reference/gateway/claims.json`](docs/reference/gateway/claims.json) -> shows the gateway authz table — the `akadmin` admin claim is added -> as part of this step on the kfclab path, so authenticated human users -> can hit the gateway UI without being denied. +> shows the gateway authorization (claims) table, which maps OAuth +> subjects to gateway roles. This step's request body doesn't create +> claims; `scripts/register/03-gateway-claims.sh` seeds them. Add a claim +> for every human operator who needs the gateway UI. > > The CA configuration itself is **not GET-able** (the gateway returns > HTTP 405 on `GET /config/configuration` — POST/PUT only), so there's @@ -367,7 +406,7 @@ The shape uses four top-level keys: | Key | Purpose | |---|---| -| `CAConnection` | The CERTInext plugin's connection config (auth + identifying numbers). All `RequestorIsdCode`, `RequestorMobileNumber`, `SignerPlace`, `Enabled` etc. live here. | +| `CAConnection` | The CERTInext plugin's connection config (auth + identifying numbers). Also includes `RequestorIsdCode`, `RequestorMobileNumber`, `SignerPlace`, and `Enabled`. | | `GatewayRegistration` | `LogicalName` (what Command will see) + `GatewayCertificate.ImportedCertificate` (PEM blob, base64-of-PEM is also accepted). | | `ServiceSettings` | Scan intervals; tune for your environment. | | `Templates[]` | The (ProductID → CertificateProfile) mapping. Parameters carry per-product config like `ProductCode` and `ValidityYears`. | @@ -375,6 +414,10 @@ The shape uses four top-level keys: `POST` creates; `PUT` updates an existing config. Most operators end up using `PUT` after the first run. +The `CAConnection` body below does not set `DcvEnabled`, so it takes the +default of `true`. DV orders then need a DNS provider plugin on the gateway +(see [Prerequisites](#prerequisites)); add `"DcvEnabled": false` to opt out. + ### Bash ```bash @@ -503,17 +546,10 @@ try { } ``` -After this completes, the gateway is fully wired to CERTInext. Confirm -by GETting the configuration back: - -```bash -curl -sk "${GATEWAY_URL}/AnyGatewayREST/config/configuration" \ - -H "Authorization: Bearer ${GW_TOKEN}" \ - -H "x-keyfactor-requested-with: APIClient" | jq '.Templates' -``` - -You should see your `Templates[]` array with the (ProductID, -CertificateProfile) entries from above. +After this completes, the gateway is wired to CERTInext. The configuration +endpoint is not GET-able (see the note at the top of this step), so confirm +the POST/PUT returned a 2xx status, then check the result in Step 4 (Command +registers the CA) and Step 5 (Command imports your `Templates[]`). --- @@ -530,16 +566,17 @@ CertificateProfile) entries from above. Command needs to know the gateway exists and what auth to use when talking to it. The CA registration carries the OAuth client used for Command-to-gateway calls (the same gateway OAuth client from Step 1) and -the `ConfigurationTenant` that ties this registration to the gateway's -plugin (the plugin name — by convention `certinext-caplugin`). +the `ConfigurationTenant` that ties this registration to the gateway CA +configuration (the `GatewayRegistration.LogicalName` from Step 3 — by +convention `certinext-caplugin`). Important fields: | Field | Value | Why | |---|---|---| -| `HostName` | `${GATEWAY_URL}/AnyGatewayREST/ejbca/ejbca-rest-api` | All AnyCA REST Gateway plugins are served behind the EJBCA-compatible prefix; Command speaks EJBCA REST to the gateway. | +| `HostName` | `${GATEWAY_URL}/AnyGatewayREST/ejbca` | The gateway serves plugins behind an EJBCA-compatible prefix; Command speaks EJBCA REST to it. | | `CAType` | `1` | HTTPS (AnyCA REST). `0` is DCOM (legacy Windows). | -| `ConfigurationTenant` | `certinext-caplugin` | Must match the LogicalName the plugin uses; also the value you'll pass to `/Templates/Import` in Step 5. | +| `ConfigurationTenant` | `certinext-caplugin` | Must match the `GatewayRegistration.LogicalName` from Step 3; also the value you pass to `/Templates/Import` in Step 5. | | `Scope` | `keyfactor-anyca-gateway` | The OAuth scope the gateway's token introspection allows. | | `ClientSecret` | `{"SecretValue": "..."}` | Command's `KeyfactorSecret` shape; raw strings are rejected with `"Invalid JSON schema. Expected: 'StartObject' Received: 'String'"`. | @@ -548,7 +585,7 @@ Important fields: ```bash CA_BODY=$(jq -n \ --arg logical "${CA_LOGICAL_NAME}" \ - --arg host "${GATEWAY_URL}/AnyGatewayREST/ejbca/ejbca-rest-api" \ + --arg host "${GATEWAY_URL}/AnyGatewayREST/ejbca" \ --arg tenant "${CA_LOGICAL_NAME}" \ --arg token_url "${TOKEN_URL}" \ --arg client_id "${GW_CLIENT_ID}" \ @@ -561,7 +598,7 @@ CA_BODY=$(jq -n \ "NewEndEntityOnRenewAndReissue": true, "AllowOneClickRenewals": true, "UseForEnrollment": true, - "KeyRetention": "Indefinite", + "KeyRetention": 1, "AllowedEnrollmentTypes": 3, "FullScan": {"Interval": {"Minutes": 720}}, "IncrementalScan": {"Interval": {"Minutes": 5}}, @@ -584,13 +621,13 @@ curl -sk -X POST "${COMMAND_URL}/KeyfactorAPI/CertificateAuthorities" \ ```powershell $CaBody = @{ LogicalName = $CaLogicalName - HostName = "$GatewayUrl/AnyGatewayREST/ejbca/ejbca-rest-api" + HostName = "$GatewayUrl/AnyGatewayREST/ejbca" CAType = 1 ConfigurationTenant = $CaLogicalName NewEndEntityOnRenewAndReissue = $true AllowOneClickRenewals = $true UseForEnrollment = $true - KeyRetention = "Indefinite" + KeyRetention = 1 AllowedEnrollmentTypes = 3 FullScan = @{ Interval = @{ Minutes = 720 } } IncrementalScan = @{ Interval = @{ Minutes = 5 } } @@ -627,8 +664,8 @@ curl -sk "${COMMAND_URL}/KeyfactorAPI/CertificateAuthorities" \ > **Reference state after this step:** see > [`docs/reference/command/templates-certinext.json`](docs/reference/command/templates-certinext.json) -> for the 8 templates Command creates from the 8 ProductIDs registered -> in Step 3 (filtered from `GET /KeyfactorAPI/Templates` by +> for the 8 templates Command creates from the 8 non-EV ProductIDs +> registered in Step 3 (filtered from `GET /KeyfactorAPI/Templates` by > `ConfigurationTenant=certinext-caplugin`). Confirms the > `AnyCA_` naming convention, the `ExtendedKeyUsages` set, > the `KeyTypes` list synced from the gateway profile's `key_algs`, @@ -636,7 +673,8 @@ curl -sk "${COMMAND_URL}/KeyfactorAPI/CertificateAuthorities" \ Command's `/Templates/Import` endpoint asks the registered gateway CA for its template list and creates corresponding Command-side templates -named `AnyCA_` (e.g. `AnyCA_DV SSL`). One call covers every +with `CommonName` `AnyCA_` (e.g. `AnyCA_DV SSL`). The +`TemplateName` and `DisplayName` are `AnyCA ()`. One call covers every template you defined under `Templates[]` in Step 3. ### Bash @@ -654,7 +692,7 @@ curl -sk -X POST "${COMMAND_URL}/KeyfactorAPI/Templates/Import" \ curl -sk "${COMMAND_URL}/KeyfactorAPI/Templates" \ -H "Authorization: Bearer ${CMD_TOKEN}" \ -H "x-keyfactor-requested-with: APIClient" \ - | jq '[.[] | select(.ShortName | startswith("AnyCA_"))] | map({Id, ShortName, DisplayName})' + | jq '[.[] | select(.CommonName | startswith("AnyCA_"))] | map({Id, CommonName, DisplayName})' ``` ### PowerShell @@ -672,8 +710,8 @@ $AllTemplates = Invoke-RestMethod -Method Get ` -Headers $CmdHeaders -SkipCertificateCheck $AllTemplates ` - | Where-Object { $_.ShortName -like "AnyCA_*" } ` - | Select-Object Id, ShortName, DisplayName + | Where-Object { $_.CommonName -like "AnyCA_*" } ` + | Select-Object Id, CommonName, DisplayName ``` > **Re-run after gateway profile changes.** Any time you update the @@ -681,7 +719,8 @@ $AllTemplates ` > call — Command caches the allowed key types per-template in > `dbo.KeyAlgorithms` and only refreshes them through this endpoint. If > you skip the re-import, PFX enrollment continues to fail with -> `0xA0110004` despite the gateway being correct. +> `0xA0110004` despite the gateway being correct. (Reported from the +> field; the Command internals are not verified in this repo.) --- @@ -789,18 +828,18 @@ sync pulls down the actual certificate. Useful when the requesting system already has a keypair it doesn't want to surface to Command. - **Sandbox quota.** The CERTInext sandbox enforces a burst rate limit - that surfaces as the misleading error string `"Inactive Account - User."`. If you're submitting many test orders in tight succession - and start seeing that error, throttle to one order every 1-2 seconds - and wait ~5-25 minutes for the cooldown. Tracking issue: - [Keyfactor/certinext-caplugin#8](https://github.com/Keyfactor/certinext-caplugin/issues/8). + that surfaces as the misleading error `"Inactive Account User."`. + - Rule: submit at most one test order every 1-2 seconds. + - Wait: 30-60 seconds after hitting the error, then retry one order. + - Details: [Troubleshooting in overview.md](docsource/overview.md#inactive-account-user-returned-from-generateorderssl) + and issue [Keyfactor/certinext-caplugin#8](https://github.com/Keyfactor/certinext-caplugin/issues/8). ## Troubleshooting | Symptom | Likely cause | Fix | |---|---|---| -| Step 5 returns 0 templates imported | `ConfigurationTenant` doesn't match between Steps 3 and 4 | Re-check both call to make sure the LogicalName / ConfigurationTenant agree. | +| Step 5 returns 0 templates imported | `ConfigurationTenant` doesn't match the gateway `LogicalName` from Step 3 | Re-check both calls to make sure `ConfigurationTenant` (Steps 4 and 5) equals `GatewayRegistration.LogicalName` (Step 3). | | Step 6 returns `0xA0110004` "Key type 'RSA' disallowed by policy" | Gateway `key_algs` are empty or wrong, or Command hasn't re-imported templates after a profile change | Update `key_algs` (Step 2), re-run `/Templates/Import` (Step 5). | -| Step 6 returns `0xA0010023` "external validation" with HTTP 400 | The gateway returned a pending response and Command's exception filter translated it — Command 25.x bug | The plugin DID accept the order. Confirm via `GET ${GATEWAY_URL}/AnyGatewayREST/.../v1/certificate/`. Fixed in newer Command builds; rewrite as 200 with disposition `EXTERNAL_VALIDATION`. | -| Step 6 returns `"Inactive Account User."` from the gateway log | CERTInext sandbox rate limit | Wait 5-25 minutes; retry a single order to confirm the account is alive. See [#8](https://github.com/Keyfactor/certinext-caplugin/issues/8). | -| Step 6 returns `TypeLoadException IDomainValidatorFactory` in the gateway pod log | DCV build deployed on a gateway running IAnyCAPlugin 3.2.x (25.5.x) | Deploy the no-DCV build (the default release artifact); do not deploy the DCV build (`-p:DcvSupport=true`) on a gateway running IAnyCAPlugin 3.2.x (25.5.x). Use the DCV build only on 26.x. | +| Step 6 returns `0xA0010023` "external validation" with HTTP 400 | The gateway returned a pending response and Command translated it into an error (reported from the field; not verified in this repo) | The plugin accepted the order. Confirm it in the gateway or Command certificate list. Reportedly fixed in newer Command builds, which return 200 with disposition `EXTERNAL_VALIDATION`. | +| Step 6 returns `"Inactive Account User."` from the gateway log | CERTInext sandbox rate limit | Wait 30-60 seconds, then retry one order. See [overview.md](docsource/overview.md#inactive-account-user-returned-from-generateorderssl) and [#8](https://github.com/Keyfactor/certinext-caplugin/issues/8). | +| Step 6 returns `TypeLoadException IDomainValidatorFactory` in the gateway pod log | The plugin is deployed on a gateway older than AnyCA Gateway REST 26.2.0 (IAnyCAPlugin before 3.3) | Upgrade the gateway to 26.2.0 or later (see [Prerequisites](#prerequisites)). | diff --git a/README.md b/README.md index ff91ab1..061f2d3 100644 --- a/README.md +++ b/README.md @@ -37,20 +37,23 @@ The CERTInext AnyCA Gateway REST plugin extends the certificate lifecycle capabi * CA Synchronization: * Download all certificates issued through the CERTInext CA, either as a full inventory or incrementally since the last sync. - * Expired certificates can optionally be excluded from synchronization using the `IgnoreExpired` configuration flag. + * Expired certificates can optionally be excluded from synchronization using the `IgnoreExpired` configuration flag (V2 only; the V1 API does not currently apply it). * Certificate Enrollment for profiles configured in CERTInext: * New certificate enrollment (new keys and certificate). - * Certificate renewal — submits a new `GenerateOrderSSL` order when the prior certificate is within the configured renewal window (CERTInext has no dedicated renewal endpoint; the renewal-window check governs how Command tracks old→new, not which API is called). + * Certificate renewal — on the V1 API, submits a new `GenerateOrderSSL` order when the prior certificate is within the configured renewal window (CERTInext has no dedicated renewal endpoint; the renewal-window check governs how Command tracks old→new, not which API is called). On the V2 API every renewal places a new order. * Certificate reissuance (new keys with the same or updated subject/SANs) when outside the renewal window or no prior certificate is found. + * Synchronous certificate pickup — a fast-issuing order (DV, or already-approved) can return the certificate in the same enrollment call instead of always waiting for the next sync, via `PickupRetries`/`PickupDelay`. + * DNS-01 domain control validation (DCV) — the plugin publishes the validation TXT record through a DNS provider plugin deployed on the gateway and asks CERTInext to verify it, during enrollment and during synchronization (`DcvEnabled`, on by default). * Certificate Revocation: - * Request revocation of a previously issued certificate using any RFC 5280 CRL reason code. + * Request revocation of a previously issued certificate using RFC 5280 reason codes, mapped to the reasons CERTInext accepts (see [Revocation Reason Codes](#revocation-reason-codes)). * Supported authentication modes for calls to the CERTInext API: - * AccessKey (HMAC-based request signing) — the primary and recommended mode - * OAuth (bearer token via client credentials flow) + * V1 API (default): AccessKey — SHA-256 signed requests. + * V2 API: OAuth2 `client_credentials` bearer token. +* Two CERTInext API generations, selected per connector with `UseV2Api`: the V1 API (default) and the order-centric V2 REST API, which adds Private PKI products. See [V2 API](#v2-api) and [Migrating from V1 to V2](#migrating-from-v1-to-v2). ## Compatibility -The CERTInext AnyCA Gateway REST plugin is compatible with the Keyfactor AnyCA Gateway REST 25.5.0 and later. +The CERTInext AnyCA Gateway REST plugin is compatible with the Keyfactor AnyCA Gateway REST 26.2.0 and later. ## Support The CERTInext AnyCA Gateway REST plugin is supported by Keyfactor for Keyfactor customers. If you have a support issue, please open a support ticket via the Keyfactor Support Portal at https://support.keyfactor.com. @@ -59,21 +62,41 @@ The CERTInext AnyCA Gateway REST plugin is supported by Keyfactor for Keyfactor ## Requirements -* Keyfactor Command 25.5.x or later -* AnyCA Gateway REST framework version 25.5.0 or later +* Keyfactor Command 25.5 or later +* AnyCA Gateway REST framework version 26.2.0 or later +* A DNS provider plugin deployed on the AnyCA Gateway if the connector validates domains with DNS-01 DCV (the default; see `DcvEnabled`) * A CERTInext account with API access enabled and at least one certificate product configured * Network connectivity from the AnyCA Gateway host to the CERTInext API endpoint for your region (see table below) * The AnyCA Gateway host must trust the TLS certificate presented by the CERTInext API endpoint +### Compatibility and Authentication Matrix + +The connector runs in one of two modes, chosen with `UseV2Api`. The mode decides the `ApiUrl` shape, how the plugin authenticates, and which credential fields are used. + +| | V1 (default) | V2 (`UseV2Api` = `true`) | +|---|---|---| +| AnyCA Gateway REST / `IAnyCAPlugin` | 26.2.0 or later / 3.3.0 | 26.2.0 or later / 3.3.0 | +| Authentication | AccessKey (SHA-256 signed request body) | OAuth2 `client_credentials` bearer token | +| `ApiUrl` shape | `https:///emSignHub-API/` | Bare host, for example `https://us-api.certinext.io` | +| Token URL | None | Derived: `{ApiUrl}/oauth/token` | +| `AccountNumber` | Required | Ignored | +| `ApiKey` | Required | Ignored | +| `AuthMode` | Optional; leave as `AccessKey` (legacy field) | Ignored | +| `OAuthClientId` / `OAuthClientSecret` | Not used (legacy only) | Required | +| `OAuthTokenUrl` | Not used (legacy only) | Ignored | +| `SignerPlace` | Set it; sent on every order | Required at save | +| Products | SSL/TLS (DV, OV, EV) | SSL/TLS (DV, OV, EV) and Private PKI | +| DCV | On by default; needs a DNS provider plugin | On by default; needs a DNS provider plugin | + ### CERTInext Environments CERTInext operates three separate environments. Use the sandbox environment for initial integration testing. Switch to a production environment only after all functionality has been verified. -| Environment | Portal Sign-in URL | API Base URL | -|---|---|---| -| Sandbox | https://sandbox-us.certinext.io/ | `https://sandbox-us-api.certinext.io/emSignHub-API/` | -| Production — India (Global) | https://in.certinext.io/ | `https://api.certinext.io/emSignHub-API/` | -| Production — US | https://us.certinext.io/ | `https://us-api.certinext.io/emSignHub-API/` | +| Environment | Portal Sign-in URL | V1 API Base URL | V2 API Base URL | +|---|---|---|---| +| Sandbox | https://sandbox-us.certinext.io/ | `https://sandbox-us-api.certinext.io/emSignHub-API/` | `https://sandbox-us-api.certinext.io` | +| Production — India (Global) | https://in.certinext.io/ | `https://api.certinext.io/emSignHub-API/` | `https://api.certinext.io` | +| Production — US | https://us.certinext.io/ | `https://us-api.certinext.io/emSignHub-API/` | `https://us-api.certinext.io` | > Note: Product codes differ between sandbox and production. Always confirm product codes from the GetProductDetails API call against the environment you are targeting before going live. @@ -109,101 +132,157 @@ CERTInext operates three separate environments. Use the sandbox environment for 1. Log in to the CERTInext portal and download the root CA certificate and any intermediate CA certificates in the chain as PEM or DER files. 2. On the Keyfactor Command server, import those certificates into the appropriate Windows certificate store — **Trusted Root Certification Authorities** for the root CA and **Intermediate Certification Authorities** for any subordinate CAs. 3. In the Keyfactor Command Management Portal, navigate to **CA Connectors** and add a new CA using the **CERTInext AnyCA REST Gateway Plugin**. - 4. Complete the CA connector configuration fields described in the next section, then save and test the connection. The gateway performs a live connectivity test against the CERTInext `ValidateCredentials` endpoint during validation. + 4. Complete the CA connector configuration fields described in the next section, then save and test the connection. The gateway performs a live connectivity test during validation: the V1 `ValidateCredentials` endpoint, or `GET /api/certinext/v2/auth/me` when `UseV2Api` is `true`. + + ### Change of issuing CA (eMudhra exit from public TLS) + + eMudhra, CERTInext's parent company, is withdrawing from the public SSL/TLS certificate business, and browser root programs are phasing out the emSign roots that CERTInext public TLS certificates have chained to. Public TLS certificates ordered through CERTInext will be issued under a different CA. Which CA depends on your service: InCommon members are moving to [SSL.com](https://incommon.org/about/news/incommon-certificate-service-update), and eMudhra offers [Sectigo](https://emudhra.com/en/post/certificate-security-incident) certificates to its customers. Confirm the new chain for your account with CERTInext. + + Dates published by eMudhra for the emSign G1 root (check the [eMudhra statement](https://emudhra.com/en/post/certificate-security-incident) for changes): + + | Root program | Effect | + |---|---| + | Chrome, Mozilla Firefox | Certificates logged after November 16, 2026 are not trusted. Certificates issued before then stay trusted until they expire. | + | Apple | The root is removed on November 30, 2026. Every certificate issued under it stops being trusted on Apple platforms, including existing ones. | + | Microsoft | No date announced. | + + The plugin does not need to change. It stores only the issued certificate and never reads or checks the issuer. Repeat the trust and registration steps above with the new chain: + + 1. Get the new root and intermediate certificates for your account from CERTInext. + 2. Import them on the Keyfactor Command server and the AnyCA Gateway REST host, and on any orchestrator or client that builds or validates certificate chains. Use **Trusted Root Certification Authorities** for the root and **Intermediate Certification Authorities** for subordinates. + 3. Replace the CA certificate in this CA's **Gateway Registration** with the new issuing chain. + 4. Replace certificates that chain to the emSign G1 root before November 30, 2026 if Apple clients rely on them. Keep the emSign certificates in your trust stores until you have replaced every certificate issued under them. + + Also confirm with CERTInext whether your account's product codes change. If they do, update the `ProductCode` mapping on each template. * **CA Connection** Populate using the configuration fields collected in the [requirements](#requirements) section. - * **ApiUrl** - REQUIRED: CERTInext API base URL. Sandbox (US): https://sandbox-us-api.certinext.io/emSignHub-API/ — Production (US): https://us-api.certinext.io/emSignHub-API/ — Production (Global/India): https://api.certinext.io/emSignHub-API/ - * **AccountNumber** - REQUIRED: Your CERTInext account number (numeric string). Available in the CERTInext portal. - * **GroupNumber** - OPTIONAL: CERTInext group (delegation) number. When set, it is included in GetProductDetails requests AND in the `delegationInformation.groupNumber` field of every SSL order so the order is routed to the correct account group. Some accounts will queue orders for additional review when this field is omitted. Available in the CERTInext portal under Delegation → Groups. - * **OrganizationNumber** - STRONGLY RECOMMENDED for OV/EV and faster DV issuance: numeric CERTInext organization number for a pre-vetted organization (e.g. your company's pre-vetted entry). When set, every SSL order is submitted with `organizationDetails.preVetting="1"` and the configured `organizationNumber`, telling CERTInext to skip the manual organization-vetting queue. Without this value, orders are placed without any organizationDetails block and CERTInext may park them in `Pending System RA` for extended manual review (observed: tens of hours). Available in the CERTInext portal under Organizations → Pre-vetted Organizations. - * **TechnicalContactName** - OPTIONAL: Name sent in the `technicalPointOfContact.tpcName` field of every SSL order. Defaults to the configured RequestorName when blank. Some product configurations require a TPoC to be present; omitting it can cause CERTInext to park orders awaiting manual completion of the field. - * **TechnicalContactEmail** - OPTIONAL: Email sent in the `technicalPointOfContact.tpcEmail` field of every SSL order. Defaults to the configured RequestorEmail when blank. - * **TechnicalContactIsdCode** - OPTIONAL: International dialing code for the TPoC phone number. Defaults to the configured RequestorIsdCode when blank. - * **TechnicalContactMobileNumber** - OPTIONAL: Mobile number for the TPoC (digits only). Defaults to the configured RequestorMobileNumber when blank. - * **AuthMode** - REQUIRED: Authentication mode. 'AccessKey' (default) — uses authKey = SHA256(accessKey + ts + txn) in every request body. 'OAuth' — uses an OAuth2 bearer token (requires OAuthTokenUrl, OAuthClientId, OAuthClientSecret). - * **ApiKey** - REQUIRED when AuthMode is 'AccessKey': the REST API Access Key generated in the CERTInext portal under Integrations → APIs. This value is used to compute authKey = SHA256(accessKey + ts + txn); it is never transmitted directly. - * **OAuthTokenUrl** - OAuth token endpoint URL. Required when AuthMode is 'OAuth'. - * **OAuthClientId** - OAuth client ID. Required when AuthMode is 'OAuth'. - * **OAuthClientSecret** - OAuth client secret. Required when AuthMode is 'OAuth'. + * **ApiUrl** - REQUIRED: CERTInext API base URL. V1 (default): host plus /emSignHub-API/, e.g. https://us-api.certinext.io/emSignHub-API/. V2 (UseV2Api=true): bare host, e.g. https://us-api.certinext.io. Must use https. + * **AccountNumber** - REQUIRED when UseV2Api is false: your CERTInext account number (numeric string). Included in the `meta` block of every V1 request. Not used when UseV2Api is true. Available in the CERTInext portal. + * **GroupNumber** - OPTIONAL: CERTInext group (delegation) number. When set, it is included in product-catalog requests and in the order (`orderDetails.groupNumber` on V1, `groupNumber` on V2) so the order is routed to the configured account group, and V2 synchronization is scoped to the group. When blank, CERTInext uses the account's default group. Available in the CERTInext portal under Delegation → Groups. + * **OrganizationNumber** - OPTIONAL: Pre-vetted CERTInext organization number. Required for OV/EV on V2; recommended for V1 OV/EV and faster DV. Skips CERTInext's manual vetting queue. + * **TechnicalContactName** - OPTIONAL: Name sent as the order's technical point of contact (V1 `technicalPointOfContact.pocFirstName` / `pocLastName`, V2 `technicalPointOfContact.name`). On V1 the name is split on the first whitespace: the first word is the first name and the rest is the last name; a single-word name is sent in both. Defaults to the configured RequestorName when blank. On V1, if no contact name or no email resolves (including from RequestorName/RequestorEmail), the whole technicalPointOfContact block is omitted from the order and a Warning is logged, since CERTInext requires both inside the block. + * **TechnicalContactEmail** - OPTIONAL: Email sent as the order's technical point of contact (V1 `technicalPointOfContact.pocEmail`, V2 `email`). Defaults to the configured RequestorEmail when blank. On V1, if no contact name or no email resolves (including from RequestorName/RequestorEmail), the whole technicalPointOfContact block is omitted from the order and a Warning is logged, since CERTInext requires both inside the block. + * **TechnicalContactIsdCode** - OPTIONAL: International dialing code for the technical contact phone number. Defaults to the configured RequestorIsdCode when blank. + * **TechnicalContactMobileNumber** - OPTIONAL: Mobile number for the technical contact (digits only). Defaults to the configured RequestorMobileNumber when blank. + * **AuthMode** - OPTIONAL, legacy (V1 only): leave as 'AccessKey' (default). V1 does not honor OAuth tokens, so 'OAuth' is unsupported. Ignored when UseV2Api is true. + * **ApiKey** - REQUIRED when UseV2Api is false: the REST API Access Key generated in the CERTInext portal under Integrations → APIs. Used to compute authKey = SHA256(accessKey + ts + txn); never transmitted directly. Not used when UseV2Api is true. + * **OAuthTokenUrl** - Legacy / unsupported (V1): V1 does not honor OAuth tokens; leave blank. Ignored when UseV2Api is true — V2 requests its token from {ApiUrl}/oauth/token. + * **OAuthClientId** - OAuth client ID. REQUIRED when UseV2Api is true: V2 authenticates with client_credentials against {ApiUrl}/oauth/token. The key must be generated in OAuth mode in the CERTInext portal. Not used on V1. + * **OAuthClientSecret** - OAuth client secret. REQUIRED when UseV2Api is true (see OAuthClientId). Not used on V1. * **RequestorName** - REQUIRED: Default requestor name submitted with all certificate orders. This is the name of the person/service responsible for the certificates. * **RequestorEmail** - REQUIRED: Default requestor email submitted with all certificate orders. Must be a valid email address registered in your CERTInext account. * **RequestorIsdCode** - International dialing code for the requestor phone number (e.g. '1' for US). Default: '1'. * **RequestorMobileNumber** - Requestor mobile number (digits only, no country code). - * **SignerPlace** - City or location of the subscriber agreement signer. Required by CERTInext for all orders. - * **SignerIp** - IP address of the subscriber agreement signer. Required by CERTInext for all orders. - * **DefaultProductCode** - OPTIONAL: Default numeric product code used when not specified at template level. Product codes are provided by eMudhra (e.g. the SSL DV 1-year code for your account). Retrieve available codes from Integrations → APIs → GetProductDetails. - * **AccountingModel** - OPTIONAL: CERTInext billing model sent in `orderDetails.accountingModel`. "2" = credit-based (most accounts, default). "1" = cash model. - * **EmailNotifications** - OPTIONAL: Whether CERTInext sends lifecycle-event emails to the requestor. "1" = enabled, "0" = silent (recommended for gateway-driven orders so end users aren't surprised by CA emails). Default: "0". - * **SubscriptionValidityYears** - OPTIONAL: Default validity in years for SSL orders. "1", "2", or "3". Override per template via the ValidityYears product parameter. Default: "1". + * **RequestorDesignation** - OPTIONAL: Job title / role of the requestor (e.g. 'IT Administrator'). Sent as requestorInformation.requestorDesignation (V1) and requestor.designation (V2). Free text. Omitted when blank. + * **SignerPlace** - City or location of the subscriber agreement signer (e.g. 'San Francisco, CA'). REQUIRED when UseV2Api is on: the V2 Subscriber Agreement sent with every SSL order requires it, so the connector cannot be saved with it blank. A per-template SignerPlace enrollment parameter overrides it. On V1, if neither is set, the placeholder "Gateway" is sent and a Warning is logged; set it so the agreement audit record is accurate. + * **SignerIp** - V1 ONLY: IP address of the subscriber agreement signer. A template-level SignerIp enrollment parameter overrides it. If neither is set, the placeholder 127.0.0.1 is sent and a Warning is logged, and a value that is not an IP address is still sent unchanged, with a Warning. Ignored on V2: the V2 agreement block has no signer IP field, so it is never sent. + * **DefaultProductCode** - OPTIONAL: Default numeric product code. V1 only: used for renewals when the template supplies none. Not used on V2, where the product is resolved by CERTInext (set the template's ProductCode to override). Get codes via GetProductDetails. + * **AccountingModel** - OPTIONAL: CERTInext billing model sent in `orderDetails.accountingModel` on V1 orders. "2" = credit-based (most accounts, default). "1" = cash model. Not used by V2. + * **EmailNotifications** - OPTIONAL: Lifecycle emails to the requestor. "1" = full set (V2: "all"), "0" = silent (V1: "0"; V2: "consent-only", the quietest value the V2 API accepts). Blank: silent on V1, omitted on V2 (CA default applies). Other values fail V2 enrollment. Default: "0". + * **SubscriptionValidityYears** - OPTIONAL: Default validity in years for SSL orders. "1", "2", or "3". Used when the template sets no ValidityYears (and, on V1, no ValidityDays); a template term (on V1 the larger of ValidityYears and ValidityDays in years) overrides it. Default: "1". * **SubscriptionAutoRenew** - OPTIONAL: Whether CERTInext should auto-renew certificates issued through this connector. "0" = disabled (recommended — renewal is driven by Keyfactor Command), "1" = enabled. Default: "0". * **SubscriptionRenewCriteriaDays** - OPTIONAL: Days before expiry at which CERTInext auto-renews (only honored when SubscriptionAutoRenew = "1"). Typical values: "30" or "60". Default: "30". - * **AutoSecureWww** - OPTIONAL: If "1", CERTInext automatically adds the `www.` variant of the primary domain as an additional SAN. "0" = use only the CN/SANs supplied with the CSR. Default: "0". - * **IgnoreExpired** - If true, expired certificates will be skipped during synchronization. Default: false. - * **PageSize** - Number of orders to fetch per page during synchronization. Default: 100, max: 500. + * **AutoSecureWww** - OPTIONAL: Sent as `orderDetails.autoSecureWWW` on every V1 SSL order (new and renewal) and as `autoSecureWww` on V2 SSL orders. If "1", CERTInext automatically adds the `www.` variant of the primary domain as an additional SAN, which must also pass domain validation. "0" = use only the CN/SANs supplied with the CSR. Default: "0". + * **IgnoreExpired** - If true, expired certificates are skipped during synchronization. V2 only: the V1 sync does not currently apply it. Default: false. + * **SubmitNonDnsSans** - OPTIONAL (V1 only): If true (default), non-DNS SANs (IP, email, URI) are submitted, but CERTInext cannot validate them, so the order won't issue. If false, only DNS names are submitted. + * **PageSize** - Number of orders to fetch per page during synchronization (1 or higher). Default: 100, max: 500 (V2 `/reports/orders` pages are capped at 100). * **Enabled** - Enables or disables the CA connector. Set to false to create the connector record before credentials are available. Default: true. - * **DcvEnabled** - OPTIONAL: When true, the gateway will perform DNS-based Domain Control Validation (DCV) during enrollment for orders that require it, using the configured DNS provider plugin. Requires a DNS provider plugin (e.g. azure-azuredns-dnsplugin) to be deployed on the gateway. Default: false. + * **LogSensitiveRequestData** - OPTIONAL temporary diagnostic switch. When true, requestor personal data (name, email, phone) and full CA payloads are logged. Credentials are always redacted. Turn off after verifying. Default: false. + * **PickupRetries** - OPTIONAL: Times Enroll() polls CERTInext for the certificate after order submission (0-30; 0 disables the wait). Unissued orders are picked up by sync. Default: 5. + * **PickupDelay** - OPTIONAL: Seconds between certificate-pickup polls (1-60). Total wait is 5 s + PickupRetries x this value. Command's own enrollment call into the gateway is bounded at roughly 100 s, so the plugin caps the total at 75 s regardless of how PickupRetries/PickupDelay are set, reducing the retry count to fit. Keep your configured total well under that ceiling. Default: 10 (~55 s with default retries). + * **DcvEnabled** - OPTIONAL: When true, the plugin performs DNS-based Domain Control Validation (DCV) during enrollment and synchronization for orders that require it, using the DNS provider plugin deployed on the gateway (e.g. azure-azuredns-dnsplugin). Without a DNS provider plugin, orders that need validation stay pending and the plugin logs why. Set to false to skip DCV. Default: true. * **DcvTxtRecordTemplate** - OPTIONAL: Format string for the DNS TXT record hostname used during DCV. {0} is replaced with the domain name being validated. Default: _emsign-validation.{0} * **DcvPropagationDelaySeconds** - OPTIONAL: Seconds to wait after publishing the DNS TXT record before asking CERTInext to verify it. Increase for zones with slow propagation. Default: 30. - * **DcvTimeoutMinutes** - OPTIONAL: Maximum minutes to wait for the entire DCV flow (DNS publish + propagation + verify) before timing out the enrollment. Can also be set via the CERTINEXT_DCV_TIMEOUT_MINUTES environment variable; the env var takes precedence when both are set. Default: 10. - * **DcvWaitForChallengeSeconds** - OPTIONAL: How long (seconds) the plugin will wait inside Enroll() for CERTInext to expose the DCV challenge (i.e. populate `domainVerification` in TrackOrder). Under concurrent load CERTInext sometimes takes a few seconds after GenerateOrderSSL before the slot appears. Without this wait, the plugin's initial TrackOrder check sees null and skips DCV — the order then has to wait for the next gateway sync cycle to be picked up. Setting to 0 disables the wait (single-check behaviour). Can also be set via the CERTINEXT_DCV_WAIT_FOR_CHALLENGE_SECONDS environment variable; the env var takes precedence when both are set. Default: 60. - * **DcvWaitForIssuanceSeconds** - OPTIONAL: How long (seconds) the plugin will wait inside Enroll() after DCV verifies for CERTInext to finish generating the certificate. CERTInext issuance is async — DCV may be verified but the cert PEM isn't yet available for download. Without this wait, Enroll() returns a pending result and the issued cert is picked up by the next sync cycle. Setting to 0 disables the wait (single-fetch behaviour). Can also be set via the CERTINEXT_DCV_WAIT_FOR_ISSUANCE_SECONDS environment variable; the env var takes precedence when both are set. Default: 60. - * **DcvSyncMaxOrderAgeHours** - OPTIONAL: During synchronization, only pending DV orders younger than this many hours are eligible to be driven through DCV. This keeps a sync pass fast when there is a large backlog of old, never-completing pending orders (e.g. abandoned orders or domains outside the configured DNS provider's zone): they age out and are simply reported as pending rather than retried every pass. Recently-placed orders (the ones that legitimately deferred DCV) are always within the window and complete via the normal scan cadence. Set to 0 to disable the age filter (attempt DCV for all pending). Default: 24. - * **DcvSyncMaxPerPass** - OPTIONAL: Maximum number of pending DV orders the plugin will attempt to drive through DCV in a single synchronization pass. Bounds the per-pass cost regardless of backlog size; remaining pending orders are reported as-is and picked up on a later pass (the per-minute incremental scan keeps recent orders moving). Set to 0 to disable the cap. Default: 50. + * **DcvTimeoutMinutes** - OPTIONAL: Maximum minutes for the entire DCV flow (DNS publish + propagation + verify) for one order before it is abandoned and left pending. Can also be set via the CERTINEXT_DCV_TIMEOUT_MINUTES environment variable; the env var takes precedence when both are set. Default: 10. + * **DcvWaitForChallengeSeconds** - OPTIONAL (V1 only): Seconds Enroll() waits for CERTInext to expose the DCV challenge. 0 disables the wait. CERTINEXT_DCV_WAIT_FOR_CHALLENGE_SECONDS overrides it. Default: 60. + * **DcvWaitForIssuanceSeconds** - OPTIONAL (V1 only): Seconds Enroll() waits for issuance after DCV verifies. 0 disables the wait. CERTINEXT_DCV_WAIT_FOR_ISSUANCE_SECONDS overrides it. Default: 60. + * **DcvSyncMaxOrderAgeHours** - OPTIONAL: During synchronization, only pending DV orders younger than this many hours are driven through DCV. 0 disables the filter. Default: 24. + * **DcvSyncMaxPerPass** - OPTIONAL: Maximum pending DV orders driven through DCV per synchronization pass. 0 disables the cap. Default: 50. + * **UseV2Api** - OPTIONAL: When true, the plugin routes Ping / Enroll / GetSingleRecord / Revoke / Synchronize through the CERTInext V2 REST API (/api/certinext/v2/), including V2 /reports/orders for Synchronize. Requires ApiUrl (the V2 base URL in this mode), OAuthClientId, OAuthClientSecret, and SignerPlace. V1 credentials (ApiKey/AccountNumber/AuthMode) are not required when this is true. Default: false (V1 API). + * **V2SyncLookbackHours** - OPTIONAL (V2 only): Hours subtracted from the last-sync time on incremental sync, so an order created earlier but issued later is not missed. Default: 72. + * **SyncRecentOrderGraceSeconds** - OPTIONAL: during a Synchronize (full or incremental, in both V1 and V2 modes), a pending or issued order created less than this many seconds ago (plus a small clock margin) is not emitted to the gateway (an issued one is not downloaded); the next incremental pass imports it. This stops the sync from inserting a gateway row for an order whose enrollment is still in flight, which would make the enrollment's own save fail with a duplicate key. Revoked and failed orders are never held back. 0 disables the hold; a negative value uses the default. Default: 120. + * **V2InlineCsr** - OPTIONAL (V2 mode only): when true (the default), SSL/TLS enrollment sends the CSR inline in the order create call (a single POST /ssl-certificates), as a direct API integration does. When false, the plugin creates the order and then submits the CSR (PUT .../csr); that two-call flow fails for a domain the account has already validated, because CERTInext approves the order at create and then rejects the CSR. A create that times out or returns a 5xx can leave an order that still issues; it is not cancelled and the next synchronization imports it, so do not resubmit. Private PKI orders ignore this setting and always use the two-call flow (the CA rejects an inline CSR on Private PKI create). Ignored when UseV2Api is false. Default: true (single call). + * **SslComSubmitOrganization** - OPTIONAL (V2 mode only): before an OV or EV SSL/TLS order, the plugin checks whether SSL.com has validated the organization (OrganizationNumber) at that level, refreshing the status once if not. When this is true and the organization is still unvalidated and ready to submit, the plugin also SUBMITS it to SSL.com for validation. WARNING: enabling this ACCEPTS SSL.COM'S SUBSCRIBER AGREEMENT ON THE ORGANIZATION'S BEHALF; each acceptance is audit-logged. Leave false unless you are authorized to do that. Whatever the outcome, the order is placed anyway and a not-validated organization only logs a warning. Default: false. + * **SslComAdminEmail** - OPTIONAL (V2 mode only): administrator email sent as adminEmail when the plugin submits an organization to SSL.com (only used when SslComSubmitOrganization is true). Blank omits it and SSL.com uses the organization's own contact. 2. A Keyfactor Command certificate template maps an enrollment request to a specific CERTInext product. Create one template per CERTInext product that you want to make available to requesters. +The AnyCA Gateway REST portal also needs one certificate profile per product before Command templates can be created against it. Create the profiles by hand in the gateway portal, or with the helper script this repository ships (`make register-profiles`; set `DRY_RUN=1` to preview). By default the script also registers a ` V2` profile per product, for a second set of templates that carry no `ProductCode` (see [V2 Product Code Resolution](#v2-product-code-resolution)); set `V2_TEMPLATES=0` to skip them. See [scripts/register/README.md](https://github.com/Keyfactor/certinext-caplugin/blob/main/scripts/register/README.md) for authentication and options. + In the Keyfactor Command Management Portal, navigate to **Certificate Templates** and create a new template associated with the CERTInext CA connector. The following enrollment parameters are available: | Parameter | Required / Optional | Type | Description | Example / Default | |---|---|---|---|---| -| `ProductCode` | Optional | String | Override the numeric CERTInext product code for this template. Product codes are provisioned per account by eMudhra — obtain the correct code from `GetProductDetails` for your account. Set this explicitly when targeting the sandbox environment or when the connector `DefaultProductCode` should not apply to this template. See the [Product Codes](#product-codes) section for the sandbox/production lookup table. | DV SSL: `842` (sandbox) or `838` (production) | +| `ProductCode` | Optional | String | Overrides the numeric CERTInext product code. Get the right code from `GetProductDetails` for your account. On V2 it is an override sent as `X-Product-Code`; leave it blank and CERTInext resolves the product. | DV SSL: `842` (sandbox) or `838` (production) | | `ProfileId` | Deprecated | String | Legacy alias for `ProductCode`. Accepted for backward compatibility — if `ProductCode` is not set, `ProfileId` is used in its place. New templates should use `ProductCode`. | `838` | -| `ValidityYears` | Optional | Number | Subscription validity period in years: `1`, `2`, or `3`. Default: `1`. CERTInext certificates are issued within a subscription term at up to 390 days per certificate, with free renewals within the term. | `1` | -| `ValidityDays` | Deprecated | Number | Legacy validity field. If set, the value is divided by 365 and rounded up to derive a year count. New templates should use `ValidityYears`. | `365` | -| `AutoApprove` | Optional | Boolean | If `true`, the gateway will attempt automatic approval of certificates returned in a pending-approval state. Only set this if your CERTInext product is configured with automatic approval. Default: `false`. | `false` | -| `RequesterName` | Optional | String | Per-template override for the requestor name. When set, overrides the connector-level `RequestorName` for orders using this template. | `Keyfactor Automation` | -| `RequesterEmail` | Optional | String | Per-template override for the requestor email address. When set, overrides the connector-level `RequestorEmail` for orders using this template. | `pki-admin@example.com` | -| `RenewalWindowDays` | Optional | Number | Number of days before certificate expiration within which a renewal is attempted instead of a reissue. Default: `90`. | `90` | -| `KeyType` | Optional | String | Key algorithm to request at enrollment time. The key type is carried by the submitted CSR. CERTInext accepts **RSA 2048 / 3072 / 4096 and ECC P-256 / P-384** only — larger RSA, ECC P-521, and the Ed25519/Ed448 curves are rejected by the CA (`Invalid key size`). If omitted, the product default is used. | `RSA2048`, `RSA3072`, `RSA4096`, `EC256`, `EC384` | -| `DomainName` | Optional | String | Primary domain name for SSL/TLS orders. If omitted, the gateway derives the domain from the CSR `CN` field. | `example.com` | -| `SignerName` | Optional | String | Per-template override for the subscriber agreement signer name. When omitted, defaults to the connector-level `RequestorName`. | `Jane Smith` | -| `SignerPlace` | Optional | String | Per-template override for the subscriber agreement signer location. When omitted, defaults to the connector-level `SignerPlace`. | `Austin` | -| `SignerIp` | Optional | String | Per-template override for the subscriber agreement signer IP address. When omitted, defaults to the connector-level `SignerIp`. | `203.0.113.10` | +| `ValidityYears` | Optional | Number | Subscription term in years: `1`, `2`, or `3`. Default: `1`. CERTInext certificates are issued within a subscription term at up to 390 days per certificate, with free renewals within the term. | `1` | +| `ValidityDays` | Optional | Number | V1 only; ignored on V2. Requested validity in days, converted to whole subscription years and rounded up (365 days = 1 year), because the order API takes years. Default: `365`. See the note below the table. | `365` | +| `AutoApprove` | Optional | Boolean | **Currently has no effect** — reserved for future use. The plugin does not call any approval endpoint against CERTInext regardless of this setting. | `false` | +| `RequesterName` | Optional | String | Overrides the connector `RequestorName` for this template when non-blank. Never derived from the certificate subject. | `Keyfactor Automation` | +| `RequesterEmail` | Optional | String | Overrides the connector `RequestorEmail` for this template when non-blank. Never derived from the certificate subject. | `pki-admin@example.com` | +| `RenewalWindowDays` | Optional | Number | V1 only. Number of days before certificate expiration within which a renewal is attempted instead of a reissue. V2 places a new order for every renewal and reissue. Default: `90`. | `90` | +| `KeyType` | Optional | String | Informational. The CSR decides the key algorithm. CERTInext accepts only RSA 2048/3072/4096 and ECC P-256/P-384. | `RSA2048`, `RSA3072`, `RSA4096`, `EC256`, `EC384` | +| `DomainName` | Optional | String | V2 only: primary domain name for SSL/TLS orders (for Private PKI, the primary hostname). If omitted, the plugin uses the CSR subject `CN`. V1 always uses the CSR subject `CN`. | `example.com` | +| `SignerName` | Optional | String | Per-template override for the subscriber agreement signer name. When omitted, defaults to the connector-level `RequestorName` (V2: the requestor name). If no name resolves, V1 sends `Keyfactor Gateway` and logs a warning. | `Jane Smith` | +| `SignerPlace` | Optional | String | Per-template override for the subscriber agreement signer location. When omitted, defaults to the connector-level `SignerPlace`. If neither is set, V1 sends `Gateway` and logs a warning. | `Austin` | +| `SignerIp` | Optional (V1 only) | String | Per-template override for the subscriber agreement signer IP address. Ignored on V2. When omitted, defaults to the connector-level `SignerIp`. If neither is set, V1 sends `127.0.0.1` and logs a warning; a V1 value that is not an IP address is sent unchanged, with a warning. | `203.0.113.10` | + +- **Subscription term (V1):** the order's term is the larger of `ValidityYears` and `ValidityDays` rounded up to whole years (365 days = 1 year). Each field counts only when it is set, and a field left at its default (1 year) never overrides the other, so a template saved with only `ValidityDays` keeps its term. Because the larger value wins, a stale larger `ValidityDays` cannot be shortened with `ValidityYears` alone; set `ValidityDays` back to `365`. V2 uses only `ValidityYears`. +- **Key types:** larger RSA, ECC P-521, and the Ed25519/Ed448 curves are rejected by the CA (`Invalid key size`). + +When `ProductCode` is omitted: + +- **V1:** the plugin uses the built-in default code for the selected product name (see [Product Codes](#product-codes)). +- **V2:** no code is sent and CERTInext resolves the product itself (see [V2 Product Code Resolution](#v2-product-code-resolution)). Set `ProductCode` to override that choice. +- **Sandbox or non-standard codes (V1):** set `ProductCode` explicitly. + +The V2-only template parameters `ProductFamily` and `ProductVariant` are described under [V2 Certificate Template Fields](#v2-certificate-template-fields). 3. Follow the [official Keyfactor documentation](https://software.keyfactor.com/Guides/AnyCAGatewayREST/Content/AnyCAGatewayREST/AddCA-Keyfactor.htm) to add each defined Certificate Authority to Keyfactor Command and import the newly defined Certificate Templates. 4. In Keyfactor Command (v12.3+), for each imported Certificate Template, follow the [official documentation](https://software.keyfactor.com/Core-OnPrem/Current/Content/ReferenceGuide/Configuring%20Template%20Options.htm) to define enrollment fields for each of the following parameters: - * **ProductCode** - OPTIONAL: Override the numeric CERTInext product code for this template. When omitted, the default production code for the selected product is used automatically (e.g. DV SSL → 838). Set this explicitly when targeting sandbox or a non-standard code. + * **ProductCode** - OPTIONAL: Override the numeric CERTInext product code for this template. When omitted: on V1, the default production code for the selected product is used (e.g. DV SSL → 838); on V2, no X-Product-Code header is sent and CERTInext resolves the product from the variant, the wildcard shape of the domain and any additional domains. On V2 an explicit value is an override, sent as X-Product-Code to choose between several matching catalog products (for example different CA profiles for the same variant). * **ProfileId** - DEPRECATED: Use ProductCode instead. Kept for backward compatibility — mapped to ProductCode if ProductCode is not set. - * **ValidityYears** - OPTIONAL: Subscription validity in years: 1, 2, or 3. Default: 1. Note: CERTInext validates per 390-day certificate within the subscription; the 'validity' field in the order is the subscription term, not certificate lifetime. - * **ValidityDays** - DEPRECATED: Use ValidityYears instead. If set, value is divided by 365 and rounded up to get the subscription year count. - * **AutoApprove** - OPTIONAL: If true, the gateway will attempt automatic approval of certificates that are returned in a pending-approval state. Default: false. - * **RequesterName** - OPTIONAL: Default requester name to include in the enrollment request. Used when no requester name can be derived from the subject. - * **RequesterEmail** - OPTIONAL: Default requester email address. Used when no email can be derived from the subject. - * **RenewalWindowDays** - OPTIONAL: Number of days before certificate expiration within which a renewal is triggered. Certificates expiring further than this window are reissued instead. Certificates that have already expired also fall back to reissue. Default: 90. - * **KeyType** - OPTIONAL: Key algorithm to request (e.g. 'RSA2048', 'RSA4096', 'EC256', 'EC384'). If omitted, the profile default is used. - * **DomainName** - OPTIONAL: Primary domain for SSL/TLS orders. Derived from the CSR CN if omitted. - * **SignerName** - OPTIONAL: Per-template subscriber agreement signer name. Falls back to the connector-level RequestorName if omitted. - * **SignerPlace** - OPTIONAL: Per-template signer city/location. Falls back to the connector-level SignerPlace if omitted. - * **SignerIp** - OPTIONAL: Per-template signer IP address. Falls back to the connector-level SignerIp if omitted. + * **ValidityYears** - OPTIONAL: Subscription term in years: 1, 2, or 3. On V1 the order's term is the larger of ValidityYears and ValidityDays rounded up to whole years (365 days = 1 year); a field left at its default (1 year) never overrides the other. On V2 only ValidityYears is used. A template value overrides the connector's SubscriptionValidityYears. Because the larger value wins on V1, a stale larger ValidityDays cannot be shortened with ValidityYears alone; set ValidityDays back to 365. Default: 1. Note: CERTInext validates per 390-day certificate within the subscription; the 'validity' field in the order is the subscription term, not certificate lifetime. + * **ValidityDays** - OPTIONAL: V1 only (ignored on V2, which uses ValidityYears). Requested validity in days. CERTInext's order API takes whole subscription years, so days are converted to years, rounded up (365 days = 1 year). The order's term is the larger of this and ValidityYears; a field left at its default (365 days = 1 year) never overrides the other. Kept because certificate lifetimes are shrinking and days is the unit that will matter if CERTInext adds a lifetime field. To shorten a template with a larger value, set this back to 365. Default: 365. + * **AutoApprove** - Currently has no effect — reserved for future use. The plugin does not call any approval endpoint against CERTInext regardless of this setting. Default: false. + * **RequesterName** - OPTIONAL: Overrides the connector RequestorName for this template when non-blank. Never derived from the certificate subject. + * **RequesterEmail** - OPTIONAL: Overrides the connector RequestorEmail for this template when non-blank. Never derived from the certificate subject. + * **RenewalWindowDays** - OPTIONAL: V1 only. Number of days before certificate expiration within which a renewal is triggered. Certificates expiring further than this window are reissued instead. Certificates that have already expired also fall back to reissue. V2 places a new order for every renewal and reissue. Default: 90. + * **KeyType** - OPTIONAL: Informational. The key algorithm is determined by the submitted CSR; CERTInext accepts RSA 2048/3072/4096 and ECC P-256/P-384 and rejects larger RSA, ECC P-521, and Ed25519/Ed448. + * **DomainName** - OPTIONAL: Primary domain for SSL/TLS orders (for V2 private-pki orders, the primary hostname). Derived from the CSR CN if omitted. + * **SignerName** - OPTIONAL: Per-template subscriber agreement signer name. Falls back to the connector-level RequestorName if omitted (V2: the requestor name). If no name resolves, V1 sends the placeholder "Keyfactor Gateway" and logs a Warning. + * **SignerPlace** - OPTIONAL: Per-template signer city/location. Falls back to the connector-level SignerPlace if omitted. If neither is set, V1 sends the placeholder "Gateway" and logs a Warning. + * **SignerIp** - V1 ONLY, OPTIONAL: Per-template signer IP address. Falls back to the connector-level SignerIp if omitted. If neither is set, V1 sends the placeholder 127.0.0.1 and logs a Warning; a V1 value that is not an IP address is sent unchanged, with a Warning. Ignored on V2 (the V2 agreement block has no signer IP field). + * **ProductFamily** - V2 ONLY: Product family for this template. Accepted values: 'ssl' (default) or 'private-pki'. 'private-pki' requires a Private PKI ProductVariant. 'signature' (Document Signer) is accepted by the parameter, but Document Signer enrollment is not supported. + * **ProductVariant** - V2 ONLY: Product variant sent in the V2 order body. ProductFamily 'ssl': 'dv', 'ov', or 'ev' — if omitted, derived from the selected product; an explicit value that contradicts the product fails enrollment. ProductFamily 'private-pki': 'intranet-ssl' or 'igtf-host' (required; no default). ## CERTInext API Setup -### AccessKey (HMAC) — the primary auth mode +The credentials you create in the CERTInext portal depend on the API generation the connector uses. + +| Mode | API | Where credentials go | Fields required | +|---|---|---|---| +| AccessKey | V1 (default) | `authKey` in the `meta` block of every request body. There is no `Authorization` header. | `AccountNumber`, `ApiKey` | +| OAuth2 client credentials | V2 (`UseV2Api` = `true`) | `Authorization: Bearer` header. The token comes from `{ApiUrl}/oauth/token`. | `OAuthClientId`, `OAuthClientSecret`, `SignerPlace` | + +> Note: V1 OAuth is not supported. The live V1 API ignores a bearer token and answers HTTP 401 (`clientAccessKey is not active`) whether or not one is sent. The `AuthMode` and `OAuthTokenUrl` fields remain only so connectors saved with them keep loading. Leave `AuthMode` as `AccessKey`. -The CERTInext REST API uses HMAC-style request signing. Every API call includes a computed `authKey` field in the request body. The access key itself is never transmitted — only the derived hash is sent. +### AccessKey (SHA-256 signed requests) — V1 -The `authKey` is computed as: +The V1 API signs every request. Each call includes a computed `authKey` field in the `meta` block of the request body. The access key itself is never transmitted — only the derived hash is sent. + +The `authKey` is a plain SHA-256 digest (not an HMAC), computed as: ``` -authKey = SHA256(accessKey + requestTs + requestTxnId) +authKey = SHA256(accessKey + ts + txn) ``` -Where `requestTs` is the ISO 8601 timestamp of the request and `requestTxnId` is the unique transaction ID generated per request. The gateway performs this computation automatically on every outbound API call. +Where `ts` is the ISO 8601 timestamp of the request and `txn` is the unique transaction ID generated per request; both are sent in the same `meta` block. The gateway performs this computation automatically on every outbound API call. **Steps to generate an Access Key:** @@ -221,59 +300,190 @@ Where `requestTs` is the ISO 8601 timestamp of the request and `requestTxnId` is Enter the copied value in the `ApiKey` field of the CA connector configuration. The field is masked in the Keyfactor Command UI and stored in Command's encrypted gateway configuration. -### OAuth — alternative auth mode - -If your CERTInext account has OAuth enabled, you can use OAuth client credentials as an alternative to AccessKey signing. +### OAuth2 client credentials — V2 -1. Log in to the CERTInext portal. -2. Navigate to **Integrations → APIs**. -3. Click **+ Create API Credentials**. -4. Set **API Type** to `REST` and **Auth Type** to `OAuth`. -5. Complete the form and click **Generate**. -6. Note the **Client ID** and **Client Secret**. Enter them in the `OAuthClientId` and `OAuthClientSecret` fields respectively. -7. Confirm the OAuth token endpoint URL with eMudhra and enter it in the `OAuthTokenUrl` field. -8. Set the `AuthMode` connector field to `OAuth`. +The V2 API authenticates with an OAuth2 `client_credentials` bearer token. Create the credential with **Auth Type** `OAuth` and enter the client ID and secret in `OAuthClientId` and `OAuthClientSecret`. See [V2 OAuth2 Setup](#v2-oauth2-setup) for the steps. > Note: Credentials are stored in Keyfactor Command's encrypted gateway configuration and are never written to disk by the plugin. ## CA Configuration -The following fields are presented in the Keyfactor Command Management Portal when creating or editing the CERTInext CA connector. All fields marked **Required** must be provided before the connector can be saved in an enabled state. +The following fields are presented in the Keyfactor Command Management Portal when creating or editing the CERTInext CA connector. The **Applies to** column shows which API generation uses the field: **V1**, **V2**, or **Both**. + +### Save-Time Validation -| Field | Required / Optional | Description | Where to find it | Example | +When the connector is saved (and `Enabled` is `true`), the plugin checks only the fields below. Every other field marked **Required** in the tables is needed by CERTInext for a successful order, but the connector saves without it — enrollment then fails, or the order is parked pending, until it is set. + +| Mode | Fields checked at save | +|---|---| +| All | `ApiUrl` must be present and use `https` (`http` is allowed only for a loopback host: `localhost`, `127.0.0.1`, `::1`). | +| V1 AccessKey | `AccountNumber`, `ApiKey` | +| V2 | `OAuthClientId`, `OAuthClientSecret`, `SignerPlace` | + +### Connection + +| Field | Applies to | Required | Description | +|---|---|---|---| +| `ApiUrl` | Both | Required | CERTInext API base URL. The shape depends on `UseV2Api`; see [ApiUrl by mode](#apiurl-by-mode). | +| `UseV2Api` | Both | Optional | Route all operations through the V2 REST API. Requires `OAuthClientId`, `OAuthClientSecret`, and `SignerPlace`. Default: `false`. | +| `AccountNumber` | V1 | Required | CERTInext account number (numeric string), sent in the `meta` block of every request. Example: `1234567890`. | +| `ApiKey` | V1 | Required | Access Key from **Integrations → APIs**. Masked in the UI. | +| `AuthMode` | V1 | Optional | Legacy. Default: `AccessKey`. Leave as is; V1 does not honor OAuth. Ignored on V2. | +| `OAuthClientId` | V2 | Required | OAuth client ID. The key must be generated in OAuth mode. | +| `OAuthClientSecret` | V2 | Required | OAuth client secret. Masked in the UI. | +| `OAuthTokenUrl` | V1 (legacy) | Optional | Legacy / unsupported: V1 does not honor OAuth tokens. Ignored on V2, which derives `{ApiUrl}/oauth/token`. | +| `Enabled` | Both | Optional | Set to `false` to create the connector record before credentials exist; skips validation and the live connectivity test. Default: `true`. | + +#### ApiUrl by Mode + +| Mode | Value | Examples | +|---|---|---| +| V1 (default) | Host plus the `/emSignHub-API/` path | Sandbox: `https://sandbox-us-api.certinext.io/emSignHub-API/`
Production US: `https://us-api.certinext.io/emSignHub-API/`
Production India: `https://api.certinext.io/emSignHub-API/` | +| V2 (`UseV2Api` = `true`) | Bare host, no path suffix | `https://sandbox-us-api.certinext.io` | + +- The two APIs are hosted differently, so change `ApiUrl` whenever you toggle `UseV2Api`. +- A trailing slash is accepted in either mode. +- The URL must use `https`: the API key (V1) or OAuth client secret (V2) is sent to it on every request. `http` is rejected except for a loopback host, for local test servers only. + +### Requestor and Signer + +| Field | Applies to | Required | Description | +|---|---|---|---| +| `RequestorName` | Both | Required | Default name of the person or service submitting orders. Example: `PKI Automation`. | +| `RequestorEmail` | Both | Required | Default requestor email. Use a monitored inbox registered in your CERTInext account. | +| `RequestorIsdCode` | Both | Optional | Dialing code for the requestor phone, digits only, no `+`. Default: `1`. | +| `RequestorMobileNumber` | Both | Optional | Requestor mobile number, digits only, no country code. | +| `RequestorDesignation` | Both | Optional | Job title of the requestor. Sent as `requestorInformation.requestorDesignation` (V1) and `requestor.designation` (V2). Omitted when blank. | +| `TechnicalContactName`
`TechnicalContactEmail`
`TechnicalContactIsdCode`
`TechnicalContactMobileNumber` | Both | Optional | Technical point of contact on every SSL order. Each defaults to the matching `Requestor*` field. On V1 the name is sent as `pocFirstName` and `pocLastName`, split on the first whitespace (a single word goes in both). If no name or no email resolves, V1 omits the whole block and logs a warning, because CERTInext requires both inside it. | +| `SignerPlace` | Both | Required | City of the person accepting the subscriber agreement. Required at save on V2; a template `SignerPlace` overrides it on both. On V1, if neither is set, the plugin sends `Gateway` and logs a warning. Example: `Austin`. | +| `SignerIp` | V1 | Required on V1 | Public IP of the host accepting the subscriber agreement. Not sent on V2, whose agreement block has no IP field. See the bullets below. Example: `203.0.113.10`. | + +- **`SignerIp` blank:** on V1, when neither a template `SignerIp` nor this field is set, the plugin sends `127.0.0.1` and logs a warning, which misstates the audit record CERTInext keeps. Set it to the gateway host's outbound IP. A V1 value that is not an IP address is still sent unchanged, with a warning. On V2 the setting is ignored: the V2 agreement block has no signer IP field (the CA records the signer's IP itself), so it is never sent and never warned about. +- **Signer values per order:** the agreement signer is the template `SignerName`, `SignerPlace`, and `SignerIp` parameters first, then the connector's `RequestorName`, `SignerPlace`, and `SignerIp`, then the placeholders `Keyfactor Gateway`, `Gateway`, and `127.0.0.1` (each placeholder logs a warning on V1). `SignerIp` is V1 only. Blank values fall through. This applies to new orders and renewals on both V1 and Vt. +- **Where to find values:** the account number is under your name or avatar → **Account Settings** or **My Profile**. Use a monitored team inbox for `RequestorEmail`. + +### Order Defaults + +| Field | Applies to | Required | Description | +|---|---|---|---| +| `GroupNumber` | Both | Optional | CERTInext group (delegation) number, from **Delegation → Groups**. Routes orders to the right group. See the bullets below. | +| `OrganizationNumber` | Both | Optional | Pre-vetted organization number, from **Organizations → Pre-vetted Organizations**. Required for OV/EV on V2: enrollment fails before any CA call if blank. | +| `DefaultProductCode` | Both | Optional | Numeric product code fallback. See [DefaultProductCode](#defaultproductcode). | +| `AccountingModel` | V1 | Optional | Billing model: `2` = credit-based (most accounts), `1` = cash. Default: `2`. | +| `EmailNotifications` | Both | Optional | Lifecycle emails to the requestor. See [EmailNotifications values](#emailnotifications-values). Default: `0`. | +| `SubscriptionValidityYears` | Both | Optional | Default validity in years: `1`, `2`, or `3`. Used when the template sets no `ValidityYears` (and, on V1, no `ValidityDays`); a template term overrides it. Default: `1`. | +| `SubscriptionAutoRenew` | Both | Optional | `0` = CERTInext does not auto-renew (recommended; Command drives renewal), `1` = enabled. Default: `0`. | +| `SubscriptionRenewCriteriaDays` | Both | Optional | Days before expiry at which CERTInext auto-renews. Honored only when `SubscriptionAutoRenew` is `1`. Default: `30`. | +| `AutoSecureWww` | Both | Optional | `1` adds the `www.` variant of the primary domain as an extra SAN, which must also pass domain validation. Sent as `orderDetails.autoSecureWWW` on every V1 SSL order (new and renewal). Default: `0`. | +| `SubmitNonDnsSans` | V1 | Optional | `true` submits non-DNS SANs (IP, email, URI) to CERTInext, which cannot validate them, so the order will not issue until they are removed. `false` submits DNS names only. Default: `true`. | + +- **`GroupNumber`:** it is sent in `productDetails.groupNumber` on `GetProductDetails` and in `orderDetails.groupNumber` on every V1 SSL order (new and renewal). When blank, CERTInext uses the account's default group. On V2 it is sent as `groupNumber` on order create and as a query parameter on the catalog and orders-report calls. Some sandbox accounts return an empty product list unless it is set. +- **`GroupNumber` is not `AccountNumber`:** `AccountNumber` is your top-level account identifier. Each CERTInext group (cost center or department) has its own `groupNumber`, which is separate from any organization number on the Organizations page. +- **`OrganizationNumber`:** when set, V1 orders carry `organizationDetails.preVetting="1"` and this number, so CERTInext skips its manual vetting queue. Without it, orders can sit in `Pending System RA` for tens of hours. V2 DV orders never send an organization block. +- **Non-DNS SANs on V2:** `SubmitNonDnsSans` is not consulted. See [Migrating from V1 to V2](#step-2--update-the-ca-connector). + +#### DefaultProductCode + +Calling `GetProductDetails` against your account lists the codes available to you (see [Product Codes](#product-codes)). + +| Mode | When it applies | +|---|---| +| V1 | Renewals only, and only when the template supplies no `ProductCode`/`ProfileId`. CERTInext's `TrackOrder` does not return the prior order's product code. No effect on new enrollments. | +| V2 | Not used. V2 orders send `X-Product-Code` only for an explicit template `ProductCode`; otherwise CERTInext resolves the product. | + +- If neither the template nor this field supplies a code on a V1 renewal, the renewal goes out with an empty product code. + +#### EmailNotifications Values + +| Value | V1 | V2 | +|---|---|---| +| `1` | Full notification set (sent as `1`) | Sent as `all` | +| `0` | Silent (sent as `0`) | Silent: sent as `consent-only`, the quietest value the V2 spec allows (its enum is `consent-only` or `all`) | +| Blank | Silent (sent as `0`) | Omitted, so the CA default (`all`, not silent) applies | +| Anything else | Sent unchanged, not validated | Enrollment fails before any CA call | + +### Synchronization and Pickup + +| Field | Applies to | Required | Description | +|---|---|---|---| +| `IgnoreExpired` | V2 | Optional | Skip expired certificates during sync. The V1 API does not currently apply it. Default: `false`. | +| `PageSize` | Both | Optional | Orders fetched per page during sync. Must be 1 or higher; reduce it if sync requests time out. Default: `100`. Maximum: `500` on V1, `100` on V2. | +| `V2SyncLookbackHours` | V2 | Optional | Extra hours subtracted from the last-sync time on incremental sync, so a slow order is not missed. Default: `72`. | +| `SyncRecentOrderGraceSeconds` | Both | Optional | A sync (full or incremental) skips pending or issued orders created less than this many seconds ago (plus a 5-second clock margin); the next incremental sync imports them. This keeps a sync that runs during an in-flight enrollment from causing that enrollment to fail with a duplicate key. `0` disables it. Default: `120`. | +| `PickupRetries` | Both | Optional | Times `Enroll` polls CERTInext for the certificate after a successful order. `0` disables the wait. Default: `5`. | +| `PickupDelay` | Both | Optional | Seconds between pickup polls. Default: `10`. | + +- **`IgnoreExpired` on V1:** the V1 sync maps no certificate expiry date, so the filter never matches and expired certificates are still imported. The V2 sync applies it. +- **`PageSize` limits:** values above the maximum are clamped. On V2, a value of 0 or less falls back to 100. On V1, a value below 1 is not corrected, so keep it at 1 or higher. +- **`PickupRetries` and `PickupDelay`:** OV/EV orders validate asynchronously (minutes to hours) and typically exhaust the wait regardless of these values. Pickup applies to V1 and V2. + +#### Pickup Limits + +| Setting | Minimum | Maximum | Default | Out-of-range behavior | |---|---|---|---|---| -| `ApiUrl` | Required | CERTInext API base URL for your environment. Must include the `/emSignHub-API/` path segment. No trailing slash is required but is accepted. | See the environments table above. | `https://api.certinext.io/emSignHub-API/` | -| `AccountNumber` | Required | Your CERTInext account number (numeric string). Included in the `meta` block of every API request. | Portal → click your name or avatar → **Account Settings** or **My Profile**. | `1234567890` | -| `AuthMode` | Required | Authentication mode. `AccessKey` uses HMAC signing (recommended). `OAuth` uses a bearer token. | N/A — choose based on the credential type you created. | `AccessKey` | -| `ApiKey` | Conditional | The REST API Access Key generated in the CERTInext portal. Used to compute `authKey = SHA256(accessKey + ts + txn)`. The raw key is never transmitted. Required when `AuthMode` is `AccessKey`. This field is masked in the UI. | Portal → **Integrations → APIs** → generate or view the credential row. | *(generated, masked in UI)* | -| `OAuthTokenUrl` | Conditional | OAuth token endpoint URL. Required when `AuthMode` is `OAuth`. | Provided by eMudhra for your account. | `https://auth.certinext.io/oauth/token` | -| `OAuthClientId` | Conditional | OAuth client ID. Required when `AuthMode` is `OAuth`. | Portal → **Integrations → APIs** → the OAuth credential row. | `keyfactor-gateway` | -| `OAuthClientSecret` | Conditional | OAuth client secret. Required when `AuthMode` is `OAuth`. This field is masked in the UI. | Generated at OAuth credential creation time. | *(generated, masked in UI)* | -| `RequestorName` | Required | Default name of the person or service submitting certificate orders. Sent in the `requestorInformation` block of every order request. | Use the name of the team or automation account responsible for these certificates. | `PKI Automation` | -| `RequestorEmail` | Required | Default email address for the requestor. Must be a valid email address associated with your CERTInext account. Sent in the `requestorInformation` block of every order request. | Use a monitored team inbox or the account holder's email. | `pki-admin@example.com` | -| `RequestorIsdCode` | Optional | International dialing code for the requestor phone number (digits only, no `+` prefix). Default: `1` (United States). | N/A — use the country code for your requestor. | `1` | -| `RequestorMobileNumber` | Optional | Requestor mobile number (digits only, no country code). Included in the `requestorInformation` block. | N/A | `5551234567` | -| `SignerPlace` | Required | City or location of the person accepting the subscriber agreement on behalf of your organization. Required by CERTInext for all orders. | Use the physical city where the signer is located. | `Austin` | -| `SignerIp` | Required | Public IP address of the host accepting the subscriber agreement. Required by CERTInext for all orders. | Use the outbound IP of the AnyCA Gateway host, or the IP of the workstation from which the agreement was accepted. | `203.0.113.10` | -| `GroupNumber` | Optional | CERTInext group (delegation) number. When set, it is passed in the `productDetails.groupNumber` field of `GetProductDetails` requests. Some sandbox accounts return an empty product list from `GetProductDetails` unless this field is included. Available in the CERTInext portal under **Delegation → Groups**. | Portal → **Delegation → Groups**. | `2345678901` | -| `DefaultProductCode` | Optional | Default numeric product code to use when no product code is set on the certificate template. If omitted and the template also has no product code, enrollment will fail. Product codes are provisioned per account by eMudhra — contact your eMudhra account representative to obtain the numeric codes available to your account. | Call `GetProductDetails` against your account/environment (see product code table below). | `842` | -| `IgnoreExpired` | Optional | If `true`, expired certificates are skipped during synchronization and are not imported into Keyfactor Command. Default: `false`. | N/A | `false` | -| `PageSize` | Optional | Number of orders to retrieve per page during synchronization. Default: `100`. Maximum: `500`. Reduce this value if synchronization requests time out. | N/A | `100` | -| `Enabled` | Optional | Enables or disables the CA connector. Setting this to `false` allows the connector record to be created before all credentials are available, without triggering a live connectivity test. Default: `true`. | N/A | `true` | -| `DcvEnabled` | Optional | When `true`, the gateway performs DNS-based Domain Control Validation (DCV) during enrollment for orders that require it. Requires a DNS provider plugin (e.g. `azure-azuredns-dnsplugin`) to be deployed on the gateway. Default: `false`. | N/A | `false` | -| `DcvTxtRecordTemplate` | Optional | Format string for the DNS TXT record hostname published during DCV. `{0}` is replaced with the domain being validated. Default: `_emsign-validation.{0}`. | N/A | `_emsign-validation.{0}` | -| `DcvPropagationDelaySeconds` | Optional | Seconds to wait after publishing the DNS TXT record before asking CERTInext to verify it. Increase for zones with slow propagation. Default: `30`. | N/A | `30` | -| `DcvTimeoutMinutes` | Optional | Maximum minutes to wait for the entire DCV flow (DNS publish + propagation + verify) before cancelling the enrollment. Can also be set via the `CERTINEXT_DCV_TIMEOUT_MINUTES` environment variable; the environment variable takes precedence when both are set. Default: `10`. | N/A | `10` | - -> Note: `AccountNumber` and group-level identifiers are distinct values. The `AccountNumber` is your top-level user account identifier. CERTInext groups (cost centers or departments) each have their own `groupNumber`, which is passed per-order and is separate from any organization number displayed on the Organizations page. - -> Note: Only the credential fields that correspond to the selected `AuthMode` are evaluated at runtime. Fields belonging to the other auth mode are ignored. +| `PickupRetries` | 0 (disabled) | 30 | 5 | Negative becomes 0; above 30 becomes 30 | +| `PickupDelay` (seconds) | 1 | 60 | 10 | Zero or negative becomes 10; above 60 becomes 60 | +| Total wait | — | 75 s | ~55 s | The retry count is reduced to fit the cap | + +> **Pickup timing detail:** after a successful order placement, the plugin waits a fixed 5-second initial delay before the first poll, then polls CERTInext every `PickupDelay` seconds up to `PickupRetries` times. Each poll calls `GetCertificate` to check whether the certificate has been issued. The total time budget is **5 s + (`PickupRetries` × `PickupDelay`) + about 1 s API round trip per poll**. With the defaults this is 5 + (5 × 10) = **~55 s plus round trips**. +> +> **Tuning for faster pickup:** if CERTInext typically issues certificates within a few seconds of order placement (as is typical for DV and auto-approved orders), lower `PickupDelay` and raise `PickupRetries` to compensate. This polls more often without changing the total budget. Command's own enrollment call into the gateway is bounded at about 100 s, and order submission and each poll's round trip also use that budget, so keep the total well under the 75 s ceiling. +> +> | Configuration | PickupRetries | PickupDelay | Total budget | Poll cadence | +> |---------------|:---:|:---:|---|---| +> | Default | `5` | `10` | ~55 s | Every 10 s | +> | Faster polling | `10` | `5` | ~55 s | Every 5 s | +> | Aggressive | `30` | `2` | ~65 s | Every 2 s | +> | Minimal wait | `0` | — | 0 s | No polling; defers to sync | +> +> The 5-second initial delay is not configurable, and the 75-second ceiling applies regardless of configuration. It sits inside Command's roughly 100-second enrollment-call timeout, which leaves headroom for order submission and per-poll round trips. When the DCV flow ran for the order inside the same `Enroll` call, the pickup poll is skipped, because the DCV flow already waited for issuance. + +### Domain Control Validation (DCV) + +DCV needs a DNS provider plugin (for example `azure-azuredns-dnsplugin`) deployed on the gateway. Without one, orders that need validation stay pending and the plugin logs why. + +| Field | Applies to | Required | Description | +|---|---|---|---| +| `DcvEnabled` | Both | Optional | Perform DNS-based DCV during enrollment and synchronization. Set to `false` to validate domains another way. Default: `true`. | +| `DcvTxtRecordTemplate` | Both | Optional | TXT record hostname format; `{0}` is the domain being validated. Default: `_emsign-validation.{0}`. | +| `DcvPropagationDelaySeconds` | Both | Optional | Seconds to wait after publishing the TXT record before asking CERTInext to verify. Default: `30`. | +| `DcvTimeoutMinutes` | Both | Optional | Maximum minutes for the whole DCV flow before the order is left pending. Default: `10`. | +| `DcvWaitForChallengeSeconds` | V1 | Optional | How long `Enroll()` waits for CERTInext to expose the DCV challenge. `0` disables the wait. Default: `60`. | +| `DcvWaitForIssuanceSeconds` | V1 | Optional | How long `Enroll()` waits for issuance after DCV verifies. `0` disables the wait. Default: `60`. | +| `DcvSyncMaxOrderAgeHours` | Both | Optional | During sync, only pending DV orders younger than this are driven through DCV. `0` disables the filter. Default: `24`. | +| `DcvSyncMaxPerPass` | Both | Optional | Maximum pending DV orders driven through DCV per sync pass. `0` disables the cap. Default: `50`. | + +- **Environment variables:** `DcvTimeoutMinutes`, `DcvWaitForChallengeSeconds`, and `DcvWaitForIssuanceSeconds` can also be set with `CERTINEXT_DCV_TIMEOUT_MINUTES`, `CERTINEXT_DCV_WAIT_FOR_CHALLENGE_SECONDS`, and `CERTINEXT_DCV_WAIT_FOR_ISSUANCE_SECONDS`. The environment variable wins when both are set. +- **Propagation delay:** on V1, DCV driven during synchronization uses its own fixed 3-second delay. V2 uses `DcvPropagationDelaySeconds` everywhere. +- **Sync limits:** `DcvSyncMaxOrderAgeHours` and `DcvSyncMaxPerPass` keep a large backlog of old or abandoned pending orders from slowing every sync pass. + +### Diagnostics + +| Field | Applies to | Required | Description | +|---|---|---|---| +| `LogSensitiveRequestData` | Both | Optional | Temporary diagnostic switch. When `true`, requestor personal data and full CA request/response payloads are written to the gateway logs. Default: `false`. | + +- **Use it briefly:** turn it on only while verifying a new deployment (to confirm exactly what was sent to the CA), then turn it off. +- **When `false`:** personal-data fields are redacted. Emails are masked but keep their domain (for example `j***@example.com`), and the enrollment log line omits the requester name. +- **Email SANs:** `rfc822Name` values in log lines are masked the same way. DNS, IP, and URI SANs are always logged in full. +- **Credentials:** API keys, OAuth secrets, and tokens are always redacted, whatever this setting is. ## Product Codes -CERTInext uses numeric product codes to identify certificate types. **Product codes are provisioned per account by eMudhra** — the codes available to your account are determined when your account is set up. The codes in the tables below are the values observed on specific sandbox and production accounts; your account may have different codes. +**V2 connectors (`UseV2Api = true`) don't need product codes.** CERTInext picks the product from the template's `ProductVariant` and the request's shape, so leave `ProductCode` blank. Set it only to choose one product when several match (see [V2 Product Code Resolution](#v2-product-code-resolution)). The variants the V2 API defines are: -To retrieve the exact codes available to your account, call the `GetProductDetails` endpoint: +| Family (`ProductFamily`) | `ProductVariant` values | How the exact product is chosen | +|---|---|---| +| `ssl` | `dv`, `ov`, `ev` | The variant plus the domain's shape: a `*.` domain selects a wildcard product, and extra DNS names select a multi-domain (UCC) product | +| `private-pki` | `intranet-ssl`, `igtf-host` | The variant | + +Where several catalog products match a variant, CERTInext picks one, and it may not be the one you want: on the US sandbox, `dv` resolves to a 1-month product that rejects a client CSR. If that happens, set `ProductCode` on the template. + +The rest of this section applies to **V1 connectors**, which select every product by its numeric code. It also applies to the optional V2 override. + +CERTInext uses numeric product codes to identify certificate types. **Product codes are provisioned per account by eMudhra**, so the codes available to your account depend on how it was set up and which CA it issues from. The tables below are **eMudhra's published reference values from the emSign era**. They haven't been verified against every environment, and they may differ for accounts that issue through SSL.com after eMudhra's exit from public TLS. Your account's own product list is the only authority. + +To retrieve the exact codes available to your account, call the `GetProductDetails` endpoint (V1) or `GET /api/certinext/v2/catalog/products` (V2): - If you have a `GroupNumber` configured, include it in the request `productDetails` block — some accounts require this to return a non-empty list. - Use the `make get-product-details-group` Makefile target to retrieve products from the sandbox with `groupNumber` included. @@ -283,13 +493,13 @@ To retrieve the exact codes available to your account, call the `GetProductDetai ### SSL/TLS -The product codes in this table were observed on: -- the US sandbox environment (`sandbox-us-api.certinext.io`) in April–May 2026 -- the Production India environment (`api.certinext.io`) via the live draft-order coverage matrix in [development.md](development.md) +The product codes in this table are for: +- the US sandbox environment (`sandbox-us-api.certinext.io`) +- the Production India environment (`api.certinext.io`) **Your account may still have different codes.** Always call `GetProductDetails` against your target environment before going live. -| Product | Sandbox Code | Production Code | Required fields beyond base (`domainName`, `csr`, `requestorInformation`, `subscriptionDetails`, `agreementDetails`) | +| Product | Sandbox Code | Production Code | CERTInext-side requirements (beyond `domainName`, `csr`, `requestorInformation`, `subscriptionDetails`, `agreementDetails`) | |---|---|---|---| | DV (Domain Validated) | `842` | `838` | None. `domainName` is derived from the CSR CN if omitted on the template. | | DV Wildcard | `843` | `839` | CSR CN must use wildcard format (e.g. `*.example.com`). `domainName` in the order must also use the wildcard format. | @@ -302,51 +512,424 @@ The product codes in this table were observed on: | EV (Extended Validation) | `850` | `846` | All OV fields plus: `contractSignerInfo` object (`name`, `email`, `isdCode`, `mobileNumber`, `designation`, `employeeID`); `certificateApproverInfo` object (same fields); `certificateInformation.companyRegistrationNumber`; `streetAddress2` must be non-empty. | | EV UCC (Multi-domain EV) | `851` | `847` | Same as EV plus `certificateInformation.additionalDomains`. | -> Note: SSL/TLS codes appear to be offset by 4 between the US sandbox and Production India in the snapshots we've observed — but treat that as a coincidence, not a guarantee. eMudhra controls the per-account mapping and may use different numeric codes for any new account. Always confirm via `GetProductDetails`. +> Note: The plugin supplies `domainName` and `additionalDomains` (from the CSR and its SANs), but none of the organization, address, or EV fields in the table. For OV and EV it sends only `organizationDetails.preVetting` and `organizationNumber` (V1), so these products need a pre-vetted organization: set `OrganizationNumber` on the connector. -> Note: The CERTInext portal may display additional short-validity products (e.g. **DV SSL Certificate 1 Month**, **DV SSL Certificate Wildcard 1 Month**) that do not appear in the `GetProductDetails` API response and have no published product code. These products are not accessible via the API and are therefore **not supported by this plugin**. Contact eMudhra to determine whether API ordering is available for these products on your account. +> Note: SSL/TLS codes are offset by 4 between the US sandbox and Production India in the tables above — treat that as a coincidence, not a guarantee. eMudhra controls the per-account mapping and may use different numeric codes for any new account. Always confirm via `GetProductDetails`. + +> Note: Some accounts also have short-validity products (for example **SSL DV 1 month**, code `917` on the US sandbox). They don't always appear in the V1 `GetProductDetails` response, but they can appear in the V2 catalog. Under V2, CERTInext may pick one for a `dv` order with no `ProductCode`, and on the sandbox that product rejects a client-supplied CSR. Set `ProductCode` on the template to the 1-year product you want. ### Private PKI | Product | Sandbox Code | Production Code | Availability | |---|---|---|---| | emSign Intranet SSL 1 year | `149` | `100` | Requires special provisioning by eMudhra. Not orderable on standard accounts. | -| IGTF Host 1 year | (not observed) | `104` | Requires special provisioning by eMudhra. Not orderable on standard accounts. | +| IGTF Host 1 year | n/a | `104` | Requires special provisioning by eMudhra. Not orderable on standard accounts. | -> Note: Private PKI products are not available for ordering on standard CERTInext accounts. Attempting to place an order will return EMS-1162 (product not provisioned). The sandbox Private PKI code (`149`) also returns EMS-1162 on standard sandbox accounts even though it appears in the `GetProductDetails` list. Contact eMudhra to have these products enabled on your account. +> Note: Private PKI products need a separate entitlement. On an account without it, placing an order returns EMS-1162 (product not provisioned). Contact eMudhra to have these products enabled. Whether the sandbox code `149` ("Sandbox emSign Intranet SSL 1 Year", `productTypeID` `39`) is available depends on the account. Check your own account's catalog. ### S/MIME and Document Signing -The same numeric product codes have been observed for S/MIME and document-signing products on both the US sandbox and Production India in the snapshots we have. **Treat that as an empirical observation, not a contract** — eMudhra is free to assign different codes per account. Always confirm via `GetProductDetails`. +**Not supported by this plugin.** `GetProductIds` advertises SSL/TLS products only, and V2 `ProductFamily=signature` enrollment fails before any order is placed. The codes below are listed for reference only, because they can appear in your account's `GetProductDetails` response. + +CERTInext uses the same numeric codes for these products on the US sandbox and Production India in the snapshots we have. **Treat that as an example, not a contract** — eMudhra assigns codes per account. + +| Product | Sandbox / Production Code | Notes | +|---|---|---| +| S/MIME | `894` | Not supported. Needs a separate S/MIME entitlement. | +| Document Signer | `819`–`827` | Not supported. Needs a document signing entitlement. | + +CERTInext's published references don't agree on which Document Signer code maps to which product. The V2 API spec lists: + +| Code | Product (per V2 API spec) | +|---|---| +| `819` / `820` / `821` | Natural Person, 1 / 2 / 3 year | +| `822` / `823` / `824` | Legal Person, 1 / 2 / 3 year | +| `825` / `826` / `827` | Legal Entity, 1 / 2 / 3 year | + +## V2 API + +The plugin includes an opt-in CERTInext V2 REST API code path that uses OAuth2 `client_credentials` authentication and an order-centric resource model. V2 is disabled by default; V1 remains the active path unless `UseV2Api` is explicitly set to `true`. When enabled, V2 is fully self-contained: Ping, Enroll, GetSingleRecord, Revoke, and Synchronize all route through the V2 API, and V1 credentials (`ApiKey`, `AccountNumber`, `AuthMode`) are not required. Known limitations are listed under [Known Gaps](#known-gaps). + +### V2 CA Connector Fields + +V2 mode reuses the connector's `ApiUrl`, `OAuthClientId`, and `OAuthClientSecret` fields (see [Connection](#connection)) rather than separate V2-only credentials. `ApiUrl` becomes the V2 host, and the client ID and secret authenticate against it regardless of `AuthMode`. Two fields are specific to V2: + +| Field | Required | Description | +|---|---|---| +| `UseV2Api` | Optional | Enables the V2 code path for connection tests, enrollment, revocation, status checks, and synchronization. Default: `false`. | +| `V2SyncLookbackHours` | Optional | Hours subtracted from the last-sync time on incremental sync. Default: `72`. | +| `SslComSubmitOrganization` | Optional | OV/EV on V2. `true` lets the plugin submit an unvalidated organization to SSL.com, which **accepts SSL.com's subscriber agreement on the organization's behalf**; see [SSL.com organization validation](#sslcom-organization-validation). Default: `false`. | +| `SslComAdminEmail` | Optional | Administrator email sent as `adminEmail` on that submission. Blank omits it. Example: `pki-admin@example.com`. | +| `V2InlineCsr` | Optional | SSL/TLS only. `true` (the default) sends the CSR inline in the create call (a single `POST /ssl-certificates`), as a direct API integration does. `false` creates the order and then submits the CSR; that two-call flow fails for a domain the account has already validated, because CERTInext approves the order at create and then rejects the CSR. A create that times out or returns a 5xx can leave an order that issues and is imported by the next sync rather than cancelled, and the create call can hold about 20 seconds until issuance. Private PKI always uses two calls. Default: `true`. | + +- **Why a lookback:** the API's `from`/`to` filter may bracket either the order-placement date or the issuance date. The window keeps an order created before the last sync but issued afterward (for example a slow DCV order) from being missed. + +#### V2 OAuth2 Setup + +1. Log in to the CERTInext portal for your environment. +2. Navigate to **Integrations → APIs**. +3. Click **+ Create API Credentials**, set **API Type** to `REST`, and select the **OAuth** auth type (not `Access Key`). The V2 spec requires the key to be generated in OAuth mode. A key that wasn't gets HTTP 403 `unauthorized_client` at token time. +4. Note the client ID and client secret. Enter them in `OAuthClientId` and `OAuthClientSecret`. The V2 spec's token example uses the account number as `client_id`, but the plugin never substitutes `AccountNumber` for it, so set `OAuthClientId` explicitly. See [Step 1 of the migration guide](#step-1--create-a-v2-oauth2-credential) for the failure modes. +5. Set `UseV2Api` to `true` and set `ApiUrl` to the V2 base URL (no trailing path suffix), e.g. `https://sandbox-us-api.certinext.io`. +6. V1-only fields (`ApiKey`, `AccountNumber`, `AuthMode`) are not required in this mode and can be left blank. + +#### V2 Token Caching + +The plugin obtains a V2 bearer token via the standard OAuth2 `client_credentials` grant (`grant_type=client_credentials`, form-encoded) against `{ApiUrl}/oauth/token`. Tokens are cached in memory and reused until 60 seconds before expiry (minimum 30-second cache). Token refresh is thread-safe. + +### V2 Certificate Template Fields + +When `UseV2Api` is `true`, two additional enrollment parameters become relevant: + +| Parameter | Required / Optional | Type | Description | Example / Default | +|---|---|---|---|---| +| `ProductFamily` | Optional | String | CERTInext V2 product family: `ssl` or `private-pki` (see [V2 Private PKI Orders](#v2-private-pki-orders)). Default: `ssl`. | `ssl` | +| `ProductVariant` | Optional | String | Variant within the family. `ssl`: `dv`, `ov`, or `ev`. `private-pki`: `intranet-ssl` or `igtf-host` (required). | Derived from `ProductId` (for example `dv`) | + +- **`ProductVariant` default:** when omitted for `ssl`, the plugin derives it from the selected product (an OV product sends `ov`, an EV product sends `ev`). An explicit value that contradicts the product fails enrollment. +- **`signature` (Document Signer):** the parameter accepts it, but enrollment is not supported and fails before any order is placed. +- **Unrecognized family:** treated as `ssl`. +- **`ProductCode`:** optional on V2. When set, it is sent in the `X-Product-Code` header as an override; when blank, no header is sent and CERTInext resolves the product. + +### V2 Product Code Resolution + +When `UseV2Api` is `true`, the plugin does not choose a numeric product code. The V2 spec treats the `X-Product-Code` header on order create as an optional override: CERTInext's wrapper picks the right catalog product from the variant (`productVariant` for SSL/TLS, `variant` for Private PKI), whether `certificate.domain` is a wildcard (it starts with `*.`), and whether `additionalDomains` is non-empty (multi-domain, UCC). The create response reports the product it chose as `resolvedProductCode`, which the plugin logs at Information level. + +1. **No `ProductCode` on the template (the default)** — no `X-Product-Code` header is sent. The connector's `DefaultProductCode` is not used, and neither is the catalog: save-time validation does no catalog check, and enrollment makes no catalog call. The plugin decides whether the order is wildcard or multi-domain from the request itself: + - **Wildcard:** the primary domain starts with `*.`. + - **Multi-domain:** the selected product is a UCC product, or the CSR or gateway SAN list carries DNS names beyond the primary domain (its `www.` variant, and a wildcard's bare apex, don't count). Those names are sent as `additionalDomains`, which makes CERTInext choose a UCC product. +2. **Explicit `ProductCode` (or the deprecated `ProfileId` alias)** — the override. It is sent as-is in the `X-Product-Code` header, after template save-time validation confirms it exists in the live V2 catalog and matches the selected product. Use it when your account holds several matching products (for example different CA profiles for the same variant) and you want to force one. With an override, the plugin reads the catalog once per enrollment to recognize UCC and wildcard products, and rejects extra SANs on a single-domain product. + +This differs from V1, where `DefaultProductCode` only affects renewals (see [DefaultProductCode](#defaultproductcode)). + +### V2 Private PKI Orders + +With `ProductFamily=private-pki`, the plugin places the order against CERTInext's Private PKI endpoint using the Private PKI request body, which differs from the SSL/TLS one: + +- **Product code is optional.** CERTInext resolves the Private PKI product from `ProductVariant`. Set `ProductCode` to your account's Private PKI catalog code only to pick between several matching products; template validation then checks that it is a Private PKI product (`productTypeID` `39`). +- **Which `ProductID` to pick.** The plugin advertises SSL/TLS product names only, so the template still needs one from that list. It does not affect a `private-pki` order, which is built from `ProductVariant` (and `ProductCode`, if set), so any ProductID (for example `DV SSL`) works. +- **Variant is required.** Set `ProductVariant` to `intranet-ssl` or `igtf-host`. +- **Hostname.** The order's primary `hostname` comes from `DomainName`, or from the CSR's CN when `DomainName` isn't set. +- **SANs.** Sent in `additionalHosts`, which accepts DNS names and IPv4/IPv6 addresses. They come from the gateway's SAN list, or from the CSR when the gateway supplies none. +- **Unsupported SANs.** Email and URI SANs can't be expressed, so they are left off the order and a warning is logged. `SubmitNonDnsSans` isn't consulted. +- **No DCV, organization, or subscriber agreement.** Private PKI orders have none of these steps, so DCV is never attempted for them, and `OrganizationNumber`, `AutoSecureWww`, `SignerName`, `SignerPlace`, and `SignerIp` aren't used. +- **Shared fields.** The requestor, technical contact, subscription, email-notification, and group settings are sent exactly as they are for SSL/TLS orders. +- **Two-call CSR delivery.** The plugin creates the order without a CSR and then submits it, always. CERTInext rejects an inline CSR on the Private PKI create (HTTP 422), so the SSL/TLS-only `V2InlineCsr` setting doesn't apply; when it's on, the plugin logs a one-time notice that Private PKI ignores it. + +### V2 Order Lifecycle + +A V2 enrollment places the order, submits the CSR (or, with `V2InlineCsr` on for SSL/TLS, sends it inline in the create call), and then checks the order status; see [V2 enrollment flow](#v2-enrollment-flow) for the full sequence. V2 orders are identified by the `orderId` the V2 order placement endpoint returns, which the plugin stores unchanged as the `CARequestID` and uses for all later tracking, certificate download, and revocation calls. The V2 spec's examples show `ord_`-prefixed IDs, but V2 returns numeric order numbers in the same format as V1 (e.g. `6625262451`). Treat the ID as an opaque string. + +V2 status strings map to Keyfactor enrollment statuses as follows: -| Product | Sandbox / Production Code | Availability | +| V2 Status | Keyfactor Status | Notes | |---|---|---| -| S/MIME | `894` | Requires a separate S/MIME entitlement on the account. Not available on standard SSL accounts. | -| Natural Person Doc Signer (tier 1) | `825` | Requires document signing entitlement. Not orderable on standard accounts. | -| Natural Person Doc Signer (tier 2) | `826` | Requires document signing entitlement. Not orderable on standard accounts. | -| Natural Person Doc Signer (tier 3) | `827` | Requires document signing entitlement. Not orderable on standard accounts. | -| Legal Person Doc Signer (tier 1) | `822` | Requires document signing entitlement. Not orderable on standard accounts. | -| Legal Person Doc Signer (tier 2) | `823` | Requires document signing entitlement. Not orderable on standard accounts. | -| Legal Person Doc Signer (tier 3) | `824` | Requires document signing entitlement. Not orderable on standard accounts. | -| Legal Entity Doc Signer (tier 1) | `819` | Requires document signing entitlement. Not orderable on standard accounts. | -| Legal Entity Doc Signer (tier 2) | `820` | Requires document signing entitlement. Not orderable on standard accounts. | -| Legal Entity Doc Signer (tier 3) | `821` | Requires document signing entitlement. Not orderable on standard accounts. | +| `issued` | Issued | Certificate is immediately downloaded and returned to Command. CERTInext can report `issued` for a while before the certificate is generated (Download Certificate answers 422 `EMS-1165`); see [Issued but not generated yet](#issued-but-not-generated-yet). | +| `pending-dcv` | Pending External Validation | Order is awaiting domain control validation. | +| `pending-csr` | Pending External Validation | Order is awaiting CSR submission or processing. | +| `pending-agreement` | Pending External Validation | Order requires subscriber agreement acceptance. For SSL/TLS orders the plugin accepts it (see [Subscriber agreement fallback](#subscriber-agreement-fallback)). | +| `pending-organization-verification` | Pending External Validation | OV/EV order is awaiting organization verification. | +| `pending-documents` | Pending External Validation | Order is awaiting supporting document submission. | +| `pending-approval` | Pending External Validation | Order is awaiting final CA/LRA approval before issuance. | +| `revoked` | Revoked | Order has been revoked. | +| `cancelled` | Failed | Order was cancelled; a new enrollment is required. | +| `rejected` | Failed | Order was rejected by the CA/LRA; a new enrollment is required. | +| `expired` | Issued | An expired-but-not-revoked order is reported as issued (GENERATED), matching V1's convention — it remains visible in Command's inventory rather than disappearing as a failure. | +| `unknown` | Pending External Validation | CERTInext can't currently report where the order is; the order is kept pending and re-checked on the next status poll or sync, and the plugin logs a warning. | + +Any V2 status not in this table (e.g. a value CERTInext adds in the future) maps to Failed, and the +plugin logs a warning distinguishing "unmapped status" from the statuses above that are deliberately +mapped to Failed — see the gateway trace log if certificates unexpectedly show as failed. + +**V2 synchronization:** + +- Synchronize pages through `/reports/orders`. Pages are capped at 100 rows, and `PageSize` is clamped to that. +- The report carries display strings (for example `Order Fulfilled`, `Certificate Downloaded`) rather than the status enum above. Recognized strings are mapped directly. Any other combination falls back to a live order-status call, so a new display value never silently misclassifies an order. +- Cancelled and rejected orders are skipped. Issued orders have their certificate chain downloaded. +- CERTInext does not serve the certificate body of a revoked order. A revoked order is propagated as revoked only when the gateway already holds that certificate (the revocation date and reason come from a live status call). +- Otherwise a revoked order is reported as Failed (the gateway has a record without a body) or skipped (no record), so the gateway never stores a revoked record without a certificate. +- `IgnoreExpired` is applied here: expired certificates are skipped. +- An issued order whose download answers 422 `EMS-1165` is emitted without a certificate body and counted as `IssuedNotGeneratedYet` in the sync summary instead of logging a warning per order; a later pass picks it up. + +#### SSL.com organization validation + +OV and EV certificates are issued under an organization that SSL.com must have validated. Before placing a V2 OV or EV SSL/TLS order for the connector's `OrganizationNumber`, the plugin reads that organization's SSL.com validation status (`GET /organizations/{orgNumber}/ca-validations/sslcom`): + +1. **Validated at the order's level (OV or EV):** nothing more is done. +2. **Not validated:** the plugin asks SSL.com to refresh the status once (`POST .../sslcom/sync`) and checks again. +3. **Still not validated, and `SslComSubmitOrganization` is `true`,** the level isn't already requested, and SSL.com's readiness block says the organization is ready for that level (`ready` for OV, `evReady` for EV, with nothing missing): the plugin submits it (`POST .../sslcom` with `levels` set to the order's level, `subscriberAgreementAccepted: true`, and `adminEmail` when `SslComAdminEmail` is set). **This accepts SSL.com's subscriber agreement on the organization's behalf.** The intent is logged at Information level before the call, and the connector start-up log warns that the setting is on. Leave it `false` (the default) unless you are authorized to accept that agreement; the plugin then only reads and refreshes the status. +4. **Whatever happens, the order is still placed.** A not-validated organization, a not-ready organization, or any failed SSL.com call logs one warning and never blocks or fails the enrollment (a not-validated organization's OV/EV order simply stays pending until SSL.com validates it). The warning includes SSL.com's status, `lastError`, and the fields it reports missing; email addresses are masked unless `LogSensitiveRequestData` is on. + +DV and Private PKI orders skip this check entirely. + +**How "validated" is decided.** The spec describes the response only in prose ("status per level (OV, EV) with validTill"), so the plugin reads it defensively. A level counts as validated when its entry in `levels` carries a validated status word (`VALIDATED`, `VALID`, `APPROVED`, `ACTIVE`, `COMPLETE`, `COMPLETED`, or `ISSUED`) or a true `validated` flag, or has no status but a `validTill` in the future; an entry whose `validTill` has passed is not validated. A bare level name in `levels` counts only when the overall `status` is itself a validated word. The overall `status` and `validatedAt` alone never count, since they aren't per level. Any shape the plugin doesn't recognize is treated as not validated; because that only produces a warning, the cost of a false "not validated" is a log line. + +#### Subscriber agreement fallback + +The create body already carries the agreement (`signerName`, `signerPlace`, `accepted: true`), but if Track Order still shows an SSL/TLS order at `pending-agreement`, the CA won't release the certificate until the agreement is accepted. The plugin then calls `POST /api/certinext/v2/ssl-certificates/{orderId}/agreement` with the same signer values: + +- **Enrollment:** at most once per order per `Enroll` call, whether the status is seen right after create, after DCV, or during the pickup poll. The signer is the template's `SignerName` (else the requestor name) and `SignerPlace` (else the connector's), as on create. +- **Synchronize:** at most once per order per pass, using the connector's `RequestorName` and `SignerPlace` (a sync has no template). A pending SSL/TLS order in the listing that wasn't already tracked costs one extra status call per pass; with no `SignerPlace` or `RequestorName` configured the step is skipped entirely. +- **Audit and failures:** the intent is logged at Information before the call (the signer's name and place appear only when `LogSensitiveRequestData` is on). A failed call is logged as a warning and never fails the enrollment or the sync; the order stays pending. +- **Not applicable:** Private PKI orders have no Subscriber Agreement, and `GetSingleRecord` doesn't accept agreements. + +#### Issued but not generated yet + +CERTInext can report an order as `issued` before the certificate exists: Download Certificate then answers HTTP 422 `EMS-1165 Invalid request status.` Normally the certificate is generated about 20 seconds later, but the sandbox has been seen to take far longer. The plugin treats this as an expected state, not an error: -> Note: S/MIME (894) and document signing products (819–827) require a separate entitlement that is not included in a standard SSL/TLS account. Contact eMudhra to request access. +- **Enrollment:** the pickup poll keeps waiting (within `PickupRetries` x `PickupDelay`), logging each attempt at Debug level and writing one Information summary if the budget runs out. The enrollment returns pending, and a later synchronization imports the certificate. +- **`GetSingleRecord` and Synchronize:** logged at Information (single record) or Debug with a count in the sync summary, rather than a warning. The record is returned without a certificate body, as for any failed download. +- **Log fields:** the lines include CERTInext's `orderState` and `certificateState` text (for example `Approved by System` versus `Certificate Generated`) for diagnosis. Their vocabulary isn't documented, so the plugin never acts on it. +- **Any other download error** is still logged as a warning. -To retrieve the full list of product codes available to your account, call the `GetProductDetails` endpoint against your target environment. The sandbox and production APIs each return their own set of codes. +V2 has no *renew* endpoint. CERTInext does document a `/reissue` endpoint (`mode: rekey|update-sans`, with optional `revokePrevious`/`revokeReason`), but the plugin does not use it — every enrollment type (New, Reissue, Renew, RenewOrReissue) places a fresh V2 order, and the prior order/certificate is left issued rather than auto-revoked. -> Note: SSL/TLS products are supported on standard accounts — see the SSL/TLS table above for the exact sandbox/production code pair for each product. Private PKI (Production `100`, `104` / Sandbox `149`), S/MIME (`894`), and document-signing products (`819`–`827`) require special provisioning by eMudhra and are not available on standard SSL/TLS accounts — ordering them returns EMS-1162. +### V2 Revocation Reason Handling + +CERTInext's V2 revoke endpoint accepts only a subset of its own documented reason enum. When Command's revoke reason maps to one CERTInext rejects, the plugin substitutes an accepted reason and retries once, rather than failing the revoke outright: CA-compromise and AA-compromise are retried as key-compromise; unspecified (Command's default when no reason is given) and certificate-hold are retried as cessation-of-operation. See [Revocation Reason Codes](#revocation-reason-codes) in the migration guide below for the full accepted/rejected matrix. + +## Migrating from V1 to V2 + +The CERTInext V2 REST API is an opt-in, order-centric API with OAuth2 authentication. It is +controlled entirely by the `UseV2Api` connector flag: `false` (default) keeps the connector on the +V1 API documented above; `true` switches **all** operations — Ping, Enroll, GetSingleRecord, Revoke, +and Synchronize — to V2. The two APIs cannot be mixed on a single connector. + +> Read [Known Gaps](#known-gaps) before migrating a production connector. The most important: +> +> - Document Signer (`ProductFamily=signature`) enrollment isn't supported. +> - DCV isn't validated end to end for per-SAN UCC domains, never-validated domains, or wildcards. +> - Every renewal places a new order. +> +> The plugin requires AnyCA Gateway REST 26.2.0 or later; see the compatibility matrix under [Requirements](#requirements). + +### Before You Begin: Confirm V2 Will Work for Your Templates + +- **Multi-domain (UCC) certificates are supported.** That covers DV UCC, DV Wildcard UCC, OV UCC, OV Wildcard UCC, and EV UCC. The plugin detects a UCC product from the live catalog's `productTypeID` and sends the extra SAN domains in the order's `additionalDomains` field. Per the V2 spec, a UCC order's SANs come from the order, not the CSR. +- **Only DNS SANs are sent.** `additionalDomains` takes DNS names only, so IP, email, and URI SANs are left off a UCC order and a warning is written to the gateway log. +- **Non-UCC SSL products are checked up front.** A CSR or SAN list with DNS names beyond the primary domain and its `www.` variant is rejected before any order is placed. UCC products are exempt. +- **DCV is not validated end to end in three cases.** These are per-SAN DCV on UCC orders, a domain that has never been validated, and wildcard DCV. The plugin runs the DNS-01 flow for each domain CERTInext reports as not yet validated, but test each UCC or wildcard template on the sandbox before relying on it in production. Keep it on a V1 connector if you need a validated path today. +- **DCV needs a DNS provider plugin.** `DcvEnabled` defaults to `true`. Without a DNS provider plugin for the order's domains, V2 DV orders stay pending after the order is placed. Deploy one, or set `DcvEnabled` to `false` and validate domains another way. See [DCV under V2](#dcv-under-v2). + +### Step 1 — Create a V2 OAuth2 Credential + +V2 authenticates with an OAuth2 `client_credentials` token, and the CERTInext V2 spec requires the API key to be generated in **OAuth mode**. The credential goes in the connector's `OAuthClientId` and `OAuthClientSecret` fields. + +1. Log in to the CERTInext portal for your environment. +2. Navigate to **Integrations → APIs**. +3. Click **+ Create API Credentials**. +4. Set **API Type** to `REST` and select the **OAuth** auth type, not `Access Key`. +5. Complete the form and click **Generate**. +6. Note the client ID and client secret right away. + +A V1 `Access Key` credential won't work against V2. The token request fails in one of two ways: + +| Response | Meaning | Fix | +|---|---|---| +| HTTP 403 `unauthorized_client` | The key exists but wasn't generated in OAuth mode. The plugin reports this. | Create a new key in OAuth mode. | +| HTTP 401 `invalid_client` | The client ID or secret is wrong. | Re-enter the values from the portal, or regenerate the secret. | + +> **Warning:** The V2 spec's token example sends the account number as `client_id`. The plugin never substitutes `AccountNumber` for the client ID, so always set `OAuthClientId` explicitly to the client ID shown in the portal, even if the value matches your account number. + +### Step 2 — Update the CA Connector + +You can update the existing CA connector in place, or create a second connector for the same CERTInext account with `UseV2Api=true` to validate V2 without disturbing V1 traffic. + +> **Caution:** Two connectors on one account both import the same orders, and each plugin instance can run DCV for the same pending order. Use the second-connector approach on the sandbox only, not in production. + +To switch a connector: + +- [ ] Set `UseV2Api` to `true`. +- [ ] Change `ApiUrl` to the V2 host. +- [ ] Set `OAuthClientId` and `OAuthClientSecret`. +- [ ] Set `SignerPlace`. The connector can't be saved with it blank in V2 mode. + +New fields `UseV2Api` and `V2SyncLookbackHours` are documented in [V2 API](#v2-api). The remaining V1 fields behave as follows. + +**Not used on V2** + +| V1 field | Behavior | +|---|---| +| `AccountNumber` | Not read by any V2 code path. The plugin never reuses it as the OAuth `client_id` (see Step 1). | +| `AuthMode` | V2 always authenticates with OAuth2 `client_credentials`. On V1, `OAuth` is legacy and unsupported: V1 does not honor OAuth, though the code still accepts it for already-saved connectors. | +| `ApiKey` | V2 never computes an `authKey`. | +| `OAuthTokenUrl` | V2 always requests a token from `{ApiUrl}/oauth/token`. Legacy and unsupported on V1, as for `AuthMode`. | +| `AccountingModel` | V2 order create has no equivalent field. | + +**Used unchanged** + +| V1 field | Behavior | +|---|---| +| `SubscriptionValidityYears` | Fallback validity when the template's `ValidityYears` is not set. | +| `TechnicalContactName` / `Email` / `IsdCode` / `MobileNumber` | Sent as the order's `technicalPointOfContact` on SSL/TLS and Private PKI orders. A blank field falls back to the matching `Requestor*` value, as on V1. `designation` is always `Technical Contact`. | +| `RequestorName` / `RequestorEmail` / `RequestorIsdCode` / `RequestorMobileNumber` / `RequestorDesignation` | Carried into the order's `requestor` block. The phone number is sent as `+`, and a blank `RequestorDesignation` is omitted. | +| `SignerPlace` / `SignerIp` | `SignerPlace` is carried into the order's `agreement` block and is required in V2 mode. `SignerIp` is V1 only: the V2 agreement block has no IP field, so it is never sent. | +| `AutoSecureWww` | Controls whether V2 adds the `www.` variant. | +| `PageSize` | Applies to V2 `/reports/orders` paging, capped at 100 per page. | +| `PickupRetries` / `PickupDelay` | V2 enrollment polls for a quickly issued certificate the same way V1 does. | +| `LogSensitiveRequestData` | Governs redaction of V2 request and response bodies in the gateway log. | +| `Enabled` | Unchanged. | + +**Used with changed behavior** + +| V1 field | What changes on V2 | +|---|---| +| `ApiUrl` | Use the bare host (for example `https://us-api.certinext.io`), not the V1 `/emSignHub-API/` URL. A trailing slash is harmless because the client trims it. A V1-style URL under V2, or the reverse, fails every call. Both modes require `https`; `http` is rejected except for a loopback host. | +| `OAuthClientId` / `OAuthClientSecret` | Set them to the OAuth-mode credential from Step 1. | +| `GroupNumber` | Sent as `groupNumber` on SSL/TLS and Private PKI order create, and as a query parameter on catalog and orders-report calls. Omitted when blank, so the account's default group applies. | +| `OrganizationNumber` | Required for OV/EV, unused for DV. V2 OV/EV orders send `organization.organizationNumber` with `preVetted=true`. CERTInext rejects an OV/EV order without organization data (HTTP 422 `EMS-1180`), so the plugin fails the enrollment before any CA call if it is blank. | +| `EmailNotifications` | `1` maps to `"all"` and `0` maps to `"consent-only"` (the V2 spec's enum is `consent-only` or `all`, so the V1 value `"0"` is no longer sent). Blank is omitted on V2, so the CA's default of `"all"` applies; V1 sends `"0"`. Set `0` explicitly for silent V2 orders. Any other value fails the enrollment before any CA call. | +| `SubscriptionAutoRenew` / `SubscriptionRenewCriteriaDays` | `SubscriptionAutoRenew=1` sets `subscription.autoRenew=true`. `SubscriptionRenewCriteriaDays` sets `subscription.renewBeforeDays` (blank omits it, so the CA's default of 30 applies). An unparseable or negative value fails the enrollment before any CA call. | +| `DefaultProductCode` | Not used on V2: no product code is sent unless the template sets `ProductCode` (see [V2 Product Code Resolution](#v2-product-code-resolution)). Renewals don't need it. | +| `IgnoreExpired` | Honored during V2 Synchronize: a report row with a parseable, past `certificateExpiryDate` is skipped, and a row with a missing or unparseable date is kept. Not applied on V1 yet. | +| `SubmitNonDnsSans` | SSL family: not consulted. A UCC order's `additionalDomains` takes DNS names only, so non-DNS SANs are left off with a gateway-log warning. Private PKI: not consulted. `additionalHosts` takes DNS names and IPs, so IP SANs are always submitted, and email and URI SANs are left off with a warning. | + +#### DCV under V2 + +`DcvEnabled` defaults to `true`, and the DCV settings behave as follows under V2: + +- `DcvEnabled`, `DcvTxtRecordTemplate`, `DcvPropagationDelaySeconds`, and `DcvTimeoutMinutes` are used. +- `DcvSyncMaxOrderAgeHours` and `DcvSyncMaxPerPass` bound DCV during synchronization, the same as V1. +- `DcvWaitForChallengeSeconds` and `DcvWaitForIssuanceSeconds` apply to V1 only. V2 publishes the challenge as soon as the order exists and polls the order until it leaves `pending-dcv` (bounded by `DcvTimeoutMinutes`), then runs the normal pickup poll. +- DCV applies to the SSL/TLS family. Private PKI orders have no DCV step. + +### Step 3 — Update Certificate Templates + +For each template you're migrating: + +1. **Leave `ProductCode` blank unless you need to force a catalog product.** On V2 the plugin sends no + `X-Product-Code` header and CERTInext resolves the product from the variant, the wildcard shape of the + domain and any additional domains, so a template with only `ProductId` works even when the catalog has + several products at that assurance level. Set `ProductCode` only to override that choice (for example + to pick one of several CA profiles). See [V2 Product Code Resolution](#v2-product-code-resolution). +2. Add `ProductFamily` (default `ssl`) if not already present — this is a V2-only parameter with no + V1 equivalent. `ProductVariant` (`dv`/`ov`/`ev`) is optional for `ssl`: if left unset, the plugin + derives it from the selected product (an OV product sends `ov`, an EV product sends `ev`) instead + of defaulting to `dv`; set it explicitly only to override. For a Private PKI template, set + `ProductFamily=private-pki`, `ProductVariant` to `intranet-ssl` or `igtf-host` (required, no + default); `ProductCode` is optional (see [V2 Private PKI Orders](#v2-private-pki-orders)). + `ProductFamily=signature` (Document Signer) enrollment is not supported. +3. Re-verify `ProductCode` (if set explicitly) against the V2 catalog. V1 and V2 product codes are not + guaranteed to be the same numeric values on your account — check the V2 catalog + rather than assuming the V1 code carries over. Template validation + (`ValidateProductInfo`) automatically checks `ProductCode` against the V2 catalog once + `UseV2Api=true`, so an incorrect code will be caught at template save time, not silently at + enrollment. +4. The `DomainName` template parameter takes effect in V2 only. The `SignerName` and `SignerPlace` + template parameters take effect in both V1 and V2 (`SignerIp` is V1 only). `RenewalWindowDays` and `ValidityDays` + are V1-only and are ignored. +5. If the template enrolls for a UCC (multi-domain) or wildcard product, test it on the sandbox first. + The plugin runs DCV for each domain, but per-SAN, never-validated-domain, and wildcard DCV aren't + validated end to end (see + [Before You Begin](#before-you-begin-confirm-v2-will-work-for-your-templates)). +6. If the product is OV or EV (whether `ProductVariant` is set explicitly or left to be derived), set + `OrganizationNumber` on the CA connector (a pre-vetted organization number from CERTInext's + Accounts → List Organizations). It is mandatory for OV/EV under V2 — enrollment fails fast with a + clear error if it's missing, rather than reaching the CA and getting back an opaque 422. + +### Step 4 — Test Before Cutting Over + +Run a full enroll → sync → revoke cycle against the sandbox environment with `UseV2Api=true` before +pointing a production template at the V2 connector. At minimum, confirm: + +- A new enrollment issues (or parks pending DCV/approval as expected) and is retrievable via + `GetSingleRecord`. +- A full and an incremental `Synchronize` both pick up the order. +- `Revoke` succeeds for the Command revoke reasons you actually use. + +### Verification Checklist + +- [ ] **Connection test.** Save the connector. It succeeds after a token request to `{ApiUrl}/oauth/token` and `GET /api/certinext/v2/auth/me`; a 401 or 403 is explained in Step 1. +- [ ] **Template save.** Each template saves. An explicit `ProductCode` that is missing from the catalog, or whose product type doesn't match the selected product, is rejected. +- [ ] **DV enrollment.** Enroll a single-domain DV order. It returns the certificate, or returns pending and is imported by the next sync, and its TXT record is removed. +- [ ] **UCC and wildcard.** Enroll each migrated template. One order carries every DNS SAN, and each domain reaches the validated state. +- [ ] **OV/EV.** Set `OrganizationNumber` and enroll. The order is accepted, stays pending until organization verification completes, and the next sync imports it. +- [ ] **Synchronization.** Run a full and then an incremental sync. New orders are imported with their certificates; revoked orders appear only when the gateway already holds their certificate. +- [ ] **Revocation.** Revoke a test certificate with Command's default reason (unspecified) and with key compromise. The gateway log shows the substituted reason for the first. +- [ ] **Logs.** The gateway log has no requestor names, email addresses, or request bodies unless `LogSensitiveRequestData` is on. + +## Behavioral Differences After Migrating + +- **Order identifiers.** The V2 spec's examples show `ord_`-prefixed IDs (for example `ord_8K9mQ2vR8nP4bL`), but V2 returns numeric order numbers in the same format as V1 (for example `6625262451`). V1-placed order numbers also resolve through V2 Track Order and appear under the same number in the V2 orders report, so existing `CARequestID` values carry over. The plugin stores whatever `orderId` CERTInext returns; treat it as an opaque string in external tooling. +- **Status vocabulary.** V2 reports order status as strings (`issued`, `pending-dcv`, `pending-csr`, + `pending-agreement`, `pending-organization-verification`, `pending-documents`, `pending-approval`, + `revoked`, `cancelled`, `rejected`, `expired`, `unknown`) rather than V1's numeric CERTInext status + codes. The plugin maps both to the same Keyfactor status values, so this is transparent to + Command, but it changes what you'll see in gateway trace logs. +- **Synchronization source.** V2 sync reads CERTInext's `/reports/orders` endpoint instead of V1's + `GetOrderReport`. Incremental sync queries a window starting `V2SyncLookbackHours` (default 72) + before the last sync time rather than the exact last-sync timestamp, because the API's date filter + may bracket either the order-placement or the issuance date — this trades a small + amount of redundant re-processing for not missing a slow-issuing order. +- **Revoked orders in sync.** CERTInext doesn't serve the certificate body of a revoked order, so a + revoked order is imported as revoked only when the gateway already holds its certificate. Otherwise + it is reported as failed or skipped, so the gateway never stores a revoked record with no + certificate. +- **Orphaned orders.** If CERTInext rejects the CSR after the order was created, the plugin cancels + the order once and returns a failed result carrying the order ID. After a timeout, the plugin + checks the order before deciding: it cancels the order only if the CSR never arrived. + +- **CSR delivery.** By default V2 SSL/TLS enrollment sends the CSR inline in the create call + (`V2InlineCsr`, default `true`), the same call shape as a direct single-call API integration. The + create call can hold about 20 seconds until issuance, and a create that times out or returns a 5xx + can leave an order that issues and is imported by the next sync rather than cancelled. Setting + `V2InlineCsr` to `false` creates the order and then submits the CSR, as above; that two-call flow + fails for a domain the account has already validated. Private PKI always uses the two-call flow. + +### Renewals and Reissuance + +CERTInext V2 has no *renew* endpoint. It documents a `/reissue` endpoint (`mode: rekey|update-sans`, with optional `revokePrevious` and `revokeReason`), which the plugin does not use. + +- **Every enrollment type places a new order.** `New`, `Renew`, `Reissue`, and `RenewOrReissue` all take the same path as a new enrollment, without V1's renewal-window logic. +- **The prior order is untouched.** The old order and certificate stay issued and are not auto-revoked. Command links the old and new certificates through history only. +- **Each renewal is billed as a new order.** Confirm with eMudhra how your account treats renewals before you rely on free renewals within a subscription term. + +### Revocation Reasons After Migrating + +V1 sends a numeric `revokeReasonId` and V2 sends a kebab-case string; the plugin translates automatically. CERTInext rejects four of the V2 reason values on SSL/TLS orders, including Command's default `unspecified`. The plugin retries each once with an accepted substitute, so no customer action is needed. The full mapping is in [Revocation Reason Codes](#revocation-reason-codes). + +## Known Gaps + +The following V2 limitations are known. None of them is a show-stopper for a single-domain +deployment, but decide with these in mind rather than discovering them after cutting over: + +- **DCV isn't validated end to end** for per-SAN domains on UCC orders, for a domain that has never been validated, or for wildcards. The plugin runs the flow for each of these, but the paths haven't been confirmed against the CA. See [Before You Begin](#before-you-begin-confirm-v2-will-work-for-your-templates). +- **Document Signer (`ProductFamily=signature`) enrollment isn't supported.** It fails before any + order is placed. +- **Every renewal/reissue places a new order.** See [Renewals and Reissuance](#renewals-and-reissuance) + above. +- **`OrganizationNumber` is required to enroll OV/EV via V2.** V2 OV/EV orders send + `organization.organizationNumber` with `preVetted=true` (mirroring V1's + `organizationDetails.preVetting`); omitting it fails the enrollment. If your account relies on + `OrganizationNumber` to fast-path DV issuance under V1, note that DV orders under V2 never send an + organization block, so that benefit does not carry over. +- **`AccountingModel` has no V2 effect.** V2 order create has no equivalent field. `GroupNumber`, the + technical-contact fields, `EmailNotifications`, `SubscriptionAutoRenew`/`SubscriptionRenewCriteriaDays`, and + `IgnoreExpired` are all honored on V2 (see the tables in Step 2). +- **OV and OV UCC orders can exceed the plugin's fixed 120-second request timeout.** The order may + still be created on the CA and is imported by the next sync. EV orders under V2 are not validated + end to end. + +## Rolling Back to V1 + +Rolling back means setting `UseV2Api` back to `false`, as long as you kept the V1 values. + +1. Set `UseV2Api` to `false` on the connector. +2. Restore the V1-format `ApiUrl` (with the `/emSignHub-API/` path). Keep a copy of this value before you edit an existing connector. +3. Confirm `ApiKey` and `AccountNumber` are intact. They are unaffected by being unused while V2 was active, unless you overwrote them in Step 2. +4. Save the connector and confirm the connection test passes. + +**Rollback caveat:** `Enroll`, `GetSingleRecord`, `Revoke`, and `Synchronize` choose V1 or V2 from the connector's current `UseV2Api` flag, not from the stored `CARequestID`. V1-placed order numbers resolve through V2 Track Order, and V2 order numbers use the V1 format, but V1 Track Order and `GetOrderReport` may not see an order placed through V2. Rolling back a connector that has already issued V2 certificates isn't validated: check on the sandbox that sync, revoke, and renewal still work for them. Certificates enrolled before the switch to V2 are V1 orders and are unaffected. ## Architecture -This document describes how the CERTInext AnyCA Gateway REST plugin integrates with Keyfactor Command and the CERTInext certificate authority. It covers the three primary certificate lifecycle operations — synchronization, enrollment, and revocation — and how the plugin routes each through the CERTInext API. +This document describes how the CERTInext AnyCA Gateway REST plugin integrates with Keyfactor Command and the CERTInext certificate authority. It covers the primary certificate lifecycle operations — synchronization, enrollment, domain control validation, and revocation — for both CERTInext API generations (V1 and V2), and how the plugin routes each one. -## Component Overview +### Component Overview -``` +```text ┌─────────────────────────────────────────────────────────┐ -│ Keyfactor Command │ +│ Keyfactor Command │ │ │ │ Certificate Enrollment · Revocation · Sync Jobs │ └────────────────────────────┬────────────────────────────┘ @@ -355,49 +938,79 @@ This document describes how the CERTInext AnyCA Gateway REST plugin integrates w (plugin host process) │ ┌────────────────────────────▼────────────────────────────┐ -│ CERTInext AnyCA Gateway Plugin │ +│ CERTInext AnyCA Gateway Plugin │ │ │ │ Translates Keyfactor operations into CERTInext API │ │ calls, maps responses back to Command's data model, │ -│ and enforces audit logging on every operation. │ +│ publishes DNS-01 validation records through the │ +│ gateway's DNS provider plugin, and logs every │ +│ operation. │ └────────────────────────────┬────────────────────────────┘ - │ HTTPS · HMAC-signed requests + │ HTTPS · AccessKey (V1) or OAuth2 bearer │ ┌────────────────────────────▼────────────────────────────┐ -│ CERTInext REST API (eMudhra) │ +│ CERTInext REST API (eMudhra) │ │ │ -│ ValidateCredentials GenerateOrderSSL TrackOrder │ -│ GetCertificate RevokeOrder GetOrderReport │ -│ GetProductDetails SubmitCSR │ +│ V1 ValidateCredentials · GenerateOrderSSL │ +│ TrackOrder · GetCertificate · GetOrderReport │ +│ RevokeOrder · GetProductDetails │ +│ GetDcv · VerifyDcv │ +│ │ +│ V2 POST /oauth/token · GET /auth/me │ +│ GET /catalog/products · GET /reports/orders │ +│ POST /{family} create order │ +│ PUT /{family}/{id}/csr (two-call; Private PKI) │ +│ GET /{family}/{id} track order │ +│ GET /{family}/{id}/certificate │ +│ GET /ssl-certificates/{id}/dcv │ +│ POST /ssl-certificates/{id}/dcv/verify │ +│ POST /{family}/{id}/revoke · POST .../cancel │ └─────────────────────────────────────────────────────────┘ ``` -## Request Authentication +`{family}` is `ssl-certificates`, `private-pki-certificates`, or `signature-certificates` (see the [API Endpoint Reference](#api-endpoint-reference)). -Every API call is signed using HMAC-SHA256. The access key itself is never transmitted — only a derived hash is sent: +### V1 and V2 at a Glance -``` -authKey = SHA256(accessKey + requestTs + requestTxnId) -``` +`UseV2Api` selects one API generation for the whole connector; the two cannot be mixed. -A unique transaction ID (`requestTxnId`) is generated for each request. The timestamp (`requestTs`) and transaction ID travel alongside the `authKey` so the CERTInext server can reproduce and verify the hash. The plugin handles this automatically; no manual signing is required during normal operation. +| Aspect | V1 (default) | V2 (`UseV2Api` = `true`) | +|---|---|---| +| Authentication | Access key, sent as `meta.authKey` | OAuth2 `client_credentials` bearer token | +| `ApiUrl` | Includes the `/emSignHub-API/` path | Bare host, no path | +| Order ID (`CARequestID`) | Order number (a request number comes first) | Single `orderId`, stored unchanged | +| Sync source | `GetOrderReport`, filtered by order date (`yyyy-MM-dd`), no lookback | `/reports/orders`, from `V2SyncLookbackHours` (default 72) before the last sync | +| `IgnoreExpired` | Not applied yet | Applied | +| Renewal | Renewal window (`RenewalWindowDays`), otherwise a new order | Every enrollment type places a new order | +| DCV waits | `DcvWaitForChallengeSeconds`, `DcvWaitForIssuanceSeconds` | None; polls until the order leaves `pending-dcv`, bounded by `DcvTimeoutMinutes` | +| Revoke reasons | Numeric `revokeReasonId`; unaccepted codes sent as key compromise | Kebab-case strings; four rejected values retried once with a substitute | +| Product code | `ProductCode`, then `ProfileId`, then the built-in default for the selected product | None sent by default: CERTInext resolves the product. An explicit template `ProductCode` is sent as the `X-Product-Code` override | + +### Request Authentication + +| Mode | Credential | Sent as | `meta.authKey` | +|---|---|---|---| +| V1 | Access key (`ApiKey`) and `AccountNumber` | A `meta` block in every JSON request body (`ver`, `ts`, `txn`, `accountNumber`, `authKey`) | `SHA256(accessKey + ts + txn)` as lowercase hex | +| V2 (`UseV2Api` = `true`) | OAuth2 client ID and secret (`OAuthClientId`, `OAuthClientSecret`) | `Authorization: Bearer` header; the token comes from `POST {ApiUrl}/oauth/token` (`client_credentials`, form-encoded) | Not used | -An OAuth client-credentials mode is also available as an alternative. When OAuth is configured, the plugin exchanges a client ID and secret for a short-lived bearer token and automatically refreshes it before expiry. +- **V1 `authKey`.** A plain SHA-256 digest, not an HMAC. The access key is never transmitted; only the digest is sent. `ts` is a timestamp and `txn` is a random numeric transaction ID generated for each request, and both travel in `meta` so CERTInext can recompute the digest. The plugin does this automatically. +- **V2 tokens.** The plugin caches the bearer token until 60 seconds before the expiry the token endpoint reports (minimum 30 seconds), and refreshes it thread-safely. +- **V1 OAuth is unsupported.** The `AuthMode=OAuth` and `OAuthTokenUrl` settings are legacy: the live V1 API ignores a bearer token and rejects the call with 401 "clientAccessKey is not active". The code still accepts them for connectors that were already saved with that mode. -## Certificate Identifiers +### Certificate Identifiers -CERTInext assigns two different reference numbers to each order. Understanding the difference matters when tracing certificates across systems: +V1 assigns two different reference numbers to each order. Understanding the difference matters when tracing certificates across systems: | Identifier | When it is assigned | What it is used for | |---|---|---| | **Request Number** | Immediately when an order is created | Tracking a draft order before it is formally submitted; attaching a CSR to a pending order | | **Order Number** | After the order is formally submitted and accepted | All post-issuance operations: checking status, downloading the certificate, revoking — **this is the identifier stored in Keyfactor Command** | ---- +V2 returns a single `orderId` when the order is created, and the plugin stores it unchanged as the `CARequestID`. V2 order IDs are numeric, in the same format as V1 order numbers; see [Behavioral Differences After Migrating](#behavioral-differences-after-migrating). -## Gateway Startup +### Gateway Startup -When the AnyCA Gateway process starts, it loads each configured CA connector. For CERTInext, this step reads the connector settings, establishes the API client, and confirms that the credentials are structurally valid. +When the AnyCA Gateway process starts, it loads each configured CA connector. For CERTInext, this step reads the connector settings, checks that the API URLs are acceptable, and builds the API client. Credentials are validated separately, when an administrator saves the connector (see [Connector Validation](#connector-validation)). ```mermaid sequenceDiagram @@ -405,61 +1018,212 @@ sequenceDiagram participant Plugin as CERTInext Plugin participant API as CERTInext API - GW->>Plugin: Load CA connector configuration - Plugin->>Plugin: Validate required fields\n(API URL, account number, credentials) - Plugin->>Plugin: Initialize API client\nwith configured auth mode - Plugin->>Plugin: Record which credential fields are populated\n(values are never logged) - GW->>Plugin: Test connection - Plugin->>API: Verify credentials - API-->>Plugin: Credentials accepted - Plugin-->>GW: Connector ready + GW->>Plugin: Initialize with the CA connector configuration + Plugin->>Plugin: Require ApiUrl and reject http unless the host is loopback + Plugin->>Plugin: Build the API client
for the configured API generation + Plugin->>Plugin: Log which credential fields are populated
(values are never logged) + opt DcvEnabled is true but no DNS provider factory was injected + Plugin->>Plugin: Log a warning: DCV will be skipped + end + opt LogSensitiveRequestData is true + Plugin->>Plugin: Log a warning that personal data
and request payloads will be logged + end + GW->>Plugin: Ping + alt Connector disabled + Plugin-->>GW: Skipped, connector is disabled + else V1 + Plugin->>API: ValidateCredentials + API-->>Plugin: Credentials accepted + Plugin-->>GW: Connector ready + else V2 + Plugin->>API: GET /auth/me (after obtaining a bearer token) + API-->>Plugin: Account details + Plugin-->>GW: Connector ready + end +``` + +### Synchronization + +Keyfactor Command periodically synchronizes its certificate inventory with CERTInext. The plugin retrieves orders page by page and feeds them into Command's database. Synchronization can be a full refresh or incremental. V1 and V2 differ in the report they read and in how they classify each order. + +#### V1 synchronization + +A full sync reads every order in the account. An incremental sync requests only orders placed on or after the date of the previous sync. The filter is a date only (`yyyy-MM-dd`) on the order date, with no lookback, so an older order that is slow to issue is missed by incremental syncs; run a full sync to import it. V2 avoids this with `V2SyncLookbackHours`. The one exception is the recent-order hold-back below, which moves the incremental start back by the hold window. + +```mermaid +flowchart TD + A([Command starts a sync]) --> B["Request the next page of orders from GetOrderReport
(PageSize per page, date filter when incremental)"] + B --> C{More orders on this page?} + C -- No more pages --> Z["Log totals and signal completion to the gateway"] + C -- Next order --> D{"IgnoreExpired is on and the expiry date
is known and past? (V1 never sets the
expiry date yet)"} + D -- Yes --> C + D -- No --> D2{"Order is pending or issued and younger than
SyncRecentOrderGraceSeconds?"} + D2 -- Yes --> C + D2 -- No --> D3{"Incremental sync, order is issued or revoked, and the
gateway already holds it with the same status and a body?"} + D3 -- Yes --> C + D3 -- No --> E{"Order is pending, DCV is enabled, a DNS provider is
available, and it is inside the age window and
per-pass cap?"} + E -- Yes --> F["Run DNS-01 DCV for the order
then refetch it if DCV ran"] + E -- No --> G + F --> G{Order failed, rejected,
or cancelled?} + G -- Yes --> C + G -- No --> H{"Issued or revoked,
and no certificate body in the listing?"} + H -- Yes --> I["Fetch the certificate (TrackOrder + download)
keeping the listing's subject, product, and order date"] + H -- No --> K + I --> K{"Revoked with no certificate body?"} + K -- No --> J["Emit the record to the gateway buffer
(issued with PEM, revoked, or pending)"] + K -- Yes --> L{"Gateway already holds a certificate
body for this order?"} + L -- Yes --> J + L -- "Row but no body" --> M["Emit as failed"] + L -- "No row" --> C + M --> C + J --> C +``` + +- **Errors.** If processing an order throws, the plugin logs and counts the error and moves on to the next order. After at least 50 records, if more than 25 percent have errored, the sync aborts and is retried on the next cycle instead of completing with mostly failed records. V2 synchronization applies the same rule. +- **Recent-order hold-back.** A pending or issued order created less than `SyncRecentOrderGraceSeconds` (default 120, plus a 5-second clock margin) ago is not emitted, and issued ones are not downloaded, so a sync cannot insert the gateway row an in-flight enrollment is about to save and make that enrollment fail with a duplicate key. The next incremental pass imports the order. To keep a held order created just before UTC midnight in that next listing, the incremental start date is moved back by the grace window, the 5-second margin, and 5 minutes of slack. Revoked and failed orders, and orders with no usable order date, are never held. `0` disables the hold. +- **Unchanged orders.** The listing filter is a calendar day, so an incremental sync re-lists every order placed that day. On an incremental sync, an order listed as issued or revoked is skipped, with no `TrackOrder` or certificate download, when the gateway already holds it with the same status and a stored certificate body. New orders, status changes (pending to issued, issued to revoked), rows stored without a body, and a failed or unavailable lookup are processed as before. Pending orders and full syncs are unchanged. The sync summary reports `UnchangedInGateway`. V2 does not do this yet. +- **Revoked orders without a certificate body.** The V1 client never downloads a revoked order's certificate, so a revoked order is emitted as revoked only if the gateway already holds the certificate body. If the gateway has the order's row but no body it is emitted as failed, and if the gateway has no row for it (or the check cannot be made) the order is skipped. See [Single-Record Retrieval](#single-record-retrieval). +- **Expired certificates.** `IgnoreExpired` is applied on V2 only. On V1 the order report never populates a certificate expiry date, so the setting has no effect yet and expired certificates are imported. +- **DCV during sync.** Pending orders go through DNS-01 validation only while younger than `DcvSyncMaxOrderAgeHours` (older orders are reported as pending and left alone) and only up to `DcvSyncMaxPerPass` orders per pass, so a backlog of stalled orders can't slow every sync. +- **DCV timing.** The V1 sync path uses a short fixed propagation delay and a single-shot challenge check rather than the longer `Enroll` waits. See [Domain Control Validation](#domain-control-validation). + +#### V2 synchronization + +With `UseV2Api = true`, Synchronize pages through V2 `/reports/orders` (at most 100 rows per page, scoped to `GroupNumber` when set). An incremental sync asks for orders from `V2SyncLookbackHours` (default 72) before the last sync date, because the report's date filter may bracket either the order date or the issuance date and a slow order must not be missed. + +```mermaid +flowchart TD + A([Command starts a sync]) --> B["Compute the start date
(none for a full sync, last sync minus V2SyncLookbackHours otherwise)"] + B --> C["Request the next page of /reports/orders"] + C --> D{More rows on this page?} + D -- No more pages --> Z["Log totals and signal completion to the gateway"] + D -- Next row --> E{"IgnoreExpired is on and the certificate
expiry date is in the past?"} + E -- Yes --> D + E -- No --> F["Map the report's order and certificate status strings"] + F --> G{Status recognized?} + G -- No --> H["Look up the order live and use its status"] + G -- Yes --> I + H --> I{Failed, rejected, or cancelled?} + I -- Yes --> D + I -- No --> J{"Pending, DCV is enabled, a DNS provider is available,
and inside the age window and per-pass cap?"} + J -- Yes --> K["Run DNS-01 DCV for the order
and re-read its status"] + J -- No --> L + K --> L{Issued?} + L -- Yes --> M["Download the certificate chain
(leaf plus intermediates)"] + L -- No --> N{Revoked?} + N -- Yes --> O["Look up revocation date and reason live"] + N -- No --> P + M --> P + O --> Q{"Gateway already holds a certificate
body for this order?"} + Q -- Yes --> P["Emit the record to the gateway buffer"] + Q -- "Row but no body" --> R["Emit as failed"] + Q -- "No row" --> D + R --> D + P --> D ``` ---- +### Single-Record Retrieval + +When Command asks for one order (`GetSingleRecord`), for example to refresh a pending certificate, the plugin looks the order up and, if it is still pending, tries to advance it through DNS-01 DCV first. + +| Step | V1 | V2 | +|---|---|---| +| Look up the order | `TrackOrder`, then `GetCertificate` when the order is downloadable | Find the product family that owns the order, then track it | +| Pending order | Run DCV, then refetch the certificate if DCV ran (a failed refetch is logged and the earlier result is returned) | Run DCV when the order lists a domain, bounded by `DcvTimeoutMinutes`, then track again (a DCV failure is logged and ignored) | +| Issued order | Certificate PEM from `GetCertificate` | Download the chain, leaf first (a failed download is logged and the record is returned without a body; a 422 `EMS-1165` right after `issued` means "not generated yet" and is logged at Information, not as a warning) | +| Revoked order with no certificate body | Status, date, and reason come from `TrackOrder`. Returned as revoked only if the gateway already holds the certificate body; otherwise returned as failed | Returned as revoked only if the gateway already holds the certificate body; otherwise returned as failed | + +The last row is the body-less revoked guard, which applies to both V1 and V2. CERTInext does not serve the body of a revoked order, and a body-less revoked record would break Command's revoked-certificate scans for the whole CA. `Synchronize` applies the same guard but skips the order when the gateway has no row for it, whereas `GetSingleRecord` must return something and so returns failed. + +### Domain Control Validation + +DNS-01 domain control validation (DCV) proves control of each domain on an order by publishing a TXT record that CERTInext then checks. The plugin publishes and removes the record through the DNS provider plugin the gateway resolves for the domain (`DcvEnabled`, on by default). -## Synchronization +- **Where DCV runs.** Inline during `Enroll`, during `Synchronize` for pending orders, and during `GetSingleRecord` for a pending order. +- **Where it never runs.** For an order that is already issued, revoked, cancelled, or rejected. V2 also skips Private PKI and Document Signer orders, which have no DCV step. +- **Record name.** The TXT record is published at `DcvTxtRecordTemplate` (default `_emsign-validation.{0}`), with `{0}` replaced by the domain. +- **Wildcards.** The `*.` label is stripped, so the record is published at the base domain, and a wildcard and its apex on the same order share one record. +- **Which domains.** V1 processes only domains CERTInext lists as pending that are unassigned or assigned to the DNS TXT method. V2 processes every domain that is not yet verified. +- **Skip and continue.** A domain that can't be staged (no DNS provider resolves it, the provider fails, or CERTInext returns no token) is logged and skipped so the other domains can still be validated. The order stays pending until the skipped domain is resolved. +- **Time bounds.** The whole flow for one order is bounded by `DcvTimeoutMinutes`. TXT records are always removed afterward, each removal bounded separately at 60 seconds. -Keyfactor Command periodically synchronizes its certificate inventory with CERTInext. The plugin retrieves all orders page by page and feeds them into Command's database. Synchronization can be a full refresh or incremental (only orders placed since the last successful sync). +#### V1 DCV ```mermaid sequenceDiagram - participant CMD as Keyfactor Command participant Plugin as CERTInext Plugin participant API as CERTInext API + participant DNS as DNS Provider Plugin - CMD->>Plugin: Start synchronization\n(full refresh or incremental since last sync) - Plugin->>Plugin: Determine date filter\n(none for full sync, last sync date for incremental) - - loop Retrieve one page at a time - Plugin->>API: Request next page of orders\n(filtered by date if incremental) - API-->>Plugin: Page of order records - - loop For each order on the page - alt Certificate is expired and ignore-expired is enabled - Plugin->>Plugin: Skip — not imported - else Order failed or was cancelled - Plugin->>Plugin: Skip — no certificate to import - else Valid certificate - Plugin->>CMD: Add certificate record to inventory + loop Until the challenge is exposed or DcvWaitForChallengeSeconds elapses + Plugin->>API: TrackOrder + API-->>Plugin: Status and domainVerification (may be empty at first) + end + alt Order already issued, revoked, cancelled, or rejected + Plugin->>Plugin: Skip DCV + else Challenge not exposed in time + Plugin->>Plugin: Defer to the next sync + else Every domain already validated + Plugin->>Plugin: Skip staging and go straight to the issuance wait + else Pending DNS TXT domains + loop Each pending domain + Plugin->>API: GetDcv (order, domain, DNS TXT method) + API-->>Plugin: Validation token + Plugin->>DNS: Publish TXT record (token) + end + Plugin->>Plugin: Wait DcvPropagationDelaySeconds + loop Each staged domain + Plugin->>API: VerifyDcv + end + loop Every 3 s until each domain shows dcvStatus 1 + Plugin->>API: TrackOrder + API-->>Plugin: Per-domain dcvStatus + end + Plugin->>DNS: Remove TXT records + opt Enroll only + loop Every 3 s up to DcvWaitForIssuanceSeconds + Plugin->>API: GetCertificate + API-->>Plugin: Status and certificate PEM when issued end end end - - Plugin->>Plugin: Log totals: imported / skipped / errors - Plugin-->>CMD: Synchronization complete ``` -**Full vs. incremental sync:** A full sync imports every order in the account regardless of age. An incremental sync requests only orders placed after the previous sync timestamp, which is faster for accounts with large order histories. +If `GetDcv` returns `EMS-956` (CERTInext lists the challenge before it accepts calls for the order), the whole pass is deferred to the next sync. On the sync and single-record paths the plugin refetches the certificate after DCV instead of running the issuance wait. -**Expired certificates:** The `IgnoreExpired` connector setting controls whether expired certificates are included in synchronization. When enabled, expired certificates are silently skipped and will not appear in the Keyfactor Command inventory. +#### V2 DCV ---- +```mermaid +sequenceDiagram + participant Plugin as CERTInext Plugin + participant API as CERTInext API (V2) + participant DNS as DNS Provider Plugin + + Note over Plugin: Runs when the SSL/TLS order is pending, DcvEnabled is true,
and a DNS provider is available + loop Each domain not yet VERIFIED (the primary domain only, if the order lists no per-domain state) + Plugin->>API: GET /ssl-certificates/{id}/dcv (per domain when the order lists several) + API-->>Plugin: Validation token (EMS-1080 means already verified) + Plugin->>DNS: Publish TXT record (token) + end + Plugin->>Plugin: Wait DcvPropagationDelaySeconds once for all domains + loop Each staged domain + Plugin->>API: POST /ssl-certificates/{id}/dcv/verify (domain, method dns-txt) + API-->>Plugin: overallStatus + end + loop Every 3 s until validated or DcvTimeoutMinutes elapses + Plugin->>API: GET /ssl-certificates/{id} + API-->>Plugin: Order status and per-domain dcvStatus + end + Plugin->>DNS: Remove TXT records +``` + +For an order that lists per-domain verification state (a multi-domain order, for example), every domain that is not yet `VERIFIED` is staged, with one propagation wait for the whole batch, and the poll waits until each verified domain shows `VERIFIED` (or `REJECTED`). For a single-domain order the poll waits for the status to leave `pending-dcv`, and if `verify` doesn't report `VERIFIED` the plugin removes the record and leaves the order pending. Either way, the next sync or `GetSingleRecord` call retries only the domains that are still unverified. -## Certificate Enrollment +### Certificate Enrollment -When a requester submits a certificate request through Keyfactor Command, the plugin translates the request into a CERTInext order and returns the result. The plugin handles three enrollment scenarios: new issuance, renewal (within a configured window before expiry), and reissuance (new keys, same profile). +When a requester submits a certificate request through Keyfactor Command, the plugin translates the request into a CERTInext order and returns the result. V1 and V2 follow different flows. V1 handles renewals specially (see [V1 renewal and RenewOrReissue](#v1-renewal-and-reneworreissue)), while V2 places a new order for every enrollment type. -### New Certificate or Reissuance +#### V1 enrollment (New or Reissue) ```mermaid sequenceDiagram @@ -467,53 +1231,151 @@ sequenceDiagram participant Plugin as CERTInext Plugin participant API as CERTInext API - CMD->>Plugin: Request new certificate\n(CSR, subject, SANs, product code, requester details) - Plugin->>Plugin: Validate product code is present - Plugin->>Plugin: Record enrollment intent in audit log\n(subject, SANs, product, requester — before any API call) + CMD->>Plugin: Enroll (CSR, subject, SANs, product code, requester details) + Plugin->>Plugin: Require a product code and log the enrollment intent
(requester personal data redacted by default) - Plugin->>API: Place certificate order\n(CSR, domain, organization details,\nsubscriber agreement, requestor info) - API-->>Plugin: Order accepted — order number assigned - - Plugin->>API: Check order status - API-->>Plugin: Order status and certificate details + Plugin->>API: GenerateOrderSSL (CSR inline, domain, organization,
subscriber agreement, requestor, technical contact) + API-->>Plugin: Order number assigned + Plugin->>API: TrackOrder + API-->>Plugin: Certificate status + opt Status is downloadable + Plugin->>API: GetCertificate + API-->>Plugin: Certificate PEM + end - alt Certificate issued immediately - Plugin-->>CMD: Certificate ready — PEM returned - else Certificate pending approval - Plugin-->>CMD: Pending — Command will pick it up\nduring the next synchronization - else Order rejected by CERTInext - Plugin-->>CMD: Enrollment failed — see gateway logs + alt DCV enabled and a DNS provider plugin is available + Plugin->>Plugin: Run V1 DCV and the post-DCV issuance wait
(see Domain Control Validation) + Note over Plugin: The pickup poll below is skipped,
because the DCV flow owns the issuance wait + else DCV off or unavailable + loop Pickup poll while the order is pending
PickupRetries attempts, PickupDelay apart, after a 5 s initial delay + Plugin->>API: GetCertificate + API-->>Plugin: Status and certificate PEM + end end - Plugin->>Plugin: Record enrollment outcome in audit log\n(order number, serial number, status) + alt Certificate issued with PEM + Plugin-->>CMD: Issued, PEM returned + else Still pending + Plugin-->>CMD: Pending, Command picks it up during the next synchronization + else Order failed or rejected + Plugin-->>CMD: Failed, see gateway logs + end + Plugin->>Plugin: Log the outcome (order number, serial number, status) ``` -### Renewal +- **Issued but not yet downloadable.** An order CERTInext reports as issued before the certificate can be downloaded is returned as pending, not as an issued result with no certificate. +- **OV and EV.** These orders issue after organization verification (minutes to hours) and almost always exhaust the pickup window, so the next synchronization imports them. +- **Rate limiting.** A rate-limit rejection (`Inactive Account User.`) on order placement is retried with backoff before the failure is surfaced. +- **Failures after the order is placed.** The order already exists at CERTInext, so a failed `TrackOrder` status check or a failed in-call DCV or issuance wait is logged as a warning and the enrollment returns pending with the order number. Failing instead would hide the order number from Command and let a retry place a duplicate paid order. A later synchronization finishes the order. +- **DCV that skips a domain.** If DCV validates some domains but skips others (for example an IP or email SAN with no DNS provider), the validated domains are still verified and cleaned up, but `Enroll` does not wait for issuance, because the order cannot issue yet. It returns pending and the sync-driven DCV retry picks the order up. +- **Synchronous pickup.** After placing an order, the plugin polls CERTInext up to `PickupRetries` times (default 5), `PickupDelay` seconds apart (default 10), after a fixed 5-second initial delay and within a hard ceiling of 75 seconds, which keeps the call inside Command's own enrollment timeout of about 100 seconds. This lets fast-issuing DV certificates come back in the same enrollment call; only a result with a certificate body counts as issued. + +#### V1 renewal and RenewOrReissue -When Command initiates a renewal, the plugin checks whether the existing certificate is within the configured renewal window. If it is, the prior order record is used as context for the new request. If it is outside the window (or the prior certificate cannot be located), the plugin falls back to issuing a new certificate. +When Command initiates a renewal, the plugin checks whether the prior certificate is within the configured renewal window. Inside the window it places a renewal order; outside the window, or when the prior certificate can't be found, it places a new order. -> **Note:** CERTInext does not have a dedicated certificate renewal endpoint. Both renewal and reissuance paths submit a new `GenerateOrderSSL` order. The distinction affects how Keyfactor Command tracks the certificate record, not what is sent to CERTInext. +> **Note:** CERTInext does not have a dedicated certificate renewal endpoint. Both paths submit a new `GenerateOrderSSL` order; the prior order is not revoked. The distinction determines how the request is built, not which endpoint is called. A renewal order does not run inline DCV; sync-driven DCV completes a pending DV renewal. With DCV enabled and a DNS provider available, a renewal that is still waiting on DNS-01 validation returns pending at once and skips the pickup poll, because the poll cannot succeed until the sync-driven DCV validates the domain. Other renewals keep the pickup poll. + +> **Note:** If the prior-order lookup itself throws (rather than cleanly returning "not found" — for example a transient database error), the plugin falls back to a new order rather than failing the enrollment. ```mermaid flowchart TD - A([Renewal requested]) --> B{Prior certificate\nserial number\nprovided?} - B -- No --> C[Issue new certificate] - B -- Yes --> D[Look up prior order\nin Command database] - D --> E{Prior order\nfound?} - E -- No --> C - E -- Yes --> F[Check certificate\nexpiry date] - F --> G{Within renewal\nwindow?} - G -- Yes\nwithin window --> H[Submit new order\nlinked to prior record] - G -- No\noutside window --> C - H --> I([Certificate issued or pending]) - C --> I + A([Renew or RenewOrReissue requested]) --> B{"Prior certificate serial number
(PriorCertSN) provided?"} + B -- No --> C["Place a new order
(same as a new enrollment)"] + B -- Yes --> D["Look up the prior order ID
in the Command database"] + D --> E{Prior order found?} + E -- "No, or lookup failed" --> C + E -- Yes --> F["Read the prior certificate's expiry date"] + F --> G{"Expiry is in the future and
within RenewalWindowDays?"} + G -- Yes --> H["Place a renewal order
(GenerateOrderSSL, prior order looked up first)"] + G -- "No: outside the window, already expired, or expiry unknown" --> C + H --> H2{"DCV enabled, order pending,
and a domain waiting on DNS-01?"} + H2 -- Yes --> J + H2 -- No --> I["Pickup poll
PickupRetries x PickupDelay"] + C --> J(["Issued, pending, or failed result
returned to Command"]) + I --> J ``` ---- +#### V2 enrollment flow + +With `UseV2Api = true`, every enrollment type (New, Reissue, Renew, RenewOrReissue) takes the same path and places a new order. The plugin checks the request locally first, so a template or request that can never succeed is rejected before any order is placed. + +```mermaid +flowchart TD + A([Enroll requested]) --> B["Log the enrollment intent"] + B --> C{"Request passes local checks?
family is ssl or private-pki, CSR present, SignerPlace set for SSL,
Private PKI variant set,
OrganizationNumber set for OV or EV,
valid subscription and notification settings"} + C -- No --> X1(["Enrollment rejected, no order placed"]) + C -- Yes --> D{Private PKI?} + D -- Yes --> G0 + D -- No --> E{"Explicit template ProductCode?"} + E -- Yes --> E1["Fetch the product catalog
to recognize UCC and wildcard products"] + E -- No --> E2["Detect UCC and wildcard from the request:
wildcard domain, UCC template product or extra DNS SANs"] + E1 --> F2{"Explicit non-UCC product with extra DNS SANs
in the CSR or SAN list?"} + E2 --> G0 + F2 -- Yes --> X3(["Failed result, no order placed"]) + F2 -- No --> G0{"SSL/TLS with V2InlineCsr on?
(Private PKI never)"} + G0 -- "No: two-call (V2InlineCsr false, or Private PKI)" --> G["Create the order without a CSR
(Idempotency-Key header, X-Product-Code only if the template sets ProductCode)"] + G0 -- "Yes: single call, the default" --> GI["Create the order with the CSR inline, unchanged
(Idempotency-Key header, X-Product-Code only if the template sets ProductCode)"] + GI --> GI2{"Create call answered?"} + GI2 -- "Rejected by the CA (HTTP 4xx)" --> X5a(["Enrollment fails, no order was created"]) + GI2 -- "5xx, timeout, or no response" --> X5b(["Enrollment fails with a do-not-resubmit message:
the order may exist and may issue, the next sync imports it"]) + GI2 -- "Yes, order ID returned" --> M["Track the order"] + G --> H["Submit the CSR unchanged
PUT /{family}/{id}/csr"] + H --> I{CSR accepted?} + I -- "Rejected by the CA (HTTP 4xx)" --> J["Cancel the orphaned order once"] + J --> X4(["Failed result carrying the order ID"]) + I -- "Transport error or timeout" --> K["Track the order"] + K --> L{"Still pending-csr?"} + L -- Yes --> J + L -- "Tracking failed" --> P1(["Pending result with the order ID,
next sync resolves it"]) + L -- "Moved past pending-csr" --> M + I -- Yes --> M + M --> M2{Tracking succeeded?} + M2 -- No --> P1 + M2 -- Yes --> N{"SSL order pending, DCV enabled,
and a DNS provider available?"} + N -- Yes --> O["Run V2 DCV, then track the order again"] + N -- No --> Q + O --> Q{Issued?} + Q -- Yes --> R["Download the certificate chain"] + R --> S{Download succeeded?} + S -- Yes --> T(["Issued result with the PEM chain"]) + S -- No --> U + Q -- No --> U{"Order still pending, and DCV did not
already wait inside this call?"} + U -- No --> W + U -- Yes --> V["Pickup poll
PickupRetries x PickupDelay
track, and download once issued"] + V --> W{"Order revoked at the CA
before a certificate was delivered?"} + W -- Yes --> X5(["Failed result"]) + W -- No --> P2(["Issued if the poll found the certificate, failed if the
order was rejected or cancelled, otherwise pending
and picked up by the next sync"]) +``` + +Notes on the V2 flow: + +- **Product code.** The spec makes `X-Product-Code` an optional override: CERTInext picks the catalog product itself from the variant, whether the domain is a wildcard (starts with `*.`), and whether `additionalDomains` is non-empty. So the plugin sends the header only when the template sets `ProductCode` (or the deprecated `ProfileId`), to choose between several matching catalog products. The connector's `DefaultProductCode` doesn't affect V2 orders. The create response's `resolvedProductCode` is logged at Information level. + - **With an explicit `ProductCode`,** the plugin fetches the live catalog once per enrollment, only to recognize multi-domain and wildcard products; if it can't be fetched, the order proceeds as single-domain, so a request with extra SANs is rejected rather than silently accepted. + - **Without one,** there is no catalog call. The order is a wildcard when the domain starts with `*.`. It is multi-domain when the selected product is a UCC product, or when the CSR or SAN list has DNS names beyond the primary domain (its `www.` variant, and a wildcard's bare apex, don't count); those names go out as `additionalDomains`, which is what makes CERTInext choose a UCC product. + + Private PKI never fetches the catalog. Its `ProductCode`, when set, was validated when the template was saved. +- **SSL.com organization validation (OV/EV).** Just before the create call, an OV or EV SSL/TLS order reads the organization's SSL.com validation status, refreshes it once if the order's level isn't validated, and, only when `SslComSubmitOrganization` is on and the organization is ready, submits it (accepting SSL.com's subscriber agreement on its behalf, audit-logged). This step is advisory: any failure or not-validated result logs a warning and the order is placed anyway. See [SSL.com organization validation](configuration.md#sslcom-organization-validation). +- **Multi-domain products.** DNS SANs other than the primary domain are sent as `additionalDomains`, and non-DNS SANs are left off the order with a warning. Private PKI sends DNS and IP SANs as `additionalHosts`. +- **CSR delivery (`V2InlineCsr`).** By default (`V2InlineCsr = true`, SSL/TLS) the CSR is sent inline in the create body exactly as Command supplied it, and there is no Submit CSR step (a `PUT .../csr` after an inline CSR is rejected with HTTP 422). The create call then often holds about 20 seconds until the certificate is issued, and the order ID is known only once it returns. If that call fails with a 5xx or times out, the order may still exist and issue: the failure message says so, the plugin doesn't cancel the order, and the next sync imports it. Private PKI ignores the setting and always uses two calls, because CERTInext rejects an inline CSR on the Private PKI create (HTTP 422). With `V2InlineCsr = false` the plugin creates the order without a CSR and then submits it with `PUT .../csr`, cancelling the orphaned order once if that submit is rejected. That two-call flow fails for a domain the account has already validated: CERTInext reports the order `issued` at create, before any CSR, and then rejects the submit with HTTP 422 "Something went Wrong". A blank CSR is rejected before any CA call. +- **Idempotency.** Order-create, revoke, and cancel calls carry a fresh `Idempotency-Key` UUID. The V2 spec documents that header only for Verify DCV and Domains, as parsed but not yet enforced. On order create, a same-key retry was observed to create a second order behind an HTTP 500, so the plugin never retries an order-create call, and the AnyCA Gateway doesn't retry a timed-out `Enroll`. If an operator resubmits after an order-create error, check the CERTInext portal for an order that was created anyway. +- **Revoked before delivery.** An order CERTInext reports as revoked before any certificate was delivered is returned as failed, never as a revoked record with no certificate. +- **Full certificate chain.** The V2 `/certificate` endpoint returns the leaf in `certificatePem` and intermediates in `chainPem[]`. The plugin concatenates them, leaf first, into one PEM. + +### Status Mapping + +CERTInext statuses map to the Keyfactor statuses Command understands as follows. This applies to enrollment, synchronization, single-record retrieval, and revocation pre-checks. The V2 status strings are listed under [V2 Order Lifecycle](#v2-order-lifecycle); V1 uses CERTInext's numeric certificate status codes. -## Revocation +| CERTInext | Command status | +|---|---| +| Issued, or expired but not revoked | Issued (an expired certificate stays in inventory) | +| Any pending state (approval, validation, CSR, agreement, documents, `unknown`) | Pending external validation | +| Revoked | Revoked | +| Rejected, cancelled, or an unrecognized status | Failed | + +### Revocation -When a certificate is revoked in Keyfactor Command, the plugin verifies the certificate's current state before calling the CERTInext revocation endpoint. This prevents unnecessary API calls for certificates that are already revoked or in a non-revocable state. +When a certificate is revoked in Keyfactor Command, the plugin verifies the certificate's current state before calling the CERTInext revocation endpoint. This prevents unnecessary API calls for certificates that are already revoked or in a non-revokable state. ```mermaid sequenceDiagram @@ -521,68 +1383,129 @@ sequenceDiagram participant Plugin as CERTInext Plugin participant API as CERTInext API - CMD->>Plugin: Revoke certificate\n(order number, serial number, reason code) - Plugin->>Plugin: Record revocation intent in audit log\n(order number, serial, reason — before any API call) + CMD->>Plugin: Revoke (order number, serial number, reason code) + Plugin->>Plugin: Log the revocation intent before any API call
(order number, serial, reason) - Plugin->>API: Retrieve current certificate status - API-->>Plugin: Current status and details + Plugin->>API: Retrieve the current order status
(V2: find which product family owns the order) + API-->>Plugin: Current status alt Certificate is already revoked - Plugin->>Plugin: Log warning — already revoked - Plugin-->>CMD: Confirmed revoked (no action needed) + Plugin->>Plugin: Log a warning, already revoked + Plugin-->>CMD: Confirmed revoked, no request sent else Certificate is not in an issued state - Plugin->>Plugin: Log error — cannot revoke - Plugin-->>CMD: Error — certificate is not revocable - else Certificate is issued and active - Plugin->>API: Submit revocation request\n(order number, reason, remarks) + Plugin->>Plugin: Log an error, cannot revoke + Plugin-->>CMD: Error, certificate is not revokable + else Certificate is issued + Plugin->>API: Revoke (order number, reason, remarks) + opt V2 only, reason in the rejected set and CERTInext replies 422 Invalid Revoke Reason ID + Plugin->>API: Revoke again, once, with the substitute reason + end API-->>Plugin: Revocation confirmed - - Plugin->>Plugin: Record revocation outcome in audit log\n(order number, serial, subject, reason) + Plugin->>Plugin: Log the outcome (order number, serial, reason) Plugin-->>CMD: Certificate revoked end ``` -**Idempotency:** If Command retries a revocation request (for example, after a timeout), the plugin detects that the certificate is already revoked and returns success without submitting a duplicate request to CERTInext. +- **Idempotency.** If Command retries a revocation (for example after a timeout), the plugin sees the certificate is already revoked and returns success without a duplicate request to CERTInext. +- **Audit trail.** The revocation intent is written to the gateway log *before* the API call, so it is recorded even if the call fails. +- **V2 not revokable.** A 404 from the V2 revoke endpoint means the order was not found or is not in a revokable state. The plugin has already located the order's product family, so it reports that plainly instead of probing the other families. +- **Note field.** CERTInext rejects a semicolon (`;`) in the revoke `note` (audit remarks) with a separate 422, "Invalid Revoke Remarks." Commas, periods, slashes, and parentheses are accepted. The plugin's generated notes avoid semicolons. -**Audit trail:** The revocation intent is written to the gateway log *before* the API call is made. This ensures that the intent is captured even if the API call subsequently fails, satisfying SOX audit requirements. +#### Revocation Reason Codes ---- +V1 sends a numeric `revokeReasonId`; V2 sends a kebab-case `reason` string. The plugin translates the RFC 5280 code Command supplies. -## Connector Validation +| Command reason (CRL code) | V1 sends | V2 sends | If CERTInext rejects it | +|---|---|---|---| +| Unspecified (0) | Key compromise (1) | `unspecified` | Rejected on V2; retried once as `cessation-of-operation` | +| Key compromise (1) | 1 | `key-compromise` | Accepted | +| CA compromise (2) | Key compromise (1) | `ca-compromise` | Rejected on V2; retried once as `key-compromise` | +| Affiliation changed (3) | 3 | `affiliation-changed` | Accepted | +| Superseded (4) | 4 | `superseded` | Accepted | +| Cessation of operation (5) | 5 | `cessation-of-operation` | Accepted | +| Certificate hold (6) | Key compromise (1) | `certificate-hold` | Rejected on V2; retried once as `cessation-of-operation` | +| Privilege withdrawn (9) | 9 | `privilege-withdrawn` | Accepted | +| AA compromise (10) | Key compromise (1) | `aa-compromise` | Rejected on V2; retried once as `key-compromise` | +| Any other code (for example 8, `removeFromCRL`) | Key compromise (1) | `unspecified` | Same as Unspecified | + +- **What CERTInext accepts.** Only key compromise (1), affiliation changed (3), superseded (4), cessation of operation (5), and privilege withdrawn (9), on both API generations. V1 never sends anything else, so it needs no retry. +- **V2 spec versus live behavior.** The V2 spec documents 8 reason values for the SSL/TLS revoke endpoint (`aa-compromise` is listed only for the Private PKI and Document Signer endpoints). Live, SSL/TLS orders reject four of the values, `unspecified`, `ca-compromise`, `certificate-hold`, and `aa-compromise`, with 422 "Invalid Revoke Reason ID". +- **Retry rule.** The plugin retries a rejected reason once with the substitute in the table; any other revoke failure is surfaced as-is. +- **Why `cessation-of-operation`.** It substitutes for `unspecified` and `certificate-hold` because neither implies a key compromise, and `key-compromise` carries the V2 spec's Baseline Requirements §4.9.1.1 24-hour CRL-turnaround obligation, which would misrepresent the revoke. `unspecified` is Command's default reason, so it is the most common revoke case. + +### Connector Validation When an administrator saves or edits a CERTInext CA connector in the Keyfactor Command Management Portal, the gateway validates the configuration and performs a live connectivity check. ```mermaid flowchart TD - A([Save connector configuration]) --> B{Connector\nmarked as disabled?} - B -- Yes --> C([Saved without validation\nConnector will not process requests]) - B -- No --> D{Required fields\npresent and valid?\nAPI URL · Account Number · Credentials} - D -- Missing or invalid --> E([Validation error shown to administrator]) - D -- Valid --> F[Build temporary API client\nfrom supplied settings] - F --> G[Send test request\nto CERTInext] - G --> H{API accepted\nthe credentials?} - H -- No --> I([Connection test failed\nCheck credentials and API URL]) - H -- Yes --> J([Connector saved and active]) + A([Save connector configuration]) --> B{Connector
marked as disabled?} + B -- Yes --> C(["Saved without validation
Connector will not process requests"]) + B -- No --> D{"ApiUrl present, and https
or a loopback host?"} + D -- No --> E(["Validation error shown to administrator"]) + D -- Yes --> F{UseV2Api?} + F -- "Yes (V2)" --> G{"OAuthClientId, OAuthClientSecret,
and SignerPlace present?"} + F -- "No (V1)" --> H{"AccountNumber and ApiKey present?
(connectors saved with the legacy OAuth
AuthMode are checked for OAuth fields instead)"} + G -- No --> E + H -- No --> E + G -- Yes --> I["Build a temporary API client
from the supplied settings"] + H -- Yes --> I + I --> J["Send a test request
V1: ValidateCredentials, V2: GET /auth/me"] + J --> K{API accepted
the credentials?} + K -- No --> L(["Connection test failed
Check credentials and API URL"]) + K -- Yes --> M(["Connector saved and active"]) ``` -**Disabled connectors:** Setting `Enabled` to `false` allows the connector record to be created and saved before credentials are available. The live connectivity test is skipped, so no credentials are required at save time. +**Disabled connectors:** setting `Enabled` to `false` allows the connector record to be created and saved before credentials are available. The live connectivity test is skipped, so no credentials are required at save time. + +The same https-or-loopback check runs again at gateway startup, so a connector saved with an `http` URL before the check existed fails to start until its URL is corrected. + +#### Template validation ---- +When an administrator saves a certificate template, the gateway asks the plugin to validate its product settings. On V1 the product code must be set (explicitly, or derived from the selected product) and appear in the CERTInext product list for the account. On V2: -## API Endpoint Reference +- an explicit `ProductCode` is optional; if set, it must exist in the live catalog and match the selected product's type, and no catalog check runs without one; +- an SSL template's `ProductVariant` must agree with the selected product; +- a Private PKI template needs a Private PKI `ProductVariant`, and its `ProductCode`, if set, must be a Private PKI catalog product. + +Any failure is shown to the administrator with the candidate codes or the field to fix. + +### API Endpoint Reference The table below maps each Keyfactor Command operation to the CERTInext API endpoint it calls. +**V1 endpoints (default)** + | Operation | CERTInext API endpoint | |---|---| | Test connection / verify credentials | `POST ValidateCredentials` | -| Issue new certificate | `POST GenerateOrderSSL` then `POST TrackOrder` | -| Renew certificate | `POST GenerateOrderSSL` then `POST TrackOrder` | +| Issue new certificate | `POST GenerateOrderSSL` (CSR inline), then `POST TrackOrder` and `POST GetCertificate` | +| Renew certificate | `POST TrackOrder` on the prior order, then `POST GenerateOrderSSL` as above | | Check certificate status | `POST TrackOrder` + `POST GetCertificate` | | Revoke certificate | `POST RevokeOrder` | | Synchronize inventory | `POST GetOrderReport` (paginated) | +| Domain control validation | `POST GetDcv`, `POST VerifyDcv` | | List available product codes | `POST GetProductDetails` | -| Attach CSR to draft order | `POST SubmitCSR` | +| Attach CSR to a draft order | `POST SubmitCSR` (developer tooling only; the plugin sends the CSR inline with `GenerateOrderSSL`) | + +**V2 endpoints (UseV2Api = true)** + +| Operation | V2 endpoint | +|---|---| +| Obtain Bearer token | `POST /oauth/token` | +| Test connection | `GET /api/certinext/v2/auth/me` | +| Create order | `POST /api/certinext/v2/{family}` (carries the CSR inline for SSL/TLS by default, `V2InlineCsr`) | +| Submit CSR | `PUT /api/certinext/v2/{family}/{orderId}/csr` (two-call flow: always for Private PKI, and SSL/TLS with `V2InlineCsr = false`) | +| Check order status | `GET /api/certinext/v2/{family}/{orderId}` | +| Get DCV challenge (SSL/TLS only) | `GET /api/certinext/v2/ssl-certificates/{orderId}/dcv` (with `?domain=` per domain) | +| Verify DCV (SSL/TLS only) | `POST /api/certinext/v2/ssl-certificates/{orderId}/dcv/verify` | +| Download certificate | `GET /api/certinext/v2/{family}/{orderId}/certificate` | +| Revoke certificate | `POST /api/certinext/v2/{family}/{orderId}/revoke` | +| Cancel an orphaned order | `POST /api/certinext/v2/{family}/{orderId}/cancel` | +| List available products | `GET /api/certinext/v2/catalog/products` | +| Synchronize inventory | `GET /api/certinext/v2/reports/orders` (paginated) | + +`{family}` is `ssl-certificates`, `private-pki-certificates`, or `signature-certificates`. The plugin finds the family that owns an existing order by tracking it in each family in that order. ## License diff --git a/docs/reference/README.md b/docs/reference/README.md index dca29a6..febe58e 100644 --- a/docs/reference/README.md +++ b/docs/reference/README.md @@ -8,16 +8,13 @@ in [`QUICKSTART.md`](../../QUICKSTART.md)). ## Source -Generated from the `kfclab` localhost-kind reference lab on -2026-05-22 via: - -``` -kfclab snapshot -f examples/localhost-kind/kfclab.yaml --out /tmp/snap -``` - -Then trimmed to the CERTInext-relevant subset, with sensitive fields -either already masked by the upstream API (`ClientSecret`) or omitted -entirely (no access keys, no PAM literals). +Captured on 2026-05-22 from a local reference lab (a single-node +Kubernetes deployment of Command, the AnyCA REST Gateway, and an OIDC +identity provider), then trimmed to the CERTInext-relevant subset. +Sensitive fields are either already masked by the upstream API +(`ClientSecret`) or omitted entirely (no access keys, no PAM literals). +Hostnames and identity-provider values in the files are lab-specific +examples; replace them with your own. ## Layout @@ -34,16 +31,22 @@ docs/reference/ ## `gateway/certificate-profiles.json` -Eight profiles, one per CERTInext sandbox product. Each carries the -same `key_algs` block — the canonical "permit RSA 2048–8192 + ECDSA -P-256/384/521 + Ed25519/Ed448" policy. Match this `key_algs` shape on -new profiles to avoid Command's misleading `0xA0110004` "Key type -disallowed by policy" error. +Eight profiles, covering eight of the ten advertised products (the +non-EV ones). Each carries the same `key_algs` block, which is the lab's +deliberately broad policy: -> **Note:** The gateway profile defines what Command permits; CERTInext itself only -> accepts RSA 2048/3072/4096 and ECC P-256/P-384. Orders using P-521, Ed25519, -> Ed448, or RSA larger than 4096 bits are accepted by Command but rejected by -> CERTInext with `Invalid key size`. +| Algorithm | Permitted in this capture | Accepted by CERTInext | +|---|---|---| +| RSA | 2048, 3072, 4096, 6144, 8192 | 2048, 3072, 4096 only | +| ECDSA | P-256, P-384, P-521 | P-256, P-384 only | +| Ed25519 / Ed448 | Both | Neither | + +Always include a populated `key_algs` block on new profiles, or Command +reports a misleading `0xA0110004` "Key type disallowed by policy" error. +Do **not** copy this capture's broad policy. The gateway profile defines +what Command permits; CERTInext rejects the extra key types with +`Invalid key size`. The recommended, narrower policy is in +[QUICKSTART step 2](../../QUICKSTART.md#key-algorithm-policy). The profiles **don't** carry CA-binding information; they're top-level gateway resources. The CA configuration's `Templates[].CertificateProfile` @@ -52,11 +55,10 @@ field is what binds a product to its profile by name. ## `gateway/claims.json` The gateway authorisation table. Each row maps an OIDC subject (token -`sub`) to a gateway role. The lab seeds these on every -`init-gateway`: +`sub`) to a gateway role. The lab has three entries: -- Two for the gateway's own machine client (admin + user — defensive) -- One for `akadmin` (the Authentik admin's `nameClaimType=sub`) +- Two for the gateway's own machine client (admin + user, defensive) +- One for the identity provider's admin user (`akadmin` in this lab) Production deployments add per-operator entries here. There are no secrets in this file. @@ -74,9 +76,15 @@ Read-only fields populated by Command (e.g. `Id`, `LastSyncTime`, ## `command/templates-certinext.json` The eight Command templates created by `POST /KeyfactorAPI/Templates/Import` -(`ConfigurationTenant=certinext-caplugin`). Each is a 1-to-1 mapping -of a CERTInext sandbox product → a Command template named -`AnyCA_` and tied back to the CA by `ConfigurationTenant`. +(`ConfigurationTenant=certinext-caplugin`). Each maps one non-EV +CERTInext product to one Command template and is tied back to the CA +by `ConfigurationTenant`. + +| Field | Value | Example | +|---|---|---| +| `CommonName` | `AnyCA_` | `AnyCA_DV SSL` | +| `TemplateName` / `DisplayName` | `AnyCA ()` | `AnyCA (DV SSL)` | + Useful as a sanity check after running step 5 of the quickstart: the template count and `CommonName` set should match this file (modulo `Id` churn). diff --git a/docsource/architecture.md b/docsource/architecture.md index 93ac459..77696da 100644 --- a/docsource/architecture.md +++ b/docsource/architecture.md @@ -1,12 +1,12 @@ ## Architecture -This document describes how the CERTInext AnyCA Gateway REST plugin integrates with Keyfactor Command and the CERTInext certificate authority. It covers the three primary certificate lifecycle operations — synchronization, enrollment, and revocation — and how the plugin routes each through the CERTInext API. +This document describes how the CERTInext AnyCA Gateway REST plugin integrates with Keyfactor Command and the CERTInext certificate authority. It covers the primary certificate lifecycle operations — synchronization, enrollment, domain control validation, and revocation — for both CERTInext API generations (V1 and V2), and how the plugin routes each one. -## Component Overview +### Component Overview -``` +```text ┌─────────────────────────────────────────────────────────┐ -│ Keyfactor Command │ +│ Keyfactor Command │ │ │ │ Certificate Enrollment · Revocation · Sync Jobs │ └────────────────────────────┬────────────────────────────┘ @@ -15,49 +15,79 @@ This document describes how the CERTInext AnyCA Gateway REST plugin integrates w (plugin host process) │ ┌────────────────────────────▼────────────────────────────┐ -│ CERTInext AnyCA Gateway Plugin │ +│ CERTInext AnyCA Gateway Plugin │ │ │ │ Translates Keyfactor operations into CERTInext API │ │ calls, maps responses back to Command's data model, │ -│ and enforces audit logging on every operation. │ +│ publishes DNS-01 validation records through the │ +│ gateway's DNS provider plugin, and logs every │ +│ operation. │ └────────────────────────────┬────────────────────────────┘ - │ HTTPS · HMAC-signed requests + │ HTTPS · AccessKey (V1) or OAuth2 bearer │ ┌────────────────────────────▼────────────────────────────┐ -│ CERTInext REST API (eMudhra) │ +│ CERTInext REST API (eMudhra) │ +│ │ +│ V1 ValidateCredentials · GenerateOrderSSL │ +│ TrackOrder · GetCertificate · GetOrderReport │ +│ RevokeOrder · GetProductDetails │ +│ GetDcv · VerifyDcv │ │ │ -│ ValidateCredentials GenerateOrderSSL TrackOrder │ -│ GetCertificate RevokeOrder GetOrderReport │ -│ GetProductDetails SubmitCSR │ +│ V2 POST /oauth/token · GET /auth/me │ +│ GET /catalog/products · GET /reports/orders │ +│ POST /{family} create order │ +│ PUT /{family}/{id}/csr (two-call; Private PKI) │ +│ GET /{family}/{id} track order │ +│ GET /{family}/{id}/certificate │ +│ GET /ssl-certificates/{id}/dcv │ +│ POST /ssl-certificates/{id}/dcv/verify │ +│ POST /{family}/{id}/revoke · POST .../cancel │ └─────────────────────────────────────────────────────────┘ ``` -## Request Authentication +`{family}` is `ssl-certificates`, `private-pki-certificates`, or `signature-certificates` (see the [API Endpoint Reference](#api-endpoint-reference)). -Every API call is signed using HMAC-SHA256. The access key itself is never transmitted — only a derived hash is sent: +### V1 and V2 at a Glance -``` -authKey = SHA256(accessKey + requestTs + requestTxnId) -``` +`UseV2Api` selects one API generation for the whole connector; the two cannot be mixed. + +| Aspect | V1 (default) | V2 (`UseV2Api` = `true`) | +|---|---|---| +| Authentication | Access key, sent as `meta.authKey` | OAuth2 `client_credentials` bearer token | +| `ApiUrl` | Includes the `/emSignHub-API/` path | Bare host, no path | +| Order ID (`CARequestID`) | Order number (a request number comes first) | Single `orderId`, stored unchanged | +| Sync source | `GetOrderReport`, filtered by order date (`yyyy-MM-dd`), no lookback | `/reports/orders`, from `V2SyncLookbackHours` (default 72) before the last sync | +| `IgnoreExpired` | Not applied yet | Applied | +| Renewal | Renewal window (`RenewalWindowDays`), otherwise a new order | Every enrollment type places a new order | +| DCV waits | `DcvWaitForChallengeSeconds`, `DcvWaitForIssuanceSeconds` | None; polls until the order leaves `pending-dcv`, bounded by `DcvTimeoutMinutes` | +| Revoke reasons | Numeric `revokeReasonId`; unaccepted codes sent as key compromise | Kebab-case strings; four rejected values retried once with a substitute | +| Product code | `ProductCode`, then `ProfileId`, then the built-in default for the selected product | None sent by default: CERTInext resolves the product. An explicit template `ProductCode` is sent as the `X-Product-Code` override | + +### Request Authentication -A unique transaction ID (`requestTxnId`) is generated for each request. The timestamp (`requestTs`) and transaction ID travel alongside the `authKey` so the CERTInext server can reproduce and verify the hash. The plugin handles this automatically; no manual signing is required during normal operation. +| Mode | Credential | Sent as | `meta.authKey` | +|---|---|---|---| +| V1 | Access key (`ApiKey`) and `AccountNumber` | A `meta` block in every JSON request body (`ver`, `ts`, `txn`, `accountNumber`, `authKey`) | `SHA256(accessKey + ts + txn)` as lowercase hex | +| V2 (`UseV2Api` = `true`) | OAuth2 client ID and secret (`OAuthClientId`, `OAuthClientSecret`) | `Authorization: Bearer` header; the token comes from `POST {ApiUrl}/oauth/token` (`client_credentials`, form-encoded) | Not used | -An OAuth client-credentials mode is also available as an alternative. When OAuth is configured, the plugin exchanges a client ID and secret for a short-lived bearer token and automatically refreshes it before expiry. +- **V1 `authKey`.** A plain SHA-256 digest, not an HMAC. The access key is never transmitted; only the digest is sent. `ts` is a timestamp and `txn` is a random numeric transaction ID generated for each request, and both travel in `meta` so CERTInext can recompute the digest. The plugin does this automatically. +- **V2 tokens.** The plugin caches the bearer token until 60 seconds before the expiry the token endpoint reports (minimum 30 seconds), and refreshes it thread-safely. +- **V1 OAuth is unsupported.** The `AuthMode=OAuth` and `OAuthTokenUrl` settings are legacy: the live V1 API ignores a bearer token and rejects the call with 401 "clientAccessKey is not active". The code still accepts them for connectors that were already saved with that mode. -## Certificate Identifiers +### Certificate Identifiers -CERTInext assigns two different reference numbers to each order. Understanding the difference matters when tracing certificates across systems: +V1 assigns two different reference numbers to each order. Understanding the difference matters when tracing certificates across systems: | Identifier | When it is assigned | What it is used for | |---|---|---| | **Request Number** | Immediately when an order is created | Tracking a draft order before it is formally submitted; attaching a CSR to a pending order | | **Order Number** | After the order is formally submitted and accepted | All post-issuance operations: checking status, downloading the certificate, revoking — **this is the identifier stored in Keyfactor Command** | ---- +V2 returns a single `orderId` when the order is created, and the plugin stores it unchanged as the `CARequestID`. V2 order IDs are numeric, in the same format as V1 order numbers; see [Behavioral Differences After Migrating](#behavioral-differences-after-migrating). -## Gateway Startup +### Gateway Startup -When the AnyCA Gateway process starts, it loads each configured CA connector. For CERTInext, this step reads the connector settings, establishes the API client, and confirms that the credentials are structurally valid. +When the AnyCA Gateway process starts, it loads each configured CA connector. For CERTInext, this step reads the connector settings, checks that the API URLs are acceptable, and builds the API client. Credentials are validated separately, when an administrator saves the connector (see [Connector Validation](#connector-validation)). ```mermaid sequenceDiagram @@ -65,61 +95,212 @@ sequenceDiagram participant Plugin as CERTInext Plugin participant API as CERTInext API - GW->>Plugin: Load CA connector configuration - Plugin->>Plugin: Validate required fields\n(API URL, account number, credentials) - Plugin->>Plugin: Initialize API client\nwith configured auth mode - Plugin->>Plugin: Record which credential fields are populated\n(values are never logged) - GW->>Plugin: Test connection - Plugin->>API: Verify credentials - API-->>Plugin: Credentials accepted - Plugin-->>GW: Connector ready + GW->>Plugin: Initialize with the CA connector configuration + Plugin->>Plugin: Require ApiUrl and reject http unless the host is loopback + Plugin->>Plugin: Build the API client
for the configured API generation + Plugin->>Plugin: Log which credential fields are populated
(values are never logged) + opt DcvEnabled is true but no DNS provider factory was injected + Plugin->>Plugin: Log a warning: DCV will be skipped + end + opt LogSensitiveRequestData is true + Plugin->>Plugin: Log a warning that personal data
and request payloads will be logged + end + GW->>Plugin: Ping + alt Connector disabled + Plugin-->>GW: Skipped, connector is disabled + else V1 + Plugin->>API: ValidateCredentials + API-->>Plugin: Credentials accepted + Plugin-->>GW: Connector ready + else V2 + Plugin->>API: GET /auth/me (after obtaining a bearer token) + API-->>Plugin: Account details + Plugin-->>GW: Connector ready + end +``` + +### Synchronization + +Keyfactor Command periodically synchronizes its certificate inventory with CERTInext. The plugin retrieves orders page by page and feeds them into Command's database. Synchronization can be a full refresh or incremental. V1 and V2 differ in the report they read and in how they classify each order. + +#### V1 synchronization + +A full sync reads every order in the account. An incremental sync requests only orders placed on or after the date of the previous sync. The filter is a date only (`yyyy-MM-dd`) on the order date, with no lookback, so an older order that is slow to issue is missed by incremental syncs; run a full sync to import it. V2 avoids this with `V2SyncLookbackHours`. The one exception is the recent-order hold-back below, which moves the incremental start back by the hold window. + +```mermaid +flowchart TD + A([Command starts a sync]) --> B["Request the next page of orders from GetOrderReport
(PageSize per page, date filter when incremental)"] + B --> C{More orders on this page?} + C -- No more pages --> Z["Log totals and signal completion to the gateway"] + C -- Next order --> D{"IgnoreExpired is on and the expiry date
is known and past? (V1 never sets the
expiry date yet)"} + D -- Yes --> C + D -- No --> D2{"Order is pending or issued and younger than
SyncRecentOrderGraceSeconds?"} + D2 -- Yes --> C + D2 -- No --> D3{"Incremental sync, order is issued or revoked, and the
gateway already holds it with the same status and a body?"} + D3 -- Yes --> C + D3 -- No --> E{"Order is pending, DCV is enabled, a DNS provider is
available, and it is inside the age window and
per-pass cap?"} + E -- Yes --> F["Run DNS-01 DCV for the order
then refetch it if DCV ran"] + E -- No --> G + F --> G{Order failed, rejected,
or cancelled?} + G -- Yes --> C + G -- No --> H{"Issued or revoked,
and no certificate body in the listing?"} + H -- Yes --> I["Fetch the certificate (TrackOrder + download)
keeping the listing's subject, product, and order date"] + H -- No --> K + I --> K{"Revoked with no certificate body?"} + K -- No --> J["Emit the record to the gateway buffer
(issued with PEM, revoked, or pending)"] + K -- Yes --> L{"Gateway already holds a certificate
body for this order?"} + L -- Yes --> J + L -- "Row but no body" --> M["Emit as failed"] + L -- "No row" --> C + M --> C + J --> C ``` ---- +- **Errors.** If processing an order throws, the plugin logs and counts the error and moves on to the next order. After at least 50 records, if more than 25 percent have errored, the sync aborts and is retried on the next cycle instead of completing with mostly failed records. V2 synchronization applies the same rule. +- **Recent-order hold-back.** A pending or issued order created less than `SyncRecentOrderGraceSeconds` (default 120, plus a 5-second clock margin) ago is not emitted, and issued ones are not downloaded, so a sync cannot insert the gateway row an in-flight enrollment is about to save and make that enrollment fail with a duplicate key. The next incremental pass imports the order. To keep a held order created just before UTC midnight in that next listing, the incremental start date is moved back by the grace window, the 5-second margin, and 5 minutes of slack. Revoked and failed orders, and orders with no usable order date, are never held. `0` disables the hold. +- **Unchanged orders.** The listing filter is a calendar day, so an incremental sync re-lists every order placed that day. On an incremental sync, an order listed as issued or revoked is skipped, with no `TrackOrder` or certificate download, when the gateway already holds it with the same status and a stored certificate body. New orders, status changes (pending to issued, issued to revoked), rows stored without a body, and a failed or unavailable lookup are processed as before. Pending orders and full syncs are unchanged. The sync summary reports `UnchangedInGateway`. V2 does not do this yet. +- **Revoked orders without a certificate body.** The V1 client never downloads a revoked order's certificate, so a revoked order is emitted as revoked only if the gateway already holds the certificate body. If the gateway has the order's row but no body it is emitted as failed, and if the gateway has no row for it (or the check cannot be made) the order is skipped. See [Single-Record Retrieval](#single-record-retrieval). +- **Expired certificates.** `IgnoreExpired` is applied on V2 only. On V1 the order report never populates a certificate expiry date, so the setting has no effect yet and expired certificates are imported. +- **DCV during sync.** Pending orders go through DNS-01 validation only while younger than `DcvSyncMaxOrderAgeHours` (older orders are reported as pending and left alone) and only up to `DcvSyncMaxPerPass` orders per pass, so a backlog of stalled orders can't slow every sync. +- **DCV timing.** The V1 sync path uses a short fixed propagation delay and a single-shot challenge check rather than the longer `Enroll` waits. See [Domain Control Validation](#domain-control-validation). -## Synchronization +#### V2 synchronization -Keyfactor Command periodically synchronizes its certificate inventory with CERTInext. The plugin retrieves all orders page by page and feeds them into Command's database. Synchronization can be a full refresh or incremental (only orders placed since the last successful sync). +With `UseV2Api = true`, Synchronize pages through V2 `/reports/orders` (at most 100 rows per page, scoped to `GroupNumber` when set). An incremental sync asks for orders from `V2SyncLookbackHours` (default 72) before the last sync date, because the report's date filter may bracket either the order date or the issuance date and a slow order must not be missed. + +```mermaid +flowchart TD + A([Command starts a sync]) --> B["Compute the start date
(none for a full sync, last sync minus V2SyncLookbackHours otherwise)"] + B --> C["Request the next page of /reports/orders"] + C --> D{More rows on this page?} + D -- No more pages --> Z["Log totals and signal completion to the gateway"] + D -- Next row --> E{"IgnoreExpired is on and the certificate
expiry date is in the past?"} + E -- Yes --> D + E -- No --> F["Map the report's order and certificate status strings"] + F --> G{Status recognized?} + G -- No --> H["Look up the order live and use its status"] + G -- Yes --> I + H --> I{Failed, rejected, or cancelled?} + I -- Yes --> D + I -- No --> J{"Pending, DCV is enabled, a DNS provider is available,
and inside the age window and per-pass cap?"} + J -- Yes --> K["Run DNS-01 DCV for the order
and re-read its status"] + J -- No --> L + K --> L{Issued?} + L -- Yes --> M["Download the certificate chain
(leaf plus intermediates)"] + L -- No --> N{Revoked?} + N -- Yes --> O["Look up revocation date and reason live"] + N -- No --> P + M --> P + O --> Q{"Gateway already holds a certificate
body for this order?"} + Q -- Yes --> P["Emit the record to the gateway buffer"] + Q -- "Row but no body" --> R["Emit as failed"] + Q -- "No row" --> D + R --> D + P --> D +``` + +### Single-Record Retrieval + +When Command asks for one order (`GetSingleRecord`), for example to refresh a pending certificate, the plugin looks the order up and, if it is still pending, tries to advance it through DNS-01 DCV first. + +| Step | V1 | V2 | +|---|---|---| +| Look up the order | `TrackOrder`, then `GetCertificate` when the order is downloadable | Find the product family that owns the order, then track it | +| Pending order | Run DCV, then refetch the certificate if DCV ran (a failed refetch is logged and the earlier result is returned) | Run DCV when the order lists a domain, bounded by `DcvTimeoutMinutes`, then track again (a DCV failure is logged and ignored) | +| Issued order | Certificate PEM from `GetCertificate` | Download the chain, leaf first (a failed download is logged and the record is returned without a body; a 422 `EMS-1165` right after `issued` means "not generated yet" and is logged at Information, not as a warning) | +| Revoked order with no certificate body | Status, date, and reason come from `TrackOrder`. Returned as revoked only if the gateway already holds the certificate body; otherwise returned as failed | Returned as revoked only if the gateway already holds the certificate body; otherwise returned as failed | + +The last row is the body-less revoked guard, which applies to both V1 and V2. CERTInext does not serve the body of a revoked order, and a body-less revoked record would break Command's revoked-certificate scans for the whole CA. `Synchronize` applies the same guard but skips the order when the gateway has no row for it, whereas `GetSingleRecord` must return something and so returns failed. + +### Domain Control Validation + +DNS-01 domain control validation (DCV) proves control of each domain on an order by publishing a TXT record that CERTInext then checks. The plugin publishes and removes the record through the DNS provider plugin the gateway resolves for the domain (`DcvEnabled`, on by default). + +- **Where DCV runs.** Inline during `Enroll`, during `Synchronize` for pending orders, and during `GetSingleRecord` for a pending order. +- **Where it never runs.** For an order that is already issued, revoked, cancelled, or rejected. V2 also skips Private PKI and Document Signer orders, which have no DCV step. +- **Record name.** The TXT record is published at `DcvTxtRecordTemplate` (default `_emsign-validation.{0}`), with `{0}` replaced by the domain. +- **Wildcards.** The `*.` label is stripped, so the record is published at the base domain, and a wildcard and its apex on the same order share one record. +- **Which domains.** V1 processes only domains CERTInext lists as pending that are unassigned or assigned to the DNS TXT method. V2 processes every domain that is not yet verified. +- **Skip and continue.** A domain that can't be staged (no DNS provider resolves it, the provider fails, or CERTInext returns no token) is logged and skipped so the other domains can still be validated. The order stays pending until the skipped domain is resolved. +- **Time bounds.** The whole flow for one order is bounded by `DcvTimeoutMinutes`. TXT records are always removed afterward, each removal bounded separately at 60 seconds. + +#### V1 DCV ```mermaid sequenceDiagram - participant CMD as Keyfactor Command participant Plugin as CERTInext Plugin participant API as CERTInext API + participant DNS as DNS Provider Plugin - CMD->>Plugin: Start synchronization\n(full refresh or incremental since last sync) - Plugin->>Plugin: Determine date filter\n(none for full sync, last sync date for incremental) - - loop Retrieve one page at a time - Plugin->>API: Request next page of orders\n(filtered by date if incremental) - API-->>Plugin: Page of order records - - loop For each order on the page - alt Certificate is expired and ignore-expired is enabled - Plugin->>Plugin: Skip — not imported - else Order failed or was cancelled - Plugin->>Plugin: Skip — no certificate to import - else Valid certificate - Plugin->>CMD: Add certificate record to inventory + loop Until the challenge is exposed or DcvWaitForChallengeSeconds elapses + Plugin->>API: TrackOrder + API-->>Plugin: Status and domainVerification (may be empty at first) + end + alt Order already issued, revoked, cancelled, or rejected + Plugin->>Plugin: Skip DCV + else Challenge not exposed in time + Plugin->>Plugin: Defer to the next sync + else Every domain already validated + Plugin->>Plugin: Skip staging and go straight to the issuance wait + else Pending DNS TXT domains + loop Each pending domain + Plugin->>API: GetDcv (order, domain, DNS TXT method) + API-->>Plugin: Validation token + Plugin->>DNS: Publish TXT record (token) + end + Plugin->>Plugin: Wait DcvPropagationDelaySeconds + loop Each staged domain + Plugin->>API: VerifyDcv + end + loop Every 3 s until each domain shows dcvStatus 1 + Plugin->>API: TrackOrder + API-->>Plugin: Per-domain dcvStatus + end + Plugin->>DNS: Remove TXT records + opt Enroll only + loop Every 3 s up to DcvWaitForIssuanceSeconds + Plugin->>API: GetCertificate + API-->>Plugin: Status and certificate PEM when issued end end end - - Plugin->>Plugin: Log totals: imported / skipped / errors - Plugin-->>CMD: Synchronization complete ``` -**Full vs. incremental sync:** A full sync imports every order in the account regardless of age. An incremental sync requests only orders placed after the previous sync timestamp, which is faster for accounts with large order histories. +If `GetDcv` returns `EMS-956` (CERTInext lists the challenge before it accepts calls for the order), the whole pass is deferred to the next sync. On the sync and single-record paths the plugin refetches the certificate after DCV instead of running the issuance wait. -**Expired certificates:** The `IgnoreExpired` connector setting controls whether expired certificates are included in synchronization. When enabled, expired certificates are silently skipped and will not appear in the Keyfactor Command inventory. +#### V2 DCV ---- +```mermaid +sequenceDiagram + participant Plugin as CERTInext Plugin + participant API as CERTInext API (V2) + participant DNS as DNS Provider Plugin + + Note over Plugin: Runs when the SSL/TLS order is pending, DcvEnabled is true,
and a DNS provider is available + loop Each domain not yet VERIFIED (the primary domain only, if the order lists no per-domain state) + Plugin->>API: GET /ssl-certificates/{id}/dcv (per domain when the order lists several) + API-->>Plugin: Validation token (EMS-1080 means already verified) + Plugin->>DNS: Publish TXT record (token) + end + Plugin->>Plugin: Wait DcvPropagationDelaySeconds once for all domains + loop Each staged domain + Plugin->>API: POST /ssl-certificates/{id}/dcv/verify (domain, method dns-txt) + API-->>Plugin: overallStatus + end + loop Every 3 s until validated or DcvTimeoutMinutes elapses + Plugin->>API: GET /ssl-certificates/{id} + API-->>Plugin: Order status and per-domain dcvStatus + end + Plugin->>DNS: Remove TXT records +``` + +For an order that lists per-domain verification state (a multi-domain order, for example), every domain that is not yet `VERIFIED` is staged, with one propagation wait for the whole batch, and the poll waits until each verified domain shows `VERIFIED` (or `REJECTED`). For a single-domain order the poll waits for the status to leave `pending-dcv`, and if `verify` doesn't report `VERIFIED` the plugin removes the record and leaves the order pending. Either way, the next sync or `GetSingleRecord` call retries only the domains that are still unverified. -## Certificate Enrollment +### Certificate Enrollment -When a requester submits a certificate request through Keyfactor Command, the plugin translates the request into a CERTInext order and returns the result. The plugin handles three enrollment scenarios: new issuance, renewal (within a configured window before expiry), and reissuance (new keys, same profile). +When a requester submits a certificate request through Keyfactor Command, the plugin translates the request into a CERTInext order and returns the result. V1 and V2 follow different flows. V1 handles renewals specially (see [V1 renewal and RenewOrReissue](#v1-renewal-and-reneworreissue)), while V2 places a new order for every enrollment type. -### New Certificate or Reissuance +#### V1 enrollment (New or Reissue) ```mermaid sequenceDiagram @@ -127,53 +308,151 @@ sequenceDiagram participant Plugin as CERTInext Plugin participant API as CERTInext API - CMD->>Plugin: Request new certificate\n(CSR, subject, SANs, product code, requester details) - Plugin->>Plugin: Validate product code is present - Plugin->>Plugin: Record enrollment intent in audit log\n(subject, SANs, product, requester — before any API call) + CMD->>Plugin: Enroll (CSR, subject, SANs, product code, requester details) + Plugin->>Plugin: Require a product code and log the enrollment intent
(requester personal data redacted by default) - Plugin->>API: Place certificate order\n(CSR, domain, organization details,\nsubscriber agreement, requestor info) - API-->>Plugin: Order accepted — order number assigned - - Plugin->>API: Check order status - API-->>Plugin: Order status and certificate details + Plugin->>API: GenerateOrderSSL (CSR inline, domain, organization,
subscriber agreement, requestor, technical contact) + API-->>Plugin: Order number assigned + Plugin->>API: TrackOrder + API-->>Plugin: Certificate status + opt Status is downloadable + Plugin->>API: GetCertificate + API-->>Plugin: Certificate PEM + end - alt Certificate issued immediately - Plugin-->>CMD: Certificate ready — PEM returned - else Certificate pending approval - Plugin-->>CMD: Pending — Command will pick it up\nduring the next synchronization - else Order rejected by CERTInext - Plugin-->>CMD: Enrollment failed — see gateway logs + alt DCV enabled and a DNS provider plugin is available + Plugin->>Plugin: Run V1 DCV and the post-DCV issuance wait
(see Domain Control Validation) + Note over Plugin: The pickup poll below is skipped,
because the DCV flow owns the issuance wait + else DCV off or unavailable + loop Pickup poll while the order is pending
PickupRetries attempts, PickupDelay apart, after a 5 s initial delay + Plugin->>API: GetCertificate + API-->>Plugin: Status and certificate PEM + end end - Plugin->>Plugin: Record enrollment outcome in audit log\n(order number, serial number, status) + alt Certificate issued with PEM + Plugin-->>CMD: Issued, PEM returned + else Still pending + Plugin-->>CMD: Pending, Command picks it up during the next synchronization + else Order failed or rejected + Plugin-->>CMD: Failed, see gateway logs + end + Plugin->>Plugin: Log the outcome (order number, serial number, status) ``` -### Renewal +- **Issued but not yet downloadable.** An order CERTInext reports as issued before the certificate can be downloaded is returned as pending, not as an issued result with no certificate. +- **OV and EV.** These orders issue after organization verification (minutes to hours) and almost always exhaust the pickup window, so the next synchronization imports them. +- **Rate limiting.** A rate-limit rejection (`Inactive Account User.`) on order placement is retried with backoff before the failure is surfaced. +- **Failures after the order is placed.** The order already exists at CERTInext, so a failed `TrackOrder` status check or a failed in-call DCV or issuance wait is logged as a warning and the enrollment returns pending with the order number. Failing instead would hide the order number from Command and let a retry place a duplicate paid order. A later synchronization finishes the order. +- **DCV that skips a domain.** If DCV validates some domains but skips others (for example an IP or email SAN with no DNS provider), the validated domains are still verified and cleaned up, but `Enroll` does not wait for issuance, because the order cannot issue yet. It returns pending and the sync-driven DCV retry picks the order up. +- **Synchronous pickup.** After placing an order, the plugin polls CERTInext up to `PickupRetries` times (default 5), `PickupDelay` seconds apart (default 10), after a fixed 5-second initial delay and within a hard ceiling of 75 seconds, which keeps the call inside Command's own enrollment timeout of about 100 seconds. This lets fast-issuing DV certificates come back in the same enrollment call; only a result with a certificate body counts as issued. + +#### V1 renewal and RenewOrReissue + +When Command initiates a renewal, the plugin checks whether the prior certificate is within the configured renewal window. Inside the window it places a renewal order; outside the window, or when the prior certificate can't be found, it places a new order. + +> **Note:** CERTInext does not have a dedicated certificate renewal endpoint. Both paths submit a new `GenerateOrderSSL` order; the prior order is not revoked. The distinction determines how the request is built, not which endpoint is called. A renewal order does not run inline DCV; sync-driven DCV completes a pending DV renewal. With DCV enabled and a DNS provider available, a renewal that is still waiting on DNS-01 validation returns pending at once and skips the pickup poll, because the poll cannot succeed until the sync-driven DCV validates the domain. Other renewals keep the pickup poll. + +> **Note:** If the prior-order lookup itself throws (rather than cleanly returning "not found" — for example a transient database error), the plugin falls back to a new order rather than failing the enrollment. + +```mermaid +flowchart TD + A([Renew or RenewOrReissue requested]) --> B{"Prior certificate serial number
(PriorCertSN) provided?"} + B -- No --> C["Place a new order
(same as a new enrollment)"] + B -- Yes --> D["Look up the prior order ID
in the Command database"] + D --> E{Prior order found?} + E -- "No, or lookup failed" --> C + E -- Yes --> F["Read the prior certificate's expiry date"] + F --> G{"Expiry is in the future and
within RenewalWindowDays?"} + G -- Yes --> H["Place a renewal order
(GenerateOrderSSL, prior order looked up first)"] + G -- "No: outside the window, already expired, or expiry unknown" --> C + H --> H2{"DCV enabled, order pending,
and a domain waiting on DNS-01?"} + H2 -- Yes --> J + H2 -- No --> I["Pickup poll
PickupRetries x PickupDelay"] + C --> J(["Issued, pending, or failed result
returned to Command"]) + I --> J +``` -When Command initiates a renewal, the plugin checks whether the existing certificate is within the configured renewal window. If it is, the prior order record is used as context for the new request. If it is outside the window (or the prior certificate cannot be located), the plugin falls back to issuing a new certificate. +#### V2 enrollment flow -> **Note:** CERTInext does not have a dedicated certificate renewal endpoint. Both renewal and reissuance paths submit a new `GenerateOrderSSL` order. The distinction affects how Keyfactor Command tracks the certificate record, not what is sent to CERTInext. +With `UseV2Api = true`, every enrollment type (New, Reissue, Renew, RenewOrReissue) takes the same path and places a new order. The plugin checks the request locally first, so a template or request that can never succeed is rejected before any order is placed. ```mermaid flowchart TD - A([Renewal requested]) --> B{Prior certificate\nserial number\nprovided?} - B -- No --> C[Issue new certificate] - B -- Yes --> D[Look up prior order\nin Command database] - D --> E{Prior order\nfound?} - E -- No --> C - E -- Yes --> F[Check certificate\nexpiry date] - F --> G{Within renewal\nwindow?} - G -- Yes\nwithin window --> H[Submit new order\nlinked to prior record] - G -- No\noutside window --> C - H --> I([Certificate issued or pending]) - C --> I + A([Enroll requested]) --> B["Log the enrollment intent"] + B --> C{"Request passes local checks?
family is ssl or private-pki, CSR present, SignerPlace set for SSL,
Private PKI variant set,
OrganizationNumber set for OV or EV,
valid subscription and notification settings"} + C -- No --> X1(["Enrollment rejected, no order placed"]) + C -- Yes --> D{Private PKI?} + D -- Yes --> G0 + D -- No --> E{"Explicit template ProductCode?"} + E -- Yes --> E1["Fetch the product catalog
to recognize UCC and wildcard products"] + E -- No --> E2["Detect UCC and wildcard from the request:
wildcard domain, UCC template product or extra DNS SANs"] + E1 --> F2{"Explicit non-UCC product with extra DNS SANs
in the CSR or SAN list?"} + E2 --> G0 + F2 -- Yes --> X3(["Failed result, no order placed"]) + F2 -- No --> G0{"SSL/TLS with V2InlineCsr on?
(Private PKI never)"} + G0 -- "No: two-call (V2InlineCsr false, or Private PKI)" --> G["Create the order without a CSR
(Idempotency-Key header, X-Product-Code only if the template sets ProductCode)"] + G0 -- "Yes: single call, the default" --> GI["Create the order with the CSR inline, unchanged
(Idempotency-Key header, X-Product-Code only if the template sets ProductCode)"] + GI --> GI2{"Create call answered?"} + GI2 -- "Rejected by the CA (HTTP 4xx)" --> X5a(["Enrollment fails, no order was created"]) + GI2 -- "5xx, timeout, or no response" --> X5b(["Enrollment fails with a do-not-resubmit message:
the order may exist and may issue, the next sync imports it"]) + GI2 -- "Yes, order ID returned" --> M["Track the order"] + G --> H["Submit the CSR unchanged
PUT /{family}/{id}/csr"] + H --> I{CSR accepted?} + I -- "Rejected by the CA (HTTP 4xx)" --> J["Cancel the orphaned order once"] + J --> X4(["Failed result carrying the order ID"]) + I -- "Transport error or timeout" --> K["Track the order"] + K --> L{"Still pending-csr?"} + L -- Yes --> J + L -- "Tracking failed" --> P1(["Pending result with the order ID,
next sync resolves it"]) + L -- "Moved past pending-csr" --> M + I -- Yes --> M + M --> M2{Tracking succeeded?} + M2 -- No --> P1 + M2 -- Yes --> N{"SSL order pending, DCV enabled,
and a DNS provider available?"} + N -- Yes --> O["Run V2 DCV, then track the order again"] + N -- No --> Q + O --> Q{Issued?} + Q -- Yes --> R["Download the certificate chain"] + R --> S{Download succeeded?} + S -- Yes --> T(["Issued result with the PEM chain"]) + S -- No --> U + Q -- No --> U{"Order still pending, and DCV did not
already wait inside this call?"} + U -- No --> W + U -- Yes --> V["Pickup poll
PickupRetries x PickupDelay
track, and download once issued"] + V --> W{"Order revoked at the CA
before a certificate was delivered?"} + W -- Yes --> X5(["Failed result"]) + W -- No --> P2(["Issued if the poll found the certificate, failed if the
order was rejected or cancelled, otherwise pending
and picked up by the next sync"]) ``` ---- +Notes on the V2 flow: + +- **Product code.** The spec makes `X-Product-Code` an optional override: CERTInext picks the catalog product itself from the variant, whether the domain is a wildcard (starts with `*.`), and whether `additionalDomains` is non-empty. So the plugin sends the header only when the template sets `ProductCode` (or the deprecated `ProfileId`), to choose between several matching catalog products. The connector's `DefaultProductCode` doesn't affect V2 orders. The create response's `resolvedProductCode` is logged at Information level. + - **With an explicit `ProductCode`,** the plugin fetches the live catalog once per enrollment, only to recognize multi-domain and wildcard products; if it can't be fetched, the order proceeds as single-domain, so a request with extra SANs is rejected rather than silently accepted. + - **Without one,** there is no catalog call. The order is a wildcard when the domain starts with `*.`. It is multi-domain when the selected product is a UCC product, or when the CSR or SAN list has DNS names beyond the primary domain (its `www.` variant, and a wildcard's bare apex, don't count); those names go out as `additionalDomains`, which is what makes CERTInext choose a UCC product. + + Private PKI never fetches the catalog. Its `ProductCode`, when set, was validated when the template was saved. +- **SSL.com organization validation (OV/EV).** Just before the create call, an OV or EV SSL/TLS order reads the organization's SSL.com validation status, refreshes it once if the order's level isn't validated, and, only when `SslComSubmitOrganization` is on and the organization is ready, submits it (accepting SSL.com's subscriber agreement on its behalf, audit-logged). This step is advisory: any failure or not-validated result logs a warning and the order is placed anyway. See [SSL.com organization validation](configuration.md#sslcom-organization-validation). +- **Multi-domain products.** DNS SANs other than the primary domain are sent as `additionalDomains`, and non-DNS SANs are left off the order with a warning. Private PKI sends DNS and IP SANs as `additionalHosts`. +- **CSR delivery (`V2InlineCsr`).** By default (`V2InlineCsr = true`, SSL/TLS) the CSR is sent inline in the create body exactly as Command supplied it, and there is no Submit CSR step (a `PUT .../csr` after an inline CSR is rejected with HTTP 422). The create call then often holds about 20 seconds until the certificate is issued, and the order ID is known only once it returns. If that call fails with a 5xx or times out, the order may still exist and issue: the failure message says so, the plugin doesn't cancel the order, and the next sync imports it. Private PKI ignores the setting and always uses two calls, because CERTInext rejects an inline CSR on the Private PKI create (HTTP 422). With `V2InlineCsr = false` the plugin creates the order without a CSR and then submits it with `PUT .../csr`, cancelling the orphaned order once if that submit is rejected. That two-call flow fails for a domain the account has already validated: CERTInext reports the order `issued` at create, before any CSR, and then rejects the submit with HTTP 422 "Something went Wrong". A blank CSR is rejected before any CA call. +- **Idempotency.** Order-create, revoke, and cancel calls carry a fresh `Idempotency-Key` UUID. The V2 spec documents that header only for Verify DCV and Domains, as parsed but not yet enforced. On order create, a same-key retry was observed to create a second order behind an HTTP 500, so the plugin never retries an order-create call, and the AnyCA Gateway doesn't retry a timed-out `Enroll`. If an operator resubmits after an order-create error, check the CERTInext portal for an order that was created anyway. +- **Revoked before delivery.** An order CERTInext reports as revoked before any certificate was delivered is returned as failed, never as a revoked record with no certificate. +- **Full certificate chain.** The V2 `/certificate` endpoint returns the leaf in `certificatePem` and intermediates in `chainPem[]`. The plugin concatenates them, leaf first, into one PEM. + +### Status Mapping + +CERTInext statuses map to the Keyfactor statuses Command understands as follows. This applies to enrollment, synchronization, single-record retrieval, and revocation pre-checks. The V2 status strings are listed under [V2 Order Lifecycle](#v2-order-lifecycle); V1 uses CERTInext's numeric certificate status codes. -## Revocation +| CERTInext | Command status | +|---|---| +| Issued, or expired but not revoked | Issued (an expired certificate stays in inventory) | +| Any pending state (approval, validation, CSR, agreement, documents, `unknown`) | Pending external validation | +| Revoked | Revoked | +| Rejected, cancelled, or an unrecognized status | Failed | + +### Revocation -When a certificate is revoked in Keyfactor Command, the plugin verifies the certificate's current state before calling the CERTInext revocation endpoint. This prevents unnecessary API calls for certificates that are already revoked or in a non-revocable state. +When a certificate is revoked in Keyfactor Command, the plugin verifies the certificate's current state before calling the CERTInext revocation endpoint. This prevents unnecessary API calls for certificates that are already revoked or in a non-revokable state. ```mermaid sequenceDiagram @@ -181,65 +460,126 @@ sequenceDiagram participant Plugin as CERTInext Plugin participant API as CERTInext API - CMD->>Plugin: Revoke certificate\n(order number, serial number, reason code) - Plugin->>Plugin: Record revocation intent in audit log\n(order number, serial, reason — before any API call) + CMD->>Plugin: Revoke (order number, serial number, reason code) + Plugin->>Plugin: Log the revocation intent before any API call
(order number, serial, reason) - Plugin->>API: Retrieve current certificate status - API-->>Plugin: Current status and details + Plugin->>API: Retrieve the current order status
(V2: find which product family owns the order) + API-->>Plugin: Current status alt Certificate is already revoked - Plugin->>Plugin: Log warning — already revoked - Plugin-->>CMD: Confirmed revoked (no action needed) + Plugin->>Plugin: Log a warning, already revoked + Plugin-->>CMD: Confirmed revoked, no request sent else Certificate is not in an issued state - Plugin->>Plugin: Log error — cannot revoke - Plugin-->>CMD: Error — certificate is not revocable - else Certificate is issued and active - Plugin->>API: Submit revocation request\n(order number, reason, remarks) + Plugin->>Plugin: Log an error, cannot revoke + Plugin-->>CMD: Error, certificate is not revokable + else Certificate is issued + Plugin->>API: Revoke (order number, reason, remarks) + opt V2 only, reason in the rejected set and CERTInext replies 422 Invalid Revoke Reason ID + Plugin->>API: Revoke again, once, with the substitute reason + end API-->>Plugin: Revocation confirmed - - Plugin->>Plugin: Record revocation outcome in audit log\n(order number, serial, subject, reason) + Plugin->>Plugin: Log the outcome (order number, serial, reason) Plugin-->>CMD: Certificate revoked end ``` -**Idempotency:** If Command retries a revocation request (for example, after a timeout), the plugin detects that the certificate is already revoked and returns success without submitting a duplicate request to CERTInext. +- **Idempotency.** If Command retries a revocation (for example after a timeout), the plugin sees the certificate is already revoked and returns success without a duplicate request to CERTInext. +- **Audit trail.** The revocation intent is written to the gateway log *before* the API call, so it is recorded even if the call fails. +- **V2 not revokable.** A 404 from the V2 revoke endpoint means the order was not found or is not in a revokable state. The plugin has already located the order's product family, so it reports that plainly instead of probing the other families. +- **Note field.** CERTInext rejects a semicolon (`;`) in the revoke `note` (audit remarks) with a separate 422, "Invalid Revoke Remarks." Commas, periods, slashes, and parentheses are accepted. The plugin's generated notes avoid semicolons. + +#### Revocation Reason Codes -**Audit trail:** The revocation intent is written to the gateway log *before* the API call is made. This ensures that the intent is captured even if the API call subsequently fails, satisfying SOX audit requirements. +V1 sends a numeric `revokeReasonId`; V2 sends a kebab-case `reason` string. The plugin translates the RFC 5280 code Command supplies. ---- +| Command reason (CRL code) | V1 sends | V2 sends | If CERTInext rejects it | +|---|---|---|---| +| Unspecified (0) | Key compromise (1) | `unspecified` | Rejected on V2; retried once as `cessation-of-operation` | +| Key compromise (1) | 1 | `key-compromise` | Accepted | +| CA compromise (2) | Key compromise (1) | `ca-compromise` | Rejected on V2; retried once as `key-compromise` | +| Affiliation changed (3) | 3 | `affiliation-changed` | Accepted | +| Superseded (4) | 4 | `superseded` | Accepted | +| Cessation of operation (5) | 5 | `cessation-of-operation` | Accepted | +| Certificate hold (6) | Key compromise (1) | `certificate-hold` | Rejected on V2; retried once as `cessation-of-operation` | +| Privilege withdrawn (9) | 9 | `privilege-withdrawn` | Accepted | +| AA compromise (10) | Key compromise (1) | `aa-compromise` | Rejected on V2; retried once as `key-compromise` | +| Any other code (for example 8, `removeFromCRL`) | Key compromise (1) | `unspecified` | Same as Unspecified | -## Connector Validation +- **What CERTInext accepts.** Only key compromise (1), affiliation changed (3), superseded (4), cessation of operation (5), and privilege withdrawn (9), on both API generations. V1 never sends anything else, so it needs no retry. +- **V2 spec versus live behavior.** The V2 spec documents 8 reason values for the SSL/TLS revoke endpoint (`aa-compromise` is listed only for the Private PKI and Document Signer endpoints). Live, SSL/TLS orders reject four of the values, `unspecified`, `ca-compromise`, `certificate-hold`, and `aa-compromise`, with 422 "Invalid Revoke Reason ID". +- **Retry rule.** The plugin retries a rejected reason once with the substitute in the table; any other revoke failure is surfaced as-is. +- **Why `cessation-of-operation`.** It substitutes for `unspecified` and `certificate-hold` because neither implies a key compromise, and `key-compromise` carries the V2 spec's Baseline Requirements §4.9.1.1 24-hour CRL-turnaround obligation, which would misrepresent the revoke. `unspecified` is Command's default reason, so it is the most common revoke case. + +### Connector Validation When an administrator saves or edits a CERTInext CA connector in the Keyfactor Command Management Portal, the gateway validates the configuration and performs a live connectivity check. ```mermaid flowchart TD - A([Save connector configuration]) --> B{Connector\nmarked as disabled?} - B -- Yes --> C([Saved without validation\nConnector will not process requests]) - B -- No --> D{Required fields\npresent and valid?\nAPI URL · Account Number · Credentials} - D -- Missing or invalid --> E([Validation error shown to administrator]) - D -- Valid --> F[Build temporary API client\nfrom supplied settings] - F --> G[Send test request\nto CERTInext] - G --> H{API accepted\nthe credentials?} - H -- No --> I([Connection test failed\nCheck credentials and API URL]) - H -- Yes --> J([Connector saved and active]) + A([Save connector configuration]) --> B{Connector
marked as disabled?} + B -- Yes --> C(["Saved without validation
Connector will not process requests"]) + B -- No --> D{"ApiUrl present, and https
or a loopback host?"} + D -- No --> E(["Validation error shown to administrator"]) + D -- Yes --> F{UseV2Api?} + F -- "Yes (V2)" --> G{"OAuthClientId, OAuthClientSecret,
and SignerPlace present?"} + F -- "No (V1)" --> H{"AccountNumber and ApiKey present?
(connectors saved with the legacy OAuth
AuthMode are checked for OAuth fields instead)"} + G -- No --> E + H -- No --> E + G -- Yes --> I["Build a temporary API client
from the supplied settings"] + H -- Yes --> I + I --> J["Send a test request
V1: ValidateCredentials, V2: GET /auth/me"] + J --> K{API accepted
the credentials?} + K -- No --> L(["Connection test failed
Check credentials and API URL"]) + K -- Yes --> M(["Connector saved and active"]) ``` -**Disabled connectors:** Setting `Enabled` to `false` allows the connector record to be created and saved before credentials are available. The live connectivity test is skipped, so no credentials are required at save time. +**Disabled connectors:** setting `Enabled` to `false` allows the connector record to be created and saved before credentials are available. The live connectivity test is skipped, so no credentials are required at save time. + +The same https-or-loopback check runs again at gateway startup, so a connector saved with an `http` URL before the check existed fails to start until its URL is corrected. + +#### Template validation + +When an administrator saves a certificate template, the gateway asks the plugin to validate its product settings. On V1 the product code must be set (explicitly, or derived from the selected product) and appear in the CERTInext product list for the account. On V2: + +- an explicit `ProductCode` is optional; if set, it must exist in the live catalog and match the selected product's type, and no catalog check runs without one; +- an SSL template's `ProductVariant` must agree with the selected product; +- a Private PKI template needs a Private PKI `ProductVariant`, and its `ProductCode`, if set, must be a Private PKI catalog product. ---- +Any failure is shown to the administrator with the candidate codes or the field to fix. -## API Endpoint Reference +### API Endpoint Reference The table below maps each Keyfactor Command operation to the CERTInext API endpoint it calls. +**V1 endpoints (default)** + | Operation | CERTInext API endpoint | |---|---| | Test connection / verify credentials | `POST ValidateCredentials` | -| Issue new certificate | `POST GenerateOrderSSL` then `POST TrackOrder` | -| Renew certificate | `POST GenerateOrderSSL` then `POST TrackOrder` | +| Issue new certificate | `POST GenerateOrderSSL` (CSR inline), then `POST TrackOrder` and `POST GetCertificate` | +| Renew certificate | `POST TrackOrder` on the prior order, then `POST GenerateOrderSSL` as above | | Check certificate status | `POST TrackOrder` + `POST GetCertificate` | | Revoke certificate | `POST RevokeOrder` | | Synchronize inventory | `POST GetOrderReport` (paginated) | +| Domain control validation | `POST GetDcv`, `POST VerifyDcv` | | List available product codes | `POST GetProductDetails` | -| Attach CSR to draft order | `POST SubmitCSR` | +| Attach CSR to a draft order | `POST SubmitCSR` (developer tooling only; the plugin sends the CSR inline with `GenerateOrderSSL`) | + +**V2 endpoints (UseV2Api = true)** + +| Operation | V2 endpoint | +|---|---| +| Obtain Bearer token | `POST /oauth/token` | +| Test connection | `GET /api/certinext/v2/auth/me` | +| Create order | `POST /api/certinext/v2/{family}` (carries the CSR inline for SSL/TLS by default, `V2InlineCsr`) | +| Submit CSR | `PUT /api/certinext/v2/{family}/{orderId}/csr` (two-call flow: always for Private PKI, and SSL/TLS with `V2InlineCsr = false`) | +| Check order status | `GET /api/certinext/v2/{family}/{orderId}` | +| Get DCV challenge (SSL/TLS only) | `GET /api/certinext/v2/ssl-certificates/{orderId}/dcv` (with `?domain=` per domain) | +| Verify DCV (SSL/TLS only) | `POST /api/certinext/v2/ssl-certificates/{orderId}/dcv/verify` | +| Download certificate | `GET /api/certinext/v2/{family}/{orderId}/certificate` | +| Revoke certificate | `POST /api/certinext/v2/{family}/{orderId}/revoke` | +| Cancel an orphaned order | `POST /api/certinext/v2/{family}/{orderId}/cancel` | +| List available products | `GET /api/certinext/v2/catalog/products` | +| Synchronize inventory | `GET /api/certinext/v2/reports/orders` (paginated) | + +`{family}` is `ssl-certificates`, `private-pki-certificates`, or `signature-certificates`. The plugin finds the family that owns an existing order by tracking it in each family in that order. diff --git a/docsource/configuration.md b/docsource/configuration.md index 41c872e..02c5b69 100644 --- a/docsource/configuration.md +++ b/docsource/configuration.md @@ -4,50 +4,82 @@ The CERTInext AnyCA Gateway REST plugin extends the certificate lifecycle capabi * CA Synchronization: * Download all certificates issued through the CERTInext CA, either as a full inventory or incrementally since the last sync. - * Expired certificates can optionally be excluded from synchronization using the `IgnoreExpired` configuration flag. + * Expired certificates can optionally be excluded from synchronization using the `IgnoreExpired` configuration flag (V2 only; the V1 API does not currently apply it). * Certificate Enrollment for profiles configured in CERTInext: * New certificate enrollment (new keys and certificate). - * Certificate renewal — submits a new `GenerateOrderSSL` order when the prior certificate is within the configured renewal window (CERTInext has no dedicated renewal endpoint; the renewal-window check governs how Command tracks old→new, not which API is called). + * Certificate renewal — on the V1 API, submits a new `GenerateOrderSSL` order when the prior certificate is within the configured renewal window (CERTInext has no dedicated renewal endpoint; the renewal-window check governs how Command tracks old→new, not which API is called). On the V2 API every renewal places a new order. * Certificate reissuance (new keys with the same or updated subject/SANs) when outside the renewal window or no prior certificate is found. + * Synchronous certificate pickup — a fast-issuing order (DV, or already-approved) can return the certificate in the same enrollment call instead of always waiting for the next sync, via `PickupRetries`/`PickupDelay`. + * DNS-01 domain control validation (DCV) — the plugin publishes the validation TXT record through a DNS provider plugin deployed on the gateway and asks CERTInext to verify it, during enrollment and during synchronization (`DcvEnabled`, on by default). * Certificate Revocation: - * Request revocation of a previously issued certificate using any RFC 5280 CRL reason code. + * Request revocation of a previously issued certificate using RFC 5280 reason codes, mapped to the reasons CERTInext accepts (see [Revocation Reason Codes](#revocation-reason-codes)). * Supported authentication modes for calls to the CERTInext API: - * AccessKey (HMAC-based request signing) — the primary and recommended mode - * OAuth (bearer token via client credentials flow) + * V1 API (default): AccessKey — SHA-256 signed requests. + * V2 API: OAuth2 `client_credentials` bearer token. +* Two CERTInext API generations, selected per connector with `UseV2Api`: the V1 API (default) and the order-centric V2 REST API, which adds Private PKI products. See [V2 API](#v2-api) and [Migrating from V1 to V2](#migrating-from-v1-to-v2). ## Requirements -* Keyfactor Command 25.5.x or later -* AnyCA Gateway REST framework version 25.5.0 or later +* Keyfactor Command 25.5 or later +* AnyCA Gateway REST framework version 26.2.0 or later +* A DNS provider plugin deployed on the AnyCA Gateway if the connector validates domains with DNS-01 DCV (the default; see `DcvEnabled`) * A CERTInext account with API access enabled and at least one certificate product configured * Network connectivity from the AnyCA Gateway host to the CERTInext API endpoint for your region (see table below) * The AnyCA Gateway host must trust the TLS certificate presented by the CERTInext API endpoint +### Compatibility and Authentication Matrix + +The connector runs in one of two modes, chosen with `UseV2Api`. The mode decides the `ApiUrl` shape, how the plugin authenticates, and which credential fields are used. + +| | V1 (default) | V2 (`UseV2Api` = `true`) | +|---|---|---| +| AnyCA Gateway REST / `IAnyCAPlugin` | 26.2.0 or later / 3.3.0 | 26.2.0 or later / 3.3.0 | +| Authentication | AccessKey (SHA-256 signed request body) | OAuth2 `client_credentials` bearer token | +| `ApiUrl` shape | `https:///emSignHub-API/` | Bare host, for example `https://us-api.certinext.io` | +| Token URL | None | Derived: `{ApiUrl}/oauth/token` | +| `AccountNumber` | Required | Ignored | +| `ApiKey` | Required | Ignored | +| `AuthMode` | Optional; leave as `AccessKey` (legacy field) | Ignored | +| `OAuthClientId` / `OAuthClientSecret` | Not used (legacy only) | Required | +| `OAuthTokenUrl` | Not used (legacy only) | Ignored | +| `SignerPlace` | Set it; sent on every order | Required at save | +| Products | SSL/TLS (DV, OV, EV) | SSL/TLS (DV, OV, EV) and Private PKI | +| DCV | On by default; needs a DNS provider plugin | On by default; needs a DNS provider plugin | + ### CERTInext Environments CERTInext operates three separate environments. Use the sandbox environment for initial integration testing. Switch to a production environment only after all functionality has been verified. -| Environment | Portal Sign-in URL | API Base URL | -|---|---|---| -| Sandbox | https://sandbox-us.certinext.io/ | `https://sandbox-us-api.certinext.io/emSignHub-API/` | -| Production — India (Global) | https://in.certinext.io/ | `https://api.certinext.io/emSignHub-API/` | -| Production — US | https://us.certinext.io/ | `https://us-api.certinext.io/emSignHub-API/` | +| Environment | Portal Sign-in URL | V1 API Base URL | V2 API Base URL | +|---|---|---|---| +| Sandbox | https://sandbox-us.certinext.io/ | `https://sandbox-us-api.certinext.io/emSignHub-API/` | `https://sandbox-us-api.certinext.io` | +| Production — India (Global) | https://in.certinext.io/ | `https://api.certinext.io/emSignHub-API/` | `https://api.certinext.io` | +| Production — US | https://us.certinext.io/ | `https://us-api.certinext.io/emSignHub-API/` | `https://us-api.certinext.io` | > Note: Product codes differ between sandbox and production. Always confirm product codes from the GetProductDetails API call against the environment you are targeting before going live. ## CERTInext API Setup -### AccessKey (HMAC) — the primary auth mode +The credentials you create in the CERTInext portal depend on the API generation the connector uses. + +| Mode | API | Where credentials go | Fields required | +|---|---|---|---| +| AccessKey | V1 (default) | `authKey` in the `meta` block of every request body. There is no `Authorization` header. | `AccountNumber`, `ApiKey` | +| OAuth2 client credentials | V2 (`UseV2Api` = `true`) | `Authorization: Bearer` header. The token comes from `{ApiUrl}/oauth/token`. | `OAuthClientId`, `OAuthClientSecret`, `SignerPlace` | -The CERTInext REST API uses HMAC-style request signing. Every API call includes a computed `authKey` field in the request body. The access key itself is never transmitted — only the derived hash is sent. +> Note: V1 OAuth is not supported. The live V1 API ignores a bearer token and answers HTTP 401 (`clientAccessKey is not active`) whether or not one is sent. The `AuthMode` and `OAuthTokenUrl` fields remain only so connectors saved with them keep loading. Leave `AuthMode` as `AccessKey`. -The `authKey` is computed as: +### AccessKey (SHA-256 signed requests) — V1 + +The V1 API signs every request. Each call includes a computed `authKey` field in the `meta` block of the request body. The access key itself is never transmitted — only the derived hash is sent. + +The `authKey` is a plain SHA-256 digest (not an HMAC), computed as: ``` -authKey = SHA256(accessKey + requestTs + requestTxnId) +authKey = SHA256(accessKey + ts + txn) ``` -Where `requestTs` is the ISO 8601 timestamp of the request and `requestTxnId` is the unique transaction ID generated per request. The gateway performs this computation automatically on every outbound API call. +Where `ts` is the ISO 8601 timestamp of the request and `txn` is the unique transaction ID generated per request; both are sent in the same `meta` block. The gateway performs this computation automatically on every outbound API call. **Steps to generate an Access Key:** @@ -65,18 +97,9 @@ Where `requestTs` is the ISO 8601 timestamp of the request and `requestTxnId` is Enter the copied value in the `ApiKey` field of the CA connector configuration. The field is masked in the Keyfactor Command UI and stored in Command's encrypted gateway configuration. -### OAuth — alternative auth mode +### OAuth2 client credentials — V2 -If your CERTInext account has OAuth enabled, you can use OAuth client credentials as an alternative to AccessKey signing. - -1. Log in to the CERTInext portal. -2. Navigate to **Integrations → APIs**. -3. Click **+ Create API Credentials**. -4. Set **API Type** to `REST` and **Auth Type** to `OAuth`. -5. Complete the form and click **Generate**. -6. Note the **Client ID** and **Client Secret**. Enter them in the `OAuthClientId` and `OAuthClientSecret` fields respectively. -7. Confirm the OAuth token endpoint URL with eMudhra and enter it in the `OAuthTokenUrl` field. -8. Set the `AuthMode` connector field to `OAuth`. +The V2 API authenticates with an OAuth2 `client_credentials` bearer token. Create the credential with **Auth Type** `OAuth` and enter the client ID and secret in `OAuthClientId` and `OAuthClientSecret`. See [V2 OAuth2 Setup](#v2-oauth2-setup) for the steps. > Note: Credentials are stored in Keyfactor Command's encrypted gateway configuration and are never written to disk by the plugin. @@ -87,68 +110,242 @@ Before enrolling certificates, the Keyfactor Command server must trust the CERTI 1. Log in to the CERTInext portal and download the root CA certificate and any intermediate CA certificates in the chain as PEM or DER files. 2. On the Keyfactor Command server, import those certificates into the appropriate Windows certificate store — **Trusted Root Certification Authorities** for the root CA and **Intermediate Certification Authorities** for any subordinate CAs. 3. In the Keyfactor Command Management Portal, navigate to **CA Connectors** and add a new CA using the **CERTInext AnyCA REST Gateway Plugin**. -4. Complete the CA connector configuration fields described in the next section, then save and test the connection. The gateway performs a live connectivity test against the CERTInext `ValidateCredentials` endpoint during validation. +4. Complete the CA connector configuration fields described in the next section, then save and test the connection. The gateway performs a live connectivity test during validation: the V1 `ValidateCredentials` endpoint, or `GET /api/certinext/v2/auth/me` when `UseV2Api` is `true`. + +### Change of issuing CA (eMudhra exit from public TLS) + +eMudhra, CERTInext's parent company, is withdrawing from the public SSL/TLS certificate business, and browser root programs are phasing out the emSign roots that CERTInext public TLS certificates have chained to. Public TLS certificates ordered through CERTInext will be issued under a different CA. Which CA depends on your service: InCommon members are moving to [SSL.com](https://incommon.org/about/news/incommon-certificate-service-update), and eMudhra offers [Sectigo](https://emudhra.com/en/post/certificate-security-incident) certificates to its customers. Confirm the new chain for your account with CERTInext. + +Dates published by eMudhra for the emSign G1 root (check the [eMudhra statement](https://emudhra.com/en/post/certificate-security-incident) for changes): + +| Root program | Effect | +|---|---| +| Chrome, Mozilla Firefox | Certificates logged after November 16, 2026 are not trusted. Certificates issued before then stay trusted until they expire. | +| Apple | The root is removed on November 30, 2026. Every certificate issued under it stops being trusted on Apple platforms, including existing ones. | +| Microsoft | No date announced. | + +The plugin does not need to change. It stores only the issued certificate and never reads or checks the issuer. Repeat the trust and registration steps above with the new chain: + +1. Get the new root and intermediate certificates for your account from CERTInext. +2. Import them on the Keyfactor Command server and the AnyCA Gateway REST host, and on any orchestrator or client that builds or validates certificate chains. Use **Trusted Root Certification Authorities** for the root and **Intermediate Certification Authorities** for subordinates. +3. Replace the CA certificate in this CA's **Gateway Registration** with the new issuing chain. +4. Replace certificates that chain to the emSign G1 root before November 30, 2026 if Apple clients rely on them. Keep the emSign certificates in your trust stores until you have replaced every certificate issued under them. + +Also confirm with CERTInext whether your account's product codes change. If they do, update the `ProductCode` mapping on each template. ## CA Configuration -The following fields are presented in the Keyfactor Command Management Portal when creating or editing the CERTInext CA connector. All fields marked **Required** must be provided before the connector can be saved in an enabled state. +The following fields are presented in the Keyfactor Command Management Portal when creating or editing the CERTInext CA connector. The **Applies to** column shows which API generation uses the field: **V1**, **V2**, or **Both**. + +### Save-Time Validation + +When the connector is saved (and `Enabled` is `true`), the plugin checks only the fields below. Every other field marked **Required** in the tables is needed by CERTInext for a successful order, but the connector saves without it — enrollment then fails, or the order is parked pending, until it is set. + +| Mode | Fields checked at save | +|---|---| +| All | `ApiUrl` must be present and use `https` (`http` is allowed only for a loopback host: `localhost`, `127.0.0.1`, `::1`). | +| V1 AccessKey | `AccountNumber`, `ApiKey` | +| V2 | `OAuthClientId`, `OAuthClientSecret`, `SignerPlace` | + +### Connection -| Field | Required / Optional | Description | Where to find it | Example | +| Field | Applies to | Required | Description | +|---|---|---|---| +| `ApiUrl` | Both | Required | CERTInext API base URL. The shape depends on `UseV2Api`; see [ApiUrl by mode](#apiurl-by-mode). | +| `UseV2Api` | Both | Optional | Route all operations through the V2 REST API. Requires `OAuthClientId`, `OAuthClientSecret`, and `SignerPlace`. Default: `false`. | +| `AccountNumber` | V1 | Required | CERTInext account number (numeric string), sent in the `meta` block of every request. Example: `1234567890`. | +| `ApiKey` | V1 | Required | Access Key from **Integrations → APIs**. Masked in the UI. | +| `AuthMode` | V1 | Optional | Legacy. Default: `AccessKey`. Leave as is; V1 does not honor OAuth. Ignored on V2. | +| `OAuthClientId` | V2 | Required | OAuth client ID. The key must be generated in OAuth mode. | +| `OAuthClientSecret` | V2 | Required | OAuth client secret. Masked in the UI. | +| `OAuthTokenUrl` | V1 (legacy) | Optional | Legacy / unsupported: V1 does not honor OAuth tokens. Ignored on V2, which derives `{ApiUrl}/oauth/token`. | +| `Enabled` | Both | Optional | Set to `false` to create the connector record before credentials exist; skips validation and the live connectivity test. Default: `true`. | + +#### ApiUrl by Mode + +| Mode | Value | Examples | +|---|---|---| +| V1 (default) | Host plus the `/emSignHub-API/` path | Sandbox: `https://sandbox-us-api.certinext.io/emSignHub-API/`
Production US: `https://us-api.certinext.io/emSignHub-API/`
Production India: `https://api.certinext.io/emSignHub-API/` | +| V2 (`UseV2Api` = `true`) | Bare host, no path suffix | `https://sandbox-us-api.certinext.io` | + +- The two APIs are hosted differently, so change `ApiUrl` whenever you toggle `UseV2Api`. +- A trailing slash is accepted in either mode. +- The URL must use `https`: the API key (V1) or OAuth client secret (V2) is sent to it on every request. `http` is rejected except for a loopback host, for local test servers only. + +### Requestor and Signer + +| Field | Applies to | Required | Description | +|---|---|---|---| +| `RequestorName` | Both | Required | Default name of the person or service submitting orders. Example: `PKI Automation`. | +| `RequestorEmail` | Both | Required | Default requestor email. Use a monitored inbox registered in your CERTInext account. | +| `RequestorIsdCode` | Both | Optional | Dialing code for the requestor phone, digits only, no `+`. Default: `1`. | +| `RequestorMobileNumber` | Both | Optional | Requestor mobile number, digits only, no country code. | +| `RequestorDesignation` | Both | Optional | Job title of the requestor. Sent as `requestorInformation.requestorDesignation` (V1) and `requestor.designation` (V2). Omitted when blank. | +| `TechnicalContactName`
`TechnicalContactEmail`
`TechnicalContactIsdCode`
`TechnicalContactMobileNumber` | Both | Optional | Technical point of contact on every SSL order. Each defaults to the matching `Requestor*` field. On V1 the name is sent as `pocFirstName` and `pocLastName`, split on the first whitespace (a single word goes in both). If no name or no email resolves, V1 omits the whole block and logs a warning, because CERTInext requires both inside it. | +| `SignerPlace` | Both | Required | City of the person accepting the subscriber agreement. Required at save on V2; a template `SignerPlace` overrides it on both. On V1, if neither is set, the plugin sends `Gateway` and logs a warning. Example: `Austin`. | +| `SignerIp` | V1 | Required on V1 | Public IP of the host accepting the subscriber agreement. Not sent on V2, whose agreement block has no IP field. See the bullets below. Example: `203.0.113.10`. | + +- **`SignerIp` blank:** on V1, when neither a template `SignerIp` nor this field is set, the plugin sends `127.0.0.1` and logs a warning, which misstates the audit record CERTInext keeps. Set it to the gateway host's outbound IP. A V1 value that is not an IP address is still sent unchanged, with a warning. On V2 the setting is ignored: the V2 agreement block has no signer IP field (the CA records the signer's IP itself), so it is never sent and never warned about. +- **Signer values per order:** the agreement signer is the template `SignerName`, `SignerPlace`, and `SignerIp` parameters first, then the connector's `RequestorName`, `SignerPlace`, and `SignerIp`, then the placeholders `Keyfactor Gateway`, `Gateway`, and `127.0.0.1` (each placeholder logs a warning on V1). `SignerIp` is V1 only. Blank values fall through. This applies to new orders and renewals on both V1 and Vt. +- **Where to find values:** the account number is under your name or avatar → **Account Settings** or **My Profile**. Use a monitored team inbox for `RequestorEmail`. + +### Order Defaults + +| Field | Applies to | Required | Description | +|---|---|---|---| +| `GroupNumber` | Both | Optional | CERTInext group (delegation) number, from **Delegation → Groups**. Routes orders to the right group. See the bullets below. | +| `OrganizationNumber` | Both | Optional | Pre-vetted organization number, from **Organizations → Pre-vetted Organizations**. Required for OV/EV on V2: enrollment fails before any CA call if blank. | +| `DefaultProductCode` | Both | Optional | Numeric product code fallback. See [DefaultProductCode](#defaultproductcode). | +| `AccountingModel` | V1 | Optional | Billing model: `2` = credit-based (most accounts), `1` = cash. Default: `2`. | +| `EmailNotifications` | Both | Optional | Lifecycle emails to the requestor. See [EmailNotifications values](#emailnotifications-values). Default: `0`. | +| `SubscriptionValidityYears` | Both | Optional | Default validity in years: `1`, `2`, or `3`. Used when the template sets no `ValidityYears` (and, on V1, no `ValidityDays`); a template term overrides it. Default: `1`. | +| `SubscriptionAutoRenew` | Both | Optional | `0` = CERTInext does not auto-renew (recommended; Command drives renewal), `1` = enabled. Default: `0`. | +| `SubscriptionRenewCriteriaDays` | Both | Optional | Days before expiry at which CERTInext auto-renews. Honored only when `SubscriptionAutoRenew` is `1`. Default: `30`. | +| `AutoSecureWww` | Both | Optional | `1` adds the `www.` variant of the primary domain as an extra SAN, which must also pass domain validation. Sent as `orderDetails.autoSecureWWW` on every V1 SSL order (new and renewal). Default: `0`. | +| `SubmitNonDnsSans` | V1 | Optional | `true` submits non-DNS SANs (IP, email, URI) to CERTInext, which cannot validate them, so the order will not issue until they are removed. `false` submits DNS names only. Default: `true`. | + +- **`GroupNumber`:** it is sent in `productDetails.groupNumber` on `GetProductDetails` and in `orderDetails.groupNumber` on every V1 SSL order (new and renewal). When blank, CERTInext uses the account's default group. On V2 it is sent as `groupNumber` on order create and as a query parameter on the catalog and orders-report calls. Some sandbox accounts return an empty product list unless it is set. +- **`GroupNumber` is not `AccountNumber`:** `AccountNumber` is your top-level account identifier. Each CERTInext group (cost center or department) has its own `groupNumber`, which is separate from any organization number on the Organizations page. +- **`OrganizationNumber`:** when set, V1 orders carry `organizationDetails.preVetting="1"` and this number, so CERTInext skips its manual vetting queue. Without it, orders can sit in `Pending System RA` for tens of hours. V2 DV orders never send an organization block. +- **Non-DNS SANs on V2:** `SubmitNonDnsSans` is not consulted. See [Migrating from V1 to V2](#step-2--update-the-ca-connector). + +#### DefaultProductCode + +Calling `GetProductDetails` against your account lists the codes available to you (see [Product Codes](#product-codes)). + +| Mode | When it applies | +|---|---| +| V1 | Renewals only, and only when the template supplies no `ProductCode`/`ProfileId`. CERTInext's `TrackOrder` does not return the prior order's product code. No effect on new enrollments. | +| V2 | Not used. V2 orders send `X-Product-Code` only for an explicit template `ProductCode`; otherwise CERTInext resolves the product. | + +- If neither the template nor this field supplies a code on a V1 renewal, the renewal goes out with an empty product code. + +#### EmailNotifications Values + +| Value | V1 | V2 | +|---|---|---| +| `1` | Full notification set (sent as `1`) | Sent as `all` | +| `0` | Silent (sent as `0`) | Silent: sent as `consent-only`, the quietest value the V2 spec allows (its enum is `consent-only` or `all`) | +| Blank | Silent (sent as `0`) | Omitted, so the CA default (`all`, not silent) applies | +| Anything else | Sent unchanged, not validated | Enrollment fails before any CA call | + +### Synchronization and Pickup + +| Field | Applies to | Required | Description | +|---|---|---|---| +| `IgnoreExpired` | V2 | Optional | Skip expired certificates during sync. The V1 API does not currently apply it. Default: `false`. | +| `PageSize` | Both | Optional | Orders fetched per page during sync. Must be 1 or higher; reduce it if sync requests time out. Default: `100`. Maximum: `500` on V1, `100` on V2. | +| `V2SyncLookbackHours` | V2 | Optional | Extra hours subtracted from the last-sync time on incremental sync, so a slow order is not missed. Default: `72`. | +| `SyncRecentOrderGraceSeconds` | Both | Optional | A sync (full or incremental) skips pending or issued orders created less than this many seconds ago (plus a 5-second clock margin); the next incremental sync imports them. This keeps a sync that runs during an in-flight enrollment from causing that enrollment to fail with a duplicate key. `0` disables it. Default: `120`. | +| `PickupRetries` | Both | Optional | Times `Enroll` polls CERTInext for the certificate after a successful order. `0` disables the wait. Default: `5`. | +| `PickupDelay` | Both | Optional | Seconds between pickup polls. Default: `10`. | + +- **`IgnoreExpired` on V1:** the V1 sync maps no certificate expiry date, so the filter never matches and expired certificates are still imported. The V2 sync applies it. +- **`PageSize` limits:** values above the maximum are clamped. On V2, a value of 0 or less falls back to 100. On V1, a value below 1 is not corrected, so keep it at 1 or higher. +- **`PickupRetries` and `PickupDelay`:** OV/EV orders validate asynchronously (minutes to hours) and typically exhaust the wait regardless of these values. Pickup applies to V1 and V2. + +#### Pickup Limits + +| Setting | Minimum | Maximum | Default | Out-of-range behavior | |---|---|---|---|---| -| `ApiUrl` | Required | CERTInext API base URL for your environment. Must include the `/emSignHub-API/` path segment. No trailing slash is required but is accepted. | See the environments table above. | `https://api.certinext.io/emSignHub-API/` | -| `AccountNumber` | Required | Your CERTInext account number (numeric string). Included in the `meta` block of every API request. | Portal → click your name or avatar → **Account Settings** or **My Profile**. | `1234567890` | -| `AuthMode` | Required | Authentication mode. `AccessKey` uses HMAC signing (recommended). `OAuth` uses a bearer token. | N/A — choose based on the credential type you created. | `AccessKey` | -| `ApiKey` | Conditional | The REST API Access Key generated in the CERTInext portal. Used to compute `authKey = SHA256(accessKey + ts + txn)`. The raw key is never transmitted. Required when `AuthMode` is `AccessKey`. This field is masked in the UI. | Portal → **Integrations → APIs** → generate or view the credential row. | *(generated, masked in UI)* | -| `OAuthTokenUrl` | Conditional | OAuth token endpoint URL. Required when `AuthMode` is `OAuth`. | Provided by eMudhra for your account. | `https://auth.certinext.io/oauth/token` | -| `OAuthClientId` | Conditional | OAuth client ID. Required when `AuthMode` is `OAuth`. | Portal → **Integrations → APIs** → the OAuth credential row. | `keyfactor-gateway` | -| `OAuthClientSecret` | Conditional | OAuth client secret. Required when `AuthMode` is `OAuth`. This field is masked in the UI. | Generated at OAuth credential creation time. | *(generated, masked in UI)* | -| `RequestorName` | Required | Default name of the person or service submitting certificate orders. Sent in the `requestorInformation` block of every order request. | Use the name of the team or automation account responsible for these certificates. | `PKI Automation` | -| `RequestorEmail` | Required | Default email address for the requestor. Must be a valid email address associated with your CERTInext account. Sent in the `requestorInformation` block of every order request. | Use a monitored team inbox or the account holder's email. | `pki-admin@example.com` | -| `RequestorIsdCode` | Optional | International dialing code for the requestor phone number (digits only, no `+` prefix). Default: `1` (United States). | N/A — use the country code for your requestor. | `1` | -| `RequestorMobileNumber` | Optional | Requestor mobile number (digits only, no country code). Included in the `requestorInformation` block. | N/A | `5551234567` | -| `SignerPlace` | Required | City or location of the person accepting the subscriber agreement on behalf of your organization. Required by CERTInext for all orders. | Use the physical city where the signer is located. | `Austin` | -| `SignerIp` | Required | Public IP address of the host accepting the subscriber agreement. Required by CERTInext for all orders. | Use the outbound IP of the AnyCA Gateway host, or the IP of the workstation from which the agreement was accepted. | `203.0.113.10` | -| `GroupNumber` | Optional | CERTInext group (delegation) number. When set, it is passed in the `productDetails.groupNumber` field of `GetProductDetails` requests. Some sandbox accounts return an empty product list from `GetProductDetails` unless this field is included. Available in the CERTInext portal under **Delegation → Groups**. | Portal → **Delegation → Groups**. | `2345678901` | -| `DefaultProductCode` | Optional | Default numeric product code to use when no product code is set on the certificate template. If omitted and the template also has no product code, enrollment will fail. Product codes are provisioned per account by eMudhra — contact your eMudhra account representative to obtain the numeric codes available to your account. | Call `GetProductDetails` against your account/environment (see product code table below). | `842` | -| `IgnoreExpired` | Optional | If `true`, expired certificates are skipped during synchronization and are not imported into Keyfactor Command. Default: `false`. | N/A | `false` | -| `PageSize` | Optional | Number of orders to retrieve per page during synchronization. Default: `100`. Maximum: `500`. Reduce this value if synchronization requests time out. | N/A | `100` | -| `Enabled` | Optional | Enables or disables the CA connector. Setting this to `false` allows the connector record to be created before all credentials are available, without triggering a live connectivity test. Default: `true`. | N/A | `true` | -| `DcvEnabled` | Optional | When `true`, the gateway performs DNS-based Domain Control Validation (DCV) during enrollment for orders that require it. Requires a DNS provider plugin (e.g. `azure-azuredns-dnsplugin`) to be deployed on the gateway. Default: `false`. | N/A | `false` | -| `DcvTxtRecordTemplate` | Optional | Format string for the DNS TXT record hostname published during DCV. `{0}` is replaced with the domain being validated. Default: `_emsign-validation.{0}`. | N/A | `_emsign-validation.{0}` | -| `DcvPropagationDelaySeconds` | Optional | Seconds to wait after publishing the DNS TXT record before asking CERTInext to verify it. Increase for zones with slow propagation. Default: `30`. | N/A | `30` | -| `DcvTimeoutMinutes` | Optional | Maximum minutes to wait for the entire DCV flow (DNS publish + propagation + verify) before cancelling the enrollment. Can also be set via the `CERTINEXT_DCV_TIMEOUT_MINUTES` environment variable; the environment variable takes precedence when both are set. Default: `10`. | N/A | `10` | - -> Note: `AccountNumber` and group-level identifiers are distinct values. The `AccountNumber` is your top-level user account identifier. CERTInext groups (cost centers or departments) each have their own `groupNumber`, which is passed per-order and is separate from any organization number displayed on the Organizations page. - -> Note: Only the credential fields that correspond to the selected `AuthMode` are evaluated at runtime. Fields belonging to the other auth mode are ignored. +| `PickupRetries` | 0 (disabled) | 30 | 5 | Negative becomes 0; above 30 becomes 30 | +| `PickupDelay` (seconds) | 1 | 60 | 10 | Zero or negative becomes 10; above 60 becomes 60 | +| Total wait | — | 75 s | ~55 s | The retry count is reduced to fit the cap | + +> **Pickup timing detail:** after a successful order placement, the plugin waits a fixed 5-second initial delay before the first poll, then polls CERTInext every `PickupDelay` seconds up to `PickupRetries` times. Each poll calls `GetCertificate` to check whether the certificate has been issued. The total time budget is **5 s + (`PickupRetries` × `PickupDelay`) + about 1 s API round trip per poll**. With the defaults this is 5 + (5 × 10) = **~55 s plus round trips**. +> +> **Tuning for faster pickup:** if CERTInext typically issues certificates within a few seconds of order placement (as is typical for DV and auto-approved orders), lower `PickupDelay` and raise `PickupRetries` to compensate. This polls more often without changing the total budget. Command's own enrollment call into the gateway is bounded at about 100 s, and order submission and each poll's round trip also use that budget, so keep the total well under the 75 s ceiling. +> +> | Configuration | PickupRetries | PickupDelay | Total budget | Poll cadence | +> |---------------|:---:|:---:|---|---| +> | Default | `5` | `10` | ~55 s | Every 10 s | +> | Faster polling | `10` | `5` | ~55 s | Every 5 s | +> | Aggressive | `30` | `2` | ~65 s | Every 2 s | +> | Minimal wait | `0` | — | 0 s | No polling; defers to sync | +> +> The 5-second initial delay is not configurable, and the 75-second ceiling applies regardless of configuration. It sits inside Command's roughly 100-second enrollment-call timeout, which leaves headroom for order submission and per-poll round trips. When the DCV flow ran for the order inside the same `Enroll` call, the pickup poll is skipped, because the DCV flow already waited for issuance. + +### Domain Control Validation (DCV) + +DCV needs a DNS provider plugin (for example `azure-azuredns-dnsplugin`) deployed on the gateway. Without one, orders that need validation stay pending and the plugin logs why. + +| Field | Applies to | Required | Description | +|---|---|---|---| +| `DcvEnabled` | Both | Optional | Perform DNS-based DCV during enrollment and synchronization. Set to `false` to validate domains another way. Default: `true`. | +| `DcvTxtRecordTemplate` | Both | Optional | TXT record hostname format; `{0}` is the domain being validated. Default: `_emsign-validation.{0}`. | +| `DcvPropagationDelaySeconds` | Both | Optional | Seconds to wait after publishing the TXT record before asking CERTInext to verify. Default: `30`. | +| `DcvTimeoutMinutes` | Both | Optional | Maximum minutes for the whole DCV flow before the order is left pending. Default: `10`. | +| `DcvWaitForChallengeSeconds` | V1 | Optional | How long `Enroll()` waits for CERTInext to expose the DCV challenge. `0` disables the wait. Default: `60`. | +| `DcvWaitForIssuanceSeconds` | V1 | Optional | How long `Enroll()` waits for issuance after DCV verifies. `0` disables the wait. Default: `60`. | +| `DcvSyncMaxOrderAgeHours` | Both | Optional | During sync, only pending DV orders younger than this are driven through DCV. `0` disables the filter. Default: `24`. | +| `DcvSyncMaxPerPass` | Both | Optional | Maximum pending DV orders driven through DCV per sync pass. `0` disables the cap. Default: `50`. | + +- **Environment variables:** `DcvTimeoutMinutes`, `DcvWaitForChallengeSeconds`, and `DcvWaitForIssuanceSeconds` can also be set with `CERTINEXT_DCV_TIMEOUT_MINUTES`, `CERTINEXT_DCV_WAIT_FOR_CHALLENGE_SECONDS`, and `CERTINEXT_DCV_WAIT_FOR_ISSUANCE_SECONDS`. The environment variable wins when both are set. +- **Propagation delay:** on V1, DCV driven during synchronization uses its own fixed 3-second delay. V2 uses `DcvPropagationDelaySeconds` everywhere. +- **Sync limits:** `DcvSyncMaxOrderAgeHours` and `DcvSyncMaxPerPass` keep a large backlog of old or abandoned pending orders from slowing every sync pass. + +### Diagnostics + +| Field | Applies to | Required | Description | +|---|---|---|---| +| `LogSensitiveRequestData` | Both | Optional | Temporary diagnostic switch. When `true`, requestor personal data and full CA request/response payloads are written to the gateway logs. Default: `false`. | + +- **Use it briefly:** turn it on only while verifying a new deployment (to confirm exactly what was sent to the CA), then turn it off. +- **When `false`:** personal-data fields are redacted. Emails are masked but keep their domain (for example `j***@example.com`), and the enrollment log line omits the requester name. +- **Email SANs:** `rfc822Name` values in log lines are masked the same way. DNS, IP, and URI SANs are always logged in full. +- **Credentials:** API keys, OAuth secrets, and tokens are always redacted, whatever this setting is. ## Certificate Template Creation Step A Keyfactor Command certificate template maps an enrollment request to a specific CERTInext product. Create one template per CERTInext product that you want to make available to requesters. +The AnyCA Gateway REST portal also needs one certificate profile per product before Command templates can be created against it. Create the profiles by hand in the gateway portal, or with the helper script this repository ships (`make register-profiles`; set `DRY_RUN=1` to preview). By default the script also registers a ` V2` profile per product, for a second set of templates that carry no `ProductCode` (see [V2 Product Code Resolution](#v2-product-code-resolution)); set `V2_TEMPLATES=0` to skip them. See [scripts/register/README.md](https://github.com/Keyfactor/certinext-caplugin/blob/main/scripts/register/README.md) for authentication and options. + In the Keyfactor Command Management Portal, navigate to **Certificate Templates** and create a new template associated with the CERTInext CA connector. The following enrollment parameters are available: | Parameter | Required / Optional | Type | Description | Example / Default | |---|---|---|---|---| -| `ProductCode` | Optional | String | Override the numeric CERTInext product code for this template. Product codes are provisioned per account by eMudhra — obtain the correct code from `GetProductDetails` for your account. Set this explicitly when targeting the sandbox environment or when the connector `DefaultProductCode` should not apply to this template. See the [Product Codes](#product-codes) section for the sandbox/production lookup table. | DV SSL: `842` (sandbox) or `838` (production) | +| `ProductCode` | Optional | String | Overrides the numeric CERTInext product code. Get the right code from `GetProductDetails` for your account. On V2 it is an override sent as `X-Product-Code`; leave it blank and CERTInext resolves the product. | DV SSL: `842` (sandbox) or `838` (production) | | `ProfileId` | Deprecated | String | Legacy alias for `ProductCode`. Accepted for backward compatibility — if `ProductCode` is not set, `ProfileId` is used in its place. New templates should use `ProductCode`. | `838` | -| `ValidityYears` | Optional | Number | Subscription validity period in years: `1`, `2`, or `3`. Default: `1`. CERTInext certificates are issued within a subscription term at up to 390 days per certificate, with free renewals within the term. | `1` | -| `ValidityDays` | Deprecated | Number | Legacy validity field. If set, the value is divided by 365 and rounded up to derive a year count. New templates should use `ValidityYears`. | `365` | -| `AutoApprove` | Optional | Boolean | If `true`, the gateway will attempt automatic approval of certificates returned in a pending-approval state. Only set this if your CERTInext product is configured with automatic approval. Default: `false`. | `false` | -| `RequesterName` | Optional | String | Per-template override for the requestor name. When set, overrides the connector-level `RequestorName` for orders using this template. | `Keyfactor Automation` | -| `RequesterEmail` | Optional | String | Per-template override for the requestor email address. When set, overrides the connector-level `RequestorEmail` for orders using this template. | `pki-admin@example.com` | -| `RenewalWindowDays` | Optional | Number | Number of days before certificate expiration within which a renewal is attempted instead of a reissue. Default: `90`. | `90` | -| `KeyType` | Optional | String | Key algorithm to request at enrollment time. The key type is carried by the submitted CSR. CERTInext accepts **RSA 2048 / 3072 / 4096 and ECC P-256 / P-384** only — larger RSA, ECC P-521, and the Ed25519/Ed448 curves are rejected by the CA (`Invalid key size`). If omitted, the product default is used. | `RSA2048`, `RSA3072`, `RSA4096`, `EC256`, `EC384` | -| `DomainName` | Optional | String | Primary domain name for SSL/TLS orders. If omitted, the gateway derives the domain from the CSR `CN` field. | `example.com` | -| `SignerName` | Optional | String | Per-template override for the subscriber agreement signer name. When omitted, defaults to the connector-level `RequestorName`. | `Jane Smith` | -| `SignerPlace` | Optional | String | Per-template override for the subscriber agreement signer location. When omitted, defaults to the connector-level `SignerPlace`. | `Austin` | -| `SignerIp` | Optional | String | Per-template override for the subscriber agreement signer IP address. When omitted, defaults to the connector-level `SignerIp`. | `203.0.113.10` | +| `ValidityYears` | Optional | Number | Subscription term in years: `1`, `2`, or `3`. Default: `1`. CERTInext certificates are issued within a subscription term at up to 390 days per certificate, with free renewals within the term. | `1` | +| `ValidityDays` | Optional | Number | V1 only; ignored on V2. Requested validity in days, converted to whole subscription years and rounded up (365 days = 1 year), because the order API takes years. Default: `365`. See the note below the table. | `365` | +| `AutoApprove` | Optional | Boolean | **Currently has no effect** — reserved for future use. The plugin does not call any approval endpoint against CERTInext regardless of this setting. | `false` | +| `RequesterName` | Optional | String | Overrides the connector `RequestorName` for this template when non-blank. Never derived from the certificate subject. | `Keyfactor Automation` | +| `RequesterEmail` | Optional | String | Overrides the connector `RequestorEmail` for this template when non-blank. Never derived from the certificate subject. | `pki-admin@example.com` | +| `RenewalWindowDays` | Optional | Number | V1 only. Number of days before certificate expiration within which a renewal is attempted instead of a reissue. V2 places a new order for every renewal and reissue. Default: `90`. | `90` | +| `KeyType` | Optional | String | Informational. The CSR decides the key algorithm. CERTInext accepts only RSA 2048/3072/4096 and ECC P-256/P-384. | `RSA2048`, `RSA3072`, `RSA4096`, `EC256`, `EC384` | +| `DomainName` | Optional | String | V2 only: primary domain name for SSL/TLS orders (for Private PKI, the primary hostname). If omitted, the plugin uses the CSR subject `CN`. V1 always uses the CSR subject `CN`. | `example.com` | +| `SignerName` | Optional | String | Per-template override for the subscriber agreement signer name. When omitted, defaults to the connector-level `RequestorName` (V2: the requestor name). If no name resolves, V1 sends `Keyfactor Gateway` and logs a warning. | `Jane Smith` | +| `SignerPlace` | Optional | String | Per-template override for the subscriber agreement signer location. When omitted, defaults to the connector-level `SignerPlace`. If neither is set, V1 sends `Gateway` and logs a warning. | `Austin` | +| `SignerIp` | Optional (V1 only) | String | Per-template override for the subscriber agreement signer IP address. Ignored on V2. When omitted, defaults to the connector-level `SignerIp`. If neither is set, V1 sends `127.0.0.1` and logs a warning; a V1 value that is not an IP address is sent unchanged, with a warning. | `203.0.113.10` | + +- **Subscription term (V1):** the order's term is the larger of `ValidityYears` and `ValidityDays` rounded up to whole years (365 days = 1 year). Each field counts only when it is set, and a field left at its default (1 year) never overrides the other, so a template saved with only `ValidityDays` keeps its term. Because the larger value wins, a stale larger `ValidityDays` cannot be shortened with `ValidityYears` alone; set `ValidityDays` back to `365`. V2 uses only `ValidityYears`. +- **Key types:** larger RSA, ECC P-521, and the Ed25519/Ed448 curves are rejected by the CA (`Invalid key size`). + +When `ProductCode` is omitted: + +- **V1:** the plugin uses the built-in default code for the selected product name (see [Product Codes](#product-codes)). +- **V2:** no code is sent and CERTInext resolves the product itself (see [V2 Product Code Resolution](#v2-product-code-resolution)). Set `ProductCode` to override that choice. +- **Sandbox or non-standard codes (V1):** set `ProductCode` explicitly. + +The V2-only template parameters `ProductFamily` and `ProductVariant` are described under [V2 Certificate Template Fields](#v2-certificate-template-fields). ## Product Codes -CERTInext uses numeric product codes to identify certificate types. **Product codes are provisioned per account by eMudhra** — the codes available to your account are determined when your account is set up. The codes in the tables below are the values observed on specific sandbox and production accounts; your account may have different codes. +**V2 connectors (`UseV2Api = true`) don't need product codes.** CERTInext picks the product from the template's `ProductVariant` and the request's shape, so leave `ProductCode` blank. Set it only to choose one product when several match (see [V2 Product Code Resolution](#v2-product-code-resolution)). The variants the V2 API defines are: -To retrieve the exact codes available to your account, call the `GetProductDetails` endpoint: +| Family (`ProductFamily`) | `ProductVariant` values | How the exact product is chosen | +|---|---|---| +| `ssl` | `dv`, `ov`, `ev` | The variant plus the domain's shape: a `*.` domain selects a wildcard product, and extra DNS names select a multi-domain (UCC) product | +| `private-pki` | `intranet-ssl`, `igtf-host` | The variant | + +Where several catalog products match a variant, CERTInext picks one, and it may not be the one you want: on the US sandbox, `dv` resolves to a 1-month product that rejects a client CSR. If that happens, set `ProductCode` on the template. + +The rest of this section applies to **V1 connectors**, which select every product by its numeric code. It also applies to the optional V2 override. + +CERTInext uses numeric product codes to identify certificate types. **Product codes are provisioned per account by eMudhra**, so the codes available to your account depend on how it was set up and which CA it issues from. The tables below are **eMudhra's published reference values from the emSign era**. They haven't been verified against every environment, and they may differ for accounts that issue through SSL.com after eMudhra's exit from public TLS. Your account's own product list is the only authority. + +To retrieve the exact codes available to your account, call the `GetProductDetails` endpoint (V1) or `GET /api/certinext/v2/catalog/products` (V2): - If you have a `GroupNumber` configured, include it in the request `productDetails` block — some accounts require this to return a non-empty list. - Use the `make get-product-details-group` Makefile target to retrieve products from the sandbox with `groupNumber` included. @@ -158,13 +355,13 @@ To retrieve the exact codes available to your account, call the `GetProductDetai ### SSL/TLS -The product codes in this table were observed on: -- the US sandbox environment (`sandbox-us-api.certinext.io`) in April–May 2026 -- the Production India environment (`api.certinext.io`) via the live draft-order coverage matrix in [development.md](development.md) +The product codes in this table are for: +- the US sandbox environment (`sandbox-us-api.certinext.io`) +- the Production India environment (`api.certinext.io`) **Your account may still have different codes.** Always call `GetProductDetails` against your target environment before going live. -| Product | Sandbox Code | Production Code | Required fields beyond base (`domainName`, `csr`, `requestorInformation`, `subscriptionDetails`, `agreementDetails`) | +| Product | Sandbox Code | Production Code | CERTInext-side requirements (beyond `domainName`, `csr`, `requestorInformation`, `subscriptionDetails`, `agreementDetails`) | |---|---|---|---| | DV (Domain Validated) | `842` | `838` | None. `domainName` is derived from the CSR CN if omitted on the template. | | DV Wildcard | `843` | `839` | CSR CN must use wildcard format (e.g. `*.example.com`). `domainName` in the order must also use the wildcard format. | @@ -177,88 +374,123 @@ The product codes in this table were observed on: | EV (Extended Validation) | `850` | `846` | All OV fields plus: `contractSignerInfo` object (`name`, `email`, `isdCode`, `mobileNumber`, `designation`, `employeeID`); `certificateApproverInfo` object (same fields); `certificateInformation.companyRegistrationNumber`; `streetAddress2` must be non-empty. | | EV UCC (Multi-domain EV) | `851` | `847` | Same as EV plus `certificateInformation.additionalDomains`. | -> Note: SSL/TLS codes appear to be offset by 4 between the US sandbox and Production India in the snapshots we've observed — but treat that as a coincidence, not a guarantee. eMudhra controls the per-account mapping and may use different numeric codes for any new account. Always confirm via `GetProductDetails`. +> Note: The plugin supplies `domainName` and `additionalDomains` (from the CSR and its SANs), but none of the organization, address, or EV fields in the table. For OV and EV it sends only `organizationDetails.preVetting` and `organizationNumber` (V1), so these products need a pre-vetted organization: set `OrganizationNumber` on the connector. + +> Note: SSL/TLS codes are offset by 4 between the US sandbox and Production India in the tables above — treat that as a coincidence, not a guarantee. eMudhra controls the per-account mapping and may use different numeric codes for any new account. Always confirm via `GetProductDetails`. -> Note: The CERTInext portal may display additional short-validity products (e.g. **DV SSL Certificate 1 Month**, **DV SSL Certificate Wildcard 1 Month**) that do not appear in the `GetProductDetails` API response and have no published product code. These products are not accessible via the API and are therefore **not supported by this plugin**. Contact eMudhra to determine whether API ordering is available for these products on your account. +> Note: Some accounts also have short-validity products (for example **SSL DV 1 month**, code `917` on the US sandbox). They don't always appear in the V1 `GetProductDetails` response, but they can appear in the V2 catalog. Under V2, CERTInext may pick one for a `dv` order with no `ProductCode`, and on the sandbox that product rejects a client-supplied CSR. Set `ProductCode` on the template to the 1-year product you want. ### Private PKI | Product | Sandbox Code | Production Code | Availability | |---|---|---|---| | emSign Intranet SSL 1 year | `149` | `100` | Requires special provisioning by eMudhra. Not orderable on standard accounts. | -| IGTF Host 1 year | (not observed) | `104` | Requires special provisioning by eMudhra. Not orderable on standard accounts. | +| IGTF Host 1 year | n/a | `104` | Requires special provisioning by eMudhra. Not orderable on standard accounts. | -> Note: Private PKI products are not available for ordering on standard CERTInext accounts. Attempting to place an order will return EMS-1162 (product not provisioned). The sandbox Private PKI code (`149`) also returns EMS-1162 on standard sandbox accounts even though it appears in the `GetProductDetails` list. Contact eMudhra to have these products enabled on your account. +> Note: Private PKI products need a separate entitlement. On an account without it, placing an order returns EMS-1162 (product not provisioned). Contact eMudhra to have these products enabled. Whether the sandbox code `149` ("Sandbox emSign Intranet SSL 1 Year", `productTypeID` `39`) is available depends on the account. Check your own account's catalog. ### S/MIME and Document Signing -The same numeric product codes have been observed for S/MIME and document-signing products on both the US sandbox and Production India in the snapshots we have. **Treat that as an empirical observation, not a contract** — eMudhra is free to assign different codes per account. Always confirm via `GetProductDetails`. +**Not supported by this plugin.** `GetProductIds` advertises SSL/TLS products only, and V2 `ProductFamily=signature` enrollment fails before any order is placed. The codes below are listed for reference only, because they can appear in your account's `GetProductDetails` response. -| Product | Sandbox / Production Code | Availability | -|---|---|---| -| S/MIME | `894` | Requires a separate S/MIME entitlement on the account. Not available on standard SSL accounts. | -| Natural Person Doc Signer (tier 1) | `825` | Requires document signing entitlement. Not orderable on standard accounts. | -| Natural Person Doc Signer (tier 2) | `826` | Requires document signing entitlement. Not orderable on standard accounts. | -| Natural Person Doc Signer (tier 3) | `827` | Requires document signing entitlement. Not orderable on standard accounts. | -| Legal Person Doc Signer (tier 1) | `822` | Requires document signing entitlement. Not orderable on standard accounts. | -| Legal Person Doc Signer (tier 2) | `823` | Requires document signing entitlement. Not orderable on standard accounts. | -| Legal Person Doc Signer (tier 3) | `824` | Requires document signing entitlement. Not orderable on standard accounts. | -| Legal Entity Doc Signer (tier 1) | `819` | Requires document signing entitlement. Not orderable on standard accounts. | -| Legal Entity Doc Signer (tier 2) | `820` | Requires document signing entitlement. Not orderable on standard accounts. | -| Legal Entity Doc Signer (tier 3) | `821` | Requires document signing entitlement. Not orderable on standard accounts. | +CERTInext uses the same numeric codes for these products on the US sandbox and Production India in the snapshots we have. **Treat that as an example, not a contract** — eMudhra assigns codes per account. -> Note: S/MIME (894) and document signing products (819–827) require a separate entitlement that is not included in a standard SSL/TLS account. Contact eMudhra to request access. +| Product | Sandbox / Production Code | Notes | +|---|---|---| +| S/MIME | `894` | Not supported. Needs a separate S/MIME entitlement. | +| Document Signer | `819`–`827` | Not supported. Needs a document signing entitlement. | -To retrieve the full list of product codes available to your account, call the `GetProductDetails` endpoint against your target environment. The sandbox and production APIs each return their own set of codes. +CERTInext's published references don't agree on which Document Signer code maps to which product. The V2 API spec lists: -> Note: SSL/TLS products are supported on standard accounts — see the SSL/TLS table above for the exact sandbox/production code pair for each product. Private PKI (Production `100`, `104` / Sandbox `149`), S/MIME (`894`), and document-signing products (`819`–`827`) require special provisioning by eMudhra and are not available on standard SSL/TLS accounts — ordering them returns EMS-1162. +| Code | Product (per V2 API spec) | +|---|---| +| `819` / `820` / `821` | Natural Person, 1 / 2 / 3 year | +| `822` / `823` / `824` | Legal Person, 1 / 2 / 3 year | +| `825` / `826` / `827` | Legal Entity, 1 / 2 / 3 year | ## Mechanics ### Authentication -Every CERTInext API call is an HTTP POST with a JSON body. There is no Authorization header. Instead, the body carries a `meta` block with an `authKey` field computed as: +Every CERTInext API call is an HTTP request with a JSON body. How it authenticates depends on the API generation: -``` -authKey = SHA256(accessKey + requestTs + requestTxnId) -``` +| Mode | Where credentials go | Fields required | +|---|---|---| +| V1 AccessKey | `authKey` in the `meta` block of the POST body. No `Authorization` header. | `AccountNumber`, `ApiKey` | +| V2 OAuth2 | `Authorization: Bearer` header. Tokens are cached; see [V2 Token Caching](#v2-token-caching). | `OAuthClientId`, `OAuthClientSecret`, `SignerPlace` | + +For V1, `authKey = SHA256(accessKey + ts + txn)`, where `ts` is the ISO 8601 request timestamp and `txn` is a random numeric transaction ID generated per request. It is a plain SHA-256 digest, not an HMAC. The `meta` block also carries the version and account number. The raw access key is never transmitted, and the computation happens automatically on every outbound call. + +V1 OAuth (`AuthMode` = `OAuth`) is legacy and unsupported: the live V1 API ignores bearer tokens. + +### HTTP Timeout and Retries + +Every CERTInext API call (enroll, sync, revoke) uses a fixed 120-second request timeout, on both +V1 and V2. The V2 OAuth token request is the exception: it uses the HTTP client's default timeout. The +120 seconds is hardcoded and is not exposed as a connector setting or environment variable — it cannot be +changed without modifying the plugin. If a call doesn't return within 120 seconds, the plugin aborts it +and the operation fails. -Where `requestTs` is the ISO 8601 timestamp and `requestTxnId` is a unique transaction UUID generated per request. The raw access key is never transmitted — only the derived hash is sent. This computation happens automatically on every outbound call. When `AuthMode` is `OAuth`, the gateway obtains a bearer token via the configured client credentials flow and injects it into the `meta` block instead. +- **Order placement and CSR submission are never auto-retried after a timeout or server error**, + because CERTInext may have already created the order. If the CA did create it, the next + synchronization imports it. Do not resubmit immediately; check the CERTInext + portal first. +- **Other V1 calls** (status checks, downloads, revoke, reports) are retried up to 3 attempts on a + 5xx response or network failure. 4xx responses are not retried. +- **V1 rate limit:** when order placement returns CERTInext's rate-limit response (the generic + `Inactive Account User.` error), the plugin retries it up to 5 attempts with exponential backoff + and jitter. See the rate-limit entry in [overview.md](overview.md#troubleshooting). +- **V2 calls are never auto-retried.** The only repeated V2 call is the one-time revoke-reason + fallback described under [V2 Revocation Reason Handling](#v2-revocation-reason-handling). ### Enrollment Decision Logic -When the gateway calls `Enroll`, the plugin selects between three paths based on the enrollment type and the age of the prior certificate: +**V1.** When the gateway calls `Enroll`, the plugin selects a path from the enrollment type and the age of the prior certificate: -1. **New enrollment** — no prior certificate exists. A new `GenerateOrderSSL` request is submitted. -2. **Renewal** — a prior certificate exists and its expiry is within the `RenewalWindowDays` threshold (default: 90 days). A new `GenerateOrderSSL` order is submitted within the configured renewal window (CERTInext has no dedicated renewal endpoint; the renewal-window check governs how Command tracks old→new, not which API is called). -3. **Reissue** — a prior certificate exists but is outside the renewal window. A new `GenerateOrderSSL` order is placed with the updated CSR/subject, replacing the prior certificate under a new subscription. +1. **New or Reissue** (`EnrollmentType.New` / `Reissue`) — a new `GenerateOrderSSL` request is submitted. +2. **Renew or RenewOrReissue** — Command supplies the prior certificate's serial number (`PriorCertSN`). The plugin resolves the prior order from the Command database, then: + - no serial number, or no prior order found (including a failed lookup): a new order is submitted as for a new enrollment; + - the prior certificate's expiry is in the future and within `RenewalWindowDays` (default 90 days): a renewal order is submitted — CERTInext has no dedicated renewal endpoint, so this is also a new `GenerateOrderSSL` order; the prior order is looked up first and its details fill in anything the request doesn't supply; + - the prior certificate is outside the window, or already expired: a new order is submitted. -The `RenewalWindowDays` template parameter controls the renewal/reissue boundary per certificate template. +The prior order is never revoked automatically. The `RenewalWindowDays` template parameter sets the renewal/reissue boundary per certificate template. + +**V2.** All enrollment types (New, Reissue, Renew, RenewOrReissue) place a new V2 order; there is no renewal-window logic. See [V2 Order Lifecycle](#v2-order-lifecycle). ### Required Order Fields -The `GenerateOrderSSL` API requires an `additionalInformation.remarks` field in every order request body. The gateway populates this field automatically with the text `"Issued via Keyfactor Command AnyCA REST Gateway."`. If you encounter error `EMS-918: Additional Information cannot be empty`, verify that the gateway version is current and that the field is being sent. +The V1 `GenerateOrderSSL` API requires an `additionalInformation.remarks` field in every order request body. The gateway populates this field automatically with the text `"Issued via Keyfactor Command AnyCA REST Gateway."`. If you encounter error `EMS-918: Additional Information cannot be empty`, verify that the gateway version is current and that the field is being sent. ### Order Lifecycle and Pending Approval -CERTInext orders pass through several internal status stages before a certificate is issued. The plugin maps these to Keyfactor enrollment statuses as follows: +CERTInext orders pass through several internal status stages before a certificate is issued. The plugin maps the V1 `certificateStatusId` values to Keyfactor statuses as follows: -- **Issued** (status 9, 20) → certificate returned immediately. -- **Pending approval** (status 2, 8, 15, 24) → enrollment returns a pending status to Command. If `AutoApprove` is enabled on the template, the plugin attempts automatic approval before returning. -- **Rejected / cancelled** (status 4, 5, 13, 14) → enrollment fails with an error. +| Keyfactor result | CERTInext status IDs | Behavior | +|---|---|---| +| Issued | `7`, `9`, `12`, `15`, `20`, `23` | Certificate returned immediately. Status `12` (expired) stays in inventory as issued rather than failing. | +| Pending | `1`, `2`, `4`, `6`, `16`, `17`, `24` | Enrollment returns pending. `Enroll()` first polls briefly (see `PickupRetries`/`PickupDelay`). | +| Revoked | `22` | Certificate marked revoked. | +| Failed | `3`, `5`, `8`, `13`, `14`, `18`, `19`, `21`, or any unrecognized ID | Enrollment returns a failed result. | -The gateway polls the `TrackOrder` endpoint during sync to pick up certificates that were approved after the initial enrollment call. +Orders that are still pending when `Enroll()` returns are picked up by a later synchronization. ### Synchronization -Synchronization uses the `GetOrderReport` endpoint with paginated results (controlled by `PageSize`, default 100, max 500). Each page is fetched sequentially until all orders are retrieved. The plugin maps each order's status to a Keyfactor certificate status and returns the result set to the gateway framework, which reconciles it against the Command inventory. +On V1, synchronization uses the `GetOrderReport` endpoint with paginated results (controlled by `PageSize`, default 100, max 500). Each page is fetched sequentially until all orders are retrieved; a full sync requests every order, and an incremental sync requests orders placed since the last sync date. The plugin maps each order's status to a Keyfactor certificate status and returns the result set to the gateway framework, which reconciles it against the Command inventory. + +- The order report carries no certificate body, so the plugin refetches the certificate for issued and revoked orders. +- Rejected and cancelled orders are skipped. +- Pending orders are emitted as pending. When DCV is enabled and a DNS provider plugin is available, recently placed pending orders are first driven through DNS-01 validation, bounded by `DcvSyncMaxOrderAgeHours` and `DcvSyncMaxPerPass`. +- If more than 25% of the records processed so far have failed (after at least 50 records), the sync aborts and is retried on the next cycle. + +Expired certificates are included in the V1 sync. `IgnoreExpired` has no effect on V1 today because the V1 sync never populates a certificate expiry date; it is applied on V2 only. -Expired certificates are included by default. Set `IgnoreExpired: true` on the connector to skip them during sync. +On V2, synchronization reads `/reports/orders` instead — see [V2 Order Lifecycle](#v2-order-lifecycle). ### Product Code Resolution -When an enrollment request arrives, the numeric CERTInext product code is resolved in this order: +On V1, the numeric CERTInext product code is resolved in this order (V2 follows [V2 Product Code Resolution](#v2-product-code-resolution)): 1. `ProductCode` template parameter (explicit override — use for sandbox or non-standard codes). 2. `ProfileId` template parameter (deprecated alias, accepted for backward compatibility). @@ -266,4 +498,146 @@ When an enrollment request arrives, the numeric CERTInext product code is resolv If none of these yield a code, enrollment fails with a validation error. -{% include 'architecture.md' %} +## V2 API + +The plugin includes an opt-in CERTInext V2 REST API code path that uses OAuth2 `client_credentials` authentication and an order-centric resource model. V2 is disabled by default; V1 remains the active path unless `UseV2Api` is explicitly set to `true`. When enabled, V2 is fully self-contained: Ping, Enroll, GetSingleRecord, Revoke, and Synchronize all route through the V2 API, and V1 credentials (`ApiKey`, `AccountNumber`, `AuthMode`) are not required. Known limitations are listed under [Known Gaps](#known-gaps). + +### V2 CA Connector Fields + +V2 mode reuses the connector's `ApiUrl`, `OAuthClientId`, and `OAuthClientSecret` fields (see [Connection](#connection)) rather than separate V2-only credentials. `ApiUrl` becomes the V2 host, and the client ID and secret authenticate against it regardless of `AuthMode`. Two fields are specific to V2: + +| Field | Required | Description | +|---|---|---| +| `UseV2Api` | Optional | Enables the V2 code path for connection tests, enrollment, revocation, status checks, and synchronization. Default: `false`. | +| `V2SyncLookbackHours` | Optional | Hours subtracted from the last-sync time on incremental sync. Default: `72`. | +| `SslComSubmitOrganization` | Optional | OV/EV on V2. `true` lets the plugin submit an unvalidated organization to SSL.com, which **accepts SSL.com's subscriber agreement on the organization's behalf**; see [SSL.com organization validation](#sslcom-organization-validation). Default: `false`. | +| `SslComAdminEmail` | Optional | Administrator email sent as `adminEmail` on that submission. Blank omits it. Example: `pki-admin@example.com`. | +| `V2InlineCsr` | Optional | SSL/TLS only. `true` (the default) sends the CSR inline in the create call (a single `POST /ssl-certificates`), as a direct API integration does. `false` creates the order and then submits the CSR; that two-call flow fails for a domain the account has already validated, because CERTInext approves the order at create and then rejects the CSR. A create that times out or returns a 5xx can leave an order that issues and is imported by the next sync rather than cancelled, and the create call can hold about 20 seconds until issuance. Private PKI always uses two calls. Default: `true`. | + +- **Why a lookback:** the API's `from`/`to` filter may bracket either the order-placement date or the issuance date. The window keeps an order created before the last sync but issued afterward (for example a slow DCV order) from being missed. + +#### V2 OAuth2 Setup + +1. Log in to the CERTInext portal for your environment. +2. Navigate to **Integrations → APIs**. +3. Click **+ Create API Credentials**, set **API Type** to `REST`, and select the **OAuth** auth type (not `Access Key`). The V2 spec requires the key to be generated in OAuth mode. A key that wasn't gets HTTP 403 `unauthorized_client` at token time. +4. Note the client ID and client secret. Enter them in `OAuthClientId` and `OAuthClientSecret`. The V2 spec's token example uses the account number as `client_id`, but the plugin never substitutes `AccountNumber` for it, so set `OAuthClientId` explicitly. See [Step 1 of the migration guide](#step-1--create-a-v2-oauth2-credential) for the failure modes. +5. Set `UseV2Api` to `true` and set `ApiUrl` to the V2 base URL (no trailing path suffix), e.g. `https://sandbox-us-api.certinext.io`. +6. V1-only fields (`ApiKey`, `AccountNumber`, `AuthMode`) are not required in this mode and can be left blank. + +#### V2 Token Caching + +The plugin obtains a V2 bearer token via the standard OAuth2 `client_credentials` grant (`grant_type=client_credentials`, form-encoded) against `{ApiUrl}/oauth/token`. Tokens are cached in memory and reused until 60 seconds before expiry (minimum 30-second cache). Token refresh is thread-safe. + +### V2 Certificate Template Fields + +When `UseV2Api` is `true`, two additional enrollment parameters become relevant: + +| Parameter | Required / Optional | Type | Description | Example / Default | +|---|---|---|---|---| +| `ProductFamily` | Optional | String | CERTInext V2 product family: `ssl` or `private-pki` (see [V2 Private PKI Orders](#v2-private-pki-orders)). Default: `ssl`. | `ssl` | +| `ProductVariant` | Optional | String | Variant within the family. `ssl`: `dv`, `ov`, or `ev`. `private-pki`: `intranet-ssl` or `igtf-host` (required). | Derived from `ProductId` (for example `dv`) | + +- **`ProductVariant` default:** when omitted for `ssl`, the plugin derives it from the selected product (an OV product sends `ov`, an EV product sends `ev`). An explicit value that contradicts the product fails enrollment. +- **`signature` (Document Signer):** the parameter accepts it, but enrollment is not supported and fails before any order is placed. +- **Unrecognized family:** treated as `ssl`. +- **`ProductCode`:** optional on V2. When set, it is sent in the `X-Product-Code` header as an override; when blank, no header is sent and CERTInext resolves the product. + +### V2 Product Code Resolution + +When `UseV2Api` is `true`, the plugin does not choose a numeric product code. The V2 spec treats the `X-Product-Code` header on order create as an optional override: CERTInext's wrapper picks the right catalog product from the variant (`productVariant` for SSL/TLS, `variant` for Private PKI), whether `certificate.domain` is a wildcard (it starts with `*.`), and whether `additionalDomains` is non-empty (multi-domain, UCC). The create response reports the product it chose as `resolvedProductCode`, which the plugin logs at Information level. + +1. **No `ProductCode` on the template (the default)** — no `X-Product-Code` header is sent. The connector's `DefaultProductCode` is not used, and neither is the catalog: save-time validation does no catalog check, and enrollment makes no catalog call. The plugin decides whether the order is wildcard or multi-domain from the request itself: + - **Wildcard:** the primary domain starts with `*.`. + - **Multi-domain:** the selected product is a UCC product, or the CSR or gateway SAN list carries DNS names beyond the primary domain (its `www.` variant, and a wildcard's bare apex, don't count). Those names are sent as `additionalDomains`, which makes CERTInext choose a UCC product. +2. **Explicit `ProductCode` (or the deprecated `ProfileId` alias)** — the override. It is sent as-is in the `X-Product-Code` header, after template save-time validation confirms it exists in the live V2 catalog and matches the selected product. Use it when your account holds several matching products (for example different CA profiles for the same variant) and you want to force one. With an override, the plugin reads the catalog once per enrollment to recognize UCC and wildcard products, and rejects extra SANs on a single-domain product. + +This differs from V1, where `DefaultProductCode` only affects renewals (see [DefaultProductCode](#defaultproductcode)). + +### V2 Private PKI Orders + +With `ProductFamily=private-pki`, the plugin places the order against CERTInext's Private PKI endpoint using the Private PKI request body, which differs from the SSL/TLS one: + +- **Product code is optional.** CERTInext resolves the Private PKI product from `ProductVariant`. Set `ProductCode` to your account's Private PKI catalog code only to pick between several matching products; template validation then checks that it is a Private PKI product (`productTypeID` `39`). +- **Which `ProductID` to pick.** The plugin advertises SSL/TLS product names only, so the template still needs one from that list. It does not affect a `private-pki` order, which is built from `ProductVariant` (and `ProductCode`, if set), so any ProductID (for example `DV SSL`) works. +- **Variant is required.** Set `ProductVariant` to `intranet-ssl` or `igtf-host`. +- **Hostname.** The order's primary `hostname` comes from `DomainName`, or from the CSR's CN when `DomainName` isn't set. +- **SANs.** Sent in `additionalHosts`, which accepts DNS names and IPv4/IPv6 addresses. They come from the gateway's SAN list, or from the CSR when the gateway supplies none. +- **Unsupported SANs.** Email and URI SANs can't be expressed, so they are left off the order and a warning is logged. `SubmitNonDnsSans` isn't consulted. +- **No DCV, organization, or subscriber agreement.** Private PKI orders have none of these steps, so DCV is never attempted for them, and `OrganizationNumber`, `AutoSecureWww`, `SignerName`, `SignerPlace`, and `SignerIp` aren't used. +- **Shared fields.** The requestor, technical contact, subscription, email-notification, and group settings are sent exactly as they are for SSL/TLS orders. +- **Two-call CSR delivery.** The plugin creates the order without a CSR and then submits it, always. CERTInext rejects an inline CSR on the Private PKI create (HTTP 422), so the SSL/TLS-only `V2InlineCsr` setting doesn't apply; when it's on, the plugin logs a one-time notice that Private PKI ignores it. + +### V2 Order Lifecycle + +A V2 enrollment places the order, submits the CSR (or, with `V2InlineCsr` on for SSL/TLS, sends it inline in the create call), and then checks the order status; see [V2 enrollment flow](#v2-enrollment-flow) for the full sequence. V2 orders are identified by the `orderId` the V2 order placement endpoint returns, which the plugin stores unchanged as the `CARequestID` and uses for all later tracking, certificate download, and revocation calls. The V2 spec's examples show `ord_`-prefixed IDs, but V2 returns numeric order numbers in the same format as V1 (e.g. `6625262451`). Treat the ID as an opaque string. + +V2 status strings map to Keyfactor enrollment statuses as follows: + +| V2 Status | Keyfactor Status | Notes | +|---|---|---| +| `issued` | Issued | Certificate is immediately downloaded and returned to Command. CERTInext can report `issued` for a while before the certificate is generated (Download Certificate answers 422 `EMS-1165`); see [Issued but not generated yet](#issued-but-not-generated-yet). | +| `pending-dcv` | Pending External Validation | Order is awaiting domain control validation. | +| `pending-csr` | Pending External Validation | Order is awaiting CSR submission or processing. | +| `pending-agreement` | Pending External Validation | Order requires subscriber agreement acceptance. For SSL/TLS orders the plugin accepts it (see [Subscriber agreement fallback](#subscriber-agreement-fallback)). | +| `pending-organization-verification` | Pending External Validation | OV/EV order is awaiting organization verification. | +| `pending-documents` | Pending External Validation | Order is awaiting supporting document submission. | +| `pending-approval` | Pending External Validation | Order is awaiting final CA/LRA approval before issuance. | +| `revoked` | Revoked | Order has been revoked. | +| `cancelled` | Failed | Order was cancelled; a new enrollment is required. | +| `rejected` | Failed | Order was rejected by the CA/LRA; a new enrollment is required. | +| `expired` | Issued | An expired-but-not-revoked order is reported as issued (GENERATED), matching V1's convention — it remains visible in Command's inventory rather than disappearing as a failure. | +| `unknown` | Pending External Validation | CERTInext can't currently report where the order is; the order is kept pending and re-checked on the next status poll or sync, and the plugin logs a warning. | + +Any V2 status not in this table (e.g. a value CERTInext adds in the future) maps to Failed, and the +plugin logs a warning distinguishing "unmapped status" from the statuses above that are deliberately +mapped to Failed — see the gateway trace log if certificates unexpectedly show as failed. + +**V2 synchronization:** + +- Synchronize pages through `/reports/orders`. Pages are capped at 100 rows, and `PageSize` is clamped to that. +- The report carries display strings (for example `Order Fulfilled`, `Certificate Downloaded`) rather than the status enum above. Recognized strings are mapped directly. Any other combination falls back to a live order-status call, so a new display value never silently misclassifies an order. +- Cancelled and rejected orders are skipped. Issued orders have their certificate chain downloaded. +- CERTInext does not serve the certificate body of a revoked order. A revoked order is propagated as revoked only when the gateway already holds that certificate (the revocation date and reason come from a live status call). +- Otherwise a revoked order is reported as Failed (the gateway has a record without a body) or skipped (no record), so the gateway never stores a revoked record without a certificate. +- `IgnoreExpired` is applied here: expired certificates are skipped. +- An issued order whose download answers 422 `EMS-1165` is emitted without a certificate body and counted as `IssuedNotGeneratedYet` in the sync summary instead of logging a warning per order; a later pass picks it up. + +#### SSL.com organization validation + +OV and EV certificates are issued under an organization that SSL.com must have validated. Before placing a V2 OV or EV SSL/TLS order for the connector's `OrganizationNumber`, the plugin reads that organization's SSL.com validation status (`GET /organizations/{orgNumber}/ca-validations/sslcom`): + +1. **Validated at the order's level (OV or EV):** nothing more is done. +2. **Not validated:** the plugin asks SSL.com to refresh the status once (`POST .../sslcom/sync`) and checks again. +3. **Still not validated, and `SslComSubmitOrganization` is `true`,** the level isn't already requested, and SSL.com's readiness block says the organization is ready for that level (`ready` for OV, `evReady` for EV, with nothing missing): the plugin submits it (`POST .../sslcom` with `levels` set to the order's level, `subscriberAgreementAccepted: true`, and `adminEmail` when `SslComAdminEmail` is set). **This accepts SSL.com's subscriber agreement on the organization's behalf.** The intent is logged at Information level before the call, and the connector start-up log warns that the setting is on. Leave it `false` (the default) unless you are authorized to accept that agreement; the plugin then only reads and refreshes the status. +4. **Whatever happens, the order is still placed.** A not-validated organization, a not-ready organization, or any failed SSL.com call logs one warning and never blocks or fails the enrollment (a not-validated organization's OV/EV order simply stays pending until SSL.com validates it). The warning includes SSL.com's status, `lastError`, and the fields it reports missing; email addresses are masked unless `LogSensitiveRequestData` is on. + +DV and Private PKI orders skip this check entirely. + +**How "validated" is decided.** The spec describes the response only in prose ("status per level (OV, EV) with validTill"), so the plugin reads it defensively. A level counts as validated when its entry in `levels` carries a validated status word (`VALIDATED`, `VALID`, `APPROVED`, `ACTIVE`, `COMPLETE`, `COMPLETED`, or `ISSUED`) or a true `validated` flag, or has no status but a `validTill` in the future; an entry whose `validTill` has passed is not validated. A bare level name in `levels` counts only when the overall `status` is itself a validated word. The overall `status` and `validatedAt` alone never count, since they aren't per level. Any shape the plugin doesn't recognize is treated as not validated; because that only produces a warning, the cost of a false "not validated" is a log line. + +#### Subscriber agreement fallback + +The create body already carries the agreement (`signerName`, `signerPlace`, `accepted: true`), but if Track Order still shows an SSL/TLS order at `pending-agreement`, the CA won't release the certificate until the agreement is accepted. The plugin then calls `POST /api/certinext/v2/ssl-certificates/{orderId}/agreement` with the same signer values: + +- **Enrollment:** at most once per order per `Enroll` call, whether the status is seen right after create, after DCV, or during the pickup poll. The signer is the template's `SignerName` (else the requestor name) and `SignerPlace` (else the connector's), as on create. +- **Synchronize:** at most once per order per pass, using the connector's `RequestorName` and `SignerPlace` (a sync has no template). A pending SSL/TLS order in the listing that wasn't already tracked costs one extra status call per pass; with no `SignerPlace` or `RequestorName` configured the step is skipped entirely. +- **Audit and failures:** the intent is logged at Information before the call (the signer's name and place appear only when `LogSensitiveRequestData` is on). A failed call is logged as a warning and never fails the enrollment or the sync; the order stays pending. +- **Not applicable:** Private PKI orders have no Subscriber Agreement, and `GetSingleRecord` doesn't accept agreements. + +#### Issued but not generated yet + +CERTInext can report an order as `issued` before the certificate exists: Download Certificate then answers HTTP 422 `EMS-1165 Invalid request status.` Normally the certificate is generated about 20 seconds later, but the sandbox has been seen to take far longer. The plugin treats this as an expected state, not an error: + +- **Enrollment:** the pickup poll keeps waiting (within `PickupRetries` x `PickupDelay`), logging each attempt at Debug level and writing one Information summary if the budget runs out. The enrollment returns pending, and a later synchronization imports the certificate. +- **`GetSingleRecord` and Synchronize:** logged at Information (single record) or Debug with a count in the sync summary, rather than a warning. The record is returned without a certificate body, as for any failed download. +- **Log fields:** the lines include CERTInext's `orderState` and `certificateState` text (for example `Approved by System` versus `Certificate Generated`) for diagnosis. Their vocabulary isn't documented, so the plugin never acts on it. +- **Any other download error** is still logged as a warning. + +V2 has no *renew* endpoint. CERTInext does document a `/reissue` endpoint (`mode: rekey|update-sans`, with optional `revokePrevious`/`revokeReason`), but the plugin does not use it — every enrollment type (New, Reissue, Renew, RenewOrReissue) places a fresh V2 order, and the prior order/certificate is left issued rather than auto-revoked. + +### V2 Revocation Reason Handling + +CERTInext's V2 revoke endpoint accepts only a subset of its own documented reason enum. When Command's revoke reason maps to one CERTInext rejects, the plugin substitutes an accepted reason and retries once, rather than failing the revoke outright: CA-compromise and AA-compromise are retried as key-compromise; unspecified (Command's default when no reason is given) and certificate-hold are retried as cessation-of-operation. See [Revocation Reason Codes](#revocation-reason-codes) in the migration guide below for the full accepted/rejected matrix. + +{% include 'migration-v1-to-v2.md' %} diff --git a/docsource/development.md b/docsource/development.md index 14c6cff..16de668 100644 --- a/docsource/development.md +++ b/docsource/development.md @@ -4,136 +4,188 @@ This document covers local development, testing, and live API smoke-testing for ## Prerequisites -- .NET SDK 8.0 or later -- `python3` (used for HMAC computation in Makefile API targets) -- `jq` (used for JSON pretty-printing in Makefile API targets) -- `~/.env_certinext` populated with credentials (see below) +| Tool | Used for | +|---|---| +| .NET 10 SDK | Building the solution. The plugin multi-targets `net8.0` and `net10.0`. | +| .NET 8 runtime | Running the unit and integration test projects, which target `net8.0`. | +| `bash`, `curl` | The API smoke-test scripts under `scripts/` | +| `python3` | The scripts compute the SHA-256 `authKey`, random transaction IDs, and V2 idempotency UUIDs with it. | +| `jq` | Pretty-printing JSON in the scripts | +| `openssl` | `make generate-test-csr` and the CSR helper scripts | +| `~/.env_certinext` | Credentials for the V1 targets and tests (see below). The V2 targets and tests also need `~/.env_certinext_v2`. | -## Credentials File +## Credential Files -Create `~/.env_certinext` with the following variables. This file is **never committed** — add it to your global `.gitignore` or keep it only in `$HOME`. +Both files hold `KEY=VALUE` lines and are **never committed**. Keep them in `$HOME`, or add them to your global `.gitignore`. The tests and runner let real environment variables override values in `~/.env_certinext`; the scripts source the file, so the file wins there. -```bash -CERTINEXT_API_URL=https://api.certinext.io/emSignHub-API # or sandbox URL -CERTINEXT_ACCESS_KEY= -CERTINEXT_ACCOUNT_NUMBER= -CERTINEXT_GROUP_NUMBER= -CERTINEXT_ORG_NUMBER= -CERTINEXT_PRODUCT_CODE=838 # default product used by generate-order -CERTINEXT_REQUESTOR_EMAIL= -CERTINEXT_REQUESTOR_NAME= -CERTINEXT_REQUESTOR_MOBILE= -# Public IP of the machine running generate-order. Leave blank to auto-detect via api.ipify.org. -CERTINEXT_SIGNER_IP= -``` - -> Note: `CERTINEXT_GROUP_NUMBER` and `CERTINEXT_ORG_NUMBER` are distinct. The group number is the delegation unit (cost center/department) used in every order request. The org number is the validated organization record used for OV and EV orders. +| File | API | Contents | +|---|---|---| +| `~/.env_certinext` | V1 | Access key, account number, and the V1 `emSignHub-API` URL | +| `~/.env_certinext_v2` | V2 | OAuth client ID and secret, and the bare V2 host URL | + +Set `CERTINEXT_V2_ENV_FILE` to point the `v2-*` Makefile targets at a different V2 file. The V2 integration tests always read `~/.env_certinext_v2`. + +| Variable | `~/.env_certinext` (V1) | `~/.env_certinext_v2` | Used by | +|---|---|---|---| +| `CERTINEXT_API_URL` | `https://sandbox-us-api.certinext.io/emSignHub-API` (scripts append `/`) | `https://sandbox-us-api.certinext.io` (V2 host, no path) | All scripts, tests, and the runner | +| `CERTINEXT_ACCESS_KEY` | Access key from Integrations → APIs | n/a | V1 scripts, tests, runner | +| `CERTINEXT_ACCOUNT_NUMBER` | Numeric account ID from the account profile | n/a | V1 scripts, tests, runner | +| `CERTINEXT_GROUP_NUMBER` | Group number from the credential row | n/a | V1 scripts, tests, runner | +| `CERTINEXT_ORG_NUMBER` | Organization ID, for OV and EV orders | n/a | V1 and V2 OV/EV tests | +| `CERTINEXT_PRODUCT_CODE` | Default product code for `generate-order` (for example `838`) | V2 product code | Scripts and tests | +| `CERTINEXT_REQUESTOR_EMAIL` | Email on your CERTInext account | n/a | Scripts, tests, runner | +| `CERTINEXT_REQUESTOR_NAME` | Requestor or automation account name | n/a | Scripts, tests, runner | +| `CERTINEXT_REQUESTOR_MOBILE` | Digits only, no country code | n/a | `generate-order` | +| `CERTINEXT_SIGNER_IP` | Public IP of this machine; blank auto-detects via `api.ipify.org` | n/a | `generate-order` | +| `CERTINEXT_CLIENT_ID` | n/a | OAuth client ID | V2 targets and tests | +| `CERTINEXT_CLIENT_SECRET` | n/a | OAuth client secret | V2 targets and tests | +| `CERTINEXT_USE_V2_API` | n/a | `1` enables the V2 integration tests | V2 tests | +| `CERTINEXT_CF_API_TOKEN` | Cloudflare token with DNS:Edit on the zone | n/a | DCV tests (both API generations) | +| `CERTINEXT_CF_ZONE_ID` | Cloudflare zone ID | n/a | DCV tests | +| `CERTINEXT_DCV_DOMAIN` | Domain in that zone used by the DCV tests | n/a | DCV tests | +| `CERTINEXT_ORDER_ID` | Existing V1 order for the order-lookup smoke tests | n/a | `SmokeTests` | +| `CERTINEXT_V2_ORDER_ID` | n/a | Existing V2 order for the V2 lifecycle tests | `V2LifecycleTests` | +| `CERTINEXT_TEST_ORDER_NUMBER` | Order for the runner to track | n/a | `CERTInext.IntegrationRunner` | + +> **Note:** `CERTINEXT_GROUP_NUMBER` and `CERTINEXT_ORG_NUMBER` are distinct. The group number is the delegation unit (cost center or department) used in every order request. The org number is the validated organization record used for OV and EV orders. + +The V2 file reuses the key names `CERTINEXT_API_URL` and `CERTINEXT_PRODUCT_CODE` with V2 values. Source only `~/.env_certinext` into your shell, never the V2 file; the V2 tests read it from disk themselves. For the V2 helper scripts, see [scripts/v2/README.md](../scripts/v2/README.md). + +### Opt-in flags + +Tests that place real orders, publish DNS records, or cancel orders run only when you export the matching flag in your shell. The test fixture deliberately ignores these flags in both env files, so a flag left in a file can't arm every run. + +| Flag | Arms | +|---|---| +| `CERTINEXT_COMPLETE_PENDING` | Complete every pending DV order (needs Cloudflare) | +| `CERTINEXT_RUN_BULK_TEST`, `CERTINEXT_V2_RUN_BULK_TEST` | V1 and V2 bulk enrollment and pagination tests | +| `CERTINEXT_PRIVATE_PKI_LIVE` | One live Private PKI order and revoke | +| `CERTINEXT_V2_OPS_TESTS` | V2 order-window sweep (maintenance tool) | +| `CERTINEXT_V2_LIFECYCLE_DV_UCC`, `_OV`, `_OV_UCC`, `_EV`, `_WILDCARD_DV`, `_RENEW_REISSUE`, `_FRESH_DCV` | The matching V2 full-lifecycle test | + +Set each to `1`. [INTEGRATION_TESTING.md](../CERTInext.IntegrationTests/INTEGRATION_TESTING.md) lists the remaining flags, such as the algorithm matrices, and the extra variables each test needs. To load `~/.env_certinext` into a shell that also exports a flag, use `set -a; . ~/.env_certinext; set +a`. ## Build and Test Targets | Target | Command | Description | |---|---|---| | Build | `make build` | `dotnet build` the solution | -| Unit tests | `make test` | Run all mock/unit tests | -| Integration tests | `make integration-test` | Run live API tests (requires `~/.env_certinext`; tests skip automatically if credentials are absent) | -| Coverage report (terminal) | `make coverage` | Run tests with XPlat coverage and print summary | -| Coverage report (browser) | `make coverage-report` | Same as `coverage`, then opens HTML report in the default browser | +| All tests | `make test` | `dotnet test` the whole solution, **including the live integration tests** (they skip when credentials are absent) | +| Unit tests only | `dotnet test CERTInext.Tests/` | Mock and contract tests with no external services | +| Integration tests | `make integration-test` | Live API tests only (requires the env files; tests skip automatically when credentials are absent) | +| Coverage report (terminal) | `make coverage` | Run the solution's tests with XPlat coverage and print a summary | +| Coverage report (browser) | `make coverage-report` | Same as `coverage`, then opens the HTML report with macOS `open` (on Linux, open `/tmp/certinext-coverage-report/index.html` yourself) | | Clean | `make clean` | `dotnet clean` and wipe coverage output directories | -### Build variants — `DcvSupport` (DCV vs no-DCV) +## DCV Build and Code Layout + +DNS-01 domain control validation (DCV) is part of the standard build. For how the flow behaves, see [Domain Control Validation](architecture.md#domain-control-validation); for the connector settings, see the `Dcv*` rows in [configuration.md](configuration.md#ca-configuration). + +### Build -The plugin builds against two `Keyfactor.AnyGateway.IAnyCAPlugin` contracts from a single -codebase, selected by the `DcvSupport` MSBuild property. The plugin's `AnyCAPluginCertificate` -records must match the gateway host's IAnyCAPlugin version to persist, so the build must target -the host (see issue 0003). +- **Package and gateway.** The plugin compiles against `Keyfactor.AnyGateway.IAnyCAPlugin` **3.3.0**, which provides `IDomainValidatorFactory`, and targets AnyCA Gateway REST **26.2.0** and later. +- **One MSBuild property.** `CERTInext/CERTInext.csproj` sets `DcvSupport` to `true` by default. It selects the IAnyCAPlugin package version, defines the `SUPPORTS_DCV` compile constant, and includes the DCV test files in the test projects. Plain `dotnet build` and `make build` produce the DCV build, and release builds use the same default. +- **Test projects mirror it.** `CERTInext.Tests/CERTInext.Tests.csproj` and `CERTInext.IntegrationTests/CERTInext.IntegrationTests.csproj` define the same property so the DCV test files compile with it. +- **Target frameworks.** The plugin targets `net8.0` and `net10.0`; both test projects target `net8.0`. -| Build | Command | IAnyCAPlugin | DCV | Target gateway host | -|---|---|---|---|---| -| **No-DCV (default)** | `make build` / `dotnet build` | `3.2.0` (stable) | fenced out (`#if SUPPORTS_DCV`) | AnyCA Gateway **25.5.x** (IAnyCAPlugin 3.2.0) | -| **DCV** | `dotnet build -p:DcvSupport=true` | `3.3.0-PRERELEASE` | enabled | AnyCA Gateway **26.x** (IAnyCAPlugin ≥ 3.3) | +### Where the DCV code lives -The **default is the no-DCV / 3.2.0 build** — it is the GA artifact that loads and persists on the -current GA gateway (25.5.x) and depends only on a stable package, so it is what CI ships. Build the -DCV variant explicitly with `-p:DcvSupport=true` for 26.x hosts. The one property drives the package -version, the `SUPPORTS_DCV` compile constant, and DCV test-file inclusion across all three projects, -so the two host targets are a build flag rather than a maintained fork. +The DCV code is in `CERTInext/CERTInextCAPlugin.cs`, compiled under `#if SUPPORTS_DCV`: + +| Member | What it does | +|---|---| +| `using` alias and `DomainValidatorFactory` property | Name the `IDomainValidatorFactory` type and cast the stored factory to it | +| Internal test constructor taking an `IDomainValidatorFactory` | Lets tests inject a fake or real DNS validator | +| `SetDomainValidatorFactory(object)` | Receives the gateway's DNS provider factory and logs which type was offered | +| `EnrollNewAsync` (V1) | Runs DCV right after a new order is placed, then waits for issuance | +| `EnrollV2Async` (V2) | Runs DCV when the new order is pending, then re-checks its status | +| `Synchronize` / `SynchronizeV2Async` | Drive recently placed pending orders through DCV, bounded by `DcvSyncMaxOrderAgeHours` and `DcvSyncMaxPerPass` | +| `GetSingleRecord` / `GetSingleRecordV2Async` | Drive a pending order through DCV on a manual refresh | +| `TryRunDcvDuringSyncAsync` | V1 sync and single-record wrapper: in-flight guard, bounded timeout, swallows non-cancellation errors | +| `PerformDcvIfNeededAsync` | The V1 flow: wait for the challenge, `GetDcv`, publish TXT, `VerifyDcv`, poll, clean up | +| `PerformDcvV2IfNeededAsync` | The V2 entry point; dispatches to the single-domain or multi-domain V2 flow | + +The stored factory is held as `object` and cast inside method bodies, so the plugin class loads even when the host doesn't supply `IDomainValidatorFactory`. DCV is then inactive: with `DcvEnabled` set to `true`, the plugin logs a warning at startup, and orders that need validation stay pending until a DNS provider is available or `DcvEnabled` is set to `false`. + +The DNS provider side is a separate gateway plugin that implements `IDomainValidator` (for example `azure-azuredns-dnsplugin`). The integration tests include a Cloudflare-backed validator (`CloudflareDomainValidator`) and a recording wrapper for exercising the flow against the live sandbox. ## API Smoke-Test Targets -All API targets source `~/.env_certinext`, compute the HMAC `authKey` (`SHA256(accessKey + ts + txn)`), and call the live CERTInext API via `curl`. All JSON responses are piped through `jq`. +All V1 targets source `~/.env_certinext`, compute `authKey` as the SHA-256 digest `SHA256(accessKey + ts + txn)`, and call the live V1 API with `curl`. JSON responses are piped through `jq`. The V2 equivalents are the `v2-*` targets (for example `make v2-ping`, `make v2-list-products`, `make v2-orders-report`), which read `~/.env_certinext_v2`. **Start here when setting up a new environment:** ```bash make ping # should return {"meta": {"status": "1", ...}} make products # lists product codes for your account -make orders # lists recent orders — useful to find an ORDER_NUMBER to test with +make orders # lists recent orders; useful to find an ORDER_NUMBER to test with ``` | Target | Command | Description | |---|---|---| -| Verify credentials | `make ping` | `ValidateCredentials` — confirms the access key and account number are accepted | -| List products | `make products` | `GetProductDetails` — shows all certificate product codes available to your group | -| List orders | `make orders [PAGE=1] [PAGE_SIZE=10]` | `GetOrderReport` — paginated order listing | -| Track an order | `make get-order ORDER_NUMBER=NNNNN` | `TrackOrder` — returns current status for a specific order | -| Download a certificate | `make get-cert ORDER_NUMBER=NNNNN` | `GetCertificate` — returns the PEM chain for a specific order | -| Place a draft order | `make generate-order DOMAIN=example.com [CSR_FILE=req.pem] [VALIDITY=1] [SAVE_AND_HOLD=1]` | `GenerateOrderSSL` — places a new order; `SAVE_AND_HOLD=1` (default) creates a draft | -| Revoke an order | `make revoke-order ORDER_NUMBER=NNNNN [REASON_ID=1]` | `RevokeOrder` — revokes an issued certificate | -| Attach a CSR to a draft | `make submit-csr ORDER_NUMBER=NNNNN CSR_FILE=req.pem` | `SubmitCSR` — attaches a CSR to a saveAndHold draft order | +| Verify credentials | `make ping` | `ValidateCredentials`: confirms the access key and account number are accepted | +| List products | `make products` | `GetProductDetails`: shows all certificate product codes available to your group | +| List orders | `make orders [PAGE=1] [PAGE_SIZE=10]` | `GetOrderReport`: paginated order listing | +| Track an order | `make get-order ORDER_NUMBER=NNNNN` | `TrackOrder`: returns current status for a specific order | +| Download a certificate | `make get-cert ORDER_NUMBER=NNNNN` | `GetCertificate`: returns the PEM chain for a specific order | +| Place a draft order | `make generate-order DOMAIN=example.com [CSR_FILE=req.pem] [VALIDITY=1] [SAVE_AND_HOLD=1]` | `GenerateOrderSSL`: places a new order; `SAVE_AND_HOLD=1` (default) creates a draft | +| Revoke an order | `make revoke-order ORDER_NUMBER=NNNNN [REASON_ID=1]` | `RevokeOrder`: revokes an issued certificate | +| Attach a CSR to a draft | `make submit-csr ORDER_NUMBER=NNNNN CSR_FILE=req.pem` | `SubmitCSR`: attaches a CSR to a `saveAndHold` draft order | | Discover product codes | `make probe-products` | Places `saveAndHold=1` draft orders for all known SSL/TLS product codes and reports which ones the account accepts | -| Cancel one pending order | `scripts/reject-order.sh ORDER_NUMBER=NNNNN` | Shell script — cancels a single pending order (not a `make` target) | -| Cancel all pending orders | `scripts/reject-all-pending.sh` | Shell script — dry-run by default; set `REJECT_ALL_PENDING=1` to fire (not a `make` target) | -| Show API target help | `make api-help` | Prints usage for all API targets | +| Cancel one pending order | `ORDER_NUMBER=NNNNN scripts/reject-order.sh` | Shell script that cancels a single pending order (not a `make` target); optional `REMARKS=...` | +| Cancel all pending orders | `scripts/reject-all-pending.sh` | Shell script, dry-run by default; set `REJECT_ALL_PENDING=1` to fire (not a `make` target) | +| Show API target help | `make api-help` | Prints usage for the V1 API targets | + +> **Note:** `TrackOrder` and `GetCertificate` require a formal `orderNumber`, which is only assigned after a draft order is submitted and approved. Draft orders (created with `saveAndHold:"1"`) have a `requestNumber` but no `orderNumber` until that point. + +### V2 targets -> Note: `TrackOrder` and `GetCertificate` require a formal `orderNumber`, which is only assigned after a draft order is submitted and approved. Draft orders (created with `saveAndHold:"1"`) have a `requestNumber` but no `orderNumber` until that point. +The `v2-*` targets that create, verify, submit, accept, cancel, or revoke only **preview** the request by default. To send it, add `V2_ARGS=--yes-mutate`: + +```bash +make v2-revoke-ssl ORDER_ID=123 V2_ARGS=--yes-mutate +``` + +Read-only targets such as `v2-ping`, `v2-list-products`, `v2-track-order`, and `v2-orders-report` run without it. See [scripts/v2/README.md](../scripts/v2/README.md) for all V2 scripts. ## Draft Orders (saveAndHold) -Setting `SAVE_AND_HOLD=1` (the default) on `make generate-order` places an order in "On Hold" state without triggering billing, DCV, or CA issuance. This is useful for validating that an order payload is accepted by the API. +Setting `SAVE_AND_HOLD=1` (the default) on `make generate-order` places an order in the "On Hold" state without triggering billing, DCV, or CA issuance. This is useful for validating that an order payload is accepted by the API. Draft orders behave as follows: - Assigned a `requestNumber` immediately on creation. - Do **not** receive an `orderNumber` until the draft is formally submitted and approved. - Appear in `GetOrderReport` and are included in gateway synchronization runs. -- Cannot be passed to `TrackOrder` or `GetCertificate` — those endpoints require an `orderNumber`. +- Cannot be passed to `TrackOrder` or `GetCertificate`, because those endpoints require an `orderNumber`. The gateway does not use `saveAndHold` in normal enrollment flows. It is strictly a developer testing mechanism for validating order payloads against the live API. -## Integration Tests +## Tests -The `CERTInext.IntegrationTests/` project contains live API tests that run against the production India instance (`api.certinext.io`). All tests use `[SkippableFact]` and skip automatically when `~/.env_certinext` is absent or incomplete. +The solution has two test projects, and a small runner that is not part of the solution: -Run them with: +| Project | Purpose | +|---|---| +| `CERTInext.Tests` | Unit and contract tests. No external services: HTTP is served in-process by WireMock.Net, and the client is replaced by Moq mocks. See `CERTInext.Tests/TESTING.md`. | +| `CERTInext.IntegrationTests` | Live-API tests. Every test skips automatically when credentials are absent, and destructive or order-placing tests are additionally gated behind the opt-in flags above. See `CERTInext.IntegrationTests/TESTING.md` and `CERTInext.IntegrationTests/INTEGRATION_TESTING.md`. | +| `CERTInext.IntegrationRunner` | A read-only console program that exercises the V1 client against the live API: `Ping`, then a `GetOrderReport` listing, then `TrackOrder` for one order. It is not in `certinext-caplugin.sln`. | -```bash -make integration-test -``` +- **Unit tests only:** `dotnet test CERTInext.Tests/` +- **Live tests only:** `make integration-test` +- **Everything:** `make test` +- **Runner:** `dotnet run --project CERTInext.IntegrationRunner -- [ORDER_NUMBER]`. Without an argument it uses `CERTINEXT_TEST_ORDER_NUMBER` from `~/.env_certinext`, and it skips the `TrackOrder` step if neither is set. -See `CERTInext.IntegrationTests/INTEGRATION_TESTING.md` for a full description of each test, what it validates, and the expected API state. +Drive live-API verification through the integration tests and the runner rather than ad-hoc scripts, so every check is repeatable. ## Product Integration Test Coverage -The table below records live draft-order results against the Production — India instance. Orders were placed with `saveAndHold:"1"` so no billing, DCV, or CA issuance was triggered. Tests are in `CERTInext.IntegrationTests/DraftOrderTests.cs`. - -| Product | Code | Test Status | requestNumber | Notes | -|---|---|---|---|---| -| DV SSL | `838` | ✓ Tested | 4572531551 | Base domain; no extra fields required beyond base set | -| DV SSL Wildcard | `839` | ✓ Tested | 9149755266 | CSR CN must be `*.domain`; `domainName` must also use wildcard format | -| DV SSL UCC | `840` | ✓ Tested | 1611445122 | `certificateInformation.additionalDomains` array required | -| DV SSL Wildcard UCC | `841` | ✗ Blocked | — | EMS-918: "Additional Information cannot be empty" — required fields for this product not yet identified | -| OV SSL | `842` | ✓ Tested | 5546366498 | Requires `locality` and `postalCode` in `certificateInformation` | -| OV SSL Wildcard | `843` | ✗ Not tested | — | Draft order not yet placed | -| OV SSL UCC | `844` | ✗ Not tested | — | Draft order not yet placed | -| OV SSL Wildcard UCC | `845` | ✗ Blocked | — | EMS-918: "Additional Information cannot be empty" — required fields for this product not yet identified | -| EV SSL | `846` | ✓ Tested | 3932332114 | Requires `contractSignerInfo`, `certificateApproverInfo`, non-empty `streetAddress2`, `companyRegistrationNumber` | -| EV SSL UCC | `847` | ✗ Blocked | — | EMS-918: "Additional Information cannot be empty" — required fields for this product not yet identified | -| DV SSL 1 Month | N/A | ✗ Not supported | — | Visible in portal but not returned by `GetProductDetails` API; no product code available. Not supported by plugin. | -| DV SSL Wildcard 1 Month | N/A | ✗ Not supported | — | Visible in portal but not returned by `GetProductDetails` API; no product code available. Not supported by plugin. | -| emSign Intranet SSL | `100` | ✗ Not tested | — | EMS-1162: not provisioned on this account type | -| IGTF Host | `104` | ✗ Not tested | — | EMS-1162: not provisioned on this account type | -| S/MIME | `894` | ✗ Not tested | — | EMS-1162: not provisioned on this account type | -| Natural Person Doc Signer | `825` | ✗ Not tested | — | EMS-1162: not provisioned on this account type | -| Legal Entity Doc Signer | `819` | ✗ Not tested | — | EMS-1162: not provisioned on this account type | - -Products returning EMS-1162 require special provisioning by eMudhra that is not included on a standard SSL/TLS account. The plugin code supports submitting orders for any product code; whether the order is accepted depends on what is provisioned for your account. +Draft-order and track-order semantics are covered by `LifecycleTests`, which creates its own order and asserts on it without relying on account-specific identifiers. + +Product codes are provisioned per account by eMudhra and are not portable across accounts (see [Product Codes](configuration.md#product-codes) in configuration.md). To discover which codes and required fields apply to *your* account: + +```bash +make probe-products +``` + +This places `saveAndHold=1` draft orders for all known SSL/TLS product codes and reports which return a `requestNumber` (valid and provisioned) versus an error (invalid or not provisioned). See `CERTInext.IntegrationTests/TESTING.md` for the expected test results. diff --git a/docsource/migration-v1-to-v2.md b/docsource/migration-v1-to-v2.md new file mode 100644 index 0000000..942fdc4 --- /dev/null +++ b/docsource/migration-v1-to-v2.md @@ -0,0 +1,234 @@ +## Migrating from V1 to V2 + +The CERTInext V2 REST API is an opt-in, order-centric API with OAuth2 authentication. It is +controlled entirely by the `UseV2Api` connector flag: `false` (default) keeps the connector on the +V1 API documented above; `true` switches **all** operations — Ping, Enroll, GetSingleRecord, Revoke, +and Synchronize — to V2. The two APIs cannot be mixed on a single connector. + +> Read [Known Gaps](#known-gaps) before migrating a production connector. The most important: +> +> - Document Signer (`ProductFamily=signature`) enrollment isn't supported. +> - DCV isn't validated end to end for per-SAN UCC domains, never-validated domains, or wildcards. +> - Every renewal places a new order. +> +> The plugin requires AnyCA Gateway REST 26.2.0 or later; see the compatibility matrix under [Requirements](#requirements). + +### Before You Begin: Confirm V2 Will Work for Your Templates + +- **Multi-domain (UCC) certificates are supported.** That covers DV UCC, DV Wildcard UCC, OV UCC, OV Wildcard UCC, and EV UCC. The plugin detects a UCC product from the live catalog's `productTypeID` and sends the extra SAN domains in the order's `additionalDomains` field. Per the V2 spec, a UCC order's SANs come from the order, not the CSR. +- **Only DNS SANs are sent.** `additionalDomains` takes DNS names only, so IP, email, and URI SANs are left off a UCC order and a warning is written to the gateway log. +- **Non-UCC SSL products are checked up front.** A CSR or SAN list with DNS names beyond the primary domain and its `www.` variant is rejected before any order is placed. UCC products are exempt. +- **DCV is not validated end to end in three cases.** These are per-SAN DCV on UCC orders, a domain that has never been validated, and wildcard DCV. The plugin runs the DNS-01 flow for each domain CERTInext reports as not yet validated, but test each UCC or wildcard template on the sandbox before relying on it in production. Keep it on a V1 connector if you need a validated path today. +- **DCV needs a DNS provider plugin.** `DcvEnabled` defaults to `true`. Without a DNS provider plugin for the order's domains, V2 DV orders stay pending after the order is placed. Deploy one, or set `DcvEnabled` to `false` and validate domains another way. See [DCV under V2](#dcv-under-v2). + +### Step 1 — Create a V2 OAuth2 Credential + +V2 authenticates with an OAuth2 `client_credentials` token, and the CERTInext V2 spec requires the API key to be generated in **OAuth mode**. The credential goes in the connector's `OAuthClientId` and `OAuthClientSecret` fields. + +1. Log in to the CERTInext portal for your environment. +2. Navigate to **Integrations → APIs**. +3. Click **+ Create API Credentials**. +4. Set **API Type** to `REST` and select the **OAuth** auth type, not `Access Key`. +5. Complete the form and click **Generate**. +6. Note the client ID and client secret right away. + +A V1 `Access Key` credential won't work against V2. The token request fails in one of two ways: + +| Response | Meaning | Fix | +|---|---|---| +| HTTP 403 `unauthorized_client` | The key exists but wasn't generated in OAuth mode. The plugin reports this. | Create a new key in OAuth mode. | +| HTTP 401 `invalid_client` | The client ID or secret is wrong. | Re-enter the values from the portal, or regenerate the secret. | + +> **Warning:** The V2 spec's token example sends the account number as `client_id`. The plugin never substitutes `AccountNumber` for the client ID, so always set `OAuthClientId` explicitly to the client ID shown in the portal, even if the value matches your account number. + +### Step 2 — Update the CA Connector + +You can update the existing CA connector in place, or create a second connector for the same CERTInext account with `UseV2Api=true` to validate V2 without disturbing V1 traffic. + +> **Caution:** Two connectors on one account both import the same orders, and each plugin instance can run DCV for the same pending order. Use the second-connector approach on the sandbox only, not in production. + +To switch a connector: + +- [ ] Set `UseV2Api` to `true`. +- [ ] Change `ApiUrl` to the V2 host. +- [ ] Set `OAuthClientId` and `OAuthClientSecret`. +- [ ] Set `SignerPlace`. The connector can't be saved with it blank in V2 mode. + +New fields `UseV2Api` and `V2SyncLookbackHours` are documented in [V2 API](#v2-api). The remaining V1 fields behave as follows. + +**Not used on V2** + +| V1 field | Behavior | +|---|---| +| `AccountNumber` | Not read by any V2 code path. The plugin never reuses it as the OAuth `client_id` (see Step 1). | +| `AuthMode` | V2 always authenticates with OAuth2 `client_credentials`. On V1, `OAuth` is legacy and unsupported: V1 does not honor OAuth, though the code still accepts it for already-saved connectors. | +| `ApiKey` | V2 never computes an `authKey`. | +| `OAuthTokenUrl` | V2 always requests a token from `{ApiUrl}/oauth/token`. Legacy and unsupported on V1, as for `AuthMode`. | +| `AccountingModel` | V2 order create has no equivalent field. | + +**Used unchanged** + +| V1 field | Behavior | +|---|---| +| `SubscriptionValidityYears` | Fallback validity when the template's `ValidityYears` is not set. | +| `TechnicalContactName` / `Email` / `IsdCode` / `MobileNumber` | Sent as the order's `technicalPointOfContact` on SSL/TLS and Private PKI orders. A blank field falls back to the matching `Requestor*` value, as on V1. `designation` is always `Technical Contact`. | +| `RequestorName` / `RequestorEmail` / `RequestorIsdCode` / `RequestorMobileNumber` / `RequestorDesignation` | Carried into the order's `requestor` block. The phone number is sent as `+`, and a blank `RequestorDesignation` is omitted. | +| `SignerPlace` / `SignerIp` | `SignerPlace` is carried into the order's `agreement` block and is required in V2 mode. `SignerIp` is V1 only: the V2 agreement block has no IP field, so it is never sent. | +| `AutoSecureWww` | Controls whether V2 adds the `www.` variant. | +| `PageSize` | Applies to V2 `/reports/orders` paging, capped at 100 per page. | +| `PickupRetries` / `PickupDelay` | V2 enrollment polls for a quickly issued certificate the same way V1 does. | +| `LogSensitiveRequestData` | Governs redaction of V2 request and response bodies in the gateway log. | +| `Enabled` | Unchanged. | + +**Used with changed behavior** + +| V1 field | What changes on V2 | +|---|---| +| `ApiUrl` | Use the bare host (for example `https://us-api.certinext.io`), not the V1 `/emSignHub-API/` URL. A trailing slash is harmless because the client trims it. A V1-style URL under V2, or the reverse, fails every call. Both modes require `https`; `http` is rejected except for a loopback host. | +| `OAuthClientId` / `OAuthClientSecret` | Set them to the OAuth-mode credential from Step 1. | +| `GroupNumber` | Sent as `groupNumber` on SSL/TLS and Private PKI order create, and as a query parameter on catalog and orders-report calls. Omitted when blank, so the account's default group applies. | +| `OrganizationNumber` | Required for OV/EV, unused for DV. V2 OV/EV orders send `organization.organizationNumber` with `preVetted=true`. CERTInext rejects an OV/EV order without organization data (HTTP 422 `EMS-1180`), so the plugin fails the enrollment before any CA call if it is blank. | +| `EmailNotifications` | `1` maps to `"all"` and `0` maps to `"consent-only"` (the V2 spec's enum is `consent-only` or `all`, so the V1 value `"0"` is no longer sent). Blank is omitted on V2, so the CA's default of `"all"` applies; V1 sends `"0"`. Set `0` explicitly for silent V2 orders. Any other value fails the enrollment before any CA call. | +| `SubscriptionAutoRenew` / `SubscriptionRenewCriteriaDays` | `SubscriptionAutoRenew=1` sets `subscription.autoRenew=true`. `SubscriptionRenewCriteriaDays` sets `subscription.renewBeforeDays` (blank omits it, so the CA's default of 30 applies). An unparseable or negative value fails the enrollment before any CA call. | +| `DefaultProductCode` | Not used on V2: no product code is sent unless the template sets `ProductCode` (see [V2 Product Code Resolution](#v2-product-code-resolution)). Renewals don't need it. | +| `IgnoreExpired` | Honored during V2 Synchronize: a report row with a parseable, past `certificateExpiryDate` is skipped, and a row with a missing or unparseable date is kept. Not applied on V1 yet. | +| `SubmitNonDnsSans` | SSL family: not consulted. A UCC order's `additionalDomains` takes DNS names only, so non-DNS SANs are left off with a gateway-log warning. Private PKI: not consulted. `additionalHosts` takes DNS names and IPs, so IP SANs are always submitted, and email and URI SANs are left off with a warning. | + +#### DCV under V2 + +`DcvEnabled` defaults to `true`, and the DCV settings behave as follows under V2: + +- `DcvEnabled`, `DcvTxtRecordTemplate`, `DcvPropagationDelaySeconds`, and `DcvTimeoutMinutes` are used. +- `DcvSyncMaxOrderAgeHours` and `DcvSyncMaxPerPass` bound DCV during synchronization, the same as V1. +- `DcvWaitForChallengeSeconds` and `DcvWaitForIssuanceSeconds` apply to V1 only. V2 publishes the challenge as soon as the order exists and polls the order until it leaves `pending-dcv` (bounded by `DcvTimeoutMinutes`), then runs the normal pickup poll. +- DCV applies to the SSL/TLS family. Private PKI orders have no DCV step. + +### Step 3 — Update Certificate Templates + +For each template you're migrating: + +1. **Leave `ProductCode` blank unless you need to force a catalog product.** On V2 the plugin sends no + `X-Product-Code` header and CERTInext resolves the product from the variant, the wildcard shape of the + domain and any additional domains, so a template with only `ProductId` works even when the catalog has + several products at that assurance level. Set `ProductCode` only to override that choice (for example + to pick one of several CA profiles). See [V2 Product Code Resolution](#v2-product-code-resolution). +2. Add `ProductFamily` (default `ssl`) if not already present — this is a V2-only parameter with no + V1 equivalent. `ProductVariant` (`dv`/`ov`/`ev`) is optional for `ssl`: if left unset, the plugin + derives it from the selected product (an OV product sends `ov`, an EV product sends `ev`) instead + of defaulting to `dv`; set it explicitly only to override. For a Private PKI template, set + `ProductFamily=private-pki`, `ProductVariant` to `intranet-ssl` or `igtf-host` (required, no + default); `ProductCode` is optional (see [V2 Private PKI Orders](#v2-private-pki-orders)). + `ProductFamily=signature` (Document Signer) enrollment is not supported. +3. Re-verify `ProductCode` (if set explicitly) against the V2 catalog. V1 and V2 product codes are not + guaranteed to be the same numeric values on your account — check the V2 catalog + rather than assuming the V1 code carries over. Template validation + (`ValidateProductInfo`) automatically checks `ProductCode` against the V2 catalog once + `UseV2Api=true`, so an incorrect code will be caught at template save time, not silently at + enrollment. +4. The `DomainName` template parameter takes effect in V2 only. The `SignerName` and `SignerPlace` + template parameters take effect in both V1 and V2 (`SignerIp` is V1 only). `RenewalWindowDays` and `ValidityDays` + are V1-only and are ignored. +5. If the template enrolls for a UCC (multi-domain) or wildcard product, test it on the sandbox first. + The plugin runs DCV for each domain, but per-SAN, never-validated-domain, and wildcard DCV aren't + validated end to end (see + [Before You Begin](#before-you-begin-confirm-v2-will-work-for-your-templates)). +6. If the product is OV or EV (whether `ProductVariant` is set explicitly or left to be derived), set + `OrganizationNumber` on the CA connector (a pre-vetted organization number from CERTInext's + Accounts → List Organizations). It is mandatory for OV/EV under V2 — enrollment fails fast with a + clear error if it's missing, rather than reaching the CA and getting back an opaque 422. + +### Step 4 — Test Before Cutting Over + +Run a full enroll → sync → revoke cycle against the sandbox environment with `UseV2Api=true` before +pointing a production template at the V2 connector. At minimum, confirm: + +- A new enrollment issues (or parks pending DCV/approval as expected) and is retrievable via + `GetSingleRecord`. +- A full and an incremental `Synchronize` both pick up the order. +- `Revoke` succeeds for the Command revoke reasons you actually use. + +### Verification Checklist + +- [ ] **Connection test.** Save the connector. It succeeds after a token request to `{ApiUrl}/oauth/token` and `GET /api/certinext/v2/auth/me`; a 401 or 403 is explained in Step 1. +- [ ] **Template save.** Each template saves. An explicit `ProductCode` that is missing from the catalog, or whose product type doesn't match the selected product, is rejected. +- [ ] **DV enrollment.** Enroll a single-domain DV order. It returns the certificate, or returns pending and is imported by the next sync, and its TXT record is removed. +- [ ] **UCC and wildcard.** Enroll each migrated template. One order carries every DNS SAN, and each domain reaches the validated state. +- [ ] **OV/EV.** Set `OrganizationNumber` and enroll. The order is accepted, stays pending until organization verification completes, and the next sync imports it. +- [ ] **Synchronization.** Run a full and then an incremental sync. New orders are imported with their certificates; revoked orders appear only when the gateway already holds their certificate. +- [ ] **Revocation.** Revoke a test certificate with Command's default reason (unspecified) and with key compromise. The gateway log shows the substituted reason for the first. +- [ ] **Logs.** The gateway log has no requestor names, email addresses, or request bodies unless `LogSensitiveRequestData` is on. + +## Behavioral Differences After Migrating + +- **Order identifiers.** The V2 spec's examples show `ord_`-prefixed IDs (for example `ord_8K9mQ2vR8nP4bL`), but V2 returns numeric order numbers in the same format as V1 (for example `6625262451`). V1-placed order numbers also resolve through V2 Track Order and appear under the same number in the V2 orders report, so existing `CARequestID` values carry over. The plugin stores whatever `orderId` CERTInext returns; treat it as an opaque string in external tooling. +- **Status vocabulary.** V2 reports order status as strings (`issued`, `pending-dcv`, `pending-csr`, + `pending-agreement`, `pending-organization-verification`, `pending-documents`, `pending-approval`, + `revoked`, `cancelled`, `rejected`, `expired`, `unknown`) rather than V1's numeric CERTInext status + codes. The plugin maps both to the same Keyfactor status values, so this is transparent to + Command, but it changes what you'll see in gateway trace logs. +- **Synchronization source.** V2 sync reads CERTInext's `/reports/orders` endpoint instead of V1's + `GetOrderReport`. Incremental sync queries a window starting `V2SyncLookbackHours` (default 72) + before the last sync time rather than the exact last-sync timestamp, because the API's date filter + may bracket either the order-placement or the issuance date — this trades a small + amount of redundant re-processing for not missing a slow-issuing order. +- **Revoked orders in sync.** CERTInext doesn't serve the certificate body of a revoked order, so a + revoked order is imported as revoked only when the gateway already holds its certificate. Otherwise + it is reported as failed or skipped, so the gateway never stores a revoked record with no + certificate. +- **Orphaned orders.** If CERTInext rejects the CSR after the order was created, the plugin cancels + the order once and returns a failed result carrying the order ID. After a timeout, the plugin + checks the order before deciding: it cancels the order only if the CSR never arrived. + +- **CSR delivery.** By default V2 SSL/TLS enrollment sends the CSR inline in the create call + (`V2InlineCsr`, default `true`), the same call shape as a direct single-call API integration. The + create call can hold about 20 seconds until issuance, and a create that times out or returns a 5xx + can leave an order that issues and is imported by the next sync rather than cancelled. Setting + `V2InlineCsr` to `false` creates the order and then submits the CSR, as above; that two-call flow + fails for a domain the account has already validated. Private PKI always uses the two-call flow. + +### Renewals and Reissuance + +CERTInext V2 has no *renew* endpoint. It documents a `/reissue` endpoint (`mode: rekey|update-sans`, with optional `revokePrevious` and `revokeReason`), which the plugin does not use. + +- **Every enrollment type places a new order.** `New`, `Renew`, `Reissue`, and `RenewOrReissue` all take the same path as a new enrollment, without V1's renewal-window logic. +- **The prior order is untouched.** The old order and certificate stay issued and are not auto-revoked. Command links the old and new certificates through history only. +- **Each renewal is billed as a new order.** Confirm with eMudhra how your account treats renewals before you rely on free renewals within a subscription term. + +### Revocation Reasons After Migrating + +V1 sends a numeric `revokeReasonId` and V2 sends a kebab-case string; the plugin translates automatically. CERTInext rejects four of the V2 reason values on SSL/TLS orders, including Command's default `unspecified`. The plugin retries each once with an accepted substitute, so no customer action is needed. The full mapping is in [Revocation Reason Codes](#revocation-reason-codes). + +## Known Gaps + +The following V2 limitations are known. None of them is a show-stopper for a single-domain +deployment, but decide with these in mind rather than discovering them after cutting over: + +- **DCV isn't validated end to end** for per-SAN domains on UCC orders, for a domain that has never been validated, or for wildcards. The plugin runs the flow for each of these, but the paths haven't been confirmed against the CA. See [Before You Begin](#before-you-begin-confirm-v2-will-work-for-your-templates). +- **Document Signer (`ProductFamily=signature`) enrollment isn't supported.** It fails before any + order is placed. +- **Every renewal/reissue places a new order.** See [Renewals and Reissuance](#renewals-and-reissuance) + above. +- **`OrganizationNumber` is required to enroll OV/EV via V2.** V2 OV/EV orders send + `organization.organizationNumber` with `preVetted=true` (mirroring V1's + `organizationDetails.preVetting`); omitting it fails the enrollment. If your account relies on + `OrganizationNumber` to fast-path DV issuance under V1, note that DV orders under V2 never send an + organization block, so that benefit does not carry over. +- **`AccountingModel` has no V2 effect.** V2 order create has no equivalent field. `GroupNumber`, the + technical-contact fields, `EmailNotifications`, `SubscriptionAutoRenew`/`SubscriptionRenewCriteriaDays`, and + `IgnoreExpired` are all honored on V2 (see the tables in Step 2). +- **OV and OV UCC orders can exceed the plugin's fixed 120-second request timeout.** The order may + still be created on the CA and is imported by the next sync. EV orders under V2 are not validated + end to end. + +## Rolling Back to V1 + +Rolling back means setting `UseV2Api` back to `false`, as long as you kept the V1 values. + +1. Set `UseV2Api` to `false` on the connector. +2. Restore the V1-format `ApiUrl` (with the `/emSignHub-API/` path). Keep a copy of this value before you edit an existing connector. +3. Confirm `ApiKey` and `AccountNumber` are intact. They are unaffected by being unused while V2 was active, unless you overwrote them in Step 2. +4. Save the connector and confirm the connection test passes. + +**Rollback caveat:** `Enroll`, `GetSingleRecord`, `Revoke`, and `Synchronize` choose V1 or V2 from the connector's current `UseV2Api` flag, not from the stored `CARequestID`. V1-placed order numbers resolve through V2 Track Order, and V2 order numbers use the V1 format, but V1 Track Order and `GetOrderReport` may not see an order placed through V2. Rolling back a connector that has already issued V2 certificates isn't validated: check on the sandbox that sync, revoke, and renewal still work for them. Certificates enrolled before the switch to V2 are V1 orders and are unaffected. + +{% include 'architecture.md' %} diff --git a/docsource/overview.md b/docsource/overview.md index f11d3d3..6695242 100644 --- a/docsource/overview.md +++ b/docsource/overview.md @@ -1,6 +1,11 @@ ## Overview -The CERTInext AnyCA Gateway REST plugin extends the certificate lifecycle capabilities of the CERTInext platform (by eMudhra) to Keyfactor Command via the Keyfactor AnyCA Gateway REST. See [configuration.md](configuration.md) for full installation and configuration details, [architecture.md](architecture.md) for design notes, and [development.md](development.md) for local development. +The CERTInext AnyCA Gateway REST plugin extends the certificate lifecycle capabilities of the CERTInext platform (by eMudhra) to Keyfactor Command via the Keyfactor AnyCA Gateway REST. Related documents: + +- [configuration.md](configuration.md): installation and configuration details. +- [architecture.md](architecture.md): design notes. +- [migration-v1-to-v2.md](migration-v1-to-v2.md): moving a connector to the V2 API. +- [development.md](development.md): local development. ## CERTInext CA Certificates @@ -12,81 +17,152 @@ Before the gateway can register a CA backed by this plugin, the Keyfactor Comman | Production — India (Global) | https://in.certinext.io/ | | Production — US | https://us.certinext.io/ | -After signing in, navigate to the certificate-authority / chain download page in the portal, export each CA in the chain as PEM or DER, and import them into the appropriate Windows certificate stores on the gateway host (Trusted Root for the root CA, Intermediate Certification Authorities for any subordinates). See [configuration.md](configuration.md#gateway-registration) and the [README](../README.md#configuration) for the full Gateway Registration walkthrough. +To import the chain: + +1. Sign in to the CERTInext portal for your environment. +2. Open the certificate-authority / chain download page. +3. Export each CA in the chain as PEM or DER. +4. On the gateway host, import the root CA into the **Trusted Root Certification Authorities** store. +5. Import any subordinate CAs into the **Intermediate Certification Authorities** store. + +See [configuration.md](configuration.md#gateway-registration) for the full Gateway Registration walkthrough. + +> Note: eMudhra is withdrawing from public TLS, and the emSign roots are being phased out by browser root programs (Chrome and Firefox after November 16, 2026; Apple on November 30, 2026). CERTInext public TLS certificates will be issued under a different CA, so the steps above need repeating with the new chain. See [Change of issuing CA](configuration.md#change-of-issuing-ca-emudhra-exit-from-public-tls). ## Troubleshooting -### `"Inactive Account User."` returned from `GenerateOrderSSL` +| Symptom | Section | +|---|---| +| V1 enrollments fail with `Inactive Account User.` | [`"Inactive Account User."` from `GenerateOrderSSL`](#inactive-account-user-returned-from-generateorderssl-v1) | +| Enrollment returns pending (`Status=90`, `EXTERNALVALIDATION`) | [Enrollment returns immediately with `Status=90`](#enrollment-returns-immediately-with-status90-externalvalidation) | +| `EMS-956 "Invalid Request for this API"` from `GetDcv` | [`EMS-956` from `GetDcv`](#ems-956-invalid-request-for-this-api-from-getdcv-v1) | +| HTTP 500 and a `TypeLoadException` in the gateway log | [Plugin fails to load](#plugin-fails-to-load-with-could-not-load-type-keyfactoranygatewayextensionsidomainvalidatorfactory) | +| Connector fails to start with an `https` error | [`ApiUrl` must use https](#connector-fails-to-start-apiurl--must-use-https) | +| Enrollment fails with `invalid custom extension or certificate policy OIDs` | [Enrollment fails with `invalid custom extension or certificate policy OIDs`](#enrollment-fails-with-invalid-custom-extension-or-certificate-policy-oids) | + +### `"Inactive Account User."` returned from `GenerateOrderSSL` (V1) **Symptom** -Enrollments fail with the gateway exception: +V1 enrollments fail with the gateway exception: ``` CERTInext order failed: Inactive Account User.. See gateway logs for details. ``` -The same access key / account works perfectly fine before and after the failing window — a `Ping` (`ValidateCredentials`) call seconds earlier returns success, and the next individual enrollment after a brief pause also succeeds. +The same access key / account works before and after the failing window — a `Ping` (`ValidateCredentials`) call seconds earlier returns success, and the next individual enrollment after a brief pause also succeeds. **Root cause** -The CERTInext sandbox at `https://sandbox-us-api.certinext.io/emSignHub-API` applies a **burst rate limit** on order placement and surfaces rate‑limit rejection through the **generic** error string `"Inactive Account User."` — the same string the API uses for genuinely inactive accounts. There is currently no distinguishing `errorCode`, `Retry-After` header, or structured field to tell the two conditions apart from the meta block alone. - -Empirically the limit kicks in at roughly **16+ enrollments submitted within 10 seconds** on the US sandbox. Sustained submission velocity well below that runs cleanly. +- **Cause:** the CERTInext sandbox at `https://sandbox-us-api.certinext.io/emSignHub-API` applies a **burst rate limit** on order placement. +- **Generic error:** the rejection uses the string `"Inactive Account User."`, the same string the API uses for genuinely inactive accounts. +- **No distinguishing field:** the response has no `errorCode`, `Retry-After` header, or structured field that tells the two conditions apart. +- **Trigger:** roughly **16 or more enrollments submitted within 10 seconds** on the US sandbox. +- **Below the threshold:** lower submission velocity runs cleanly. **Confirmation steps** -1. Run a single `Ping` against the same `ApiUrl` / `AccessKey`. If it succeeds, the account is active; the prior failure was almost certainly a rate-limit hit. -2. Check the gateway warning log for the `LogApiFailure` line emitted just before the throw (see issue [#8](https://github.com/Keyfactor/certinext-caplugin/issues/8) and the `LogApiFailure` helper in `CERTInextClient.cs`). The full raw response body is included there — if CERTInext ever surfaces a distinguishing code or message for rate-limit (as opposed to account-state), it will appear in that line. -3. Wait 30–60 seconds, then retry the failed enrollment(s). A successful retry confirms it was rate-limit. +1. Run a single `Ping` against the same `ApiUrl` / `ApiKey`. If it succeeds, the account is active; the failure was almost certainly a rate-limit hit. +2. Check the gateway warning log for the API-failure line the plugin writes just before it throws. It includes the full raw response body, so any distinguishing code or message CERTInext returns appears there. +3. Wait 30–60 seconds, then retry the failed enrollment. A successful retry confirms it was a rate limit. **Mitigation** -- **Reduce submission velocity**: throttle order placements to roughly one per 1–2 seconds. The plugin does not yet have a built-in client-side throttle; pacing must come from the caller (e.g. Keyfactor Command's enrollment scheduling, or a workflow that places certs in batches). -- **For high-volume migration scenarios**: split the workload into batches of ~10 orders separated by a short pause, rather than firing everything at once. -- **No client-side automatic retry on this error**: a defensive retry inside `PlaceOrderAsync` would paper over the misleading error string and burn the operator's order quota on retries. We document the gotcha instead. +- **Automatic retry**: when order placement returns this error, the plugin retries it with exponential backoff and jitter (up to 5 attempts) before surfacing the failure, so brief bursts resolve without operator action. +- **Reduce submission velocity**: throttle order placements to roughly one per 1–2 seconds. The plugin has no built-in client-side throttle; pacing must come from the caller (for example Keyfactor Command's enrollment scheduling, or a workflow that places certificates in batches). +- **High-volume migrations**: split the workload into batches of about 10 orders separated by a short pause, rather than submitting everything at once. ### Enrollment returns immediately with `Status=90 (EXTERNALVALIDATION)` **Symptom** -Enrollment completes successfully but the cert is not yet issued — Command shows the request in pending status. A subsequent `Synchronize` picks it up. +Enrollment completes but the certificate is not yet issued — Command shows the request as pending. A later `Synchronize` picks it up. **Root cause** -This is the expected return shape on two paths: +This is the expected result in any of these cases: -1. The plugin was loaded on an older gateway host (pre-IAnyCAPlugin v3.3) that does not inject `IDomainValidatorFactory`. DCV cannot run, so any product that requires DNS validation completes only after CERTInext-side validation finishes. -2. The plugin's bounded `Enroll()` budget (`DcvWaitForChallengeSeconds` + `DcvWaitForIssuanceSeconds`, defaults 60s each) elapsed before CERTInext finished asynchronous issuance. +- **OV or EV order:** CERTInext issues these after organization verification (minutes to hours), longer than the enrollment call waits. +- **DCV enabled but unable to run:** no DNS provider plugin is deployed on the gateway, or none resolves the order's domain. The plugin logs why. The order completes only after the domain is validated some other way. +- **`Enroll()` budget elapsed:** the plugin's bounded wait ended before CERTInext finished issuing. The budget is: + - `PickupRetries` × `PickupDelay` for the certificate pickup poll, capped at 75 s in total (inside Command's roughly 100 s enrollment-call timeout); + - on V1, `DcvWaitForChallengeSeconds` + `DcvWaitForIssuanceSeconds` (default 60 s each) around DCV. When DCV engages for an order, these waits replace the pickup wait; they do not stack. +- **Issued but certificate not generated yet (V2):** CERTInext reports the order `issued` while Download Certificate still answers 422 `EMS-1165`. Normal generation takes about 20 s; the pickup poll waits for it, logging at Debug level and writing one Information summary. If the budget runs out the next sync imports the certificate. +- **DCV could not validate every domain:** for example an IP or email SAN with no DNS provider. V1 still validates the other domains but returns pending without waiting for issuance. +- **V1 renewal still pending DNS-01 validation:** with DCV enabled, a renewal waiting on DNS-01 validation returns pending at once instead of holding a worker for the pickup wait; the next sync completes the validation. **Mitigation** -The next gateway sync cycle will pick the cert up and transition it to `GENERATED`. The plugin's sync-driven DCV retry is single-shot per record, so even with hundreds of pending orders the sync completes in seconds, not minutes — see [configuration.md](configuration.md) for the `DcvWaitForChallengeSeconds`/`DcvWaitForIssuanceSeconds` knobs if you want to tune the Enroll-time budget. +The next gateway sync cycle picks the certificate up and moves it to issued. Sync-driven DCV is bounded per pass by `DcvSyncMaxOrderAgeHours` and `DcvSyncMaxPerPass`, so a large backlog of old pending orders doesn't slow each pass. See [configuration.md](configuration.md) for the knobs that tune the `Enroll()` wait. -### `EMS-956 "Invalid Request for this API"` from `GetDcv` +### `EMS-956 "Invalid Request for this API"` from `GetDcv` (V1) **Symptom** -The plugin's DCV machinery starts but the first `GetDcv` call returns this error. Plugin gracefully defers DCV to the next sync cycle (single warning log line, no exception thrown). +The plugin's DCV machinery starts but the first `GetDcv` call returns this error. The plugin defers DCV to the next sync cycle (a single log line, no exception). **Root cause** -CERTInext exposes the `domainVerification` slot in `TrackOrder` **before** the `GetDcv` endpoint will accept calls for that order — there's an internal gating window. The plugin's `IsDcvNotYetReady` predicate explicitly recognizes this and treats it as "DCV not ready yet, retry on the next sync". +CERTInext exposes the `domainVerification` slot in `TrackOrder` **before** the `GetDcv` endpoint accepts calls for that order. The plugin recognizes this condition and treats it as "DCV not ready yet, retry on the next sync". **Mitigation** -No action needed. Plugin's sync-driven DCV retry handles this transparently — the order will be picked up on a subsequent sync cycle once the CA-side gate clears (observed window: seconds to a few hours, environment-dependent). +No action needed. The order is picked up on a subsequent sync cycle once CERTInext's gate clears; the wait can range from seconds to several hours. ### Plugin fails to load with `Could not load type 'Keyfactor.AnyGateway.Extensions.IDomainValidatorFactory'` **Symptom** -Gateway returns HTTP 500 on CA registration or first enrollment with the body `{"ErrorCode":"0x80131509"}`. Pod logs show `TypeLoadException` for `Keyfactor.AnyGateway.Extensions.IDomainValidatorFactory`. +The gateway returns HTTP 500 on CA registration or first enrollment (the response body is only a generic `ErrorCode`), and the gateway log shows a `TypeLoadException` for `Keyfactor.AnyGateway.Extensions.IDomainValidatorFactory`. + +**Root cause** + +The gateway's bundled `Keyfactor.AnyGateway.IAnyCAPlugin` assembly is older than 3.3, which does not define `IDomainValidatorFactory`. This plugin requires AnyCA Gateway REST 26.2.0 or later. + +**Mitigation** + +Upgrade the AnyCA Gateway REST to 26.2.0 or later. + +### Connector fails to start: `'ApiUrl' ... must use https` + +**Symptom** + +After upgrading, a connector fails initialization with an error naming `ApiUrl` and `https`. **Root cause** -Older gateway image whose bundled `Keyfactor.AnyGateway.IAnyCAPlugin` assembly is v3.2 or earlier (the `IDomainValidatorFactory` interface is v3.3+). This was fully addressed by the issue [#7](https://github.com/Keyfactor/certinext-caplugin/issues/7) fix in v1.0 — both the constructor-signature surface AND the field-type surface are now safe to load on v3.2 hosts. +The API key (V1) or OAuth client secret (V2) is sent to `ApiUrl` on every request, so the plugin rejects `http` URLs on save and at startup. A loopback host (`localhost`, `127.0.0.1`, `::1`) is the only exception, for local test servers. **Mitigation** -Deploy the default (no-DCV) build for AnyCA Gateway 25.5.x; do not deploy the DCV build on a 25.5.x host. The **default build (no-DCV, IAnyCAPlugin 3.2.0)** is the one that loads *and* persists records on AnyCA Gateway 25.5.x, and it is what the released artifact ships. The DCV-capable build (IAnyCAPlugin 3.3.0-PRERELEASE, `dotnet build -p:DcvSupport=true`) is for AnyCA Gateway 26.x; loading it on a 25.5.x host triggers the type-load error above and, even when it loads, its records do not persist on a 3.2 host. See the `DcvSupport` build variants in the developer guide. +Change the connector's `ApiUrl` to an `https` URL. + +### Enrollment fails with `invalid custom extension or certificate policy OIDs` + +**Symptom** + +Command reports this error for an enrollment: + +``` +An error occurred while performing the operation. This may be due to invalid custom extension or certificate policy OIDs. Please see CA logs for more information. +``` + +The certificate request may be valid, and CERTInext may already have issued the certificate. + +**Root cause** + +This is a known timing issue. If the scheduled gateway sync runs while an enrollment is still finishing, the sync can create the record for that request first. The enrollment's own save then fails, because a record for the same request already exists. That record may or may not include the certificate yet. The error message does not describe this, so it looks like a problem with the request. The problem is more likely when the sync runs more often. + +The plugin reduces the race: a sync skips pending and issued orders created in the last `SyncRecentOrderGraceSeconds` (default 120, plus a 5-second margin) and imports them on the next pass. That makes the error less likely, not impossible. An enrollment that takes longer than about two minutes to finish saving, or a connector with `SyncRecentOrderGraceSeconds` set to `0`, can still hit it. + +**What to do before you retry** + +1. Check whether CERTInext has already issued a certificate for the request. +2. In Command, search for the certificate by subject name. It may already be there, or it may appear after a later sync. +3. Check the gateway log for a "duplicate key" error. If you find one, this issue is the likely cause. + +Retrying can place a second order with CERTInext, which may be billed again. Check first. + +**Versions** + +Seen with the CERTInext plugin on AnyCA REST Gateway 25.5, before the hold-back existed. Other versions have not been tested. diff --git a/experiment-results/v2-inline-csr-10142103.csv b/experiment-results/v2-inline-csr-10142103.csv new file mode 100644 index 0000000..8763eda --- /dev/null +++ b/experiment-results/v2-inline-csr-10142103.csv @@ -0,0 +1,5 @@ +trial,arm,arm_a_encoding,product_header,domain,order_id,t0_utc,create_http,create_ms,create_status,create_order_state,create_cert_state,create_body,put_http,put_ms,put_body,t_create_resp_s,t_put_resp_s,t_first_track_obs_s,t_issued_track_s,t_issued_track_lower_s,track_seq,system_error_seen,system_error_first_s,system_error_cleared_s,first_seen_listing_s,first_seen_listing_lower_s,first_seen_listing_status,t_issued_listing_s,listing_seq,seen_in_listing_before_create_resp,listing_first_seen_to_create_resp_s,issued_in_listing_before_create_resp,create_resp_minus_issued_listing_s,dl_first_at_s,dl_first_result,dl_success_at_s,dl_ms,dl_attempts,cert_pubkey,cert_cn,track_polls,track_errors,list_polls,list_poll_median_s,list_errors,cleanup,final_state,error +1,A,pem,"842",dcv-test.scrup.org,5957883216,2026-10-14T21:03:40.6215230Z,201,5162.65,pending-approval,"Order Accepted","Pending for Approver","{'orderId':'5957883216','requestId':'6266932213','status':'pending-approval','orderState':'Order Accepted','certificateState':'Pending for Approver','productVariant':'dv','domain':'dcv-test.scrup.org','createdAt':'2026-10-15T02:33:45.853604699+05:30','resolvedProductCode':'842','requestor':{},'orderedBy':{},'csrSubmitted':true,'subscriberAgreement':{'signed':true,'signerName':'Keyfactor Plugin Test','signedAt':'2026-10-01T18:43:09Z','signedPlace':'Gateway Lab'},'subscription':{'validityYears':...",0,,"",5.16,,5.31,6.94,6.81,"create:pending-approval|Order Accepted|Pending for Approver@5.16; issued|Order Accepted|Approved by System@6.94; issued|Order Accepted|Certificate Generated@23.35",0,,,4.75,4.50,"Order Accepted|Pending for Approver",22.78,"Order Accepted|Pending for Approver@4.75; Order Accepted|Approved by System@6.26; Order Accepted|Certificate Generated@22.78",1,0.41,0,-17.62,6.94,"HTTP 422 Error: ",26.22,2871.68,4,"match","match",5,0,19,0.27,0,"5957883216: before=issued; revoke(superseded); after=revoked","revoked","" +2,B,n/a,"842",dcv-test.scrup.org,7887125641,2026-10-14T21:04:46.8005010Z,201,4832.87,pending-approval,"Order Accepted","Pending for Approver","{'orderId':'7887125641','requestId':'1639168658','status':'pending-approval','orderState':'Order Accepted','certificateState':'Pending for Approver','productVariant':'dv','domain':'dcv-test.scrup.org','createdAt':'2026-10-15T02:34:51.699916986+05:30','resolvedProductCode':'842','requestor':{},'orderedBy':{},'csrSubmitted':false,'subscriberAgreement':{'signed':true,'signerName':'Keyfactor Plugin Test','signedAt':'2026-10-01T18:43:09Z','signedPlace':'Gateway Lab'},'subscription':{'validityYears'...",204,24328.25,"",4.83,29.16,5.23,5.23,4.83,"create:pending-approval|Order Accepted|Pending for Approver@4.83; issued|Order Accepted|Approved by System@5.23",0,,,4.78,4.50,"Order Accepted|Pending for Approver",28.79,"Order Accepted|Pending for Approver@4.78; Order Accepted|Approved by System@6.81; Order Accepted|Certificate Generated@28.79",1,0.05,0,-23.96,5.23,"HTTP 422 Error: ",28.85,3361.25,5,"match","match",5,0,21,0.27,0,"7887125641: before=issued; revoke(superseded); after=revoked","revoked","" +3,A,pem,"842",dcv-test.scrup.org,5723142281,2026-10-14T21:05:56.5967040Z,201,20396.16,issued,"Order Accepted","Certificate Generated","{'orderId':'5723142281','requestId':'5487849844','status':'issued','orderState':'Order Accepted','certificateState':'Certificate Generated','productVariant':'dv','domain':'dcv-test.scrup.org','createdAt':'2026-10-15T02:36:16.954808263+05:30','expiresAt':'2027-01-12T21:06:13Z','resolvedProductCode':'842','requestor':{},'orderedBy':{},'csrSubmitted':true,'subscriberAgreement':{'signed':true,'signerName':'Keyfactor Plugin Test','signedAt':'2026-10-01T18:43:09Z','signedPlace':'Gateway Lab'},'subsc...",0,,"",20.40,,20.54,20.54,20.40,"create:issued|Order Accepted|Certificate Generated@20.40",0,,,4.76,4.50,"Order Accepted|Approved by System",19.77,"Order Accepted|Approved by System@4.76; Order Accepted|Certificate Generated@19.77",1,15.64,1,0.62,20.54,"ok-with-certificate",23.80,3260.61,1,"match","match",1,0,17,0.26,0,"5723142281: before=issued; revoke(superseded); after=revoked","revoked","" +4,B,n/a,"842",dcv-test.scrup.org,5674735366,2026-10-14T21:07:05.8984480Z,201,4511.04,issued,"Order Accepted","Approved by System","{'orderId':'5674735366','requestId':'2226658722','status':'issued','orderState':'Order Accepted','certificateState':'Approved by System','productVariant':'dv','domain':'dcv-test.scrup.org','createdAt':'2026-10-15T02:37:10.440934796+05:30','resolvedProductCode':'842','requestor':{},'orderedBy':{},'csrSubmitted':false,'subscriberAgreement':{'signed':true,'signerName':'Keyfactor Plugin Test','signedAt':'2026-10-01T18:43:09Z','signedPlace':'Gateway Lab'},'subscription':{'validityYears':1},'verific...",204,19159.67,"",4.51,23.67,4.63,4.63,4.51,"create:issued|Order Accepted|Approved by System@4.51",0,,,4.78,4.50,"Order Accepted|Approved by System",24.29,"Order Accepted|Approved by System@4.78; Order Accepted|Certificate Generated@24.29",0,-0.27,0,-19.77,4.63,"HTTP 422 Error: ",24.48,3945.86,4,"match","match",4,0,18,0.27,0,"5674735366: before=issued; revoke(superseded); after=revoked","revoked","" diff --git a/experiment-results/v2-inline-csr-10142109.csv b/experiment-results/v2-inline-csr-10142109.csv new file mode 100644 index 0000000..ab2f91e --- /dev/null +++ b/experiment-results/v2-inline-csr-10142109.csv @@ -0,0 +1,7 @@ +trial,arm,arm_a_encoding,product_header,domain,order_id,t0_utc,create_http,create_ms,create_status,create_order_state,create_cert_state,create_body,put_http,put_ms,put_body,t_create_resp_s,t_put_resp_s,t_first_track_obs_s,t_issued_track_s,t_issued_track_lower_s,track_seq,system_error_seen,system_error_first_s,system_error_cleared_s,first_seen_listing_s,first_seen_listing_lower_s,first_seen_listing_status,t_issued_listing_s,listing_seq,seen_in_listing_before_create_resp,listing_first_seen_to_create_resp_s,issued_in_listing_before_create_resp,create_resp_minus_issued_listing_s,dl_first_at_s,dl_first_result,dl_last_failure,dl_success_at_s,dl_ms,dl_attempts,cert_pubkey,cert_cn,track_polls,track_errors,list_polls,list_poll_median_s,list_errors,cleanup,final_state,error +1,A,pem,"842",dcv-test.scrup.org,4939197847,2026-10-14T21:09:26.3780490Z,201,5067.92,pending-approval,"Order Accepted","Pending for Approver","{'orderId':'4939197847','requestId':'8555699965','status':'pending-approval','orderState':'Order Accepted','certificateState':'Pending for Approver','productVariant':'dv','domain':'dcv-test.scrup.org','createdAt':'2026-10-15T02:39:31.475498682+05:30','resolvedProductCode':'842','requestor':{},'orderedBy':{},'csrSubmitted':true,'subscriberAgreement':{'signed':true,'signerName':'Keyfactor Plugin Test','signedAt':'2026-10-01T18:43:09Z','signedPlace':'Gateway Lab'},'subscription':{'validityYears':...",0,,"",5.07,,5.18,6.84,6.69,"create:pending-approval|Order Accepted|Pending for Approver@5.07; issued|Order Accepted|Approved by System@6.84; issued|Order Accepted|Certificate Generated@25.29; issued|Order Fulfilled|Certificate Downloaded@28.59",0,,,4.77,4.50,"Order Accepted|Pending for Approver",24.28,"Order Accepted|Pending for Approver@4.77; Order Accepted|Approved by System@6.26; Order Accepted|Certificate Generated@24.28; Order Fulfilled|Certificate Downloaded@27.30",1,0.30,0,-19.21,7.07,"HTTP 422 {'type':'https://api.certinext.io/errors/unprocessable-entity','title':'Unprocessable Entity','status':422,'detail':'EMS-1165 Invalid request status.'}","HTTP 422 {'type':'https://api.certinext.io/errors/unprocessable-entity','title':'Unprocessable Entity','status':422,'detail':'EMS-1165 Invalid request status.'} @21.10s (3.38s call)",27.10,3990.72,4,"match","match",17,0,23,0.27,0,"4939197847: before=issued; revoke(superseded); after=revoked","revoked","" +2,B,n/a,"842",dcv-test.scrup.org,1659521538,2026-10-14T21:10:33.6326610Z,201,4509.84,issued,"Order Accepted","Approved by System","{'orderId':'1659521538','requestId':'6539647983','status':'issued','orderState':'Order Accepted','certificateState':'Approved by System','productVariant':'dv','domain':'dcv-test.scrup.org','createdAt':'2026-10-15T02:40:38.202971097+05:30','resolvedProductCode':'842','requestor':{},'orderedBy':{},'csrSubmitted':false,'subscriberAgreement':{'signed':true,'signerName':'Keyfactor Plugin Test','signedAt':'2026-10-01T18:43:09Z','signedPlace':'Gateway Lab'},'subscription':{'validityYears':1},'verific...",204,20713.79,"",4.51,25.22,4.79,4.79,4.51,"create:issued|Order Accepted|Approved by System@4.51; issued|Order Accepted|Certificate Generated@25.35; issued|Order Fulfilled|Certificate Downloaded@26.98",0,,,4.77,4.50,"Order Accepted|Approved by System",25.78,"Order Accepted|Approved by System@4.77; Order Accepted|Certificate Generated@25.78; Order Fulfilled|Certificate Downloaded@27.29",0,-0.26,0,-21.27,6.51,"HTTP 422 {'type':'https://api.certinext.io/errors/unprocessable-entity','title':'Unprocessable Entity','status':422,'detail':'EMS-1165 Invalid request status.'}","HTTP 422 {'type':'https://api.certinext.io/errors/unprocessable-entity','title':'Unprocessable Entity','status':422,'detail':'EMS-1165 Invalid request status.'} @21.42s (3.44s call)",26.33,2908.96,4,"match","match",17,0,23,0.27,0,"1659521538: before=issued; revoke(superseded); after=revoked","revoked","" +3,A,pem,"842",dcv-test.scrup.org,8569533161,2026-10-14T21:11:47.6767670Z,201,24307.00,issued,"Order Accepted","Certificate Generated","{'orderId':'8569533161','requestId':'7283751316','status':'issued','orderState':'Order Accepted','certificateState':'Certificate Generated','productVariant':'dv','domain':'dcv-test.scrup.org','createdAt':'2026-10-15T02:42:12.105684406+05:30','expiresAt':'2027-01-12T21:12:08Z','resolvedProductCode':'842','requestor':{},'orderedBy':{},'csrSubmitted':true,'subscriberAgreement':{'signed':true,'signerName':'Keyfactor Plugin Test','signedAt':'2026-10-01T18:43:09Z','signedPlace':'Gateway Lab'},'subsc...",0,,"",24.31,,24.43,24.43,24.31,"create:issued|Order Accepted|Certificate Generated@24.31; issued|Order Fulfilled|Certificate Downloaded@29.73",0,,,4.77,4.50,"Order Accepted|Approved by System",24.30,"Order Accepted|Approved by System@4.77; Order Accepted|Certificate Generated@24.30; Order Fulfilled|Certificate Downloaded@30.27",1,19.53,1,0.01,26.31,"ok-with-certificate","",29.31,3000.31,1,"match","match",6,0,24,0.27,0,"8569533161: before=issued; revoke(superseded); after=revoked","revoked","" +4,B,n/a,"842",dcv-test.scrup.org,4127996897,2026-10-14T21:12:56.9288040Z,201,4107.51,issued,"Order Accepted","Approved by System","{'orderId':'4127996897','requestId':'3177311237','status':'issued','orderState':'Order Accepted','certificateState':'Approved by System','productVariant':'dv','domain':'dcv-test.scrup.org','createdAt':'2026-10-15T02:43:01.157041473+05:30','resolvedProductCode':'842','requestor':{},'orderedBy':{},'csrSubmitted':false,'subscriberAgreement':{'signed':true,'signerName':'Keyfactor Plugin Test','signedAt':'2026-10-01T18:43:09Z','signedPlace':'Gateway Lab'},'subscription':{'validityYears':1},'verific...",204,21131.99,"",4.11,25.24,4.25,4.25,4.11,"create:issued|Order Accepted|Approved by System@4.11; issued|Order Fulfilled|Certificate Downloaded@26.19",0,,,4.78,4.50,"Order Accepted|Approved by System",25.80,"Order Accepted|Approved by System@4.78; Order Fulfilled|Certificate Downloaded@25.80",0,-0.67,0,-21.69,6.11,"HTTP 422 {'type':'https://api.certinext.io/errors/unprocessable-entity','title':'Unprocessable Entity','status':422,'detail':'EMS-1165 Invalid request status.'}","HTTP 422 {'type':'https://api.certinext.io/errors/unprocessable-entity','title':'Unprocessable Entity','status':422,'detail':'EMS-1165 Invalid request status.'} @19.53s (3.23s call)",24.88,3348.19,4,"match","match",17,0,22,0.28,0,"4127996897: before=issued; revoke(superseded); after=revoked","revoked","" +5,A,pem,"842",dcv-test.scrup.org,4697648548,2026-10-14T21:13:59.9964920Z,201,21429.03,issued,"Order Accepted","Certificate Generated","{'orderId':'4697648548','requestId':'6579433444','status':'issued','orderState':'Order Accepted','certificateState':'Certificate Generated','productVariant':'dv','domain':'dcv-test.scrup.org','createdAt':'2026-10-15T02:44:21.546989131+05:30','expiresAt':'2027-01-12T21:14:18Z','resolvedProductCode':'842','requestor':{},'orderedBy':{},'csrSubmitted':true,'subscriberAgreement':{'signed':true,'signerName':'Keyfactor Plugin Test','signedAt':'2026-10-01T18:43:09Z','signedPlace':'Gateway Lab'},'subsc...",0,,"",21.43,,21.55,21.55,21.43,"create:issued|Order Accepted|Certificate Generated@21.43; issued|Order Fulfilled|Certificate Downloaded@28.15",0,,,4.77,4.50,"Order Accepted|Pending for Approver",21.29,"Order Accepted|Pending for Approver@4.77; Order Accepted|Approved by System@6.27; Order Accepted|Certificate Generated@21.29; Order Fulfilled|Certificate Downloaded@27.27",1,16.66,1,0.14,23.43,"ok-with-certificate","",26.67,3242.81,1,"match","match",7,0,23,0.27,0,"4697648548: before=issued; revoke(superseded); after=revoked","revoked","" +6,B,n/a,"842",dcv-test.scrup.org,2259467277,2026-10-14T21:15:08.7198050Z,201,3879.05,pending-approval,"Order Accepted","Pending for Approver","{'orderId':'2259467277','requestId':'4545963272','status':'pending-approval','orderState':'Order Accepted','certificateState':'Pending for Approver','productVariant':'dv','domain':'dcv-test.scrup.org','createdAt':'2026-10-15T02:45:12.629701911+05:30','resolvedProductCode':'842','requestor':{},'orderedBy':{},'csrSubmitted':false,'subscriberAgreement':{'signed':true,'signerName':'Keyfactor Plugin Test','signedAt':'2026-10-01T18:43:09Z','signedPlace':'Gateway Lab'},'subscription':{'validityYears'...",204,23393.52,"",3.88,27.27,4.08,5.71,5.58,"create:pending-approval|Order Accepted|Pending for Approver@3.88; issued|Order Accepted|Approved by System@5.71; issued|Order Accepted|Certificate Generated@27.93; issued|Order Fulfilled|Certificate Downloaded@31.20",0,,,5.43,4.50,"Order Accepted|Approved by System",27.30,"Order Accepted|Approved by System@5.43; Order Accepted|Certificate Generated@27.30; Order Fulfilled|Certificate Downloaded@31.17",0,-1.55,0,-23.42,5.88,"HTTP 422 {'type':'https://api.certinext.io/errors/unprocessable-entity','title':'Unprocessable Entity','status':422,'detail':'EMS-1165 Invalid request status.'}","HTTP 422 {'type':'https://api.certinext.io/errors/unprocessable-entity','title':'Unprocessable Entity','status':422,'detail':'EMS-1165 Invalid request status.'} @26.08s (3.18s call)",30.88,2796.93,5,"match","match",20,0,26,0.30,0,"2259467277: before=issued; revoke(superseded); after=revoked","revoked","" diff --git a/experiment-results/v2-inline-csr-10142116.csv b/experiment-results/v2-inline-csr-10142116.csv new file mode 100644 index 0000000..af93b66 --- /dev/null +++ b/experiment-results/v2-inline-csr-10142116.csv @@ -0,0 +1,7 @@ +trial,arm,arm_a_encoding,product_header,domain,order_id,t0_utc,create_http,create_ms,create_status,create_order_state,create_cert_state,create_body,put_http,put_ms,put_body,t_create_resp_s,t_put_resp_s,t_first_track_obs_s,t_issued_track_s,t_issued_track_lower_s,track_seq,system_error_seen,system_error_first_s,system_error_cleared_s,first_seen_listing_s,first_seen_listing_lower_s,first_seen_listing_status,t_issued_listing_s,listing_seq,seen_in_listing_before_create_resp,listing_first_seen_to_create_resp_s,issued_in_listing_before_create_resp,create_resp_minus_issued_listing_s,dl_first_at_s,dl_first_result,dl_last_failure,dl_success_at_s,dl_ms,dl_attempts,cert_pubkey,cert_cn,track_polls,track_errors,list_polls,list_poll_median_s,list_errors,cleanup,final_state,error +1,B,n/a,"842",dcv-test.scrup.org,5222651969,2026-10-14T21:16:45.6686650Z,201,5276.77,issued,"Order Accepted","Approved by System","{'orderId':'5222651969','requestId':'2364848422','status':'issued','orderState':'Order Accepted','certificateState':'Approved by System','productVariant':'dv','domain':'dcv-test.scrup.org','createdAt':'2026-10-15T02:46:51.071772081+05:30','resolvedProductCode':'842','requestor':{},'orderedBy':{},'csrSubmitted':false,'subscriberAgreement':{'signed':true,'signerName':'Keyfactor Plugin Test','signedAt':'2026-10-01T18:43:09Z','signedPlace':'Gateway Lab'},'subscription':{'validityYears':1},'verific...",204,20941.14,"",5.28,26.22,5.77,5.77,5.28,"create:issued|Order Accepted|Approved by System@5.28; issued|Order Accepted|Certificate Generated@25.90; issued|Order Fulfilled|Certificate Downloaded@29.38",0,,,5.00,4.51,"Order Accepted|Pending for Approver",27.51,"Order Accepted|Pending for Approver@5.00; Order Accepted|Approved by System@6.85; Order Accepted|Certificate Generated@27.51; Order Fulfilled|Certificate Downloaded@28.85",1,0.28,0,-22.23,7.28,"HTTP 422 {'type':'https://api.certinext.io/errors/unprocessable-entity','title':'Unprocessable Entity','status':422,'detail':'EMS-1165 Invalid request status.'}","HTTP 422 {'type':'https://api.certinext.io/errors/unprocessable-entity','title':'Unprocessable Entity','status':422,'detail':'EMS-1165 Invalid request status.'} @22.33s (3.05s call)",28.03,3698.14,4,"match","match",17,0,24,0.30,0,"5222651969: before=issued; revoke(superseded); after=revoked","revoked","" +2,A,der,"842",dcv-test.scrup.org,8717554352,2026-10-14T21:17:52.6713690Z,201,19322.91,issued,"Order Accepted","Certificate Generated","{'orderId':'8717554352','requestId':'2464423582','status':'issued','orderState':'Order Accepted','certificateState':'Certificate Generated','productVariant':'dv','domain':'dcv-test.scrup.org','createdAt':'2026-10-15T02:48:12.122289868+05:30','expiresAt':'2027-01-12T21:18:09Z','resolvedProductCode':'842','requestor':{},'orderedBy':{},'csrSubmitted':true,'subscriberAgreement':{'signed':true,'signerName':'Keyfactor Plugin Test','signedAt':'2026-10-01T18:43:09Z','signedPlace':'Gateway Lab'},'subsc...",0,,"",19.32,,19.44,19.44,19.32,"create:issued|Order Accepted|Certificate Generated@19.32; issued|Order Fulfilled|Certificate Downloaded@26.05",0,,,4.79,4.50,"Order Accepted|Approved by System",19.83,"Order Accepted|Approved by System@4.79; Order Accepted|Certificate Generated@19.83; Order Fulfilled|Certificate Downloaded@25.87",1,14.54,0,-0.51,21.32,"ok-with-certificate","",24.41,3084.58,1,"match","match",7,0,21,0.29,0,"8717554352: before=issued; revoke(superseded); after=revoked","revoked","" +3,B,n/a,"842",dcv-test.scrup.org,9828129796,2026-10-14T21:18:56.9325190Z,201,4421.15,issued,"Order Accepted","Approved by System","{'orderId':'9828129796','requestId':'6677826354','status':'issued','orderState':'Order Accepted','certificateState':'Approved by System','productVariant':'dv','domain':'dcv-test.scrup.org','createdAt':'2026-10-15T02:49:01.420531031+05:30','resolvedProductCode':'842','requestor':{},'orderedBy':{},'csrSubmitted':false,'subscriberAgreement':{'signed':true,'signerName':'Keyfactor Plugin Test','signedAt':'2026-10-01T18:43:09Z','signedPlace':'Gateway Lab'},'subscription':{'validityYears':1},'verific...",204,19739.10,"",4.42,24.16,4.54,4.54,4.42,"create:issued|Order Accepted|Approved by System@4.42; issued|Order Accepted|Certificate Generated@24.94; issued|Order Fulfilled|Certificate Downloaded@26.56",0,,,4.82,4.50,"Order Accepted|Approved by System",24.30,"Order Accepted|Approved by System@4.82; Order Accepted|Certificate Generated@24.30; Order Fulfilled|Certificate Downloaded@27.35",0,-0.40,0,-19.88,6.42,"HTTP 422 {'type':'https://api.certinext.io/errors/unprocessable-entity','title':'Unprocessable Entity','status':422,'detail':'EMS-1165 Invalid request status.'}","HTTP 422 {'type':'https://api.certinext.io/errors/unprocessable-entity','title':'Unprocessable Entity','status':422,'detail':'EMS-1165 Invalid request status.'} @20.40s (3.40s call)",26.03,3627.32,4,"match","match",16,0,22,0.29,0,"9828129796: before=issued; revoke(superseded); after=revoked","revoked","" +4,A,der,"842",dcv-test.scrup.org,5888732121,2026-10-14T21:20:03.7305880Z,201,4116.11,pending-approval,"Order Accepted","Pending for Approver","{'orderId':'5888732121','requestId':'6581787545','status':'pending-approval','orderState':'Order Accepted','certificateState':'Pending for Approver','productVariant':'dv','domain':'dcv-test.scrup.org','createdAt':'2026-10-15T02:50:07.947725031+05:30','resolvedProductCode':'842','requestor':{},'orderedBy':{},'csrSubmitted':true,'subscriberAgreement':{'signed':true,'signerName':'Keyfactor Plugin Test','signedAt':'2026-10-01T18:43:09Z','signedPlace':'Gateway Lab'},'subscription':{'validityYears':...",0,,"",4.12,,4.38,6.02,5.88,"create:pending-approval|Order Accepted|Pending for Approver@4.12; issued|Order Accepted|Approved by System@6.02; issued|Order Accepted|Certificate Generated@19.80; issued|Order Fulfilled|Certificate Downloaded@21.44",0,,,4.91,4.50,"Order Accepted|Approved by System",19.82,"Order Accepted|Approved by System@4.91; Order Accepted|Certificate Generated@19.82; Order Fulfilled|Certificate Downloaded@21.34",0,-0.79,0,-15.71,6.12,"HTTP 422 {'type':'https://api.certinext.io/errors/unprocessable-entity','title':'Unprocessable Entity','status':422,'detail':'EMS-1165 Invalid request status.'}","HTTP 422 {'type':'https://api.certinext.io/errors/unprocessable-entity','title':'Unprocessable Entity','status':422,'detail':'EMS-1165 Invalid request status.'} @15.00s (3.25s call)",20.51,3504.87,3,"match","match",13,0,19,0.31,0,"5888732121: before=issued; revoke(superseded); after=revoked","revoked","" +5,B,n/a,"842",dcv-test.scrup.org,6344583923,2026-10-14T21:21:06.2875940Z,201,4127.17,issued,"Order Accepted","Approved by System","{'orderId':'6344583923','requestId':'9677141412','status':'issued','orderState':'Order Accepted','certificateState':'Approved by System','productVariant':'dv','domain':'dcv-test.scrup.org','createdAt':'2026-10-15T02:51:10.550482543+05:30','resolvedProductCode':'842','requestor':{},'orderedBy':{},'csrSubmitted':false,'subscriberAgreement':{'signed':true,'signerName':'Keyfactor Plugin Test','signedAt':'2026-10-01T18:43:09Z','signedPlace':'Gateway Lab'},'subscription':{'validityYears':1},'verific...",204,22570.91,"",4.13,26.70,4.27,4.27,4.13,"create:issued|Order Accepted|Approved by System@4.13; issued|Order Accepted|Certificate Generated@26.56; issued|Order Fulfilled|Certificate Downloaded@33.08",0,,,3.28,3.00,"Order Accepted|Pending for Approver",27.29,"Order Accepted|Pending for Approver@3.28; Order Accepted|Approved by System@4.83; Order Accepted|Certificate Generated@27.29; Order Fulfilled|Certificate Downloaded@31.82",1,0.84,0,-23.16,6.13,"HTTP 422 {'type':'https://api.certinext.io/errors/unprocessable-entity','title':'Unprocessable Entity','status':422,'detail':'EMS-1165 Invalid request status.'}","HTTP 422 {'type':'https://api.certinext.io/errors/unprocessable-entity','title':'Unprocessable Entity','status':422,'detail':'EMS-1165 Invalid request status.'} @25.68s (3.27s call)",31.50,3822.99,5,"match","match",20,0,26,0.29,0,"6344583923: before=issued; revoke(superseded); after=revoked","revoked","" +6,A,der,"842",dcv-test.scrup.org,1377694183,2026-10-14T21:22:20.3844710Z,201,22039.31,issued,"Order Accepted","Certificate Generated","{'orderId':'1377694183','requestId':'2497619935','status':'issued','orderState':'Order Accepted','certificateState':'Certificate Generated','productVariant':'dv','domain':'dcv-test.scrup.org','createdAt':'2026-10-15T02:52:42.562771292+05:30','expiresAt':'2027-01-12T21:22:38Z','resolvedProductCode':'842','requestor':{},'orderedBy':{},'csrSubmitted':true,'subscriberAgreement':{'signed':true,'signerName':'Keyfactor Plugin Test','signedAt':'2026-10-01T18:43:09Z','signedPlace':'Gateway Lab'},'subsc...",0,,"",22.04,,22.17,22.17,22.04,"create:issued|Order Accepted|Certificate Generated@22.04; issued|Order Fulfilled|Certificate Downloaded@28.69",0,,,4.80,4.51,"Order Accepted|Pending for Approver",22.80,"Order Accepted|Pending for Approver@4.80; Order Accepted|Approved by System@6.30; Order Accepted|Certificate Generated@22.80; Order Fulfilled|Certificate Downloaded@28.81",1,17.24,0,-0.76,24.04,"ok-with-certificate","",27.61,3569.02,1,"match","match",7,0,24,0.29,0,"1377694183: before=issued; revoke(superseded); after=revoked","revoked","" diff --git a/experiment-results/v2-inline-csr-10142123.csv b/experiment-results/v2-inline-csr-10142123.csv new file mode 100644 index 0000000..05fdecd --- /dev/null +++ b/experiment-results/v2-inline-csr-10142123.csv @@ -0,0 +1,3 @@ +trial,arm,arm_a_encoding,product_header,domain,order_id,t0_utc,create_http,create_ms,create_status,create_order_state,create_cert_state,create_body,put_http,put_ms,put_body,t_create_resp_s,t_put_resp_s,t_first_track_obs_s,t_issued_track_s,t_issued_track_lower_s,track_seq,system_error_seen,system_error_first_s,system_error_cleared_s,first_seen_listing_s,first_seen_listing_lower_s,first_seen_listing_status,t_issued_listing_s,listing_seq,seen_in_listing_before_create_resp,listing_first_seen_to_create_resp_s,issued_in_listing_before_create_resp,create_resp_minus_issued_listing_s,dl_first_at_s,dl_first_result,dl_last_failure,dl_success_at_s,dl_ms,dl_attempts,cert_pubkey,cert_cn,track_polls,track_errors,list_polls,list_poll_median_s,list_errors,cleanup,final_state,error +1,A,pem,"",dcv-test.scrup.org,4428272458,2026-10-14T21:23:38.5491800Z,201,6215.77,pending-dcv,"Order Accepted","System Error","{'orderId':'4428272458','requestId':'7935764337','status':'pending-dcv','orderState':'Order Accepted','certificateState':'System Error','productVariant':'dv','domain':'dcv-test.scrup.org','createdAt':'2026-10-15T02:53:44.881111843+05:30','resolvedProductCode':'917','requestor':{},'orderedBy':{},'csrSubmitted':true,'subscriberAgreement':{'signed':true,'signerName':'Keyfactor Plugin Test','signedAt':'2026-10-01T18:43:09Z','signedPlace':'Gateway Lab'},'subscription':{'validityYears':1},'verificat...",0,,"",6.22,,6.37,,,"create:pending-dcv|Order Accepted|System Error@6.22",1,6.22,,4.79,4.50,"Order Accepted|Pending for Validation",,"Order Accepted|Pending for Validation@4.79",1,1.43,0,,,"","",,,0,"","",50,0,62,0.29,0,"4428272458: before=pending-dcv; cancel -> Cancelled; after=cancelled","cancelled","" +2,A,pem,"",dcv-test.scrup.org,3191323532,2026-10-14T21:25:32.8312190Z,201,4735.23,pending-dcv,"Order Accepted","System Error","{'orderId':'3191323532','requestId':'5711814624','status':'pending-dcv','orderState':'Order Accepted','certificateState':'System Error','productVariant':'dv','domain':'dcv-test.scrup.org','createdAt':'2026-10-15T02:55:37.683900471+05:30','resolvedProductCode':'917','requestor':{},'orderedBy':{},'csrSubmitted':true,'subscriberAgreement':{'signed':true,'signerName':'Keyfactor Plugin Test','signedAt':'2026-10-01T18:43:09Z','signedPlace':'Gateway Lab'},'subscription':{'validityYears':1},'verificat...",0,,"",4.74,,5.01,,,"create:pending-dcv|Order Accepted|System Error@4.74",1,4.74,,3.32,3.00,"Order Accepted|Pending for Approver",,"Order Accepted|Pending for Approver@3.32; Order Accepted|Pending for Validation@5.18",1,1.42,0,,,"","",,,0,"","",51,0,62,0.29,0,"3191323532: before=pending-dcv; cancel -> Cancelled; after=cancelled","cancelled","" diff --git a/experiment-results/v2-inline-csr-10142127.csv b/experiment-results/v2-inline-csr-10142127.csv new file mode 100644 index 0000000..f45d263 --- /dev/null +++ b/experiment-results/v2-inline-csr-10142127.csv @@ -0,0 +1,2 @@ +trial,arm,arm_a_encoding,product_header,domain,order_id,t0_utc,create_http,create_ms,create_status,create_order_state,create_cert_state,create_body,put_http,put_ms,put_body,t_create_resp_s,t_put_resp_s,t_first_track_obs_s,t_issued_track_s,t_issued_track_lower_s,track_seq,system_error_seen,system_error_first_s,system_error_cleared_s,first_seen_listing_s,first_seen_listing_lower_s,first_seen_listing_status,t_issued_listing_s,listing_seq,seen_in_listing_before_create_resp,listing_first_seen_to_create_resp_s,issued_in_listing_before_create_resp,create_resp_minus_issued_listing_s,dl_first_at_s,dl_first_result,dl_last_failure,dl_success_at_s,dl_ms,dl_attempts,cert_pubkey,cert_cn,track_polls,track_errors,list_polls,list_poll_median_s,list_errors,cleanup,final_state,error +1,B,n/a,"",dcv-test.scrup.org,1219642577,2026-10-14T21:27:25.9745510Z,201,5926.16,pending-dcv,"Order Accepted","System Error","{'orderId':'1219642577','requestId':'6966478445','status':'pending-dcv','orderState':'Order Accepted','certificateState':'System Error','productVariant':'dv','domain':'dcv-test.scrup.org','createdAt':'2026-10-15T02:57:32.023591726+05:30','resolvedProductCode':'917','requestor':{},'orderedBy':{},'csrSubmitted':false,'subscriberAgreement':{'signed':true,'signerName':'Keyfactor Plugin Test','signedAt':'2026-10-01T18:43:09Z','signedPlace':'Gateway Lab'},'subscription':{'validityYears':1},'verifica...",422,3423.01,"{'type':'https://api.certinext.io/errors/unprocessable-entity','title':'Unprocessable Entity','status':422,'detail':'PFX based certificate orders are not allowed.'}",5.93,9.35,6.42,,,"create:pending-dcv|Order Accepted|System Error@5.93",1,5.93,,4.82,4.51,"Order Accepted|Pending for Validation",,"Order Accepted|Pending for Validation@4.82",1,1.11,0,,,"","",,,0,"","",32,0,41,0.31,0,"1219642577: before=pending-dcv; cancel -> Cancelled; after=cancelled","cancelled","put HTTP 422: {'type':'https://api.certinext.io/errors/unprocessable-entity','title':'Unprocessable Entity','status':422,'detail':'PFX based certificate orders are not allowed.'}; " diff --git a/experiment-results/v2-placeorder-latency-10141548.csv b/experiment-results/v2-placeorder-latency-10141548.csv new file mode 100644 index 0000000..f886d7b --- /dev/null +++ b/experiment-results/v2-placeorder-latency-10141548.csv @@ -0,0 +1,2 @@ +trial,domain,order_id,t0_utc,create_resp_status,place_ms,csr_ms,track_calls_ms,download_ms,enroll_wall_s,enroll_status,enroll_has_cert,t_place_resp_s,t_csr_resp_s,t_enroll_end_s,first_seen_listing_s,first_seen_listing_lower_s,first_seen_listing_status,seen_in_listing_before_place_resp,seen_in_listing_before_csr_resp,exposure_seen_to_enroll_end_s,track_first_obs_s,track_first_obs_status,status_after_csr,t_issued_track_s,t_issued_track_lower_s,t_issued_listing_s,issued_before_place_resp,issued_before_csr_resp,issued_before_enroll_end,track_seq,listing_seq,list_polls,list_poll_median_s,track_polls,list_errors,track_errors,cleanup,error +1,v2lat-10141548-01.dcv-test.scrup.org,3544182867,2026-10-14T15:48:36.3313250Z,pending-approval,4387.38,3244.75,"120.71;121.24;119.17;118.29;137.02;112.14",,64.72,EXTERNALVALIDATION,0,5.73,8.98,64.72,4.62,4.50,"Order Accepted|Pending for Approver",1,1,60.10,6.67,"pending-approval","pending-approval@10.04",,,,0,0,0,"pending-approval@6.67","Order Accepted|Pending for Approver@4.62",105,0.12,132,0,0,"cancelled (status was 90)","" diff --git a/experiment-results/v2-placeorder-latency-10141551.csv b/experiment-results/v2-placeorder-latency-10141551.csv new file mode 100644 index 0000000..7712774 --- /dev/null +++ b/experiment-results/v2-placeorder-latency-10141551.csv @@ -0,0 +1,2 @@ +trial,domain,order_id,t0_utc,create_resp_status,place_ms,csr_ms,track_calls_ms,download_ms,enroll_wall_s,enroll_status,enroll_has_cert,t_place_resp_s,t_csr_resp_s,t_enroll_end_s,first_seen_listing_s,first_seen_listing_lower_s,first_seen_listing_status,seen_in_listing_before_place_resp,seen_in_listing_before_csr_resp,exposure_seen_to_enroll_end_s,track_first_obs_s,track_first_obs_status,status_after_csr,t_issued_track_s,t_issued_track_lower_s,t_issued_listing_s,issued_before_place_resp,issued_before_csr_resp,issued_before_enroll_end,track_seq,listing_seq,list_polls,list_poll_median_s,track_polls,list_errors,track_errors,cleanup,error +1,dcv-test.scrup.org,1226469856,2026-10-14T15:51:31.5398990Z,pending-approval,4680.93,2878.95,"125.41;121.05;120.10;130.79",2719.68,39.90,GENERATED,1,6.02,8.90,39.90,4.64,4.50,"Order Accepted|Pending for Approver",1,1,35.26,6.97,"pending-approval","pending-approval@9.22",17.27,17.14,36.15,0,0,1,"pending-approval@6.97; issued@17.27","Order Accepted|Pending for Approver@4.64; Order Accepted|Approved by System@16.63; Order Accepted|Certificate Generated@36.15; Order Fulfilled|Certificate Downloaded@40.64",31,0.12,33,0,0,"revoked (50)","" diff --git a/experiment-results/v2-placeorder-latency-10141552.csv b/experiment-results/v2-placeorder-latency-10141552.csv new file mode 100644 index 0000000..c8a9022 --- /dev/null +++ b/experiment-results/v2-placeorder-latency-10141552.csv @@ -0,0 +1,5 @@ +trial,domain,order_id,t0_utc,create_resp_status,place_ms,csr_ms,track_calls_ms,download_ms,enroll_wall_s,enroll_status,enroll_has_cert,t_place_resp_s,t_csr_resp_s,t_enroll_end_s,first_seen_listing_s,first_seen_listing_lower_s,first_seen_listing_status,seen_in_listing_before_place_resp,seen_in_listing_before_csr_resp,exposure_seen_to_enroll_end_s,track_first_obs_s,track_first_obs_status,status_after_csr,t_issued_track_s,t_issued_track_lower_s,t_issued_listing_s,issued_before_place_resp,issued_before_csr_resp,issued_before_enroll_end,track_seq,listing_seq,list_polls,list_poll_median_s,track_polls,list_errors,track_errors,cleanup,error +1,dcv-test.scrup.org,1918886693,2026-10-14T15:52:58.5753240Z,issued,4103.53,20227.87,"113.49",2777.85,28.52,GENERATED,1,5.39,25.61,28.52,6.13,6.01,"Order Accepted|Approved by System",0,1,22.39,6.33,"issued","issued@26.73",6.33,5.39,25.63,0,1,1,"issued@6.33","Order Accepted|Approved by System@6.13; Order Accepted|Certificate Generated@25.63; Order Fulfilled|Certificate Downloaded@28.64",23,0.12,24,0,0,"revoked (50)","" +2,dcv-test.scrup.org,7313697899,2026-10-14T15:53:55.5921110Z,pending-approval,3527.19,18789.17,"117.85",2736.23,25.58,GENERATED,1,3.93,22.72,25.58,4.64,4.50,"Order Accepted|Approved by System",0,1,20.94,4.07,"pending-approval","issued@23.17",5.18,5.07,24.14,0,1,1,"pending-approval@4.07; issued@5.18","Order Accepted|Approved by System@4.64; Order Accepted|Certificate Generated@24.14; Order Fulfilled|Certificate Downloaded@25.63",21,0.13,23,0,0,"revoked (50)","" +3,dcv-test.scrup.org,3428572213,2026-10-14T15:54:48.6744050Z,issued,4340.89,20293.81,"119.36",2772.59,28.10,GENERATED,1,4.91,25.20,28.10,4.63,4.50,"Order Accepted|Pending for Approver",1,1,23.47,5.04,"issued","issued@25.32",5.04,4.91,25.64,0,1,1,"issued@5.04","Order Accepted|Pending for Approver@4.63; Order Accepted|Approved by System@6.13; Order Accepted|Certificate Generated@25.64; Order Fulfilled|Certificate Downloaded@28.64",23,0.13,25,0,0,"revoked (50)","" +4,dcv-test.scrup.org,7915224579,2026-10-14T15:55:42.5126450Z,issued,3776.63,21483.81,"125.22",2740.45,28.52,GENERATED,1,4.17,25.66,28.52,4.63,4.50,"Order Accepted|Approved by System",0,1,23.89,4.37,"issued","issued@25.81",4.37,4.17,25.64,0,1,1,"issued@4.37","Order Accepted|Approved by System@4.63; Order Accepted|Certificate Generated@25.64; Order Fulfilled|Certificate Downloaded@28.64",23,0.13,26,0,0,"revoked (50)","" diff --git a/experiment-results/v2-placeorder-latency-10141556.csv b/experiment-results/v2-placeorder-latency-10141556.csv new file mode 100644 index 0000000..e6447e1 --- /dev/null +++ b/experiment-results/v2-placeorder-latency-10141556.csv @@ -0,0 +1,5 @@ +trial,domain,order_id,t0_utc,create_resp_status,place_ms,csr_ms,track_calls_ms,download_ms,enroll_wall_s,enroll_status,enroll_has_cert,t_place_resp_s,t_csr_resp_s,t_enroll_end_s,first_seen_listing_s,first_seen_listing_lower_s,first_seen_listing_status,seen_in_listing_before_place_resp,seen_in_listing_before_csr_resp,exposure_seen_to_enroll_end_s,track_first_obs_s,track_first_obs_status,status_after_csr,t_issued_track_s,t_issued_track_lower_s,t_issued_listing_s,issued_before_place_resp,issued_before_csr_resp,issued_before_enroll_end,track_seq,listing_seq,list_polls,list_poll_median_s,track_polls,list_errors,track_errors,cleanup,error +1,dcv-test.scrup.org,8731931793,2026-10-14T15:56:53.6759880Z,issued,3730.35,18629.94,"116.12",2719.01,26.44,GENERATED,1,4.96,23.59,26.44,4.65,4.50,"Order Accepted|Pending for Approver",1,1,21.79,5.92,"issued","issued@24.13",5.92,4.96,24.13,0,1,1,"issued@5.92","Order Accepted|Pending for Approver@4.65; Order Accepted|Approved by System@6.13; Order Accepted|Certificate Generated@24.13; Order Fulfilled|Certificate Downloaded@27.14",22,0.13,22,0,0,"revoked (50)","" +2,dcv-test.scrup.org,8487123326,2026-10-14T15:57:46.0516710Z,issued,3789.28,18738.54,"131.37",2940.75,26.04,GENERATED,1,4.23,22.97,26.04,4.64,4.50,"Order Accepted|Approved by System",0,1,21.40,4.35,"issued","issued@23.51",4.35,4.23,24.16,0,1,1,"issued@4.35","Order Accepted|Approved by System@4.64; Order Accepted|Certificate Generated@24.16; Order Fulfilled|Certificate Downloaded@27.14",22,0.13,23,0,0,"revoked (50)","" +3,dcv-test.scrup.org,7447643132,2026-10-14T15:58:37.0139520Z,issued,3789.65,17374.89,"116.52",2850.52,24.60,GENERATED,1,4.26,21.64,24.60,4.63,4.50,"Order Accepted|Approved by System",0,1,19.97,4.39,"issued","issued@22.45",4.39,4.26,22.65,0,1,1,"issued@4.39","Order Accepted|Approved by System@4.63; Order Accepted|Certificate Generated@22.65; Order Fulfilled|Certificate Downloaded@25.63",21,0.13,22,0,0,"revoked (50)","" +4,dcv-test.scrup.org,8595485484,2026-10-14T15:59:25.4610260Z,issued,4030.05,20343.68,"118.29",3001.09,27.90,GENERATED,1,4.44,24.78,27.90,4.63,4.50,"Order Accepted|Approved by System",0,1,23.27,4.57,"issued","issued@24.83",4.57,4.44,25.64,0,1,1,"issued@4.57","Order Accepted|Approved by System@4.63; Order Accepted|Certificate Generated@25.64; Order Fulfilled|Certificate Downloaded@28.80",23,0.13,25,0,0,"revoked (50)","" diff --git a/experiment-results/v2-placeorder-latency-10141601.csv b/experiment-results/v2-placeorder-latency-10141601.csv new file mode 100644 index 0000000..e95ecc1 --- /dev/null +++ b/experiment-results/v2-placeorder-latency-10141601.csv @@ -0,0 +1,4 @@ +trial,domain,order_id,t0_utc,create_resp_status,place_ms,csr_ms,track_calls_ms,download_ms,enroll_wall_s,enroll_status,enroll_has_cert,t_place_resp_s,t_csr_resp_s,t_enroll_end_s,first_seen_listing_s,first_seen_listing_lower_s,first_seen_listing_status,seen_in_listing_before_place_resp,seen_in_listing_before_csr_resp,exposure_seen_to_enroll_end_s,track_first_obs_s,track_first_obs_status,status_after_csr,t_issued_track_s,t_issued_track_lower_s,t_issued_listing_s,issued_before_place_resp,issued_before_csr_resp,issued_before_enroll_end,dl_probe_at_s,dl_probe_ms,dl_probe_result,track_seq,listing_seq,list_polls,list_poll_median_s,track_polls,list_errors,track_errors,cleanup,error +1,dcv-test.scrup.org,2299934381,2026-10-14T16:01:25.5594380Z,issued,4017.95,20289.41,"114.72",2998.62,28.65,GENERATED,1,5.23,25.52,28.65,4.67,4.50,"Order Accepted|Pending for Approver",1,1,23.98,6.27,"issued","issued@25.81",6.27,5.23,25.65,0,1,1,6.27,3567.11,"error: Exception: CERTInext V2 API error during 'V2 download certificate'. HTTP 422. Unprocessable Entity: EMS-1165 Invalid request status.","issued@6.27","Order Accepted|Pending for Approver@4.67; Order Accepted|Approved by System@6.14; Order Accepted|Certificate Generated@25.65; Order Fulfilled|Certificate Downloaded@28.65",23,0.14,21,0,0,"revoked (50)","" +2,dcv-test.scrup.org,1732815671,2026-10-14T16:02:44.5566100Z,issued,3760.70,19069.55,"118.24",2766.61,26.23,GENERATED,1,4.28,23.35,26.23,4.65,4.50,"Order Accepted|Approved by System",0,1,21.58,4.40,"issued","issued@23.95",4.40,4.28,24.15,0,1,1,4.40,3807.95,"error: Exception: CERTInext V2 API error during 'V2 download certificate'. HTTP 422. Unprocessable Entity: EMS-1165 Invalid request status.","issued@4.40","Order Accepted|Approved by System@4.65; Order Accepted|Certificate Generated@24.15; Order Fulfilled|Certificate Downloaded@27.15",22,0.14,20,0,0,"revoked (50)","" +3,dcv-test.scrup.org,7966694779,2026-10-14T16:03:48.0246110Z,issued,3890.93,23110.25,"119.99",2794.07,30.35,GENERATED,1,4.32,27.43,30.35,5.16,4.50,"Order Accepted|Approved by System",0,1,25.19,4.51,"issued","issued@28.34",4.51,4.32,28.64,0,1,1,4.51,3557.85,"error: Exception: CERTInext V2 API error during 'V2 download certificate'. HTTP 422. Unprocessable Entity: EMS-1165 Invalid request status.","issued@4.51","Order Accepted|Approved by System@5.16; Order Accepted|Certificate Generated@28.64; Order Fulfilled|Certificate Downloaded@31.65",24,0.14,24,0,0,"revoked (50)","" diff --git a/experiment-results/v2-placeorder-latency-summary.md b/experiment-results/v2-placeorder-latency-summary.md new file mode 100644 index 0000000..ae5b66a --- /dev/null +++ b/experiment-results/v2-placeorder-latency-summary.md @@ -0,0 +1,49 @@ +# V2 place-order latency vs. issue 0090 (2026-10-14, CERTInext sandbox) + +Test: `CERTInext.IntegrationTests/V2PlaceOrderLatencyExperimentTests.cs` (opt-in `CERTINEXT_V2_LATENCY_EXPERIMENT=1`). +The plugin's real `Enroll` (V2, DV SSL 842, DCV off, default pickup 5 x 10 s) runs through a timing proxy over +`ICERTInextClient`. Beside it, an independent client lists `/reports/orders` every 1.5 s (what Synchronize calls) and +another tracks the order every 1 s from the moment the create response lands. Times are seconds after Enroll start (t0). +Raw data: `v2-placeorder-latency-*.csv` (13 orders: 12 on the verified base domain, 1 on a fresh unverified subdomain). +All 13 orders were revoked or cancelled by the test. + +## V2 order placement is three calls, and the hold moved to the second one +1. `POST create` returns the orderId after 3.5-4.7 s (median 3.9 s). It does NOT hold for ~19 s. +2. `PUT /csr` blocks 17.4-23.1 s (median 20.2 s) in 11 of 12 base-domain orders (the 12th, the first base-domain order of the day, took 2.9 s and issued ~17 s after t0 instead). The certificate is generated inside this call. +3. `GET track` + `GET certificate` + pickup: ~0.12 s + ~2.8 s. Total `Enroll` wall time: 24.6-30.4 s (median 27.9 s) for + the 11 held orders; 39.9 s for the anomalous one. + +## Per-order table (base domain `reuse` orders; seconds after t0 unless noted) +| order | create-resp status | place HTTP | csr HTTP | track 'issued' first seen | listing 'Certificate Generated' | csr resp | Enroll wall | listing-first-seen -> Enroll end | +|---|---|---|---|---|---|---|---|---| +| 1226469856 | pending-approval | 4.7 | 2.9 | 17.3 | 36.2 | 8.9 | 39.9 | 35.3 | +| 1918886693 | issued | 4.1 | 20.2 | 6.3 | 25.6 | 25.6 | 28.5 | 22.4 | +| 7313697899 | pending-approval | 3.5 | 18.8 | 5.2 | 24.1 | 22.7 | 25.6 | 20.9 | +| 3428572213 | issued | 4.3 | 20.3 | 5.0 | 25.6 | 25.2 | 28.1 | 23.5 | +| 7915224579 | issued | 3.8 | 21.5 | 4.4 | 25.6 | 25.7 | 28.5 | 23.9 | +| 8731931793 | issued | 3.7 | 18.6 | 5.9 | 24.1 | 23.6 | 26.4 | 21.8 | +| 8487123326 | issued | 3.8 | 18.7 | 4.4 | 24.2 | 23.0 | 26.0 | 21.4 | +| 7447643132 | issued | 3.8 | 17.4 | 4.4 | 22.7 | 21.6 | 24.6 | 20.0 | +| 8595485484 | issued | 4.0 | 20.3 | 4.6 | 25.6 | 24.8 | 27.9 | 23.3 | +| 2299934381 | issued | 4.0 | 20.3 | 6.3 | 25.7 | 25.5 | 28.7 | 24.0 | +| 1732815671 | issued | 3.8 | 19.1 | 4.4 | 24.2 | 23.4 | 26.2 | 21.6 | +| 7966694779 | issued | 3.9 | 23.1 | 4.5 | 28.6 | 27.4 | 30.4 | 25.2 | + +Unverified fresh subdomain (3544182867): create `pending-approval`, place 4.4 s, csr 3.2 s, still `pending-approval` +>150 s later (no DCV in this run); Enroll returned EXTERNALVALIDATION after 64.7 s. + +## Key datum +- In 11 of 12 base-domain orders the order is already `issued` (per the V2 track endpoint) **before the CSR PUT returns**, + by ~17-21 s; in 10 of 12 the create response itself already says `issued`. This is the production V1 pattern (order + already issued while the response is held), moved to `PUT /csr`. +- The sync-visible window (first sighting in `/reports/orders`, within ~1.5 s of the create response (before it in 5 of 13 orders), to Enroll return, when + the gateway learns the CARequestID) is 20.0-25.2 s (median 22.4 s) for held orders; 35.3 s for the anomalous one. + The listing shows `Order Accepted | Pending for Approver` or `Approved by System` for the whole window and flips to + `Certificate Generated` only about when the CSR PUT returns. + +## Caveats +- V1 sandbox did NOT reproduce production's hold, so these are suggestive, not proof, for production V2. The V2 sandbox + does reproduce the shape (issued before response, ~20 s hold), which V1 sandbox did not. +- One account, one ~25 minute window, 13 orders; first-sighting resolution is the 1.5 s poll interval. +- Phase 1 orders share the sandbox account with the kfclab gateway, whose own sync imported at least one of them + (gateway row 1826, order 8595485484). diff --git a/integration-manifest.json b/integration-manifest.json index 8a6d4ee..3a5e9b8 100644 --- a/integration-manifest.json +++ b/integration-manifest.json @@ -7,7 +7,7 @@ "link_github": true, "update_catalog": true, "description": "AnyCA REST Gateway plugin for CERTInext (eMudhra) certificate lifecycle management platform", - "gateway_framework": "25.5.0", + "gateway_framework": "26.2.0", "release_dir": "CERTInext/bin/Release", "release_project": "CERTInext/CERTInext.csproj", "about": { @@ -27,157 +27,345 @@ "ca_plugin_config": [ { "name": "ApiUrl", - "description": "REQUIRED: CERTInext API base URL. Sandbox (US): https://sandbox-us-api.certinext.io/emSignHub-API/ \u2014 Production (US): https://us-api.certinext.io/emSignHub-API/ \u2014 Production (Global/India): https://api.certinext.io/emSignHub-API/" + "description": "REQUIRED: CERTInext API base URL. V1 (default): host plus /emSignHub-API/, e.g. https://us-api.certinext.io/emSignHub-API/. V2 (UseV2Api=true): bare host, e.g. https://us-api.certinext.io. Must use https.", + "required": "Required", + "example": "https://sandbox-us-api.certinext.io/emSignHub-API/", + "default": "" }, { "name": "AccountNumber", - "description": "REQUIRED: Your CERTInext account number (numeric string). Available in the CERTInext portal." + "description": "REQUIRED when UseV2Api is false: your CERTInext account number (numeric string). Included in the `meta` block of every V1 request. Not used when UseV2Api is true. Available in the CERTInext portal.", + "required": "Conditional", + "example": "1234567890", + "default": "" }, { "name": "GroupNumber", - "description": "OPTIONAL: CERTInext group (delegation) number. When set, it is included in GetProductDetails requests AND in the `delegationInformation.groupNumber` field of every SSL order so the order is routed to the correct account group. Some accounts will queue orders for additional review when this field is omitted. Available in the CERTInext portal under Delegation \u2192 Groups." + "description": "OPTIONAL: CERTInext group (delegation) number. When set, it is included in product-catalog requests and in the order (`orderDetails.groupNumber` on V1, `groupNumber` on V2) so the order is routed to the configured account group, and V2 synchronization is scoped to the group. When blank, CERTInext uses the account's default group. Available in the CERTInext portal under Delegation \u2192 Groups.", + "required": "Optional", + "example": "2345678901", + "default": "" }, { "name": "OrganizationNumber", - "description": "STRONGLY RECOMMENDED for OV/EV and faster DV issuance: numeric CERTInext organization number for a pre-vetted organization (e.g. your company's pre-vetted entry). When set, every SSL order is submitted with `organizationDetails.preVetting=\"1\"` and the configured `organizationNumber`, telling CERTInext to skip the manual organization-vetting queue. Without this value, orders are placed without any organizationDetails block and CERTInext may park them in `Pending System RA` for extended manual review (observed: tens of hours). Available in the CERTInext portal under Organizations \u2192 Pre-vetted Organizations." + "description": "OPTIONAL: Pre-vetted CERTInext organization number. Required for OV/EV on V2; recommended for V1 OV/EV and faster DV. Skips CERTInext's manual vetting queue.", + "required": "Optional", + "example": "1234567", + "default": "" }, { "name": "TechnicalContactName", - "description": "OPTIONAL: Name sent in the `technicalPointOfContact.tpcName` field of every SSL order. Defaults to the configured RequestorName when blank. Some product configurations require a TPoC to be present; omitting it can cause CERTInext to park orders awaiting manual completion of the field." + "description": "OPTIONAL: Name sent as the order's technical point of contact (V1 `technicalPointOfContact.pocFirstName` / `pocLastName`, V2 `technicalPointOfContact.name`). On V1 the name is split on the first whitespace: the first word is the first name and the rest is the last name; a single-word name is sent in both. Defaults to the configured RequestorName when blank. On V1, if no contact name or no email resolves (including from RequestorName/RequestorEmail), the whole technicalPointOfContact block is omitted from the order and a Warning is logged, since CERTInext requires both inside the block.", + "required": "Optional", + "example": "Jane Smith", + "default": "" }, { "name": "TechnicalContactEmail", - "description": "OPTIONAL: Email sent in the `technicalPointOfContact.tpcEmail` field of every SSL order. Defaults to the configured RequestorEmail when blank." + "description": "OPTIONAL: Email sent as the order's technical point of contact (V1 `technicalPointOfContact.pocEmail`, V2 `email`). Defaults to the configured RequestorEmail when blank. On V1, if no contact name or no email resolves (including from RequestorName/RequestorEmail), the whole technicalPointOfContact block is omitted from the order and a Warning is logged, since CERTInext requires both inside the block.", + "required": "Optional", + "example": "pki-admin@example.com", + "default": "" }, { "name": "TechnicalContactIsdCode", - "description": "OPTIONAL: International dialing code for the TPoC phone number. Defaults to the configured RequestorIsdCode when blank." + "description": "OPTIONAL: International dialing code for the technical contact phone number. Defaults to the configured RequestorIsdCode when blank.", + "required": "Optional", + "example": "1", + "default": "" }, { "name": "TechnicalContactMobileNumber", - "description": "OPTIONAL: Mobile number for the TPoC (digits only). Defaults to the configured RequestorMobileNumber when blank." + "description": "OPTIONAL: Mobile number for the technical contact (digits only). Defaults to the configured RequestorMobileNumber when blank.", + "required": "Optional", + "example": "5551234567", + "default": "" }, { "name": "AuthMode", - "description": "REQUIRED: Authentication mode. 'AccessKey' (default) \u2014 uses authKey = SHA256(accessKey + ts + txn) in every request body. 'OAuth' \u2014 uses an OAuth2 bearer token (requires OAuthTokenUrl, OAuthClientId, OAuthClientSecret)." + "description": "OPTIONAL, legacy (V1 only): leave as 'AccessKey' (default). V1 does not honor OAuth tokens, so 'OAuth' is unsupported. Ignored when UseV2Api is true.", + "required": "Optional", + "example": "AccessKey", + "default": "AccessKey" }, { "name": "ApiKey", - "description": "REQUIRED when AuthMode is 'AccessKey': the REST API Access Key generated in the CERTInext portal under Integrations \u2192 APIs. This value is used to compute authKey = SHA256(accessKey + ts + txn); it is never transmitted directly." + "description": "REQUIRED when UseV2Api is false: the REST API Access Key generated in the CERTInext portal under Integrations \u2192 APIs. Used to compute authKey = SHA256(accessKey + ts + txn); never transmitted directly. Not used when UseV2Api is true.", + "required": "Conditional", + "example": "abc123def456...", + "default": "" }, { "name": "OAuthTokenUrl", - "description": "OAuth token endpoint URL. Required when AuthMode is 'OAuth'." + "description": "Legacy / unsupported (V1): V1 does not honor OAuth tokens; leave blank. Ignored when UseV2Api is true \u2014 V2 requests its token from {ApiUrl}/oauth/token.", + "required": "Optional", + "example": "", + "default": "" }, { "name": "OAuthClientId", - "description": "OAuth client ID. Required when AuthMode is 'OAuth'." + "description": "OAuth client ID. REQUIRED when UseV2Api is true: V2 authenticates with client_credentials against {ApiUrl}/oauth/token. The key must be generated in OAuth mode in the CERTInext portal. Not used on V1.", + "required": "Conditional", + "example": "keyfactor-gateway", + "default": "" }, { "name": "OAuthClientSecret", - "description": "OAuth client secret. Required when AuthMode is 'OAuth'." + "description": "OAuth client secret. REQUIRED when UseV2Api is true (see OAuthClientId). Not used on V1.", + "required": "Conditional", + "example": "s3cr3t...", + "default": "" }, { "name": "RequestorName", - "description": "REQUIRED: Default requestor name submitted with all certificate orders. This is the name of the person/service responsible for the certificates." + "description": "REQUIRED: Default requestor name submitted with all certificate orders. This is the name of the person/service responsible for the certificates.", + "required": "Required", + "example": "PKI Automation", + "default": "" }, { "name": "RequestorEmail", - "description": "REQUIRED: Default requestor email submitted with all certificate orders. Must be a valid email address registered in your CERTInext account." + "description": "REQUIRED: Default requestor email submitted with all certificate orders. Must be a valid email address registered in your CERTInext account.", + "required": "Required", + "example": "pki-admin@example.com", + "default": "" }, { "name": "RequestorIsdCode", - "description": "International dialing code for the requestor phone number (e.g. '1' for US). Default: '1'." + "description": "International dialing code for the requestor phone number (e.g. '1' for US). Default: '1'.", + "required": "Optional", + "example": "1", + "default": "1" }, { "name": "RequestorMobileNumber", - "description": "Requestor mobile number (digits only, no country code)." + "description": "Requestor mobile number (digits only, no country code).", + "required": "Optional", + "example": "5551234567", + "default": "" + }, + { + "name": "RequestorDesignation", + "description": "OPTIONAL: Job title / role of the requestor (e.g. 'IT Administrator'). Sent as requestorInformation.requestorDesignation (V1) and requestor.designation (V2). Free text. Omitted when blank.", + "required": "Optional", + "example": "IT Administrator", + "default": "" }, { "name": "SignerPlace", - "description": "City or location of the subscriber agreement signer. Required by CERTInext for all orders." + "description": "City or location of the subscriber agreement signer (e.g. 'San Francisco, CA'). REQUIRED when UseV2Api is on: the V2 Subscriber Agreement sent with every SSL order requires it, so the connector cannot be saved with it blank. A per-template SignerPlace enrollment parameter overrides it. On V1, if neither is set, the placeholder \"Gateway\" is sent and a Warning is logged; set it so the agreement audit record is accurate.", + "required": "Conditional", + "example": "Austin", + "default": "" }, { "name": "SignerIp", - "description": "IP address of the subscriber agreement signer. Required by CERTInext for all orders." + "description": "V1 ONLY: IP address of the subscriber agreement signer. A template-level SignerIp enrollment parameter overrides it. If neither is set, the placeholder 127.0.0.1 is sent and a Warning is logged, and a value that is not an IP address is still sent unchanged, with a Warning. Ignored on V2: the V2 agreement block has no signer IP field, so it is never sent.", + "required": "Optional", + "example": "203.0.113.10", + "default": "" }, { "name": "DefaultProductCode", - "description": "OPTIONAL: Default numeric product code used when not specified at template level. Product codes are provided by eMudhra (e.g. the SSL DV 1-year code for your account). Retrieve available codes from Integrations \u2192 APIs \u2192 GetProductDetails." + "description": "OPTIONAL: Default numeric product code. V1 only: used for renewals when the template supplies none. Not used on V2, where the product is resolved by CERTInext (set the template's ProductCode to override). Get codes via GetProductDetails.", + "required": "Optional", + "example": "842", + "default": "" }, { "name": "AccountingModel", - "description": "OPTIONAL: CERTInext billing model sent in `orderDetails.accountingModel`. \"2\" = credit-based (most accounts, default). \"1\" = cash model." + "description": "OPTIONAL: CERTInext billing model sent in `orderDetails.accountingModel` on V1 orders. \"2\" = credit-based (most accounts, default). \"1\" = cash model. Not used by V2.", + "required": "Optional", + "example": "2", + "default": "2" }, { "name": "EmailNotifications", - "description": "OPTIONAL: Whether CERTInext sends lifecycle-event emails to the requestor. \"1\" = enabled, \"0\" = silent (recommended for gateway-driven orders so end users aren't surprised by CA emails). Default: \"0\"." + "description": "OPTIONAL: Lifecycle emails to the requestor. \"1\" = full set (V2: \"all\"), \"0\" = silent (V1: \"0\"; V2: \"consent-only\", the quietest value the V2 API accepts). Blank: silent on V1, omitted on V2 (CA default applies). Other values fail V2 enrollment. Default: \"0\".", + "required": "Optional", + "example": "0", + "default": "0" }, { "name": "SubscriptionValidityYears", - "description": "OPTIONAL: Default validity in years for SSL orders. \"1\", \"2\", or \"3\". Override per template via the ValidityYears product parameter. Default: \"1\"." + "description": "OPTIONAL: Default validity in years for SSL orders. \"1\", \"2\", or \"3\". Used when the template sets no ValidityYears (and, on V1, no ValidityDays); a template term (on V1 the larger of ValidityYears and ValidityDays in years) overrides it. Default: \"1\".", + "required": "Optional", + "example": "1", + "default": "1" }, { "name": "SubscriptionAutoRenew", - "description": "OPTIONAL: Whether CERTInext should auto-renew certificates issued through this connector. \"0\" = disabled (recommended \u2014 renewal is driven by Keyfactor Command), \"1\" = enabled. Default: \"0\"." + "description": "OPTIONAL: Whether CERTInext should auto-renew certificates issued through this connector. \"0\" = disabled (recommended \u2014 renewal is driven by Keyfactor Command), \"1\" = enabled. Default: \"0\".", + "required": "Optional", + "example": "0", + "default": "0" }, { "name": "SubscriptionRenewCriteriaDays", - "description": "OPTIONAL: Days before expiry at which CERTInext auto-renews (only honored when SubscriptionAutoRenew = \"1\"). Typical values: \"30\" or \"60\". Default: \"30\"." + "description": "OPTIONAL: Days before expiry at which CERTInext auto-renews (only honored when SubscriptionAutoRenew = \"1\"). Typical values: \"30\" or \"60\". Default: \"30\".", + "required": "Optional", + "example": "30", + "default": "30" }, { "name": "AutoSecureWww", - "description": "OPTIONAL: If \"1\", CERTInext automatically adds the `www.` variant of the primary domain as an additional SAN. \"0\" = use only the CN/SANs supplied with the CSR. Default: \"0\"." + "description": "OPTIONAL: Sent as `orderDetails.autoSecureWWW` on every V1 SSL order (new and renewal) and as `autoSecureWww` on V2 SSL orders. If \"1\", CERTInext automatically adds the `www.` variant of the primary domain as an additional SAN, which must also pass domain validation. \"0\" = use only the CN/SANs supplied with the CSR. Default: \"0\".", + "required": "Optional", + "example": "0", + "default": "0" }, { "name": "IgnoreExpired", - "description": "If true, expired certificates will be skipped during synchronization. Default: false." + "description": "If true, expired certificates are skipped during synchronization. V2 only: the V1 sync does not currently apply it. Default: false.", + "required": "Optional", + "example": "false", + "default": "false" + }, + { + "name": "SubmitNonDnsSans", + "description": "OPTIONAL (V1 only): If true (default), non-DNS SANs (IP, email, URI) are submitted, but CERTInext cannot validate them, so the order won't issue. If false, only DNS names are submitted.", + "required": "Optional", + "example": "true", + "default": "true" }, { "name": "PageSize", - "description": "Number of orders to fetch per page during synchronization. Default: 100, max: 500." + "description": "Number of orders to fetch per page during synchronization (1 or higher). Default: 100, max: 500 (V2 `/reports/orders` pages are capped at 100).", + "required": "Optional", + "example": "100", + "default": "100" }, { "name": "Enabled", - "description": "Enables or disables the CA connector. Set to false to create the connector record before credentials are available. Default: true." + "description": "Enables or disables the CA connector. Set to false to create the connector record before credentials are available. Default: true.", + "required": "Optional", + "example": "true", + "default": "true" + }, + { + "name": "LogSensitiveRequestData", + "description": "OPTIONAL temporary diagnostic switch. When true, requestor personal data (name, email, phone) and full CA payloads are logged. Credentials are always redacted. Turn off after verifying. Default: false.", + "required": "Optional", + "example": "false", + "default": "false" + }, + { + "name": "PickupRetries", + "description": "OPTIONAL: Times Enroll() polls CERTInext for the certificate after order submission (0-30; 0 disables the wait). Unissued orders are picked up by sync. Default: 5.", + "required": "Optional", + "example": "5", + "default": "5" + }, + { + "name": "PickupDelay", + "description": "OPTIONAL: Seconds between certificate-pickup polls (1-60). Total wait is 5 s + PickupRetries x this value. Command's own enrollment call into the gateway is bounded at roughly 100 s, so the plugin caps the total at 75 s regardless of how PickupRetries/PickupDelay are set, reducing the retry count to fit. Keep your configured total well under that ceiling. Default: 10 (~55 s with default retries).", + "required": "Optional", + "example": "10", + "default": "10" }, { "name": "DcvEnabled", - "description": "OPTIONAL: When true, the gateway will perform DNS-based Domain Control Validation (DCV) during enrollment for orders that require it, using the configured DNS provider plugin. Requires a DNS provider plugin (e.g. azure-azuredns-dnsplugin) to be deployed on the gateway. Default: false." + "description": "OPTIONAL: When true, the plugin performs DNS-based Domain Control Validation (DCV) during enrollment and synchronization for orders that require it, using the DNS provider plugin deployed on the gateway (e.g. azure-azuredns-dnsplugin). Without a DNS provider plugin, orders that need validation stay pending and the plugin logs why. Set to false to skip DCV. Default: true.", + "required": "Optional", + "example": "true", + "default": "true" }, { "name": "DcvTxtRecordTemplate", - "description": "OPTIONAL: Format string for the DNS TXT record hostname used during DCV. {0} is replaced with the domain name being validated. Default: _emsign-validation.{0}" + "description": "OPTIONAL: Format string for the DNS TXT record hostname used during DCV. {0} is replaced with the domain name being validated. Default: _emsign-validation.{0}", + "required": "Optional", + "example": "_emsign-validation.{0}", + "default": "_emsign-validation.{0}" }, { "name": "DcvPropagationDelaySeconds", - "description": "OPTIONAL: Seconds to wait after publishing the DNS TXT record before asking CERTInext to verify it. Increase for zones with slow propagation. Default: 30." + "description": "OPTIONAL: Seconds to wait after publishing the DNS TXT record before asking CERTInext to verify it. Increase for zones with slow propagation. Default: 30.", + "required": "Optional", + "example": "30", + "default": "30" }, { "name": "DcvTimeoutMinutes", - "description": "OPTIONAL: Maximum minutes to wait for the entire DCV flow (DNS publish + propagation + verify) before timing out the enrollment. Can also be set via the CERTINEXT_DCV_TIMEOUT_MINUTES environment variable; the env var takes precedence when both are set. Default: 10." + "description": "OPTIONAL: Maximum minutes for the entire DCV flow (DNS publish + propagation + verify) for one order before it is abandoned and left pending. Can also be set via the CERTINEXT_DCV_TIMEOUT_MINUTES environment variable; the env var takes precedence when both are set. Default: 10.", + "required": "Optional", + "example": "10", + "default": "10" }, { "name": "DcvWaitForChallengeSeconds", - "description": "OPTIONAL: How long (seconds) the plugin will wait inside Enroll() for CERTInext to expose the DCV challenge (i.e. populate `domainVerification` in TrackOrder). Under concurrent load CERTInext sometimes takes a few seconds after GenerateOrderSSL before the slot appears. Without this wait, the plugin's initial TrackOrder check sees null and skips DCV \u2014 the order then has to wait for the next gateway sync cycle to be picked up. Setting to 0 disables the wait (single-check behaviour). Can also be set via the CERTINEXT_DCV_WAIT_FOR_CHALLENGE_SECONDS environment variable; the env var takes precedence when both are set. Default: 60." + "description": "OPTIONAL (V1 only): Seconds Enroll() waits for CERTInext to expose the DCV challenge. 0 disables the wait. CERTINEXT_DCV_WAIT_FOR_CHALLENGE_SECONDS overrides it. Default: 60.", + "required": "Optional", + "example": "60", + "default": "60" }, { "name": "DcvWaitForIssuanceSeconds", - "description": "OPTIONAL: How long (seconds) the plugin will wait inside Enroll() after DCV verifies for CERTInext to finish generating the certificate. CERTInext issuance is async \u2014 DCV may be verified but the cert PEM isn't yet available for download. Without this wait, Enroll() returns a pending result and the issued cert is picked up by the next sync cycle. Setting to 0 disables the wait (single-fetch behaviour). Can also be set via the CERTINEXT_DCV_WAIT_FOR_ISSUANCE_SECONDS environment variable; the env var takes precedence when both are set. Default: 60." + "description": "OPTIONAL (V1 only): Seconds Enroll() waits for issuance after DCV verifies. 0 disables the wait. CERTINEXT_DCV_WAIT_FOR_ISSUANCE_SECONDS overrides it. Default: 60.", + "required": "Optional", + "example": "60", + "default": "60" }, { "name": "DcvSyncMaxOrderAgeHours", - "description": "OPTIONAL: During synchronization, only pending DV orders younger than this many hours are eligible to be driven through DCV. This keeps a sync pass fast when there is a large backlog of old, never-completing pending orders (e.g. abandoned orders or domains outside the configured DNS provider's zone): they age out and are simply reported as pending rather than retried every pass. Recently-placed orders (the ones that legitimately deferred DCV) are always within the window and complete via the normal scan cadence. Set to 0 to disable the age filter (attempt DCV for all pending). Default: 24." + "description": "OPTIONAL: During synchronization, only pending DV orders younger than this many hours are driven through DCV. 0 disables the filter. Default: 24.", + "required": "Optional", + "example": "24", + "default": "24" }, { "name": "DcvSyncMaxPerPass", - "description": "OPTIONAL: Maximum number of pending DV orders the plugin will attempt to drive through DCV in a single synchronization pass. Bounds the per-pass cost regardless of backlog size; remaining pending orders are reported as-is and picked up on a later pass (the per-minute incremental scan keeps recent orders moving). Set to 0 to disable the cap. Default: 50." + "description": "OPTIONAL: Maximum pending DV orders driven through DCV per synchronization pass. 0 disables the cap. Default: 50.", + "required": "Optional", + "example": "50", + "default": "50" + }, + { + "name": "UseV2Api", + "description": "OPTIONAL: When true, the plugin routes Ping / Enroll / GetSingleRecord / Revoke / Synchronize through the CERTInext V2 REST API (/api/certinext/v2/), including V2 /reports/orders for Synchronize. Requires ApiUrl (the V2 base URL in this mode), OAuthClientId, OAuthClientSecret, and SignerPlace. V1 credentials (ApiKey/AccountNumber/AuthMode) are not required when this is true. Default: false (V1 API).", + "required": "Optional", + "example": "false", + "default": "false" + }, + { + "name": "V2SyncLookbackHours", + "description": "OPTIONAL (V2 only): Hours subtracted from the last-sync time on incremental sync, so an order created earlier but issued later is not missed. Default: 72.", + "required": "Optional", + "example": "72", + "default": "72" + }, + { + "name": "SyncRecentOrderGraceSeconds", + "description": "OPTIONAL: during a Synchronize (full or incremental, in both V1 and V2 modes), a pending or issued order created less than this many seconds ago (plus a small clock margin) is not emitted to the gateway (an issued one is not downloaded); the next incremental pass imports it. This stops the sync from inserting a gateway row for an order whose enrollment is still in flight, which would make the enrollment's own save fail with a duplicate key. Revoked and failed orders are never held back. 0 disables the hold; a negative value uses the default. Default: 120.", + "required": "Optional", + "example": "120", + "default": "120" + }, + { + "name": "V2InlineCsr", + "description": "OPTIONAL (V2 mode only): when true (the default), SSL/TLS enrollment sends the CSR inline in the order create call (a single POST /ssl-certificates), as a direct API integration does. When false, the plugin creates the order and then submits the CSR (PUT .../csr); that two-call flow fails for a domain the account has already validated, because CERTInext approves the order at create and then rejects the CSR. A create that times out or returns a 5xx can leave an order that still issues; it is not cancelled and the next synchronization imports it, so do not resubmit. Private PKI orders ignore this setting and always use the two-call flow (the CA rejects an inline CSR on Private PKI create). Ignored when UseV2Api is false. Default: true (single call).", + "required": "Optional", + "example": "true", + "default": "true" + }, + { + "name": "SslComSubmitOrganization", + "description": "OPTIONAL (V2 mode only): before an OV or EV SSL/TLS order, the plugin checks whether SSL.com has validated the organization (OrganizationNumber) at that level, refreshing the status once if not. When this is true and the organization is still unvalidated and ready to submit, the plugin also SUBMITS it to SSL.com for validation. WARNING: enabling this ACCEPTS SSL.COM'S SUBSCRIBER AGREEMENT ON THE ORGANIZATION'S BEHALF; each acceptance is audit-logged. Leave false unless you are authorized to do that. Whatever the outcome, the order is placed anyway and a not-validated organization only logs a warning. Default: false.", + "required": "Optional", + "example": "false", + "default": "false" + }, + { + "name": "SslComAdminEmail", + "description": "OPTIONAL (V2 mode only): administrator email sent as adminEmail when the plugin submits an organization to SSL.com (only used when SslComSubmitOrganization is true). Blank omits it and SSL.com uses the organization's own contact.", + "required": "Optional", + "example": "pki-admin@example.com", + "default": "" } ], "enrollment_config": [ { "name": "ProductCode", - "description": "OPTIONAL: Override the numeric CERTInext product code for this template. When omitted, the default production code for the selected product is used automatically (e.g. DV SSL \u2192 838). Set this explicitly when targeting sandbox or a non-standard code." + "description": "OPTIONAL: Override the numeric CERTInext product code for this template. When omitted: on V1, the default production code for the selected product is used (e.g. DV SSL \u2192 838); on V2, no X-Product-Code header is sent and CERTInext resolves the product from the variant, the wildcard shape of the domain and any additional domains. On V2 an explicit value is an override, sent as X-Product-Code to choose between several matching catalog products (for example different CA profiles for the same variant)." }, { "name": "ProfileId", @@ -185,47 +373,55 @@ }, { "name": "ValidityYears", - "description": "OPTIONAL: Subscription validity in years: 1, 2, or 3. Default: 1. Note: CERTInext validates per 390-day certificate within the subscription; the 'validity' field in the order is the subscription term, not certificate lifetime." + "description": "OPTIONAL: Subscription term in years: 1, 2, or 3. On V1 the order's term is the larger of ValidityYears and ValidityDays rounded up to whole years (365 days = 1 year); a field left at its default (1 year) never overrides the other. On V2 only ValidityYears is used. A template value overrides the connector's SubscriptionValidityYears. Because the larger value wins on V1, a stale larger ValidityDays cannot be shortened with ValidityYears alone; set ValidityDays back to 365. Default: 1. Note: CERTInext validates per 390-day certificate within the subscription; the 'validity' field in the order is the subscription term, not certificate lifetime." }, { "name": "ValidityDays", - "description": "DEPRECATED: Use ValidityYears instead. If set, value is divided by 365 and rounded up to get the subscription year count." + "description": "OPTIONAL: V1 only (ignored on V2, which uses ValidityYears). Requested validity in days. CERTInext's order API takes whole subscription years, so days are converted to years, rounded up (365 days = 1 year). The order's term is the larger of this and ValidityYears; a field left at its default (365 days = 1 year) never overrides the other. Kept because certificate lifetimes are shrinking and days is the unit that will matter if CERTInext adds a lifetime field. To shorten a template with a larger value, set this back to 365. Default: 365." }, { "name": "AutoApprove", - "description": "OPTIONAL: If true, the gateway will attempt automatic approval of certificates that are returned in a pending-approval state. Default: false." + "description": "Currently has no effect \u2014 reserved for future use. The plugin does not call any approval endpoint against CERTInext regardless of this setting. Default: false." }, { "name": "RequesterName", - "description": "OPTIONAL: Default requester name to include in the enrollment request. Used when no requester name can be derived from the subject." + "description": "OPTIONAL: Overrides the connector RequestorName for this template when non-blank. Never derived from the certificate subject." }, { "name": "RequesterEmail", - "description": "OPTIONAL: Default requester email address. Used when no email can be derived from the subject." + "description": "OPTIONAL: Overrides the connector RequestorEmail for this template when non-blank. Never derived from the certificate subject." }, { "name": "RenewalWindowDays", - "description": "OPTIONAL: Number of days before certificate expiration within which a renewal is triggered. Certificates expiring further than this window are reissued instead. Certificates that have already expired also fall back to reissue. Default: 90." + "description": "OPTIONAL: V1 only. Number of days before certificate expiration within which a renewal is triggered. Certificates expiring further than this window are reissued instead. Certificates that have already expired also fall back to reissue. V2 places a new order for every renewal and reissue. Default: 90." }, { "name": "KeyType", - "description": "OPTIONAL: Key algorithm to request (e.g. 'RSA2048', 'RSA4096', 'EC256', 'EC384'). If omitted, the profile default is used." + "description": "OPTIONAL: Informational. The key algorithm is determined by the submitted CSR; CERTInext accepts RSA 2048/3072/4096 and ECC P-256/P-384 and rejects larger RSA, ECC P-521, and Ed25519/Ed448." }, { "name": "DomainName", - "description": "OPTIONAL: Primary domain for SSL/TLS orders. Derived from the CSR CN if omitted." + "description": "OPTIONAL: Primary domain for SSL/TLS orders (for V2 private-pki orders, the primary hostname). Derived from the CSR CN if omitted." }, { "name": "SignerName", - "description": "OPTIONAL: Per-template subscriber agreement signer name. Falls back to the connector-level RequestorName if omitted." + "description": "OPTIONAL: Per-template subscriber agreement signer name. Falls back to the connector-level RequestorName if omitted (V2: the requestor name). If no name resolves, V1 sends the placeholder \"Keyfactor Gateway\" and logs a Warning." }, { "name": "SignerPlace", - "description": "OPTIONAL: Per-template signer city/location. Falls back to the connector-level SignerPlace if omitted." + "description": "OPTIONAL: Per-template signer city/location. Falls back to the connector-level SignerPlace if omitted. If neither is set, V1 sends the placeholder \"Gateway\" and logs a Warning." }, { "name": "SignerIp", - "description": "OPTIONAL: Per-template signer IP address. Falls back to the connector-level SignerIp if omitted." + "description": "V1 ONLY, OPTIONAL: Per-template signer IP address. Falls back to the connector-level SignerIp if omitted. If neither is set, V1 sends the placeholder 127.0.0.1 and logs a Warning; a V1 value that is not an IP address is sent unchanged, with a Warning. Ignored on V2 (the V2 agreement block has no signer IP field)." + }, + { + "name": "ProductFamily", + "description": "V2 ONLY: Product family for this template. Accepted values: 'ssl' (default) or 'private-pki'. 'private-pki' requires a Private PKI ProductVariant. 'signature' (Document Signer) is accepted by the parameter, but Document Signer enrollment is not supported." + }, + { + "name": "ProductVariant", + "description": "V2 ONLY: Product variant sent in the V2 order body. ProductFamily 'ssl': 'dv', 'ov', or 'ev' \u2014 if omitted, derived from the selected product; an explicit value that contradicts the product fails enrollment. ProductFamily 'private-pki': 'intranet-ssl' or 'igtf-host' (required; no default)." } ] } diff --git a/scripts/lib/certinext-v2-auth.sh b/scripts/lib/certinext-v2-auth.sh index 0ed2bc2..38a33ce 100755 --- a/scripts/lib/certinext-v2-auth.sh +++ b/scripts/lib/certinext-v2-auth.sh @@ -1,43 +1,294 @@ #!/usr/bin/env bash -# Shared Bearer-token helper for CERTInext V2 API scripts. +# Shared helpers for the CERTInext V2 dev scripts in scripts/v2/. # -# Usage (from a script in scripts/v2/): -# source "$(dirname "$0")/../lib/certinext-v2-auth.sh" -# # $CERTINEXT_V2_TOKEN is now set +# Source this from a scripts/v2/*.sh script; do not execute it directly: +# . "$(dirname "$0")/../lib/certinext-v2-auth.sh" # -# Requires CERTINEXT_ACCESS_KEY, CERTINEXT_ACCOUNT_NUMBER, and -# CERTINEXT_V2_API_URL to be set in the calling environment -# (sourced from ~/.env_certinext before this file is sourced). +# Auth model (mirrors CERTInextClient.GetOrRefreshV2TokenAsync): +# POST {CERTINEXT_API_URL}/oauth/token +# Content-Type: application/x-www-form-urlencoded +# grant_type=client_credentials&client_id=...&client_secret=... +# -> {"access_token": "...", "token_type": "...", "expires_in": N} +# CERTINEXT_API_URL is the single V2 base URL (e.g. https://sandbox-us.certinext.io, +# no /emSignHub-API suffix). There is no V1 SHA256 authKey step any more. # -# Internally reuses certinext_meta from certinext-auth.sh to compute -# the SHA256 authKey, then exchanges it for a short-lived Bearer JWT -# at POST {v2BaseURL}/oauth/token. - -# shellcheck source=./certinext-auth.sh -# $0 is the calling script (in scripts/v2/), so ../lib/ reaches scripts/lib/. -. "$(dirname "$0")/../lib/certinext-auth.sh" - -read -r _v2_ts _v2_txn _v2_authKey <<< "$(certinext_meta)" - -_v2_token_response=$(curl -s -X POST "$CERTINEXT_V2_API_URL/oauth/token" \ - -H "Content-Type: application/json" \ - -d "$(jq -n \ - --arg grant_type "client_credentials" \ - --arg accountNumber "$CERTINEXT_ACCOUNT_NUMBER" \ - --arg authKey "$_v2_authKey" \ - --arg ver "1.0" \ - --arg ts "$_v2_ts" \ - --arg txn "$_v2_txn" \ - '{grant_type:$grant_type,accountNumber:$accountNumber,authKey:$authKey,ver:$ver,ts:$ts,txn:$txn}')") - -CERTINEXT_V2_TOKEN=$(echo "$_v2_token_response" | jq -r '.tokenDetails.accessToken // empty') - -if [ -z "$CERTINEXT_V2_TOKEN" ]; then - echo "ERROR: failed to acquire V2 Bearer token. Response:" >&2 - echo "$_v2_token_response" | jq . >&2 +# Credentials come from the V2 env file, default ~/.env_certinext_v2, overridable with +# CERTINEXT_V2_ENV_FILE. The file is PARSED (KEY=VALUE, '#' comments, optional +# surrounding quotes), never sourced, so it cannot run code or leak variables into the +# caller's shell. Like V2EnvHelper.LoadEnvFile in the integration tests, a value in the +# file wins over a same-named process env var (a shell that sourced the V1 +# ~/.env_certinext has a V1 CERTINEXT_API_URL exported). Process env is the fallback for +# keys the file doesn't define. +# +# Keys used: CERTINEXT_API_URL, CERTINEXT_CLIENT_ID, CERTINEXT_CLIENT_SECRET (required); +# CERTINEXT_REQUESTOR_NAME, CERTINEXT_REQUESTOR_EMAIL, CERTINEXT_REQUESTOR_MOBILE, +# CERTINEXT_SIGNER_IP (optional, order-body scripts only). +# +# Secret handling: the client secret and bearer token live only in unexported shell +# variables of the running script. They are handed to curl through process substitution +# (/dev/fd pipes), so they never appear in argv (ps), on disk, or on stdout/stderr. +# Do not add `set -x` to any script that sources this file. + +if [ -z "${BASH_VERSION:-}" ]; then + echo "ERROR: certinext-v2-auth.sh must be sourced from bash." >&2 exit 1 fi -export CERTINEXT_V2_TOKEN +for _v2_tool in curl jq; do + if ! command -v "$_v2_tool" >/dev/null 2>&1; then + echo "ERROR: '$_v2_tool' is required but not installed." >&2 + exit 1 + fi +done +unset _v2_tool + +V2_ENV_FILE="${CERTINEXT_V2_ENV_FILE:-$HOME/.env_certinext_v2}" +V2_MUTATE=0 +V2_TOKEN="" + +# _v2_trim — strip leading/trailing whitespace (bash 3.2 compatible). +_v2_trim() { + local s=$1 + s="${s#"${s%%[![:space:]]*}"}" + s="${s%"${s##*[![:space:]]}"}" + printf '%s' "$s" +} + +# _v2_file_value — print KEY's value from $V2_ENV_FILE; return 1 if not defined. +# Last definition wins. Lines without '=' and '#' comments are ignored. +_v2_file_value() { + local want=$1 line key val found=1 out="" + [ -r "$V2_ENV_FILE" ] || return 1 + while IFS= read -r line || [ -n "$line" ]; do + line="${line%$'\r'}" + line=$(_v2_trim "$line") + case "$line" in ''|'#'*) continue ;; esac + case "$line" in *=*) ;; *) continue ;; esac + key=$(_v2_trim "${line%%=*}") + key="${key#export }" + key=$(_v2_trim "$key") + [ "$key" = "$want" ] || continue + val=$(_v2_trim "${line#*=}") + if [ "${#val}" -ge 2 ]; then + case "$val" in + \"*\") val="${val#\"}"; val="${val%\"}" ;; + \'*\') val="${val#\'}"; val="${val%\'}" ;; + esac + fi + out=$val + found=0 + done < "$V2_ENV_FILE" + [ "$found" -eq 0 ] && printf '%s' "$out" + return "$found" +} + +# v2_cfg [default] — value from the env file, else process env, else default. +v2_cfg() { + local key=$1 def=${2:-} val + if val=$(_v2_file_value "$key") && [ -n "$val" ]; then + printf '%s' "$val" + return 0 + fi + val="${!key:-}" + if [ -n "$val" ]; then printf '%s' "$val"; else printf '%s' "$def"; fi +} + +# v2_require — like v2_cfg but exits with a clear message when the key is missing. +v2_require() { + local key=$1 val + val=$(v2_cfg "$key") + if [ -z "$val" ]; then + echo "ERROR: required key $key is not set in $V2_ENV_FILE (or the environment)." >&2 + echo " Set CERTINEXT_V2_ENV_FILE to use a different env file." >&2 + exit 1 + fi + printf '%s' "$val" +} + +# v2_base_url — validated CERTINEXT_API_URL without a trailing slash. +# Refuses plain http except for localhost stubs, so the client secret is never sent in clear. +v2_base_url() { + local url + url=$(v2_require CERTINEXT_API_URL) || exit 1 + url="${url%/}" + case "$url" in + https://*) ;; + http://localhost|http://localhost:*|http://localhost/*|http://127.0.0.1|http://127.0.0.1:*|http://127.0.0.1/*) ;; + *) + echo "ERROR: CERTINEXT_API_URL must be an https:// URL (plain http is only allowed for localhost stubs)." >&2 + exit 1 ;; + esac + case "$url" in + *emSignHub-API*) + echo "ERROR: CERTINEXT_API_URL looks like a V1 URL (contains /emSignHub-API)." >&2 + echo " V2 needs the base URL only, e.g. https://sandbox-us.certinext.io" >&2 + exit 1 ;; + esac + printf '%s' "$url" +} + +# v2_parse_args "$@" — read-only scripts: accepts only -h/--help. +v2_parse_args() { + local a + for a in "$@"; do + case "$a" in + -h|--help) v2_usage; exit 0 ;; + *) echo "ERROR: unknown argument '$a' (this script is read-only)" >&2; v2_usage; exit 1 ;; + esac + done +} + +# v2_parse_mutating_args "$@" — state-changing scripts: --yes-mutate sets V2_MUTATE=1. +v2_parse_mutating_args() { + local a + for a in "$@"; do + case "$a" in + --yes-mutate) V2_MUTATE=1 ;; + -h|--help) v2_usage; exit 0 ;; + *) echo "ERROR: unknown argument '$a'" >&2; v2_usage; exit 1 ;; + esac + done +} + +# v2_require_var — exit with usage if the named script input env var is empty. +v2_require_var() { + local name=$1 + if [ -z "${!name:-}" ]; then + echo "ERROR: $name is required." >&2 + v2_usage + exit 1 + fi +} + +# v2_require_id — like v2_require_var, and the value must be a safe URL path segment. +v2_require_id() { + local name=$1 + v2_require_var "$name" + case "${!name}" in + *[!A-Za-z0-9_.-]*) + echo "ERROR: $name='${!name}' contains characters not allowed in a URL path segment." >&2 + exit 1 ;; + esac +} + +# v2_signer_ip [--offline] — CERTINEXT_SIGNER_IP, else auto-detect via api.ipify.org. +# --offline returns a placeholder instead of calling out (used for the dry-run preview). +v2_signer_ip() { + local ip + ip=$(v2_cfg CERTINEXT_SIGNER_IP) + if [ -n "$ip" ]; then printf '%s' "$ip"; return 0; fi + if [ "${1:-}" = "--offline" ]; then printf '%s' ""; return 0; fi + ip=$(curl -sS --max-time 10 https://api.ipify.org) || { + echo "ERROR: could not auto-detect signer IP; set CERTINEXT_SIGNER_IP." >&2 + exit 1 + } + printf '%s' "$ip" +} + +# Default usage; scripts redefine v2_usage after sourcing this file. +v2_usage() { echo "Usage: $(basename "$0")" >&2; } + +# v2_mutation_gate [body-json] — for state-changing scripts. +# Without --yes-mutate: print the planned request (no network calls, no token) and exit 3. +v2_mutation_gate() { + local method=$1 path=$2 body=${3:-} base + if [ "$V2_MUTATE" -eq 1 ]; then + return 0 + fi + base=$(v2_base_url) || exit 1 + { + echo "REFUSING TO RUN: this script changes state on the CERTInext account." + echo "It would send:" + echo " $method $base$path" + if [ -n "$body" ]; then + echo " body:" + printf '%s\n' "$body" | jq . 2>/dev/null | sed 's/^/ /' || printf ' %s\n' "$body" + fi + echo "Re-run with --yes-mutate to actually send it." + } >&2 + exit 3 +} + +# v2_uuid — random UUID for Idempotency-Key headers. +v2_uuid() { + if command -v uuidgen >/dev/null 2>&1; then + uuidgen | tr '[:upper:]' '[:lower:]' + else + python3 -c 'import uuid; print(uuid.uuid4())' + fi +} + +# v2_get_token — fetch an OAuth2 client_credentials token into V2_TOKEN (unexported). +# Never prints the token, the secret, or the raw token-endpoint response. +v2_get_token() { + local base client_id client_secret resp status body err + base=$(v2_base_url) || exit 1 + client_id=$(v2_require CERTINEXT_CLIENT_ID) || exit 1 + client_secret=$(v2_require CERTINEXT_CLIENT_SECRET) || exit 1 + + resp=$(curl -sS -X POST "$base/oauth/token" \ + -H "Accept: application/json" \ + --data-urlencode "grant_type=client_credentials" \ + --data-urlencode "client_id=$client_id" \ + --data-urlencode "client_secret@"<(printf '%s' "$client_secret") \ + -w $'\n%{http_code}') || { + echo "ERROR: V2 token request to $base/oauth/token failed (network/TLS error)." >&2 + exit 1 + } + client_secret="" + status="${resp##*$'\n'}" + body="${resp%$'\n'*}" + resp="" + + if [ "$status" != "200" ]; then + # Never echo the body: an error response could reflect submitted form fields. + err=$(printf '%s' "$body" | jq -r '.error // empty' 2>/dev/null || true) + case "$err" in + ''|*[!A-Za-z0-9_.-]*) err="" ;; # only print short OAuth2 error codes + esac + echo "ERROR: V2 token request failed: HTTP $status${err:+ ($err)} from $base/oauth/token (client_id=$client_id)." >&2 + case "$status" in + 401) echo " Hint: CERTINEXT_CLIENT_ID / CERTINEXT_CLIENT_SECRET is wrong, or the key was revoked." >&2 ;; + 403) echo " Hint: the access key exists but was not generated in OAuth mode in the portal." >&2 ;; + esac + exit 1 + fi + + V2_TOKEN=$(printf '%s' "$body" | jq -r '.access_token // empty' 2>/dev/null || true) + body="" + if [ -z "$V2_TOKEN" ]; then + echo "ERROR: V2 token response from $base/oauth/token did not contain access_token." >&2 + exit 1 + fi +} + +# v2_request [extra curl args...] — authenticated request to the V2 API. +# Fetches a token on first use. Prints "HTTP " to stderr and the response body +# (pretty-printed by jq when it is JSON) to stdout. Returns 1 on HTTP >= 400. +v2_request() { + local method=$1 path=$2 base resp status body + shift 2 + base=$(v2_base_url) || exit 1 + [ -n "$V2_TOKEN" ] || v2_get_token + + resp=$(curl -sS -X "$method" "$base$path" \ + -H @<(printf 'Authorization: Bearer %s\n' "$V2_TOKEN") \ + -H "Accept: application/json" \ + "$@" \ + -w $'\n%{http_code}') || { + echo "ERROR: $method $base$path failed (network/TLS error)." >&2 + return 1 + } + status="${resp##*$'\n'}" + body="${resp%$'\n'*}" -unset _v2_ts _v2_txn _v2_authKey _v2_token_response + echo "HTTP $status" >&2 + if [ -n "$body" ]; then + if printf '%s' "$body" | jq -e . >/dev/null 2>&1; then + printf '%s' "$body" | jq . + else + printf '%s\n' "$body" + fi + fi + [ "$status" -lt 400 ] 2>/dev/null +} diff --git a/scripts/register/01-gateway-profiles.sh b/scripts/register/01-gateway-profiles.sh index 1d7b242..a724c1e 100755 --- a/scripts/register/01-gateway-profiles.sh +++ b/scripts/register/01-gateway-profiles.sh @@ -5,12 +5,21 @@ # driven by .about.carest.product_ids in integration-manifest.json. Idempotent: # existing profiles are PUT-updated, new ones are POSTed. # +# When V2_TEMPLATES=1 (default) a second profile named " V2" is also +# upserted per product. Command imports AnyCA templates as +# AnyCA_, so the "V2 template" set (stage 02: same ProductID, +# CertificateProfile " V2", no ProductCode) needs these profiles to +# exist alongside the pinned set (CertificateProfile = ProductID). +# # Env: see scripts/lib/command-auth.sh for the OAuth/host contract. # Optional: # KEY_ALGS_JSON override the key_algs object (default: lab set below) # MANIFEST path to integration-manifest.json (default: repo root) +# V2_TEMPLATES 1 (default) = also register " V2" profiles for the +# unpinned V2 template set; 0 = pinned profiles only # CHECK 1 = after applying, diff result vs the captured reference -# (docs/reference/gateway/certificate-profiles.json) +# (docs/reference/gateway/certificate-profiles.json) and +# confirm every profile this run registered is present # DRY_RUN 1 = print intended actions, make no write calls set -euo pipefail @@ -26,6 +35,11 @@ export REPO_ROOT MANIFEST="${MANIFEST:-$REPO_ROOT/integration-manifest.json}" DRY_RUN="${DRY_RUN:-0}" CHECK="${CHECK:-0}" +V2_TEMPLATES="${V2_TEMPLATES:-1}" +case "$V2_TEMPLATES" in + 0|1) ;; + *) echo "ERROR: V2_TEMPLATES must be 0 or 1 (got '$V2_TEMPLATES')" >&2; exit 1 ;; +esac # Lab default key algorithms — matches docs/reference/gateway/certificate-profiles.json. DEFAULT_KEY_ALGS_JSON='{ @@ -53,11 +67,20 @@ done < <(manifest_product_ids "$MANIFEST") [ "${#PRODUCTS[@]}" -gt 0 ] || { echo "ERROR: no product_ids in manifest" >&2; exit 1; } echo " products: ${#PRODUCTS[@]}" +# Profile names to register: the pinned set (one per product, name = ProductID) +# plus, when V2_TEMPLATES=1, the unpinned " V2" set. +PROFILES=() +for _p in "${PRODUCTS[@]}"; do PROFILES+=("$_p"); done +if [ "$V2_TEMPLATES" = "1" ]; then + for _p in "${PRODUCTS[@]}"; do PROFILES+=("$_p V2"); done +fi +echo " V2_TEMPLATES: $V2_TEMPLATES (profiles: ${#PROFILES[@]})" + if [ "$DRY_RUN" = "1" ]; then # Fully offline preview: no token, no listing. - echo " (dry run) would upsert ${#PRODUCTS[@]} profiles with key_algs:" + echo " (dry run) would upsert ${#PROFILES[@]} profiles with key_algs:" echo "$KEY_ALGS_JSON" | jq -c . - for name in "${PRODUCTS[@]}"; do + for name in "${PROFILES[@]}"; do printf ' [DRY ] %s\n' "$name" done echo "== done (dry run): no calls made ==" @@ -75,7 +98,7 @@ if ! echo "$EXISTING" | jq -e 'type == "array"' >/dev/null 2>&1; then fi created=0 updated=0 -for name in "${PRODUCTS[@]}"; do +for name in "${PROFILES[@]}"; do existing_id="$(echo "$EXISTING" | jq -r --arg n "$name" \ '.[] | select(.name == $n) | .id' | head -n1)" @@ -118,4 +141,14 @@ if [ "$CHECK" = "1" ] && [ "$DRY_RUN" != "1" ]; then echo " MISSING reference profiles: $missing" >&2 exit 1 fi + # Every profile registered by this run (pinned + optional V2 set) must exist. + applied_names="$(printf '%s\n' "${PROFILES[@]}" | jq -R . | jq -s .)" + missing="$(jq -n --argjson live "$live_names" --argjson app "$applied_names" \ + '$app - $live')" + if [ "$(echo "$missing" | jq 'length')" -eq 0 ]; then + echo " OK: all ${#PROFILES[@]} profiles registered by this run are present" + else + echo " MISSING registered profiles: $missing" >&2 + exit 1 + fi fi diff --git a/scripts/register/02-gateway-ca-config.sh b/scripts/register/02-gateway-ca-config.sh index 869fe5c..3fd37a1 100755 --- a/scripts/register/02-gateway-ca-config.sh +++ b/scripts/register/02-gateway-ca-config.sh @@ -15,6 +15,12 @@ # CA_CONNECTION_JSON override the entire CAConnection object (advanced) # TEMPLATE_PARAMS_JSON default per-template Parameters object (default: {}) # FULL_SCAN_MINUTES default 720; INCR_SCAN_MINUTES default 5 +# V2_TEMPLATES 1 (default) = also emit the unpinned "V2 template" set: +# {ProductID:P, CertificateProfile:"P V2", Parameters:{...}} +# with NO ProductCode/ProfileId (the plugin then sends no +# X-Product-Code and CERTInext resolves the product). +# Requires the "P V2" gateway profiles from stage 01. +# 0 = pinned set only (previous behavior). # DRY_RUN=1 print the body, make no write call # # CAConnection is assembled from the CERTINEXT_* env vars (same values the @@ -47,6 +53,11 @@ GATEWAY_CERT_FILE="${GATEWAY_CERT_FILE:-$REPO_ROOT/certinext-sandbox-chain.pem}" [ -n "${PRODUCT_CODE_MAP_JSON:-}" ] || PRODUCT_CODE_MAP_JSON='{}' FULL_SCAN_MINUTES="${FULL_SCAN_MINUTES:-720}" INCR_SCAN_MINUTES="${INCR_SCAN_MINUTES:-5}" +V2_TEMPLATES="${V2_TEMPLATES:-1}" +case "$V2_TEMPLATES" in + 0|1) ;; + *) echo "ERROR: V2_TEMPLATES must be 0 or 1 (got '$V2_TEMPLATES')" >&2; exit 1 ;; +esac echo "== Stage 02: gateway CA configuration ==" echo " gateway : $(gw_show)" @@ -96,13 +107,27 @@ else echo " warn: GATEWAY_CERT_FILE not found ($GATEWAY_CERT_FILE) — sending empty cert block" >&2 fi -# --- Templates[] (one per product_id) --------------------------------------- +# --- Templates[] ------------------------------------------------------------- +# Pinned set: one per product_id, CertificateProfile = ProductID, ProductCode +# from PRODUCT_CODE_MAP_JSON when present. Command imports these as +# AnyCA_. +# V2 set (V2_TEMPLATES=1): same ProductID, CertificateProfile " V2", +# never a ProductCode/ProfileId (stripped even if TEMPLATE_PARAMS_JSON or the +# codes map carries one). Command imports these as AnyCA_ V2. TEMPLATES="$(manifest_product_ids "$MANIFEST" | jq -R . | jq -s \ --argjson params "$TEMPLATE_PARAMS_JSON" \ --argjson codes "$PRODUCT_CODE_MAP_JSON" \ - '[.[] | . as $p - | {ProductID: $p, CertificateProfile: $p, - Parameters: ($params + (if $codes[$p] then {ProductCode: $codes[$p]} else {} end))}]')" + --argjson v2 "$V2_TEMPLATES" \ + '. as $ids + | [$ids[] | . as $p + | {ProductID: $p, CertificateProfile: $p, + Parameters: ($params + (if $codes[$p] then {ProductCode: $codes[$p]} else {} end))}] + + (if $v2 == 1 then + [$ids[] | . as $p + | {ProductID: $p, CertificateProfile: ($p + " V2"), + Parameters: ($params | del(.ProductCode, .ProfileId))}] + else [] end)')" +echo " templates: $(echo "$TEMPLATES" | jq 'length') (V2_TEMPLATES=$V2_TEMPLATES)" # --- Assemble configuration body -------------------------------------------- BODY="$(jq -n \ diff --git a/scripts/register/README.md b/scripts/register/README.md index a2d31dd..4d8d937 100644 --- a/scripts/register/README.md +++ b/scripts/register/README.md @@ -13,8 +13,8 @@ vendor API. Shared auth/host logic lives in [`../lib/command-auth.sh`](../lib/co | Stage | Script | `make` target | Side | Notes | |------:|--------|---------------|------|-------| -| 01 | `01-gateway-profiles.sh` | `register-profiles` | Gateway | one cert profile per product. **Verified.** | -| 02 | `02-gateway-ca-config.sh` | `register-ca-config` | Gateway | CAConnection + Templates[]. ⚠️ touches CA config — opt-in. | +| 01 | `01-gateway-profiles.sh` | `register-profiles` | Gateway | one cert profile per product, plus a ` V2` profile per product when `V2_TEMPLATES=1` (default). **Verified.** | +| 02 | `02-gateway-ca-config.sh` | `register-ca-config` | Gateway | CAConnection + Templates[] (pinned set, plus the V2 template set when `V2_TEMPLATES=1`). ⚠️ touches CA config — opt-in. | | 03 | `03-gateway-claims.sh` | `register-claims` | Gateway | OAuth claim→role mappings. Unverified. | | 04 | `04-command-register-ca.sh` | `register-command-ca` | Command | registers the CA. ⚠️ **CA config — leave alone unless asked.** | | 05 | `05-command-import-templates.sh` | `register-import` | Command | `POST /Templates/Import`. | @@ -28,6 +28,36 @@ and reads `~/.env_certinext` + the env contract below. > PUT) unless explicitly asked — it is fragile and easily broken. Profiles, > template import, enrollment patterns, and key-retention are safe to re-run. +## Template sets: pinned and V2 (`V2_TEMPLATES`) + +Command imports AnyCA templates under the name `AnyCA_`, so two +gateway templates can share a `ProductID` as long as their `CertificateProfile` +differs. Stages 01 and 02 register two sets per product in +`.about.carest.product_ids` (10 products → 20 templates): + +| Set | `ProductID` | `CertificateProfile` | `Parameters` | Command template | Behavior | +|-----|-------------|----------------------|--------------|------------------|----------| +| Pinned | `DV SSL` | `DV SSL` | `ProductCode` (from `PRODUCT_CODE_MAP_JSON`) + `TEMPLATE_PARAMS_JSON` | `AnyCA_DV SSL` | plugin sends `X-Product-Code` | +| V2 template | `DV SSL` | `DV SSL V2` | `TEMPLATE_PARAMS_JSON` only — **never** `ProductCode`/`ProfileId` | `AnyCA_DV SSL V2` | plugin sends no `X-Product-Code`; CERTInext resolves the product | + +- `V2_TEMPLATES=1` (default) registers both sets; `V2_TEMPLATES=0` is the previous + pinned-only behavior. Use the same value for stages 01 and 02. +- Stage 01 must run first: it creates the ` V2` gateway profiles that the + V2 templates reference. Stage 02 strips `ProductCode`/`ProfileId` from V2 entries + even if `PRODUCT_CODE_MAP_JSON` has an entry for the product. +- Stage 05 imports both sets (it imports whatever the gateway exposes). Stage 06 + iterates every template in the tenant, so the V2 templates get enrollment patterns + (named after each template's `DisplayName`) and key retention with no change. +- Unpinned DV on the CERTInext sandbox currently resolves to a product that rejects + the CSR at submit; that is a CERTInext account finding, not a registration issue. + The V2 integration tests run both ways for the same reason (see + `CERTInext.IntegrationTests/TESTING.md`). +- `CHECK=1` on stage 01 still diffs against the captured reference + (`docs/reference/gateway/certificate-profiles.json`, which only lists the pinned + DV/OV names — a subset check, so the V2 profiles do not break it) and additionally + verifies that every profile the run registered, including the V2 set, exists. + The reference JSON files are historical captures and are intentionally not edited. + ## Authentication Three ways to authenticate, resolved per side (gateway vs Command) in this order: @@ -126,7 +156,7 @@ product to a certificate profile so enrollment can resolve a CA. Two things bite export GATEWAY_LOGICAL_NAME=CertiNext # the live CA's LogicalName export CERTINEXT_SIGNER_PLACE=Gateway export PRODUCT_CODE_MAP_JSON='{"DV SSL":"842","OV SSL":"846", ...}' -make register-ca-config +make register-ca-config # V2_TEMPLATES=0 for the pinned set only ``` ## Stage 06 — Command EnrollmentPatterns schema (verified 2026-06-09) diff --git a/scripts/v2/README.md b/scripts/v2/README.md new file mode 100644 index 0000000..ca3cdcf --- /dev/null +++ b/scripts/v2/README.md @@ -0,0 +1,110 @@ +# scripts/v2 — CERTInext V2 REST API dev helpers + +Small curl + jq scripts for poking the CERTInext V2 API (`/api/certinext/v2/...`) by hand. +They are dev tooling only and are not shipped with the plugin. For repeatable live-API +verification, use `CERTInext.IntegrationTests` / `CERTInext.IntegrationRunner` instead +(see `CLAUDE.md`). + +## Auth and credentials + +The scripts use the same auth model as the plugin's V2 mode +(`CERTInextClient.GetOrRefreshV2TokenAsync`): + +``` +POST {CERTINEXT_API_URL}/oauth/token (application/x-www-form-urlencoded) +grant_type=client_credentials&client_id=...&client_secret=... +``` + +`CERTINEXT_API_URL` is the single V2 base URL, e.g. `https://sandbox-us.certinext.io` +(no `/emSignHub-API` suffix). The old `CERTINEXT_V2_API_URL` variable and the V1 SHA256 +`authKey` token exchange are gone. + +Credentials are read from `~/.env_certinext_v2`, the same file the V2 integration tests +use. Set `CERTINEXT_V2_ENV_FILE=/path/to/file` to use a different file. + +| Key | Required | Used by | +|-----|----------|---------| +| `CERTINEXT_API_URL` | yes | all | +| `CERTINEXT_CLIENT_ID` | yes | all | +| `CERTINEXT_CLIENT_SECRET` | yes | all | +| `CERTINEXT_REQUESTOR_EMAIL` | order-create only | `create-ssl-order`, `create-private-pki-order` | +| `CERTINEXT_REQUESTOR_NAME`, `CERTINEXT_REQUESTOR_MOBILE` | no (defaults) | order-create, `accept-agreement` | +| `CERTINEXT_SIGNER_IP` | no (auto-detected via api.ipify.org) | `create-ssl-order`, `accept-agreement` | + +How the file is read (see `scripts/lib/certinext-v2-auth.sh`): + +- The file is parsed as `KEY=VALUE` lines, never `source`d. It can't run code, and nothing + from it leaks into your shell. Blank lines and `#` comments are skipped, and one pair of + surrounding `"` or `'` quotes is stripped from each value. +- A value in the file wins over a same-named exported env var, the same way + `V2EnvHelper.LoadEnvFile` works. A shell that sourced the V1 `~/.env_certinext` exports + a V1 `CERTINEXT_API_URL`, and that must not leak in. Exported env vars only fill in keys + the file doesn't define. +- A missing required key fails fast and names the key and file. +- `CERTINEXT_API_URL` must be `https://`. Plain `http://` is accepted only for + `localhost` / `127.0.0.1` stubs. A URL containing `/emSignHub-API` is rejected as a V1 URL. + +Secret handling: the client secret and the bearer token are held only in unexported shell +variables. They reach curl through process substitution (`/dev/fd` pipes), so they never +show up in `ps` output, on disk, or on stdout/stderr. On a failed token request, the scripts +print only the HTTP status and the short OAuth2 `error` code, never the response body. +Don't run these scripts with `set -x` / `bash -x`. + +Requires `bash`, `curl` (7.55+ for `-H @file`), and `jq`. + +## Read-only scripts + +These run immediately and send only GET requests (plus the token request). + +| Script | Inputs | Endpoint | +|--------|--------|----------| +| `ping.sh` | — | `GET /auth/me` | +| `list-products.sh` | — | `GET /catalog/products` | +| `get-custom-fields.sh` | `PRODUCT_CODE` | `GET /catalog/products/{code}/custom-fields` | +| `list-groups.sh` | — | `GET /groups` | +| `list-organizations.sh` | — | `GET /organizations` | +| `list-domains.sh` | — | `GET /domains` | +| `orders-report.sh` | `[PAGE=1] [SIZE=100]` | `GET /reports/orders` (1-based paging) | +| `track-order.sh` | `ORDER_ID` | `GET /ssl-certificates/{id}` | +| `get-dcv.sh` | `ORDER_ID`, `DOMAIN` | `GET /ssl-certificates/{id}/dcv?domain=` | +| `download-certificate.sh` | `ORDER_ID` | `GET /ssl-certificates/{id}/certificate` | +| `track-private-pki.sh` | `ORDER_ID` | `GET /private-pki-certificates/{id}` | +| `download-certificate-private-pki.sh` | `ORDER_ID` | `GET /private-pki-certificates/{id}/certificate` | + +## Mutating scripts (`--yes-mutate` required) + +These scripts change state on the CERTInext account, and some of them are irreversible or +cost money. Without `--yes-mutate`, a script prints the request it would send (method, URL, +JSON body) and exits with status 3. The preview makes no network calls: it doesn't fetch a +token or look up the signer IP. + +| Script | Effect | Inputs | +|--------|--------|--------| +| `create-ssl-order.sh` | places an SSL order | `PRODUCT_CODE`, `DOMAIN`, `[VARIANT=dv]` | +| `create-private-pki-order.sh` | places a Private PKI order | `PRODUCT_CODE`, `CERT_HOSTNAME`, `CA_PROFILE_ID`, `MASTER_PRODUCT_ID` | +| `verify-dcv.sh` | asks the CA to check DCV, which can advance the order | `ORDER_ID`, `DOMAIN`, `[METHOD=http-url]` | +| `submit-csr.sh` | attaches a CSR to an SSL order, which advances it | `ORDER_ID`, `CSR_FILE` | +| `submit-csr-private-pki.sh` | attaches a CSR, and the customer CA signs immediately | `ORDER_ID`, `CSR_FILE` | +| `accept-agreement.sh` | accepts the Subscriber Agreement, and the CA issues | `ORDER_ID` | +| `cancel-ssl-order.sh` | cancels an unissued SSL order | `ORDER_ID` | +| `revoke-ssl.sh` | revokes an issued SSL certificate (irreversible) | `ORDER_ID`, `[REASON=superseded]` | +| `revoke-private-pki.sh` | revokes a Private PKI certificate (irreversible) | `ORDER_ID`, `[REASON=superseded]` | + +`create-private-pki-order.sh` takes `CERT_HOSTNAME`, not `HOSTNAME`. Bash always sets +`HOSTNAME` to the local machine name, so the old input silently fell back to this +workstation's hostname. + +## Examples + +```bash +scripts/v2/ping.sh +ORDER_ID=1234567890 scripts/v2/track-order.sh + +# Preview only (prints the request and exits 3): +ORDER_ID=1234567890 scripts/v2/revoke-ssl.sh +# Actually revoke: +ORDER_ID=1234567890 scripts/v2/revoke-ssl.sh --yes-mutate + +# Via make: mutating targets forward V2_ARGS to the script. +make v2-revoke-ssl ORDER_ID=1234567890 V2_ARGS=--yes-mutate +``` diff --git a/scripts/v2/accept-agreement.sh b/scripts/v2/accept-agreement.sh index ebf7320..753f8be 100755 --- a/scripts/v2/accept-agreement.sh +++ b/scripts/v2/accept-agreement.sh @@ -1,30 +1,32 @@ #!/usr/bin/env bash # V2 ssl-certificates/{orderId}/agreement — record Subscriber Agreement acceptance. +# MUTATING: the CA proceeds to issue the certificate. Refuses to run and prints the +# planned request unless --yes-mutate is passed. # Required env var: ORDER_ID +# Env-file keys: CERTINEXT_REQUESTOR_NAME, CERTINEXT_SIGNER_IP (else api.ipify.org lookup) # -# 204 No Content = recorded; the CA proceeds to issue the certificate. -# After this step poll v2-track-order until status=issued, then v2-download-certificate. +# 204 No Content = recorded. Then poll track-order.sh until status=issued, and run +# download-certificate.sh. +# Credentials: see scripts/v2/README.md. set -euo pipefail -. ~/.env_certinext +# shellcheck source=scripts/lib/certinext-v2-auth.sh . "$(dirname "$0")/../lib/certinext-v2-auth.sh" +v2_usage() { echo "Usage: ORDER_ID= scripts/v2/accept-agreement.sh [--yes-mutate]" >&2; } +v2_parse_mutating_args "$@" ORDER_ID="${ORDER_ID:-}" +v2_require_id ORDER_ID -if [ -z "$ORDER_ID" ]; then - echo "Usage: ORDER_ID= scripts/v2/accept-agreement.sh" >&2 - exit 1 -fi +name=$(v2_cfg CERTINEXT_REQUESTOR_NAME "Keyfactor Gateway Test") -name="${CERTINEXT_REQUESTOR_NAME:-Keyfactor Gateway Test}" -signerIp="${CERTINEXT_SIGNER_IP:-}" -if [ -z "$signerIp" ]; then signerIp=$(curl -s https://api.ipify.org); fi +build_body() { + jq -n --arg name "$name" --arg ip "$1" \ + '{agreement:{signerName:$name,signerIp:$ip,signerPlace:"Gateway",accepted:true}}' +} -echo "V2 POST /api/certinext/v2/ssl-certificates/$ORDER_ID/agreement signerName=$name signerIp=$signerIp" -curl -s -X POST "$CERTINEXT_V2_API_URL/api/certinext/v2/ssl-certificates/$ORDER_ID/agreement" \ - -H "Authorization: Bearer $CERTINEXT_V2_TOKEN" \ - -H "Content-Type: application/json" \ - -d "$(jq -n \ - --arg name "$name" \ - --arg ip "$signerIp" \ - '{agreement:{signerName:$name,signerIp:$ip,signerPlace:"Gateway",accepted:true}}')" \ -| jq . +path="/api/certinext/v2/ssl-certificates/$ORDER_ID/agreement" +v2_mutation_gate POST "$path" "$(build_body "$(v2_signer_ip --offline)")" + +body=$(build_body "$(v2_signer_ip)") +echo "V2 POST $path signerName=$name" >&2 +v2_request POST "$path" -H "Content-Type: application/json" --data-binary "$body" diff --git a/scripts/v2/cancel-ssl-order.sh b/scripts/v2/cancel-ssl-order.sh index 09d3a49..bf358a3 100755 --- a/scripts/v2/cancel-ssl-order.sh +++ b/scripts/v2/cancel-ssl-order.sh @@ -1,24 +1,23 @@ #!/usr/bin/env bash -# V2 ssl-certificates/{orderId}/cancel — withdraw an SSL order before issuance. +# V2 ssl-certificates/{orderId}/cancel — CANCEL an SSL order before issuance. MUTATING. +# Refuses to run and prints the planned request unless --yes-mutate is passed. # Required env var: ORDER_ID # -# Use this before the certificate is issued. -# Once issued, use v2-revoke-ssl instead. -# 204 No Content = cancelled; order remains visible via v2-track-order with status=cancelled. +# Once issued, use revoke-ssl.sh instead. +# 204 No Content = cancelled; order remains visible via track-order with status=cancelled. +# Credentials: see scripts/v2/README.md. set -euo pipefail -. ~/.env_certinext +# shellcheck source=scripts/lib/certinext-v2-auth.sh . "$(dirname "$0")/../lib/certinext-v2-auth.sh" +v2_usage() { echo "Usage: ORDER_ID= scripts/v2/cancel-ssl-order.sh [--yes-mutate]" >&2; } +v2_parse_mutating_args "$@" ORDER_ID="${ORDER_ID:-}" +v2_require_id ORDER_ID -if [ -z "$ORDER_ID" ]; then - echo "Usage: ORDER_ID= scripts/v2/cancel-ssl-order.sh" >&2 - exit 1 -fi +path="/api/certinext/v2/ssl-certificates/$ORDER_ID/cancel" +body='{"reason":"No longer required"}' +v2_mutation_gate POST "$path" "$body" -echo "V2 POST /api/certinext/v2/ssl-certificates/$ORDER_ID/cancel" -curl -s -X POST "$CERTINEXT_V2_API_URL/api/certinext/v2/ssl-certificates/$ORDER_ID/cancel" \ - -H "Authorization: Bearer $CERTINEXT_V2_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"reason":"No longer required"}' \ -| jq . +echo "V2 POST $path" >&2 +v2_request POST "$path" -H "Content-Type: application/json" --data-binary "$body" diff --git a/scripts/v2/create-private-pki-order.sh b/scripts/v2/create-private-pki-order.sh index e4fe86a..521fb1e 100755 --- a/scripts/v2/create-private-pki-order.sh +++ b/scripts/v2/create-private-pki-order.sh @@ -1,36 +1,38 @@ #!/usr/bin/env bash -# V2 private-pki-certificates — create a Private PKI certificate order. -# Required env vars: PRODUCT_CODE, HOSTNAME, CA_PROFILE_ID, MASTER_PRODUCT_ID +# V2 private-pki-certificates — PLACE a Private PKI certificate order. MUTATING. +# Refuses to run and prints the planned request unless --yes-mutate is passed. +# Required env vars: PRODUCT_CODE, CERT_HOSTNAME, CA_PROFILE_ID, MASTER_PRODUCT_ID +# (CERT_HOSTNAME, not HOSTNAME: bash always sets HOSTNAME to the local machine name, +# so the old HOSTNAME input silently ordered a certificate for this workstation.) +# Env-file keys: CERTINEXT_REQUESTOR_EMAIL (required), CERTINEXT_REQUESTOR_NAME, +# CERTINEXT_REQUESTOR_MOBILE # -# On success prints the orderId prominently. -# Use orderId with v2-track-private-pki, v2-submit-csr-private-pki, -# v2-download-certificate-private-pki, and v2-revoke-private-pki. +# On success prints the orderId. Use it with track-private-pki, submit-csr-private-pki, +# download-certificate-private-pki, and revoke-private-pki. +# Credentials: see scripts/v2/README.md. set -euo pipefail -. ~/.env_certinext +# shellcheck source=scripts/lib/certinext-v2-auth.sh . "$(dirname "$0")/../lib/certinext-v2-auth.sh" +v2_usage() { echo "Usage: PRODUCT_CODE= CERT_HOSTNAME= CA_PROFILE_ID= MASTER_PRODUCT_ID= scripts/v2/create-private-pki-order.sh [--yes-mutate]" >&2; } +v2_parse_mutating_args "$@" PRODUCT_CODE="${PRODUCT_CODE:-}" -HOSTNAME="${HOSTNAME:-}" +CERT_HOSTNAME="${CERT_HOSTNAME:-}" CA_PROFILE_ID="${CA_PROFILE_ID:-}" MASTER_PRODUCT_ID="${MASTER_PRODUCT_ID:-}" +v2_require_var PRODUCT_CODE +v2_require_var CERT_HOSTNAME +v2_require_var CA_PROFILE_ID +v2_require_var MASTER_PRODUCT_ID -if [ -z "$PRODUCT_CODE" ] || [ -z "$HOSTNAME" ] || [ -z "$CA_PROFILE_ID" ] || [ -z "$MASTER_PRODUCT_ID" ]; then - echo "Usage: PRODUCT_CODE= HOSTNAME= CA_PROFILE_ID= MASTER_PRODUCT_ID= scripts/v2/create-private-pki-order.sh" >&2 - exit 1 -fi +name=$(v2_cfg CERTINEXT_REQUESTOR_NAME "Keyfactor Gateway Test") +email=$(v2_require CERTINEXT_REQUESTOR_EMAIL) +phone=$(v2_cfg CERTINEXT_REQUESTOR_MOBILE "$(v2_cfg CERTINEXT_REQUESTOR_PHONE "+10000000000")") -idempotency_key=$(python3 -c "import uuid; print(uuid.uuid4())") - -name="${CERTINEXT_REQUESTOR_NAME:-Keyfactor Gateway Test}" -email="${CERTINEXT_REQUESTOR_EMAIL}" -phone="${CERTINEXT_REQUESTOR_PHONE:-+10000000000}" - -echo "V2 POST /api/certinext/v2/private-pki-certificates productCode=$PRODUCT_CODE hostname=$HOSTNAME caProfileId=$CA_PROFILE_ID masterProductId=$MASTER_PRODUCT_ID idempotencyKey=$idempotency_key" - -result=$(jq -n \ +body=$(jq -n \ --arg caProfileId "$CA_PROFILE_ID" \ --arg masterProductId "$MASTER_PRODUCT_ID" \ - --arg hostname "$HOSTNAME" \ + --arg hostname "$CERT_HOSTNAME" \ --arg name "$name" \ --arg email "$email" \ --arg phone "$phone" \ @@ -41,17 +43,22 @@ result=$(jq -n \ additionalHosts:[], emailNotifications:"all", subscription:{validityYears:1}, - requestor:{name:$name,email:$email,phone:$phone,designation:"IT Administrator"}}' \ - | curl -s -X POST "$CERTINEXT_V2_API_URL/api/certinext/v2/private-pki-certificates" \ - -H "Authorization: Bearer $CERTINEXT_V2_TOKEN" \ - -H "Content-Type: application/json" \ - -H "X-Product-Code: $PRODUCT_CODE" \ - -H "Idempotency-Key: $idempotency_key" \ - -d @-) + requestor:{name:$name,email:$email,phone:$phone,designation:"IT Administrator"}}') + +path="/api/certinext/v2/private-pki-certificates" +v2_mutation_gate POST "$path (X-Product-Code: $PRODUCT_CODE)" "$body" + +idempotency_key=$(v2_uuid) +echo "V2 POST $path productCode=$PRODUCT_CODE hostname=$CERT_HOSTNAME caProfileId=$CA_PROFILE_ID masterProductId=$MASTER_PRODUCT_ID idempotencyKey=$idempotency_key" >&2 +rc=0 +result=$(v2_request POST "$path" \ + -H "Content-Type: application/json" \ + -H "X-Product-Code: $PRODUCT_CODE" \ + -H "Idempotency-Key: $idempotency_key" \ + --data-binary "$body") || rc=$? -echo "" echo "==> Full response:" -echo "$result" | jq . -echo "" -echo "==> orderId (use with v2-track-private-pki, v2-submit-csr-private-pki, etc.):" -echo "$result" | jq -r '.orderId // .detail // .title // "none"' +printf '%s\n' "$result" +echo "==> orderId (use with track-private-pki, submit-csr-private-pki, etc.):" +printf '%s' "$result" | jq -r '.orderId // .detail // .title // "none"' 2>/dev/null || echo "none" +exit "$rc" diff --git a/scripts/v2/create-ssl-order.sh b/scripts/v2/create-ssl-order.sh index 785c3c0..1be9f9b 100755 --- a/scripts/v2/create-ssl-order.sh +++ b/scripts/v2/create-ssl-order.sh @@ -1,59 +1,63 @@ #!/usr/bin/env bash -# V2 ssl-certificates — create a new SSL/TLS certificate order. +# V2 ssl-certificates — PLACE a new SSL/TLS certificate order. MUTATING (may incur cost). +# Refuses to run and prints the planned request unless --yes-mutate is passed. # Required env vars: PRODUCT_CODE, DOMAIN # Optional env vars: VARIANT (default dv) +# Env-file keys: CERTINEXT_REQUESTOR_EMAIL (required), CERTINEXT_REQUESTOR_NAME, +# CERTINEXT_REQUESTOR_MOBILE, CERTINEXT_SIGNER_IP (else api.ipify.org lookup) # -# On success prints the orderId prominently. -# Use orderId with v2-get-dcv, v2-verify-dcv, v2-submit-csr, v2-accept-agreement, -# v2-download-certificate, v2-revoke-ssl, and v2-cancel-ssl-order. +# On success prints the orderId. Use it with track-order, get-dcv, verify-dcv, +# submit-csr, accept-agreement, download-certificate, revoke-ssl, cancel-ssl-order. +# Credentials: see scripts/v2/README.md. set -euo pipefail -. ~/.env_certinext +# shellcheck source=scripts/lib/certinext-v2-auth.sh . "$(dirname "$0")/../lib/certinext-v2-auth.sh" +v2_usage() { echo "Usage: PRODUCT_CODE= DOMAIN= [VARIANT=dv] scripts/v2/create-ssl-order.sh [--yes-mutate]" >&2; } +v2_parse_mutating_args "$@" PRODUCT_CODE="${PRODUCT_CODE:-}" DOMAIN="${DOMAIN:-}" VARIANT="${VARIANT:-dv}" +v2_require_var PRODUCT_CODE +v2_require_var DOMAIN + +name=$(v2_cfg CERTINEXT_REQUESTOR_NAME "Keyfactor Gateway Test") +email=$(v2_require CERTINEXT_REQUESTOR_EMAIL) +phone=$(v2_cfg CERTINEXT_REQUESTOR_MOBILE "$(v2_cfg CERTINEXT_REQUESTOR_PHONE "+10000000000")") + +build_body() { + jq -n \ + --arg variant "$VARIANT" \ + --arg domain "$DOMAIN" \ + --arg name "$name" \ + --arg email "$email" \ + --arg phone "$phone" \ + --arg signerIp "$1" \ + '{productVariant:$variant, + emailNotifications:"all", + requestor:{name:$name,email:$email,phone:$phone,designation:"IT Administrator"}, + certificate:{domain:$domain,autoSecureWww:true}, + subscription:{validityYears:1,autoRenew:false,renewBeforeDays:30}, + agreement:{signerName:$name,signerIp:$signerIp,signerPlace:"Gateway",accepted:true}, + remarks:"Issued via Keyfactor Command AnyCA REST Gateway."}' +} + +path="/api/certinext/v2/ssl-certificates" +v2_mutation_gate POST "$path (X-Product-Code: $PRODUCT_CODE)" "$(build_body "$(v2_signer_ip --offline)")" + +body=$(build_body "$(v2_signer_ip)") +idempotency_key=$(v2_uuid) + +echo "V2 POST $path productCode=$PRODUCT_CODE domain=$DOMAIN variant=$VARIANT idempotencyKey=$idempotency_key" >&2 +rc=0 +result=$(v2_request POST "$path" \ + -H "Content-Type: application/json" \ + -H "X-Product-Code: $PRODUCT_CODE" \ + -H "Idempotency-Key: $idempotency_key" \ + --data-binary "$body") || rc=$? -if [ -z "$PRODUCT_CODE" ] || [ -z "$DOMAIN" ]; then - echo "Usage: PRODUCT_CODE= DOMAIN= [VARIANT=dv] scripts/v2/create-ssl-order.sh" >&2 - exit 1 -fi - -idempotency_key=$(python3 -c "import uuid; print(uuid.uuid4())") - -name="${CERTINEXT_REQUESTOR_NAME:-Keyfactor Gateway Test}" -email="${CERTINEXT_REQUESTOR_EMAIL}" -phone="${CERTINEXT_REQUESTOR_PHONE:-+10000000000}" - -signerIp="${CERTINEXT_SIGNER_IP:-}" -if [ -z "$signerIp" ]; then signerIp=$(curl -s https://api.ipify.org); fi - -echo "V2 POST /api/certinext/v2/ssl-certificates productCode=$PRODUCT_CODE domain=$DOMAIN variant=$VARIANT idempotencyKey=$idempotency_key" - -result=$(jq -n \ - --arg variant "$VARIANT" \ - --arg domain "$DOMAIN" \ - --arg name "$name" \ - --arg email "$email" \ - --arg phone "$phone" \ - --arg signerIp "$signerIp" \ - '{productVariant:$variant, - emailNotifications:"all", - requestor:{name:$name,email:$email,phone:$phone,designation:"IT Administrator"}, - certificate:{domain:$domain,autoSecureWww:true}, - subscription:{validityYears:1,autoRenew:false,renewBeforeDays:30}, - agreement:{signerName:$name,signerIp:$signerIp,signerPlace:"Gateway",accepted:true}, - remarks:"Issued via Keyfactor Command AnyCA REST Gateway."}' \ - | curl -s -X POST "$CERTINEXT_V2_API_URL/api/certinext/v2/ssl-certificates" \ - -H "Authorization: Bearer $CERTINEXT_V2_TOKEN" \ - -H "Content-Type: application/json" \ - -H "X-Product-Code: $PRODUCT_CODE" \ - -H "Idempotency-Key: $idempotency_key" \ - -d @-) - -echo "" echo "==> Full response:" -echo "$result" | jq . -echo "" -echo "==> orderId (use with v2-track-order, v2-get-dcv, etc.):" -echo "$result" | jq -r '.orderId // .detail // .title // "none"' +printf '%s\n' "$result" +echo "==> orderId (use with track-order, get-dcv, etc.):" +printf '%s' "$result" | jq -r '.orderId // .detail // .title // "none"' 2>/dev/null || echo "none" +exit "$rc" diff --git a/scripts/v2/download-certificate-private-pki.sh b/scripts/v2/download-certificate-private-pki.sh index ad1945f..39b7a24 100755 --- a/scripts/v2/download-certificate-private-pki.sh +++ b/scripts/v2/download-certificate-private-pki.sh @@ -1,22 +1,19 @@ #!/usr/bin/env bash -# V2 private-pki-certificates/{orderId}/certificate — download issued Private PKI certificate. +# V2 private-pki-certificates/{orderId}/certificate — download issued Private PKI +# certificate. Read-only. # Required env var: ORDER_ID # # Returns JSON with certificatePem, serialNumber, subject, issuer, notBefore, notAfter. # Returns 422 if the order is not yet in issued state. +# Credentials: see scripts/v2/README.md. set -euo pipefail -. ~/.env_certinext +# shellcheck source=scripts/lib/certinext-v2-auth.sh . "$(dirname "$0")/../lib/certinext-v2-auth.sh" +v2_usage() { echo "Usage: ORDER_ID= scripts/v2/download-certificate-private-pki.sh" >&2; } +v2_parse_args "$@" ORDER_ID="${ORDER_ID:-}" +v2_require_id ORDER_ID -if [ -z "$ORDER_ID" ]; then - echo "Usage: ORDER_ID= scripts/v2/download-certificate-private-pki.sh" >&2 - exit 1 -fi - -echo "V2 GET /api/certinext/v2/private-pki-certificates/$ORDER_ID/certificate" -curl -s -X GET "$CERTINEXT_V2_API_URL/api/certinext/v2/private-pki-certificates/$ORDER_ID/certificate" \ - -H "Authorization: Bearer $CERTINEXT_V2_TOKEN" \ - -H "Accept: application/json" \ -| jq . +echo "V2 GET /api/certinext/v2/private-pki-certificates/$ORDER_ID/certificate" >&2 +v2_request GET "/api/certinext/v2/private-pki-certificates/$ORDER_ID/certificate" diff --git a/scripts/v2/download-certificate.sh b/scripts/v2/download-certificate.sh index 3da275e..4426b72 100755 --- a/scripts/v2/download-certificate.sh +++ b/scripts/v2/download-certificate.sh @@ -1,22 +1,18 @@ #!/usr/bin/env bash -# V2 ssl-certificates/{orderId}/certificate — download issued SSL certificate. +# V2 ssl-certificates/{orderId}/certificate — download issued SSL certificate. Read-only. # Required env var: ORDER_ID # # Returns JSON with certificatePem, serialNumber, subject, issuer, notBefore, notAfter. # Returns 422 if the order is not yet in issued state. +# Credentials: see scripts/v2/README.md. set -euo pipefail -. ~/.env_certinext +# shellcheck source=scripts/lib/certinext-v2-auth.sh . "$(dirname "$0")/../lib/certinext-v2-auth.sh" +v2_usage() { echo "Usage: ORDER_ID= scripts/v2/download-certificate.sh" >&2; } +v2_parse_args "$@" ORDER_ID="${ORDER_ID:-}" +v2_require_id ORDER_ID -if [ -z "$ORDER_ID" ]; then - echo "Usage: ORDER_ID= scripts/v2/download-certificate.sh" >&2 - exit 1 -fi - -echo "V2 GET /api/certinext/v2/ssl-certificates/$ORDER_ID/certificate" -curl -s -X GET "$CERTINEXT_V2_API_URL/api/certinext/v2/ssl-certificates/$ORDER_ID/certificate" \ - -H "Authorization: Bearer $CERTINEXT_V2_TOKEN" \ - -H "Accept: application/json" \ -| jq . +echo "V2 GET /api/certinext/v2/ssl-certificates/$ORDER_ID/certificate" >&2 +v2_request GET "/api/certinext/v2/ssl-certificates/$ORDER_ID/certificate" diff --git a/scripts/v2/get-custom-fields.sh b/scripts/v2/get-custom-fields.sh index b266293..729c79d 100755 --- a/scripts/v2/get-custom-fields.sh +++ b/scripts/v2/get-custom-fields.sh @@ -1,19 +1,16 @@ #!/usr/bin/env bash -# V2 catalog/products/{code}/custom-fields — mandatory + optional custom fields for a product. +# V2 catalog/products/{code}/custom-fields — mandatory + optional custom fields for a +# product. Read-only. # Required env var: PRODUCT_CODE +# Credentials: see scripts/v2/README.md. set -euo pipefail -. ~/.env_certinext +# shellcheck source=scripts/lib/certinext-v2-auth.sh . "$(dirname "$0")/../lib/certinext-v2-auth.sh" +v2_usage() { echo "Usage: PRODUCT_CODE= scripts/v2/get-custom-fields.sh" >&2; } +v2_parse_args "$@" PRODUCT_CODE="${PRODUCT_CODE:-}" +v2_require_id PRODUCT_CODE -if [ -z "$PRODUCT_CODE" ]; then - echo "Usage: PRODUCT_CODE= scripts/v2/get-custom-fields.sh" >&2 - exit 1 -fi - -echo "V2 GET /api/certinext/v2/catalog/products/$PRODUCT_CODE/custom-fields" -curl -s -X GET "$CERTINEXT_V2_API_URL/api/certinext/v2/catalog/products/$PRODUCT_CODE/custom-fields" \ - -H "Authorization: Bearer $CERTINEXT_V2_TOKEN" \ - -H "Accept: application/json" \ -| jq . +echo "V2 GET /api/certinext/v2/catalog/products/$PRODUCT_CODE/custom-fields" >&2 +v2_request GET "/api/certinext/v2/catalog/products/$PRODUCT_CODE/custom-fields" diff --git a/scripts/v2/get-dcv.sh b/scripts/v2/get-dcv.sh index a91d057..37d85f9 100755 --- a/scripts/v2/get-dcv.sh +++ b/scripts/v2/get-dcv.sh @@ -1,23 +1,21 @@ #!/usr/bin/env bash -# V2 ssl-certificates/{orderId}/dcv — get DCV challenge artifacts for a domain. +# V2 ssl-certificates/{orderId}/dcv — get DCV challenge artifacts for a domain. Read-only. # Required env vars: ORDER_ID, DOMAIN # # Returns http-url, dns-txt, and email challenge methods. -# Publish the artifact for your chosen method, then call v2-verify-dcv. +# Publish the artifact for your chosen method, then run verify-dcv.sh --yes-mutate. +# Credentials: see scripts/v2/README.md. set -euo pipefail -. ~/.env_certinext +# shellcheck source=scripts/lib/certinext-v2-auth.sh . "$(dirname "$0")/../lib/certinext-v2-auth.sh" +v2_usage() { echo "Usage: ORDER_ID= DOMAIN= scripts/v2/get-dcv.sh" >&2; } +v2_parse_args "$@" ORDER_ID="${ORDER_ID:-}" DOMAIN="${DOMAIN:-}" +v2_require_id ORDER_ID +v2_require_var DOMAIN -if [ -z "$ORDER_ID" ] || [ -z "$DOMAIN" ]; then - echo "Usage: ORDER_ID= DOMAIN= scripts/v2/get-dcv.sh" >&2 - exit 1 -fi - -echo "V2 GET /api/certinext/v2/ssl-certificates/$ORDER_ID/dcv?domain=$DOMAIN" -curl -s -X GET "$CERTINEXT_V2_API_URL/api/certinext/v2/ssl-certificates/$ORDER_ID/dcv?domain=$DOMAIN" \ - -H "Authorization: Bearer $CERTINEXT_V2_TOKEN" \ - -H "Accept: application/json" \ -| jq . +echo "V2 GET /api/certinext/v2/ssl-certificates/$ORDER_ID/dcv?domain=$DOMAIN" >&2 +v2_request GET "/api/certinext/v2/ssl-certificates/$ORDER_ID/dcv" \ + -G --data-urlencode "domain=$DOMAIN" diff --git a/scripts/v2/list-domains.sh b/scripts/v2/list-domains.sh index 0909d32..b53e612 100755 --- a/scripts/v2/list-domains.sh +++ b/scripts/v2/list-domains.sh @@ -1,12 +1,12 @@ #!/usr/bin/env bash -# V2 domains — list domains already pre-validated under this account. +# V2 domains — list domains already pre-validated under this account. Read-only. # DCV does not need to be repeated for domains in this list. +# Credentials: see scripts/v2/README.md. set -euo pipefail -. ~/.env_certinext +# shellcheck source=scripts/lib/certinext-v2-auth.sh . "$(dirname "$0")/../lib/certinext-v2-auth.sh" +v2_usage() { echo "Usage: scripts/v2/list-domains.sh" >&2; } +v2_parse_args "$@" -echo "V2 GET /api/certinext/v2/domains" -curl -s -X GET "$CERTINEXT_V2_API_URL/api/certinext/v2/domains" \ - -H "Authorization: Bearer $CERTINEXT_V2_TOKEN" \ - -H "Accept: application/json" \ -| jq . +echo "V2 GET /api/certinext/v2/domains" >&2 +v2_request GET "/api/certinext/v2/domains" diff --git a/scripts/v2/list-groups.sh b/scripts/v2/list-groups.sh index 5708490..8436e32 100755 --- a/scripts/v2/list-groups.sh +++ b/scripts/v2/list-groups.sh @@ -1,12 +1,12 @@ #!/usr/bin/env bash -# V2 groups — list billing groups accessible to this account. +# V2 groups — list billing groups accessible to this account. Read-only. # Use a groupNumber from here in order bodies to charge a specific cost centre. +# Credentials: see scripts/v2/README.md. set -euo pipefail -. ~/.env_certinext +# shellcheck source=scripts/lib/certinext-v2-auth.sh . "$(dirname "$0")/../lib/certinext-v2-auth.sh" +v2_usage() { echo "Usage: scripts/v2/list-groups.sh" >&2; } +v2_parse_args "$@" -echo "V2 GET /api/certinext/v2/groups" -curl -s -X GET "$CERTINEXT_V2_API_URL/api/certinext/v2/groups" \ - -H "Authorization: Bearer $CERTINEXT_V2_TOKEN" \ - -H "Accept: application/json" \ -| jq . +echo "V2 GET /api/certinext/v2/groups" >&2 +v2_request GET "/api/certinext/v2/groups" diff --git a/scripts/v2/list-organizations.sh b/scripts/v2/list-organizations.sh index 7fc559a..0c56630 100755 --- a/scripts/v2/list-organizations.sh +++ b/scripts/v2/list-organizations.sh @@ -1,12 +1,12 @@ #!/usr/bin/env bash -# V2 organizations — list pre-vetted organizations available for OV/EV SSL. +# V2 organizations — list pre-vetted organizations available for OV/EV SSL. Read-only. # Reference an organizationNumber in order bodies to skip re-vetting. +# Credentials: see scripts/v2/README.md. set -euo pipefail -. ~/.env_certinext +# shellcheck source=scripts/lib/certinext-v2-auth.sh . "$(dirname "$0")/../lib/certinext-v2-auth.sh" +v2_usage() { echo "Usage: scripts/v2/list-organizations.sh" >&2; } +v2_parse_args "$@" -echo "V2 GET /api/certinext/v2/organizations" -curl -s -X GET "$CERTINEXT_V2_API_URL/api/certinext/v2/organizations" \ - -H "Authorization: Bearer $CERTINEXT_V2_TOKEN" \ - -H "Accept: application/json" \ -| jq . +echo "V2 GET /api/certinext/v2/organizations" >&2 +v2_request GET "/api/certinext/v2/organizations" diff --git a/scripts/v2/list-products.sh b/scripts/v2/list-products.sh index ef0aba0..7cc82fe 100755 --- a/scripts/v2/list-products.sh +++ b/scripts/v2/list-products.sh @@ -1,12 +1,12 @@ #!/usr/bin/env bash -# V2 catalog/products — list all products the account can order. +# V2 catalog/products — list all products the account can order. Read-only. # Each entry has a stable productCode used in the X-Product-Code header. +# Credentials: see scripts/v2/README.md. set -euo pipefail -. ~/.env_certinext +# shellcheck source=scripts/lib/certinext-v2-auth.sh . "$(dirname "$0")/../lib/certinext-v2-auth.sh" +v2_usage() { echo "Usage: scripts/v2/list-products.sh" >&2; } +v2_parse_args "$@" -echo "V2 GET /api/certinext/v2/catalog/products" -curl -s -X GET "$CERTINEXT_V2_API_URL/api/certinext/v2/catalog/products" \ - -H "Authorization: Bearer $CERTINEXT_V2_TOKEN" \ - -H "Accept: application/json" \ -| jq . +echo "V2 GET /api/certinext/v2/catalog/products" >&2 +v2_request GET "/api/certinext/v2/catalog/products" diff --git a/scripts/v2/orders-report.sh b/scripts/v2/orders-report.sh index 178b263..3fb8ea0 100755 --- a/scripts/v2/orders-report.sh +++ b/scripts/v2/orders-report.sh @@ -1,14 +1,20 @@ #!/usr/bin/env bash -# V2 reports/orders — paginated order history. -# NOTE: currently returns 501 Not Implemented. -# Use v1 make get-order-report (POST /emSignHub-API/GetOrderReport) meanwhile. +# V2 reports/orders — one page of order history. Read-only. +# This is the endpoint the plugin's V2 Synchronize pages through. +# Optional env vars: PAGE (default 1; paging is 1-based, page=0 is treated as 1), +# SIZE (default 100; the server clamps to 100) +# Credentials: see scripts/v2/README.md. set -euo pipefail -. ~/.env_certinext +# shellcheck source=scripts/lib/certinext-v2-auth.sh . "$(dirname "$0")/../lib/certinext-v2-auth.sh" +v2_usage() { echo "Usage: [PAGE=1] [SIZE=100] scripts/v2/orders-report.sh" >&2; } +v2_parse_args "$@" -echo "V2 GET /api/certinext/v2/reports/orders?page=0&size=50" -echo "NOTE: this endpoint currently returns 501 Not Implemented — use v1 make get-order-report as a fallback." -curl -s -X GET "$CERTINEXT_V2_API_URL/api/certinext/v2/reports/orders?page=0&size=50" \ - -H "Authorization: Bearer $CERTINEXT_V2_TOKEN" \ - -H "Accept: application/json" \ -| jq . +PAGE="${PAGE:-1}" +SIZE="${SIZE:-100}" +case "$PAGE$SIZE" in + *[!0-9]*) echo "ERROR: PAGE and SIZE must be non-negative integers." >&2; exit 1 ;; +esac + +echo "V2 GET /api/certinext/v2/reports/orders?page=$PAGE&size=$SIZE" >&2 +v2_request GET "/api/certinext/v2/reports/orders?page=$PAGE&size=$SIZE" diff --git a/scripts/v2/ping.sh b/scripts/v2/ping.sh index 3a1886f..578bc05 100755 --- a/scripts/v2/ping.sh +++ b/scripts/v2/ping.sh @@ -1,12 +1,12 @@ #!/usr/bin/env bash # V2 auth/me — returns the account context the Bearer token resolves to. -# Mirrors ICERTInextClient.PingAsync via the V2 API. +# Mirrors ICERTInextClient.PingAsync via the V2 API. Read-only. +# Credentials: see scripts/v2/README.md. set -euo pipefail -. ~/.env_certinext +# shellcheck source=scripts/lib/certinext-v2-auth.sh . "$(dirname "$0")/../lib/certinext-v2-auth.sh" +v2_usage() { echo "Usage: scripts/v2/ping.sh" >&2; } +v2_parse_args "$@" -echo "V2 GET /api/certinext/v2/auth/me" -curl -s -X GET "$CERTINEXT_V2_API_URL/api/certinext/v2/auth/me" \ - -H "Authorization: Bearer $CERTINEXT_V2_TOKEN" \ - -H "Accept: application/json" \ -| jq . +echo "V2 GET /api/certinext/v2/auth/me" >&2 +v2_request GET "/api/certinext/v2/auth/me" diff --git a/scripts/v2/revoke-private-pki.sh b/scripts/v2/revoke-private-pki.sh index c3e15f9..71d4b8c 100755 --- a/scripts/v2/revoke-private-pki.sh +++ b/scripts/v2/revoke-private-pki.sh @@ -1,5 +1,7 @@ #!/usr/bin/env bash -# V2 private-pki-certificates/{orderId}/revoke — permanently revoke an issued Private PKI certificate. +# V2 private-pki-certificates/{orderId}/revoke — permanently REVOKE an issued Private PKI +# certificate. MUTATING and irreversible. Refuses to run and prints the planned request +# unless --yes-mutate is passed. # Required env var: ORDER_ID # Optional env var: REASON (default superseded) # @@ -8,24 +10,24 @@ # # 204 No Content = revocation recorded on the customer CA. # 422 = order not yet issued, or already revoked. +# Credentials: see scripts/v2/README.md. set -euo pipefail -. ~/.env_certinext +# shellcheck source=scripts/lib/certinext-v2-auth.sh . "$(dirname "$0")/../lib/certinext-v2-auth.sh" +v2_usage() { echo "Usage: ORDER_ID= [REASON=superseded] scripts/v2/revoke-private-pki.sh [--yes-mutate]" >&2; } +v2_parse_mutating_args "$@" ORDER_ID="${ORDER_ID:-}" REASON="${REASON:-superseded}" +v2_require_id ORDER_ID -if [ -z "$ORDER_ID" ]; then - echo "Usage: ORDER_ID= [REASON=superseded] scripts/v2/revoke-private-pki.sh" >&2 - exit 1 -fi +path="/api/certinext/v2/private-pki-certificates/$ORDER_ID/revoke" +body=$(jq -n --arg reason "$REASON" '{reason:$reason,note:"Revoked via scripts/v2 dev helper."}') +v2_mutation_gate POST "$path" "$body" -idempotency_key=$(python3 -c "import uuid; print(uuid.uuid4())") - -echo "V2 POST /api/certinext/v2/private-pki-certificates/$ORDER_ID/revoke reason=$REASON idempotencyKey=$idempotency_key" -curl -s -X POST "$CERTINEXT_V2_API_URL/api/certinext/v2/private-pki-certificates/$ORDER_ID/revoke" \ - -H "Authorization: Bearer $CERTINEXT_V2_TOKEN" \ - -H "Content-Type: application/json" \ - -H "Idempotency-Key: $idempotency_key" \ - -d "$(jq -n --arg reason "$REASON" '{reason:$reason,note:"Revoked via Makefile smoke test."}')" \ -| jq . +idempotency_key=$(v2_uuid) +echo "V2 POST $path reason=$REASON idempotencyKey=$idempotency_key" >&2 +v2_request POST "$path" \ + -H "Content-Type: application/json" \ + -H "Idempotency-Key: $idempotency_key" \ + --data-binary "$body" diff --git a/scripts/v2/revoke-ssl.sh b/scripts/v2/revoke-ssl.sh index 0cc6d28..fb76912 100755 --- a/scripts/v2/revoke-ssl.sh +++ b/scripts/v2/revoke-ssl.sh @@ -1,5 +1,7 @@ #!/usr/bin/env bash -# V2 ssl-certificates/{orderId}/revoke — permanently revoke an issued SSL certificate. +# V2 ssl-certificates/{orderId}/revoke — permanently REVOKE an issued SSL certificate. +# MUTATING and irreversible. Refuses to run and prints the planned request unless +# --yes-mutate is passed. # Required env var: ORDER_ID # Optional env var: REASON (default superseded) # @@ -8,24 +10,24 @@ # # 204 No Content = revocation queued; CRL/OCSP reflect this on next publish. # 422 = order not yet issued, or already revoked. +# Credentials: see scripts/v2/README.md. set -euo pipefail -. ~/.env_certinext +# shellcheck source=scripts/lib/certinext-v2-auth.sh . "$(dirname "$0")/../lib/certinext-v2-auth.sh" +v2_usage() { echo "Usage: ORDER_ID= [REASON=superseded] scripts/v2/revoke-ssl.sh [--yes-mutate]" >&2; } +v2_parse_mutating_args "$@" ORDER_ID="${ORDER_ID:-}" REASON="${REASON:-superseded}" +v2_require_id ORDER_ID -if [ -z "$ORDER_ID" ]; then - echo "Usage: ORDER_ID= [REASON=superseded] scripts/v2/revoke-ssl.sh" >&2 - exit 1 -fi +path="/api/certinext/v2/ssl-certificates/$ORDER_ID/revoke" +body=$(jq -n --arg reason "$REASON" '{reason:$reason,note:"Revoked via scripts/v2 dev helper."}') +v2_mutation_gate POST "$path" "$body" -idempotency_key=$(python3 -c "import uuid; print(uuid.uuid4())") - -echo "V2 POST /api/certinext/v2/ssl-certificates/$ORDER_ID/revoke reason=$REASON idempotencyKey=$idempotency_key" -curl -s -X POST "$CERTINEXT_V2_API_URL/api/certinext/v2/ssl-certificates/$ORDER_ID/revoke" \ - -H "Authorization: Bearer $CERTINEXT_V2_TOKEN" \ - -H "Content-Type: application/json" \ - -H "Idempotency-Key: $idempotency_key" \ - -d "$(jq -n --arg reason "$REASON" '{reason:$reason,note:"Revoked via Makefile smoke test."}')" \ -| jq . +idempotency_key=$(v2_uuid) +echo "V2 POST $path reason=$REASON idempotencyKey=$idempotency_key" >&2 +v2_request POST "$path" \ + -H "Content-Type: application/json" \ + -H "Idempotency-Key: $idempotency_key" \ + --data-binary "$body" diff --git a/scripts/v2/submit-csr-private-pki.sh b/scripts/v2/submit-csr-private-pki.sh index 09abf20..da056f3 100755 --- a/scripts/v2/submit-csr-private-pki.sh +++ b/scripts/v2/submit-csr-private-pki.sh @@ -1,29 +1,29 @@ #!/usr/bin/env bash # V2 private-pki-certificates/{orderId}/csr — attach a PEM CSR to a Private PKI order. +# MUTATING: the customer CA signs immediately after CSR submission. Refuses to run and +# prints the planned request unless --yes-mutate is passed. # Required env vars: ORDER_ID, CSR_FILE (path to PEM file) # -# The customer CA signs immediately after CSR submission. # 204 No Content = CSR accepted. +# Credentials: see scripts/v2/README.md. set -euo pipefail -. ~/.env_certinext +# shellcheck source=scripts/lib/certinext-v2-auth.sh . "$(dirname "$0")/../lib/certinext-v2-auth.sh" +v2_usage() { echo "Usage: ORDER_ID= CSR_FILE= scripts/v2/submit-csr-private-pki.sh [--yes-mutate]" >&2; } +v2_parse_mutating_args "$@" ORDER_ID="${ORDER_ID:-}" CSR_FILE="${CSR_FILE:-}" - -if [ -z "$ORDER_ID" ] || [ -z "$CSR_FILE" ]; then - echo "Usage: ORDER_ID= CSR_FILE= scripts/v2/submit-csr-private-pki.sh" >&2 - exit 1 -fi - +v2_require_id ORDER_ID +v2_require_var CSR_FILE if [ ! -f "$CSR_FILE" ]; then - echo "CSR_FILE '$CSR_FILE' not found" >&2 + echo "ERROR: CSR_FILE '$CSR_FILE' not found" >&2 exit 1 fi -echo "V2 PUT /api/certinext/v2/private-pki-certificates/$ORDER_ID/csr csrFile=$CSR_FILE" -curl -s -X PUT "$CERTINEXT_V2_API_URL/api/certinext/v2/private-pki-certificates/$ORDER_ID/csr" \ - -H "Authorization: Bearer $CERTINEXT_V2_TOKEN" \ - -H "Content-Type: application/json" \ - -d "$(jq -n --rawfile csr "$CSR_FILE" '{csr:$csr,attested:false}')" \ -| jq . +path="/api/certinext/v2/private-pki-certificates/$ORDER_ID/csr" +body=$(jq -n --rawfile csr "$CSR_FILE" '{csr:$csr,attested:false}') +v2_mutation_gate PUT "$path" "$body" + +echo "V2 PUT $path csrFile=$CSR_FILE" >&2 +v2_request PUT "$path" -H "Content-Type: application/json" --data-binary "$body" diff --git a/scripts/v2/submit-csr.sh b/scripts/v2/submit-csr.sh index 9ba2725..66bc84f 100755 --- a/scripts/v2/submit-csr.sh +++ b/scripts/v2/submit-csr.sh @@ -1,28 +1,29 @@ #!/usr/bin/env bash -# V2 ssl-certificates/{orderId}/csr — attach a PEM CSR to an SSL order. +# V2 ssl-certificates/{orderId}/csr — attach a PEM CSR to an SSL order. MUTATING +# (advances the order). Refuses to run and prints the planned request unless +# --yes-mutate is passed. # Required env vars: ORDER_ID, CSR_FILE (path to PEM file) # # 204 No Content = CSR accepted; order advances to pending-agreement. +# Credentials: see scripts/v2/README.md. set -euo pipefail -. ~/.env_certinext +# shellcheck source=scripts/lib/certinext-v2-auth.sh . "$(dirname "$0")/../lib/certinext-v2-auth.sh" +v2_usage() { echo "Usage: ORDER_ID= CSR_FILE= scripts/v2/submit-csr.sh [--yes-mutate]" >&2; } +v2_parse_mutating_args "$@" ORDER_ID="${ORDER_ID:-}" CSR_FILE="${CSR_FILE:-}" - -if [ -z "$ORDER_ID" ] || [ -z "$CSR_FILE" ]; then - echo "Usage: ORDER_ID= CSR_FILE= scripts/v2/submit-csr.sh" >&2 - exit 1 -fi - +v2_require_id ORDER_ID +v2_require_var CSR_FILE if [ ! -f "$CSR_FILE" ]; then - echo "CSR_FILE '$CSR_FILE' not found" >&2 + echo "ERROR: CSR_FILE '$CSR_FILE' not found" >&2 exit 1 fi -echo "V2 PUT /api/certinext/v2/ssl-certificates/$ORDER_ID/csr csrFile=$CSR_FILE" -curl -s -X PUT "$CERTINEXT_V2_API_URL/api/certinext/v2/ssl-certificates/$ORDER_ID/csr" \ - -H "Authorization: Bearer $CERTINEXT_V2_TOKEN" \ - -H "Content-Type: application/json" \ - -d "$(jq -n --rawfile csr "$CSR_FILE" '{csr:$csr,attested:false}')" \ -| jq . +path="/api/certinext/v2/ssl-certificates/$ORDER_ID/csr" +body=$(jq -n --rawfile csr "$CSR_FILE" '{csr:$csr,attested:false}') +v2_mutation_gate PUT "$path" "$body" + +echo "V2 PUT $path csrFile=$CSR_FILE" >&2 +v2_request PUT "$path" -H "Content-Type: application/json" --data-binary "$body" diff --git a/scripts/v2/track-order.sh b/scripts/v2/track-order.sh index 18e1628..9b99514 100755 --- a/scripts/v2/track-order.sh +++ b/scripts/v2/track-order.sh @@ -1,22 +1,18 @@ #!/usr/bin/env bash -# V2 ssl-certificates/{orderId} — fetch current state of an SSL order. +# V2 ssl-certificates/{orderId} — fetch current state of an SSL order. Read-only. # Required env var: ORDER_ID # # Status values: pending-dcv -> pending-csr -> pending-agreement -> issued # (or cancelled / revoked) +# Credentials: see scripts/v2/README.md. set -euo pipefail -. ~/.env_certinext +# shellcheck source=scripts/lib/certinext-v2-auth.sh . "$(dirname "$0")/../lib/certinext-v2-auth.sh" +v2_usage() { echo "Usage: ORDER_ID= scripts/v2/track-order.sh" >&2; } +v2_parse_args "$@" ORDER_ID="${ORDER_ID:-}" +v2_require_id ORDER_ID -if [ -z "$ORDER_ID" ]; then - echo "Usage: ORDER_ID= scripts/v2/track-order.sh" >&2 - exit 1 -fi - -echo "V2 GET /api/certinext/v2/ssl-certificates/$ORDER_ID" -curl -s -X GET "$CERTINEXT_V2_API_URL/api/certinext/v2/ssl-certificates/$ORDER_ID" \ - -H "Authorization: Bearer $CERTINEXT_V2_TOKEN" \ - -H "Accept: application/json" \ -| jq . +echo "V2 GET /api/certinext/v2/ssl-certificates/$ORDER_ID" >&2 +v2_request GET "/api/certinext/v2/ssl-certificates/$ORDER_ID" diff --git a/scripts/v2/track-private-pki.sh b/scripts/v2/track-private-pki.sh index 9fb2d38..9c65351 100755 --- a/scripts/v2/track-private-pki.sh +++ b/scripts/v2/track-private-pki.sh @@ -1,22 +1,19 @@ #!/usr/bin/env bash # V2 private-pki-certificates/{orderId} — fetch current state of a Private PKI order. +# Read-only. # Required env var: ORDER_ID # # Status values: pending-csr -> issued (or cancelled / revoked). # Private PKI orders skip vetting because the CA is customer-owned. +# Credentials: see scripts/v2/README.md. set -euo pipefail -. ~/.env_certinext +# shellcheck source=scripts/lib/certinext-v2-auth.sh . "$(dirname "$0")/../lib/certinext-v2-auth.sh" +v2_usage() { echo "Usage: ORDER_ID= scripts/v2/track-private-pki.sh" >&2; } +v2_parse_args "$@" ORDER_ID="${ORDER_ID:-}" +v2_require_id ORDER_ID -if [ -z "$ORDER_ID" ]; then - echo "Usage: ORDER_ID= scripts/v2/track-private-pki.sh" >&2 - exit 1 -fi - -echo "V2 GET /api/certinext/v2/private-pki-certificates/$ORDER_ID" -curl -s -X GET "$CERTINEXT_V2_API_URL/api/certinext/v2/private-pki-certificates/$ORDER_ID" \ - -H "Authorization: Bearer $CERTINEXT_V2_TOKEN" \ - -H "Accept: application/json" \ -| jq . +echo "V2 GET /api/certinext/v2/private-pki-certificates/$ORDER_ID" >&2 +v2_request GET "/api/certinext/v2/private-pki-certificates/$ORDER_ID" diff --git a/scripts/v2/verify-dcv.sh b/scripts/v2/verify-dcv.sh index 9b769e1..e41c7e6 100755 --- a/scripts/v2/verify-dcv.sh +++ b/scripts/v2/verify-dcv.sh @@ -1,26 +1,28 @@ #!/usr/bin/env bash # V2 ssl-certificates/{orderId}/dcv/verify — ask the CA to re-check a DCV artifact. +# MUTATING (can advance the order). Refuses to run and prints the planned request unless +# --yes-mutate is passed. # Required env vars: ORDER_ID, DOMAIN # Optional env var: METHOD (default http-url; also: dns-txt, email) # # 204 No Content = DCV passed; order advances to pending-csr. # 422 = CA could not find the artifact; check file path or DNS propagation. +# Credentials: see scripts/v2/README.md. set -euo pipefail -. ~/.env_certinext +# shellcheck source=scripts/lib/certinext-v2-auth.sh . "$(dirname "$0")/../lib/certinext-v2-auth.sh" +v2_usage() { echo "Usage: ORDER_ID= DOMAIN= [METHOD=http-url] scripts/v2/verify-dcv.sh [--yes-mutate]" >&2; } +v2_parse_mutating_args "$@" ORDER_ID="${ORDER_ID:-}" DOMAIN="${DOMAIN:-}" METHOD="${METHOD:-http-url}" +v2_require_id ORDER_ID +v2_require_var DOMAIN -if [ -z "$ORDER_ID" ] || [ -z "$DOMAIN" ]; then - echo "Usage: ORDER_ID= DOMAIN= [METHOD=http-url] scripts/v2/verify-dcv.sh" >&2 - exit 1 -fi +path="/api/certinext/v2/ssl-certificates/$ORDER_ID/dcv/verify" +body=$(jq -n --arg domain "$DOMAIN" --arg method "$METHOD" '{domain:$domain,method:$method}') +v2_mutation_gate POST "$path" "$body" -echo "V2 POST /api/certinext/v2/ssl-certificates/$ORDER_ID/dcv/verify domain=$DOMAIN method=$METHOD" -curl -s -X POST "$CERTINEXT_V2_API_URL/api/certinext/v2/ssl-certificates/$ORDER_ID/dcv/verify" \ - -H "Authorization: Bearer $CERTINEXT_V2_TOKEN" \ - -H "Content-Type: application/json" \ - -d "$(jq -n --arg domain "$DOMAIN" --arg method "$METHOD" '{domain:$domain,method:$method}')" \ -| jq . +echo "V2 POST $path domain=$DOMAIN method=$METHOD" >&2 +v2_request POST "$path" -H "Content-Type: application/json" --data-binary "$body"