From 2f4376e9edf31c217a5d531842654ab7b2a207f6 Mon Sep 17 00:00:00 2001 From: spbsoluble <1661003+spbsoluble@users.noreply.github.com> Date: Fri, 20 Nov 2026 16:30:32 -0800 Subject: [PATCH] feat(v2): add Private PKI product names that set ProductFamily and ProductVariant GetProductIds() advertised SSL/TLS names only, so a Private PKI template had to pick an SSL name (for example DV SSL) and set ProductFamily=private-pki plus ProductVariant. Add "Private PKI Intranet SSL" and "Private PKI IGTF Host": selecting one defaults ProductFamily to private-pki and ProductVariant to intranet-ssl / igtf-host. A ProductFamily or ProductVariant that contradicts the product is rejected at template save and at enrollment, before any CA call. SSL products paired with ProductFamily=private-pki keep working. Enroll() required a product code on V2 too; that check is now V1-only (V2 needs no code, and the new names have no V1 default). The ProductFamily/ProductVariant annotations no longer declare "ssl"/"dv" defaults, since the plugin derives both from the product. Also corrects the GetProductIds() comment, which described numeric codes as required. --- CERTInext.Tests/CERTInextCAPluginTests.cs | 27 ++++- CERTInext.Tests/EnrollmentParamsTests.cs | 45 ++++++++ CERTInext.Tests/SyncProductIdTests.cs | 5 +- .../V2PrivatePkiEnrollmentTests.cs | 104 ++++++++++++++++++ CERTInext/CERTInextCAPlugin.cs | 32 +++++- CERTInext/CERTInextCAPluginConfig.cs | 25 +++-- CERTInext/Constants.cs | 18 +++ CERTInext/Models/EnrollmentParams.cs | 20 +++- CHANGELOG.md | 1 + README.md | 25 +++-- docsource/configuration.md | 19 ++-- integration-manifest.json | 10 +- 12 files changed, 284 insertions(+), 47 deletions(-) diff --git a/CERTInext.Tests/CERTInextCAPluginTests.cs b/CERTInext.Tests/CERTInextCAPluginTests.cs index 6b5f9e2..ca2b4aa 100644 --- a/CERTInext.Tests/CERTInextCAPluginTests.cs +++ b/CERTInext.Tests/CERTInextCAPluginTests.cs @@ -133,8 +133,10 @@ public void GetProductIds_ReturnsStaticProductList() ids.Should().Contain(Constants.Products.DvSsl); ids.Should().Contain(Constants.Products.OvSsl); ids.Should().Contain(Constants.Products.EvSsl); - // Ten products total (DV/OV/EV × single/wildcard/UCC variants) - ids.Should().HaveCount(10); + ids.Should().Contain(Constants.Products.PrivatePkiIntranetSsl); + ids.Should().Contain(Constants.Products.PrivatePkiIgtfHost); + // Ten SSL products (DV/OV/EV × single/wildcard/UCC variants) plus the two V2 Private PKI products + ids.Should().HaveCount(12); mock.VerifyNoOtherCalls(); } @@ -794,6 +796,27 @@ await act.Should().ThrowAsync() .WithMessage("*ProfileId*required*"); } + [Theory] + [InlineData(Constants.Products.PrivatePkiIntranetSsl)] + [InlineData(Constants.Products.PrivatePkiIgtfHost)] + public async Task Enroll_V1_PrivatePkiProduct_WithoutProductCode_Throws(string productId) + { + // The Private PKI products have no V1 default code, so a V1 template must set ProductCode. + var mock = NewMock(); + var plugin = BuildPlugin(mock.Object); + + Func act = () => plugin.Enroll( + csr: MockCertificateData.FakeCsrPem, + subject: "CN=test.example.com", + san: null, + productInfo: new EnrollmentProductInfo { ProductID = productId, ProductParameters = new Dictionary() }, + requestFormat: RequestFormat.PKCS10, + enrollmentType: EnrollmentType.New); + + await act.Should().ThrowAsync().WithMessage("*ProfileId*required*"); + mock.Invocations.Should().BeEmpty(); + } + [Fact] public async Task Enroll_New_ThreadsTemplateSignerParamsOntoRequest() { diff --git a/CERTInext.Tests/EnrollmentParamsTests.cs b/CERTInext.Tests/EnrollmentParamsTests.cs index 9fa52e9..13b86f5 100644 --- a/CERTInext.Tests/EnrollmentParamsTests.cs +++ b/CERTInext.Tests/EnrollmentParamsTests.cs @@ -98,5 +98,50 @@ public void HasExplicitProductVariant_DistinguishesUnsetFromExplicit(string conf ep.HasExplicitProductVariant.Should().Be(expectedExplicit); ep.ProductVariant.Should().Be(expectedVariant, "the ProductVariant getter's own default is unchanged"); } + + // A Private PKI product sets the family and variant defaults; SSL products keep ssl/dv. + [Theory] + [InlineData(Constants.Products.PrivatePkiIntranetSsl, Constants.ApiV2.FamilyPrivatePki, "intranet-ssl", true)] + [InlineData(Constants.Products.PrivatePkiIgtfHost, Constants.ApiV2.FamilyPrivatePki, "igtf-host", true)] + [InlineData("private pki intranet ssl", Constants.ApiV2.FamilyPrivatePki, "intranet-ssl", true)] + [InlineData(Constants.Products.OvSsl, Constants.ApiV2.FamilySsl, "dv", false)] + [InlineData("", Constants.ApiV2.FamilySsl, "dv", false)] + public void ProductFamilyAndVariantDefaults_FollowTheProduct( + string productId, string expectedFamilySlug, string expectedVariant, bool expectedPrivatePki) + { + var ep = new EnrollmentParams(MakeProductInfo(productId)); + + ep.IsPrivatePkiProduct.Should().Be(expectedPrivatePki); + ep.ProductFamilySlug.Should().Be(expectedFamilySlug); + ep.ProductVariant.Should().Be(expectedVariant); + ep.HasExplicitProductVariant.Should().BeFalse(); + } + + [Fact] + public void ExplicitFamilyAndVariant_OverrideThePrivatePkiProductDefaults() + { + var ep = new EnrollmentParams(MakeProductInfo(Constants.Products.PrivatePkiIntranetSsl, new Dictionary + { + [Constants.EnrollmentParam.ProductFamily] = "ssl", + [Constants.EnrollmentParam.ProductVariant] = "igtf-host" + })); + + ep.ProductFamilySlug.Should().Be(Constants.ApiV2.FamilySsl); + ep.ProductVariant.Should().Be("igtf-host"); + } + + [Fact] + public void ResolveSslProductVariant_RejectsAPrivatePkiProduct() + { + var ep = new EnrollmentParams(MakeProductInfo(Constants.Products.PrivatePkiIgtfHost, new Dictionary + { + [Constants.EnrollmentParam.ProductFamily] = "ssl" + })); + + string error = CERTInextCAPlugin.ResolveSslProductVariant(ep, out string resolved); + + error.Should().Contain("Private PKI product").And.Contain("'ssl'"); + resolved.Should().BeNull(); + } } } diff --git a/CERTInext.Tests/SyncProductIdTests.cs b/CERTInext.Tests/SyncProductIdTests.cs index d0a04f6..0a3d1d0 100644 --- a/CERTInext.Tests/SyncProductIdTests.cs +++ b/CERTInext.Tests/SyncProductIdTests.cs @@ -77,11 +77,14 @@ public void ProductNameForTypeId_MapsPluginProductTypes(string typeId, string ex } [Fact] - public void EveryAdvertisedProductHasATypeId_AndMapsBackToItself() + public void EveryAdvertisedSslProductHasATypeId_AndMapsBackToItself() { + // The Private PKI products have no known catalog productTypeID, so sync can't name them. var plugin = new CERTInextCAPlugin(); foreach (string name in plugin.GetProductIds()) { + if (Constants.Products.PrivatePkiVariantsV2.ContainsKey(name)) + continue; Constants.Products.ProductTypeIdsV2.Should().ContainKey(name); CERTInextCAPlugin.ProductNameForTypeId(Constants.Products.ProductTypeIdsV2[name]).Should().Be(name); Constants.Products.SslComProductTypeIdsV2.Should().ContainKey(name); diff --git a/CERTInext.Tests/V2PrivatePkiEnrollmentTests.cs b/CERTInext.Tests/V2PrivatePkiEnrollmentTests.cs index 6604b05..93c7a52 100644 --- a/CERTInext.Tests/V2PrivatePkiEnrollmentTests.cs +++ b/CERTInext.Tests/V2PrivatePkiEnrollmentTests.cs @@ -620,5 +620,109 @@ public void ValidatePrivatePkiEnrollmentParams_UnsetVariant_SaysNotSetRatherThan error.Should().Contain("not set"); normalized.Should().BeNull(); } + + // --------------------------------------------------------------------------- + // Private PKI product names: the product sets ProductFamily and ProductVariant + // --------------------------------------------------------------------------- + + private static EnrollmentProductInfo MakePrivatePkiNamedProductInfo( + string productId, string family = null, string variant = null) + { + var parameters = new Dictionary(StringComparer.OrdinalIgnoreCase) + { + ["DomainName"] = Hostname + }; + if (family != null) parameters["ProductFamily"] = family; + if (variant != null) parameters["ProductVariant"] = variant; + return new EnrollmentProductInfo { ProductID = productId, ProductParameters = parameters }; + } + + [Theory] + [InlineData(Constants.Products.PrivatePkiIntranetSsl, "intranet-ssl")] + [InlineData(Constants.Products.PrivatePkiIgtfHost, "igtf-host")] + public async Task Enroll_V2_PrivatePkiProduct_PlacesPrivatePkiOrder_WithNoFamilyOrVariantParams( + string productId, string expectedVariant) + { + var mock = NewMock(); + var captured = StubPrivatePkiOrder(mock); + + var result = await EnrollAsync(BuildV2Plugin(mock.Object), MakePrivatePkiNamedProductInfo(productId), + new Dictionary { ["dnsname"] = new[] { Hostname } }); + + result.CARequestID.Should().Be(OrderId); + captured().Should().NotBeNull("the product name alone must route the order to the Private PKI endpoint"); + captured().Variant.Should().Be(expectedVariant); + mock.Verify(c => c.PlaceOrderV2Async( + It.IsAny(), It.IsAny(), It.IsAny(), It.IsAny()), + Times.Never); + } + + [Fact] + public async Task Enroll_V2_PrivatePkiProduct_MatchingExplicitParams_StillPlacesOrder() + { + var mock = NewMock(); + var captured = StubPrivatePkiOrder(mock); + + await EnrollAsync(BuildV2Plugin(mock.Object), + MakePrivatePkiNamedProductInfo(Constants.Products.PrivatePkiIgtfHost, family: "private-pki", variant: "IGTF-HOST"), + new Dictionary { ["dnsname"] = new[] { Hostname } }); + + captured().Variant.Should().Be("igtf-host"); + } + + [Fact] + public async Task Enroll_V2_PrivatePkiProduct_ContradictingVariant_FailsFastWithoutAnyCaCall() + { + var mock = NewMock(); + + var result = await EnrollAsync(BuildV2Plugin(mock.Object), + MakePrivatePkiNamedProductInfo(Constants.Products.PrivatePkiIntranetSsl, variant: "igtf-host"), + new Dictionary { ["dnsname"] = new[] { Hostname } }); + + result.Status.Should().Be((int)EndEntityStatus.FAILED); + result.StatusMessage.Should().Contain("ProductVariant").And.Contain("'intranet-ssl'"); + mock.Invocations.Should().BeEmpty("validation must happen before any CA call"); + } + + [Theory] + [InlineData("ssl")] + [InlineData("unknown-family")] // unrecognized families are treated as ssl + public async Task Enroll_V2_PrivatePkiProduct_NonPrivatePkiFamily_FailsFastWithoutAnyCaCall(string family) + { + var mock = NewMock(); + + var result = await EnrollAsync(BuildV2Plugin(mock.Object), + MakePrivatePkiNamedProductInfo(Constants.Products.PrivatePkiIntranetSsl, family: family), + new Dictionary { ["dnsname"] = new[] { Hostname } }); + + result.Status.Should().Be((int)EndEntityStatus.FAILED); + result.StatusMessage.Should().Contain("Private PKI product").And.Contain("ProductFamily"); + mock.Invocations.Should().BeEmpty("an SSL order must not be placed for a Private PKI product"); + } + + [Fact] + public async Task ValidateProductInfo_V2_PrivatePkiProduct_WithSslFamily_IsRejectedAtSave() + { + using var server = WireMockServer.Start(); + StubToken(server); + + Func act = () => BuildV2Plugin(NewMock().Object).ValidateProductInfo( + MakePrivatePkiNamedProductInfo(Constants.Products.PrivatePkiIgtfHost, family: "ssl"), + V2ConnectionInfo(server.Urls[0])); + + await act.Should().ThrowAsync().WithMessage("*Private PKI product*ProductFamily*"); + } + + [Fact] + public async Task ValidateProductInfo_V2_PrivatePkiProduct_WithNoParams_Succeeds() + { + using var server = WireMockServer.Start(); + StubToken(server); + + Func act = () => BuildV2Plugin(NewMock().Object).ValidateProductInfo( + MakePrivatePkiNamedProductInfo(Constants.Products.PrivatePkiIntranetSsl), V2ConnectionInfo(server.Urls[0])); + + await act.Should().NotThrowAsync(); + } } } diff --git a/CERTInext/CERTInextCAPlugin.cs b/CERTInext/CERTInextCAPlugin.cs index 6e089a2..1b3b1db 100644 --- a/CERTInext/CERTInextCAPlugin.cs +++ b/CERTInext/CERTInextCAPlugin.cs @@ -425,9 +425,10 @@ public List GetProductIds() // on GetProductDetailsAsync would risk deadlock in certain synchronization contexts. // 2. The Keyfactor integration-manifest doc tool requires a known list at reflection // time (a live API call at that point returned empty results). - // 3. CERTInext product names are stable; operators select the correct product and - // then provide the numeric ProductCode template parameter to map it to the actual - // CERTInext API code for their account (sandbox vs. production). + // 3. The names are the plugin's own, not CERTInext's. On V2 the name sets the variant + // (and, for the Private PKI names, the family), and CERTInext picks the product unless + // the template sets a ProductCode. On V1 the name maps to a default production code + // (DefaultProductCodes), which a template's ProductCode overrides. return new List { Constants.Products.DvSsl, @@ -440,6 +441,8 @@ public List GetProductIds() Constants.Products.OvSslWildcardUcc, Constants.Products.EvSsl, Constants.Products.EvSslUcc, + Constants.Products.PrivatePkiIntranetSsl, + Constants.Products.PrivatePkiIgtfHost, }; } @@ -1040,7 +1043,9 @@ public async Task Enroll( LogSanitizer.MaskEmail(LogSanitizer.Strip(ep.RequesterEmail))); } - if (string.IsNullOrWhiteSpace(ep.ProfileId)) + // V1 only: a V2 order needs no product code (CERTInext resolves it when the template sets none), + // and the Private PKI products have no V1 default code to fall back on. + if (!_config.UseV2Api && string.IsNullOrWhiteSpace(ep.ProfileId)) { _logger.LogError( "Enrollment rejected — ProfileId parameter is missing. Subject={Subject}, EnrollmentType={EnrollmentType}", @@ -1771,6 +1776,15 @@ internal static string ValidatePrivatePkiEnrollmentParams(EnrollmentParams ep, o $"{Constants.ApiV2.PrivatePkiVariantIgtfHost}. Current value: {configured}."; } + // A Private PKI product name fixes the variant; an explicit ProductVariant must agree with it. + if (Constants.Products.PrivatePkiVariantsV2.TryGetValue(ep.ProductId ?? string.Empty, out string productVariant) + && !string.Equals(variant, productVariant, StringComparison.OrdinalIgnoreCase)) + { + return $"Template parameter '{Constants.EnrollmentParam.ProductVariant}' is set to '{variant}', but " + + $"the selected product '{ep.ProductId}' is '{productVariant}'. Remove the override, or " + + $"select the product for '{variant}'."; + } + normalizedVariant = variant.ToLowerInvariant(); return null; } @@ -1800,6 +1814,16 @@ internal static string ValidatePrivatePkiEnrollmentParams(EnrollmentParams ep, o /// internal static string ResolveSslProductVariant(EnrollmentParams ep, out string resolvedVariant) { + // A Private PKI product only reaches the SSL path when the template sets ProductFamily + // to something other than private-pki; ordering it as SSL would buy the wrong product. + if (ep.IsPrivatePkiProduct) + { + resolvedVariant = null; + return $"The selected product '{ep.ProductId}' is a Private PKI product, but template parameter " + + $"'{Constants.EnrollmentParam.ProductFamily}' is set to '{ep.ProductFamily}'. Set it to " + + $"'private-pki' or remove it."; + } + bool hasMapping = Constants.Products.ProductVariantsV2.TryGetValue( ep.ProductId ?? string.Empty, out string derivedVariant); diff --git a/CERTInext/CERTInextCAPluginConfig.cs b/CERTInext/CERTInextCAPluginConfig.cs index d974561..3fd67c5 100644 --- a/CERTInext/CERTInextCAPluginConfig.cs +++ b/CERTInext/CERTInextCAPluginConfig.cs @@ -523,7 +523,8 @@ public static Dictionary GetTemplateParameterAnnotat [Constants.EnrollmentParam.ProductCode] = new PropertyConfigInfo { 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 V1, the default production code for the selected product is used (e.g. DV SSL → 838; " + + "the Private PKI products have none, so on V1 they need this set); " + "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 " + @@ -654,22 +655,24 @@ public static Dictionary GetTemplateParameterAnnotat [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.", + Comments = "V2 ONLY: Product family for this template. Accepted values: 'ssl' or 'private-pki'. " + + "If omitted, 'private-pki' for the Private PKI products and 'ssl' for the others; a " + + "Private PKI product with any other value fails enrollment. 'private-pki' with an SSL " + + "product requires a Private PKI ProductVariant. 'signature' (Document Signer) is " + + "accepted by the parameter, but Document Signer enrollment is not supported.", Hidden = false, - DefaultValue = "ssl", + DefaultValue = string.Empty, 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).", + Comments = "V2 ONLY: Product variant sent in the V2 order body. If omitted, derived from the " + + "selected product ('dv', 'ov' or 'ev' for SSL; 'intranet-ssl' or 'igtf-host' for the " + + "Private PKI products); an explicit value that contradicts the product fails enrollment. " + + "With ProductFamily 'private-pki' and an SSL product it is required: 'intranet-ssl' or " + + "'igtf-host'.", Hidden = false, - DefaultValue = "dv", + DefaultValue = string.Empty, Type = "String" }, [Constants.EnrollmentParam.OrgRepresentativeName] = new PropertyConfigInfo diff --git a/CERTInext/Constants.cs b/CERTInext/Constants.cs index 82387f1..5dc2bee 100644 --- a/CERTInext/Constants.cs +++ b/CERTInext/Constants.cs @@ -171,6 +171,24 @@ public static class Products public const string EvSsl = "EV SSL"; public const string EvSslUcc = "EV SSL Multi-Domain (UCC)"; + // V2-ONLY. Private PKI products. Selecting one sets the template's ProductFamily to + // private-pki and its ProductVariant to the mapped variant (see PrivatePkiVariantsV2), + // so the template needs neither parameter. They have no V1 default code and no catalog + // productTypeID, so on V1 they need an explicit ProductCode, and sync doesn't name them. + public const string PrivatePkiIntranetSsl = "Private PKI Intranet SSL"; + public const string PrivatePkiIgtfHost = "Private PKI IGTF Host"; + + // V2-ONLY. Private PKI product name -> the private-pki create body's variant value. + // Read by EnrollmentParams for the ProductFamily/ProductVariant defaults and by + // ValidatePrivatePkiEnrollmentParams / ResolveSslProductVariant to reject a template + // whose explicit ProductFamily or ProductVariant contradicts the product. + public static readonly System.Collections.Generic.Dictionary PrivatePkiVariantsV2 = + new System.Collections.Generic.Dictionary(System.StringComparer.OrdinalIgnoreCase) + { + [PrivatePkiIntranetSsl] = ApiV2.PrivatePkiVariantIntranetSsl, + [PrivatePkiIgtfHost] = ApiV2.PrivatePkiVariantIgtfHost, + }; + // 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 diff --git a/CERTInext/Models/EnrollmentParams.cs b/CERTInext/Models/EnrollmentParams.cs index d454932..c1a799c 100644 --- a/CERTInext/Models/EnrollmentParams.cs +++ b/CERTInext/Models/EnrollmentParams.cs @@ -128,10 +128,15 @@ private string GetExplicitProductCode() // ------------------------------------------------------------------ /// - /// V2 product family. Accepted values: "ssl" (default), "private-pki", "signature". - /// Used to select the correct V2 resource path. + /// V2 product family. Accepted values: "ssl", "private-pki", "signature". + /// Used to select the correct V2 resource path. Default: "private-pki" for a Private PKI + /// product (), else "ssl". /// - public string ProductFamily => GetString(Constants.EnrollmentParam.ProductFamily, "ssl"); + public string ProductFamily => GetString(Constants.EnrollmentParam.ProductFamily, + IsPrivatePkiProduct ? "private-pki" : "ssl"); + + /// True when is one of the Private PKI product names. + public bool IsPrivatePkiProduct => Constants.Products.PrivatePkiVariantsV2.ContainsKey(ProductId ?? string.Empty); /// /// V2 product family as the REST path slug used in V2 URL construction. @@ -150,10 +155,13 @@ private string GetExplicitProductCode() /// 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 - /// ). + /// Default: the mapped variant for a Private PKI product, else "dv" (SSL-only; + /// private-pki enrollment rejects it — see ). /// - public string ProductVariant => GetString(Constants.EnrollmentParam.ProductVariant, "dv"); + public string ProductVariant => GetString(Constants.EnrollmentParam.ProductVariant, + Constants.Products.PrivatePkiVariantsV2.TryGetValue(ProductId ?? string.Empty, out string pkiVariant) + ? pkiVariant + : "dv"); /// /// True when the ProductVariant template parameter is actually set (non-blank), as diff --git a/CHANGELOG.md b/CHANGELOG.md index e677ac2..593eb24 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,6 +3,7 @@ ## 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): New products `Private PKI Intranet SSL` and `Private PKI IGTF Host`. A template that selects one needs no `ProductFamily` or `ProductVariant`: the product sets them to `private-pki` and `intranet-ssl` or `igtf-host`. A `ProductFamily` or `ProductVariant` that contradicts the product fails when the template is saved and at enrollment. Templates that pair an SSL/TLS product with `ProductFamily=private-pki` keep working. On V1 these products have no default code, so a template that selects one must set `ProductCode`. - feat(v2): Multi-domain (UCC) and wildcard SSL/TLS enrollment, with extra SANs sent as `additionalDomains`. - feat(v2): New OV template parameters `OrgRepresentativeName`, `OrgRepresentativeEmail`, `OrgRepresentativePhone`, `OrgRepresentativeDesignation` and `OrgRepresentativeEmployeeId` register a new Organization Representative on a V2 OV order (`useNewOrgRepresentative`). CERTInext's rules (OV only, a pre-vetted organization, name and email together, a 6-15 digit phone) are checked when the template is saved and before any CA call. The response's `organizationRepresentativeStatus` (`applied` or `pending-approval`) is logged, and the representative's details are never logged. - 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. diff --git a/README.md b/README.md index da9784c..48d7046 100644 --- a/README.md +++ b/README.md @@ -259,7 +259,7 @@ The V2-only template parameters `ProductFamily` and `ProductVariant` are describ 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: 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). + * **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; the Private PKI products have none, so on V1 they need this set); 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 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. @@ -272,8 +272,8 @@ The V2-only template parameters `ProductFamily` and `ProductVariant` are describ * **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). + * **ProductFamily** - V2 ONLY: Product family for this template. Accepted values: 'ssl' or 'private-pki'. If omitted, 'private-pki' for the Private PKI products and 'ssl' for the others; a Private PKI product with any other value fails enrollment. 'private-pki' with an SSL product 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. If omitted, derived from the selected product ('dv', 'ov' or 'ev' for SSL; 'intranet-ssl' or 'igtf-host' for the Private PKI products); an explicit value that contradicts the product fails enrollment. With ProductFamily 'private-pki' and an SSL product it is required: 'intranet-ssl' or 'igtf-host'. * **OrgRepresentativeName** - V2 ONLY, OV only: Name of a new Organization Representative to register on the order. Set together with OrgRepresentativeEmail; both turn on useNewOrgRepresentative. Leave all OrgRepresentative* parameters blank to keep the organization's existing representative. Requires the connector's OrganizationNumber. Personal data: never logged. * **OrgRepresentativeEmail** - V2 ONLY, OV only: Email address of the new Organization Representative. Required with OrgRepresentativeName. An email that is already a representative of the organization is rejected by CERTInext (EMS-1317); leave these parameters blank to use the existing one. Personal data: never logged. * **OrgRepresentativePhone** - V2 ONLY, OV only, optional: Phone number of the new Organization Representative, 6-15 digits with an optional leading '+' and spaces, dashes, dots or parentheses. Needs OrgRepresentativeName and OrgRepresentativeEmail. Personal data: never logged. @@ -561,7 +561,7 @@ The product codes in this table are for: ### S/MIME and Document Signing -**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. +**Not supported by this plugin.** `GetProductIds` advertises SSL/TLS and Private PKI 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. @@ -616,10 +616,11 @@ 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`) | +| `ProductFamily` | Optional | String | CERTInext V2 product family: `ssl` or `private-pki` (see [V2 Private PKI Orders](#v2-private-pki-orders)). Default: `private-pki` for the Private PKI products, `ssl` for the others. | Derived from `ProductId` (for example `ssl`) | +| `ProductVariant` | Optional | String | Variant within the family. `ssl`: `dv`, `ov`, or `ev`. `private-pki`: `intranet-ssl` or `igtf-host`. | 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. +- **`ProductVariant` default:** when omitted, the plugin derives it from the selected product: an OV product sends `ov`, an EV product sends `ev`, `Private PKI Intranet SSL` sends `intranet-ssl`, and `Private PKI IGTF Host` sends `igtf-host`. An explicit value that contradicts the product fails enrollment. +- **`ProductFamily` default:** when omitted, `private-pki` for the two Private PKI products and `ssl` for the others. A Private PKI product with any other family 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. @@ -641,11 +642,13 @@ This differs from V1, where `DefaultProductCode` only affects renewals (see [Def ### 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: +For a template whose product is `Private PKI Intranet SSL` or `Private PKI IGTF Host`, or that sets `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. It isn't checked against the catalog; CERTInext rejects a code that isn't a Private PKI product on your account. -- **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`. +- **Which `ProductID` to pick.** Select `Private PKI Intranet SSL` or `Private PKI IGTF Host`. The product sets `ProductFamily` to `private-pki` and `ProductVariant` to `intranet-ssl` or `igtf-host`, so the template needs neither parameter. A `ProductFamily` or `ProductVariant` that contradicts the product fails enrollment. +- **Existing templates.** A template that pairs an SSL/TLS product (for example `DV SSL`) with `ProductFamily=private-pki` keeps working. It must set `ProductVariant` to `intranet-ssl` or `igtf-host`, and its SSL/TLS product name doesn't affect the order. +- **Product code is optional.** CERTInext resolves the Private PKI product from the variant. Set `ProductCode` to your account's Private PKI catalog code only to pick between several matching products. It isn't checked against the catalog; CERTInext rejects a code that isn't a Private PKI product on your account. +- **V2 only.** The Private PKI products have no V1 default code, so a V1 template that selects one must set `ProductCode`. +- **Sync.** Synced Private PKI orders aren't named after these products, so they don't get a template. - **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. diff --git a/docsource/configuration.md b/docsource/configuration.md index 8a5d1e1..dc1f490 100644 --- a/docsource/configuration.md +++ b/docsource/configuration.md @@ -416,7 +416,7 @@ The product codes in this table are for: ### S/MIME and Document Signing -**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. +**Not supported by this plugin.** `GetProductIds` advertises SSL/TLS and Private PKI 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. @@ -563,10 +563,11 @@ 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`) | +| `ProductFamily` | Optional | String | CERTInext V2 product family: `ssl` or `private-pki` (see [V2 Private PKI Orders](#v2-private-pki-orders)). Default: `private-pki` for the Private PKI products, `ssl` for the others. | Derived from `ProductId` (for example `ssl`) | +| `ProductVariant` | Optional | String | Variant within the family. `ssl`: `dv`, `ov`, or `ev`. `private-pki`: `intranet-ssl` or `igtf-host`. | 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. +- **`ProductVariant` default:** when omitted, the plugin derives it from the selected product: an OV product sends `ov`, an EV product sends `ev`, `Private PKI Intranet SSL` sends `intranet-ssl`, and `Private PKI IGTF Host` sends `igtf-host`. An explicit value that contradicts the product fails enrollment. +- **`ProductFamily` default:** when omitted, `private-pki` for the two Private PKI products and `ssl` for the others. A Private PKI product with any other family 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. @@ -588,11 +589,13 @@ This differs from V1, where `DefaultProductCode` only affects renewals (see [Def ### 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: +For a template whose product is `Private PKI Intranet SSL` or `Private PKI IGTF Host`, or that sets `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. It isn't checked against the catalog; CERTInext rejects a code that isn't a Private PKI product on your account. -- **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`. +- **Which `ProductID` to pick.** Select `Private PKI Intranet SSL` or `Private PKI IGTF Host`. The product sets `ProductFamily` to `private-pki` and `ProductVariant` to `intranet-ssl` or `igtf-host`, so the template needs neither parameter. A `ProductFamily` or `ProductVariant` that contradicts the product fails enrollment. +- **Existing templates.** A template that pairs an SSL/TLS product (for example `DV SSL`) with `ProductFamily=private-pki` keeps working. It must set `ProductVariant` to `intranet-ssl` or `igtf-host`, and its SSL/TLS product name doesn't affect the order. +- **Product code is optional.** CERTInext resolves the Private PKI product from the variant. Set `ProductCode` to your account's Private PKI catalog code only to pick between several matching products. It isn't checked against the catalog; CERTInext rejects a code that isn't a Private PKI product on your account. +- **V2 only.** The Private PKI products have no V1 default code, so a V1 template that selects one must set `ProductCode`. +- **Sync.** Synced Private PKI orders aren't named after these products, so they don't get a template. - **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. diff --git a/integration-manifest.json b/integration-manifest.json index 26ed7cf..7d97e0e 100644 --- a/integration-manifest.json +++ b/integration-manifest.json @@ -22,7 +22,9 @@ "OV SSL Multi-Domain (UCC)", "OV SSL Wildcard Multi-Domain (UCC)", "EV SSL", - "EV SSL Multi-Domain (UCC)" + "EV SSL Multi-Domain (UCC)", + "Private PKI Intranet SSL", + "Private PKI IGTF Host" ], "ca_plugin_config": [ { @@ -379,7 +381,7 @@ "enrollment_config": [ { "name": "ProductCode", - "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)." + "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; the Private PKI products have none, so on V1 they need this set); 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", @@ -431,11 +433,11 @@ }, { "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." + "description": "V2 ONLY: Product family for this template. Accepted values: 'ssl' or 'private-pki'. If omitted, 'private-pki' for the Private PKI products and 'ssl' for the others; a Private PKI product with any other value fails enrollment. 'private-pki' with an SSL product 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)." + "description": "V2 ONLY: Product variant sent in the V2 order body. If omitted, derived from the selected product ('dv', 'ov' or 'ev' for SSL; 'intranet-ssl' or 'igtf-host' for the Private PKI products); an explicit value that contradicts the product fails enrollment. With ProductFamily 'private-pki' and an SSL product it is required: 'intranet-ssl' or 'igtf-host'." }, { "name": "OrgRepresentativeName",