From 0711ce5ba49dba940aeb54b78a205a3054f47d85 Mon Sep 17 00:00:00 2001 From: Brian Hill <76450501+bhillkeyfactor@users.noreply.github.com> Date: Thu, 6 Nov 2025 19:37:17 -0500 Subject: [PATCH 01/34] Create integration-manifest.json --- integration-manifest.json | 42 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 integration-manifest.json diff --git a/integration-manifest.json b/integration-manifest.json new file mode 100644 index 0000000..de909b3 --- /dev/null +++ b/integration-manifest.json @@ -0,0 +1,42 @@ +{ + "$schema": "https://keyfactor.github.io/v2/integration-manifest-schema.json", + "integration_type": "anyca-plugin", + "name": "Idnomic PKI AnyCA Gateway Plugin", + "status": "pilot", + "support_level": "kf-supported", + "link_github": true, + "update_catalog": true, + "description": "Idnomic PKI (formerly OpenTrust PKI) plugin for the AnyCA Gateway framework. Provides certificate lifecycle management through SOAP-based integration with Idnomic PKI systems.", + "gateway_framework": "24.2.0", + "release_dir": "idnomic/bin/Release", + "release_project": "idnomic/idnomic.csproj", + "about": { + "carest": { + "ca_plugin_config": [ + { + "name": "EndpointAddress", + "description": "Full URL to the Idnomic RA connector SOAP endpoint. Example: https://idnomic-pki.example.com:8443/RA/connector.cgi" + }, + { + "name": "ClientCertLocation", + "description": "Full file path to the client certificate PFX file on the Gateway server. Example: C:\\Certificates\\gateway-client.pfx" + }, + { + "name": "ClientCertPassword", + "description": "Password for the client certificate PFX file. This certificate is used for mutual TLS authentication to the Idnomic PKI system." + }, + { + "name": "Enabled", + "description": "Flag to enable or disable gateway functionality. Disabling is primarily used to allow creation of the CA prior to configuration information being available. Default: true" + } + ], + "enrollment_config": [ + { + "name": "Zone", + "description": "REQUIRED: The Idnomic PKI zone where certificates will be issued. Must exactly match a zone configured in the Idnomic PKI system (case-sensitive). Example: Production" + } + ], + "product_ids": [] + } + } +} From 80833dcfff1237bfbfb6d58432bffbc6bb42bb67 Mon Sep 17 00:00:00 2001 From: Brian Hill <76450501+bhillkeyfactor@users.noreply.github.com> Date: Thu, 6 Nov 2025 19:48:51 -0500 Subject: [PATCH 02/34] Create CHANGELOG.md --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1 @@ + From d36ee5c7f4808395762c37bffd3c70fbbd0f477e Mon Sep 17 00:00:00 2001 From: Brian Hill <76450501+bhillkeyfactor@users.noreply.github.com> Date: Thu, 6 Nov 2025 19:49:41 -0500 Subject: [PATCH 03/34] Update CHANGELOG.md --- CHANGELOG.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8b13789..4b94880 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1 +1,2 @@ - +- 1.0.0 + - Initial Version From 272b83277308b9f0edbd229a6022831c6410a643 Mon Sep 17 00:00:00 2001 From: Brian Hill <76450501+bhillkeyfactor@users.noreply.github.com> Date: Thu, 6 Nov 2025 19:51:18 -0500 Subject: [PATCH 04/34] Create README.md --- README.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..9daeafb --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +test From b4c394c6f0ea727229f034fb2585ba5528495cdf Mon Sep 17 00:00:00 2001 From: Brian Hill <76450501+bhillkeyfactor@users.noreply.github.com> Date: Thu, 6 Nov 2025 19:56:45 -0500 Subject: [PATCH 05/34] Delete IdomicCAPlugin.cs --- IdomicCAPlugin.cs | 8 -------- 1 file changed, 8 deletions(-) delete mode 100644 IdomicCAPlugin.cs diff --git a/IdomicCAPlugin.cs b/IdomicCAPlugin.cs deleted file mode 100644 index d555ecb..0000000 --- a/IdomicCAPlugin.cs +++ /dev/null @@ -1,8 +0,0 @@ -using System; - -public class Class1 -{ - public Class1() - { - } -} From 4159c6974043e43e799888a3dfa6aa13da6025e5 Mon Sep 17 00:00:00 2001 From: Brian Hill <76450501+bhillkeyfactor@users.noreply.github.com> Date: Thu, 6 Nov 2025 20:19:29 -0500 Subject: [PATCH 06/34] Update Idnomic.csproj --- Idnomic/Idnomic.csproj | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Idnomic/Idnomic.csproj b/Idnomic/Idnomic.csproj index ec2ba80..d9c4e1f 100644 --- a/Idnomic/Idnomic.csproj +++ b/Idnomic/Idnomic.csproj @@ -1,6 +1,6 @@  - net6.0 + net6.0;net8.0 disable true Keyfactor.Extensions.CAPlugin.Idnomic @@ -47,4 +47,4 @@ - \ No newline at end of file + From 599d0bc93de9e6f270da6e26a9e6cb012d40abac Mon Sep 17 00:00:00 2001 From: Brian Hill <76450501+bhillkeyfactor@users.noreply.github.com> Date: Thu, 6 Nov 2025 20:24:35 -0500 Subject: [PATCH 07/34] Update Idnomic.csproj --- Idnomic/Idnomic.csproj | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Idnomic/Idnomic.csproj b/Idnomic/Idnomic.csproj index d9c4e1f..96ea15d 100644 --- a/Idnomic/Idnomic.csproj +++ b/Idnomic/Idnomic.csproj @@ -1,6 +1,6 @@  - net6.0;net8.0 + net6.0;net8.0 disable true Keyfactor.Extensions.CAPlugin.Idnomic From a94738ed2a9d899a24650efd6ce1b8703172e918 Mon Sep 17 00:00:00 2001 From: Brian Hill <76450501+bhillkeyfactor@users.noreply.github.com> Date: Thu, 6 Nov 2025 20:31:22 -0500 Subject: [PATCH 08/34] Update integration-manifest.json --- integration-manifest.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/integration-manifest.json b/integration-manifest.json index de909b3..332c2dd 100644 --- a/integration-manifest.json +++ b/integration-manifest.json @@ -8,8 +8,8 @@ "update_catalog": true, "description": "Idnomic PKI (formerly OpenTrust PKI) plugin for the AnyCA Gateway framework. Provides certificate lifecycle management through SOAP-based integration with Idnomic PKI systems.", "gateway_framework": "24.2.0", - "release_dir": "idnomic/bin/Release", - "release_project": "idnomic/idnomic.csproj", + "release_dir": "Idnomic/bin/Release", + "release_project": "Idnomic/Idnomic.csproj", "about": { "carest": { "ca_plugin_config": [ From bc43c2551c1e4fb5e000100b8cbfa1ecbeca543d Mon Sep 17 00:00:00 2001 From: Brian Hill <76450501+bhillkeyfactor@users.noreply.github.com> Date: Thu, 6 Nov 2025 20:41:20 -0500 Subject: [PATCH 09/34] Delete docsource/configuration.md --- docsource/configuration.md | 1 - 1 file changed, 1 deletion(-) delete mode 100644 docsource/configuration.md diff --git a/docsource/configuration.md b/docsource/configuration.md deleted file mode 100644 index 8c99f1b..0000000 --- a/docsource/configuration.md +++ /dev/null @@ -1 +0,0 @@ -# Idnomic PKI AnyCA Gateway Plugin Documentation ## Overview The Idnomic PKI Gateway plugin extends the capabilities of Idnomic PKI (formerly OpenTrust PKI) to Keyfactor Command via the Keyfactor AnyCA Gateway. This plugin leverages the Idnomic SOAP-based connectors to provide comprehensive certificate lifecycle management. The plugin represents a fully featured AnyCA Plugin with the following capabilities: * **CA Sync**: * Download all certificates issued by the Idnomic CA * Support for incremental and full synchronization * Filter certificates by issuance date * **Certificate Enrollment**: * Support certificate enrollment with new key pairs * Dynamic template (profile) discovery from the CA * Zone-based certificate issuance * Support for PKCS#10 CSR format * **Certificate Revocation**: * Request revocation of previously issued certificates * Support for standard CRL revocation reasons ## Requirements ### Idnomic PKI System Prerequisites Before configuring the AnyCA Gateway plugin, ensure the following prerequisites are met on your Idnomic PKI system: 1. **Idnomic PKI Installation**: - Idnomic PKI server must be installed and operational - RA (Registration Authority) connector must be enabled and accessible - SOAP interface must be configured and reachable 2. **Client Certificate Authentication**: - A client certificate must be issued for the AnyCA Gateway service to authenticate to Idnomic - The certificate must be trusted by the Idnomic PKI system - Certificate must be exported in PFX/PKCS#12 format with private key 3. **Network Connectivity**: - Gateway server must have network access to the Idnomic RA connector endpoint - Default endpoint format: `https://:/RA/connector.cgi` - TLS/SSL must be properly configured ### Obtaining Required Configuration Information #### 1. RA Connector Endpoint Address The RA Connector endpoint is the SOAP service URL for the Registration Authority connector. **To find the endpoint address:** 1. Contact your Idnomic PKI administrator 2. The standard format is: `https://:/RA/connector.cgi` 3. Verify the endpoint is accessible from the Gateway server 4. Confirm SOAP services are enabled on this endpoint **Example endpoint**: `https://idnomic-pki.example.com:8443/RA/connector.cgi` #### 2. Client Certificate for Authentication The Gateway authenticates to Idnomic using mutual TLS with a client certificate. **Steps to obtain and prepare the client certificate:** 1. **Request a Client Certificate**: - Contact your Idnomic PKI administrator - Request a certificate suitable for SOAP client authentication - Ensure the certificate includes the "Client Authentication" Extended Key Usage 2. **Export the Certificate**: - Export the certificate with its private key in PFX (PKCS#12) format - Set a strong password for the PFX file - Example filename: `gateway-client-cert.pfx` 3. **Deploy the Certificate**: - Copy the PFX file to a secure location on the Gateway server - Recommended location: `C:\Program Files\Keyfactor\AnyGateway\Certificates\` (Windows) - Or: `/opt/keyfactor/anygateway/certificates/` (Linux) - Set appropriate file permissions to restrict access - Record the full path and password for Gateway configuration #### 3. Certificate Profiles (Templates) Certificate profiles define the types of certificates that can be issued. The plugin automatically discovers available profiles from the Idnomic system. **To view available profiles:** 1. The profiles are retrieved automatically when the CA is configured 2. Profiles appear in Keyfactor Command as "Product IDs" after CA registration 3. Each profile represents a certificate template configured in Idnomic PKI **Note**: Profile discovery uses the `list_profiles` SOAP operation. Ensure the client certificate has permissions to call this operation. #### 4. Zones Zones in Idnomic PKI represent organizational or security boundaries within the PKI hierarchy. Each certificate enrollment request must specify a zone. **Common zone examples**: - `Default` - `Production` - `Test` - `DMZ` - Custom zones as configured in your Idnomic PKI **To identify available zones:** 1. Contact your Idnomic PKI administrator for the list of configured zones 2. Zones may be visible through the `certificate_search_properties` operation 3. Document the zone names exactly as they appear in the system (case-sensitive) ### Supported Revocation Reasons The plugin supports the following standard CRL revocation reasons: | Reason Code | Reason Name | Description | |-------------|-------------|-------------| | 0 | Unspecified | No specific reason provided | | 1 | Key Compromise | Private key has been compromised | | 2 | CA Compromise | Certificate Authority has been compromised | | 3 | Affiliation Changed | Subject's affiliation has changed | | 4 | Superseded | Certificate has been superseded by a new certificate | | 5 | Cessation of Operation | Certificate is no longer needed | | 6 | Certificate Hold | Temporary suspension (use with caution) | | 9 | Privilege Withdrawn | Privileges have been withdrawn | | 10 | AA Compromise | Attribute Authority has been compromised | **Note**: Not all Idnomic PKI configurations support all revocation reasons. Consult your Idnomic administrator for supported reasons in your environment. ## Gateway Registration and Configuration ### CA Connection Configuration When registering the Idnomic CA in the AnyCA Gateway, you'll need to provide the following configuration parameters: | Parameter | Description | Required | Example | |-----------|-------------|----------|---------| | **EndpointAddress** | Full URL to the Idnomic RA connector SOAP endpoint | Yes | `https://idnomic.example.com:8443/RA/connector.cgi` | | **ClientCertLocation** | Full file path to the client certificate PFX file on the Gateway server | Yes | `C:\Certificates\gateway-client.pfx` | | **ClientCertPassword** | Password for the client certificate PFX file | Yes | `SecureP@ssw0rd` | | **Enabled** | Whether the CA connection is enabled | No (default: true) | `true` or `false` | ### Template (Product) Configuration Each certificate template discovered from Idnomic requires configuration when used for enrollment: | Parameter | Description | Required | Example | |-----------|-------------|----------|---------| | **Zone** | The Idnomic PKI zone where certificates will be issued | Yes | `Production` | **Important Notes**: - Template names (Product IDs) are automatically discovered from Idnomic using the `list_profiles` operation - The Zone parameter must exactly match a zone configured in your Idnomic PKI system - Zone names are case-sensitive - Each template can be configured with a different zone if needed ### Configuration Example **CA Configuration in AnyCA Gateway**: ```json { "EndpointAddress": "https://idnomic-pki.example.com:8443/RA/connector.cgi", "ClientCertLocation": "C:\\Program Files\\Keyfactor\\AnyGateway\\Certificates\\gateway-client.pfx", "ClientCertPassword": "MySecurePassword123!", "Enabled": true } ``` **Template Configuration** (for each profile): ```json { "Zone": "Production" } ``` ### Gateway Registration Notes - Each defined Certificate Authority in the AnyCA Gateway REST can support one Idnomic CA endpoint - If you have multiple Idnomic PKI instances or need to issue from different zones with different permissions, you must define multiple Certificate Authorities in the AnyCA Gateway - Each CA configuration will manifest in Command as a separate CA entry - The plugin uses SOAP-based communication exclusively; ensure the RA connector endpoint is properly configured for SOAP access - Client certificate authentication is mandatory and cannot be disabled - The "Enabled" flag allows you to temporarily disable a CA connection without removing the configuration ### Security Considerations 1. **Certificate Storage**: Store client certificates in a secure location with restricted file system permissions 2. **Password Management**: Use strong passwords for client certificate PFX files and consider using a secrets management system 3. **Network Security**: Ensure TLS/SSL is properly configured for the RA connector endpoint 4. **Least Privilege**: Request client certificates with minimal required permissions in the Idnomic PKI system 5. **Audit Logging**: Enable comprehensive logging in both the Gateway and Idnomic PKI for security monitoring ## Troubleshooting ### Connection Issues - Verify the RA connector endpoint URL is correct and accessible - Check that the client certificate is valid and not expired - Confirm the client certificate is trusted by the Idnomic PKI system - Review Gateway logs for SOAP communication errors ### Profile Discovery Issues - Ensure the client certificate has permissions to call `list_profiles` - Verify the RA connector is properly configured in Idnomic - Check that profiles are published and available in the Idnomic system ### Enrollment Failures - Verify the Zone parameter exactly matches a configured zone in Idnomic - Confirm the selected profile supports the requested certificate attributes - Check that the client certificate has enrollment permissions for the specified zone - Review Idnomic PKI logs for detailed error messages ### Synchronization Issues - Confirm the client certificate has permissions to call `search_for_certificates` - Verify network connectivity and timeout settings - For large certificate databases, consider adjusting synchronization schedules ## Test Cases ### Test Case 1: CA Connection Validation **Objective**: Verify that the Gateway can successfully connect to the Idnomic RA connector using client certificate authentication. **Prerequisites**: - Idnomic PKI system is operational - Valid client certificate (PFX) is available - RA connector endpoint is accessible **Test Steps**: 1. Configure the CA in AnyCA Gateway with valid connection parameters 2. Click "Test Connection" or trigger the Ping operation 3. Observe the connection result **Expected Results**: - Connection succeeds without errors - Gateway logs show successful SOAP authentication - No certificate validation errors occur **Verification**: - Review Gateway logs for successful connection message - Check Idnomic PKI logs for incoming authenticated connection - Verify no SSL/TLS errors in either system --- ### Test Case 2: Profile Discovery **Objective**: Verify that the Gateway can retrieve the list of available certificate profiles from Idnomic PKI. **Prerequisites**: - CA connection is successfully configured - At least one certificate profile is configured in Idnomic PKI - Client certificate has permissions to call `list_profiles` **Test Steps**: 1. Save the CA configuration in AnyCA Gateway 2. Navigate to the template/product configuration section 3. Observe the list of available Product IDs **Expected Results**: - List of profiles is populated automatically - Profile names match those configured in Idnomic PKI - No empty or null profile names appear **Verification**: - Compare the list of profiles in Gateway with Idnomic PKI configuration - Verify profile names are correctly displayed - Check Gateway logs for successful `list_profiles` SOAP call --- ### Test Case 3: Certificate Enrollment - Valid Request **Objective**: Verify successful certificate enrollment through the plugin. **Prerequisites**: - CA and template are properly configured - Valid Zone parameter is configured for the template - Test CSR is available **Test Steps**: 1. Submit an enrollment request via Keyfactor Command 2. Specify the Idnomic CA and a valid template 3. Provide a valid PKCS#10 CSR 4. Wait for enrollment to complete **Expected Results**: - Enrollment completes successfully - Certificate is issued by Idnomic PKI - Certificate is returned to Keyfactor Command - Certificate appears in Command inventory **Verification**: - Verify certificate details match the CSR - Confirm certificate is present in Idnomic PKI database - Check that certificate chain is properly constructed - Validate certificate can be used for its intended purpose --- ### Test Case 4: Certificate Enrollment - Invalid Zone **Objective**: Verify proper error handling when an invalid zone is specified. **Prerequisites**: - CA and template are configured - Zone parameter is set to a non-existent zone name **Test Steps**: 1. Submit an enrollment request with invalid Zone parameter 2. Observe the enrollment result **Expected Results**: - Enrollment fails with clear error message - Error message indicates invalid zone - No certificate is issued - System remains stable **Verification**: - Check error message clarity and accuracy - Verify Gateway logs contain detailed error information - Confirm no partial enrollment occurred in Idnomic PKI --- ### Test Case 5: Certificate Synchronization - Full Sync **Objective**: Verify full certificate synchronization from Idnomic PKI to Keyfactor Command. **Prerequisites**: - CA is properly configured - Multiple certificates exist in Idnomic PKI - Synchronization is configured in Command **Test Steps**: 1. Trigger a full synchronization job 2. Wait for synchronization to complete 3. Verify synchronized certificate count **Expected Results**: - All certificates from Idnomic PKI are synchronized - Certificate details are accurate (subject, serial number, dates, etc.) - No duplicate certificates appear - Synchronization completes without errors **Verification**: - Compare certificate count in Command vs. Idnomic PKI - Spot-check several certificates for data accuracy - Review synchronization logs for any warnings or errors - Verify certificate chains are properly synchronized --- ### Test Case 6: Certificate Synchronization - Incremental Sync **Objective**: Verify incremental synchronization only retrieves new certificates since last sync. **Prerequisites**: - Initial full synchronization has been completed - Timestamp of last sync is recorded - New certificates have been issued since last sync **Test Steps**: 1. Note the timestamp of the last successful sync 2. Issue one or more new certificates in Idnomic PKI 3. Trigger an incremental synchronization 4. Observe synchronized certificates **Expected Results**: - Only certificates issued after last sync are retrieved - Sync completes faster than full sync - All new certificates are properly synchronized - Previously synchronized certificates are not duplicated **Verification**: - Verify only recent certificates were processed - Check sync duration is appropriate for certificate count - Review Gateway logs to confirm incremental sync parameters - Validate certificate data integrity --- ### Test Case 7: Certificate Revocation - Key Compromise **Objective**: Verify certificate revocation with reason code 1 (Key Compromise). **Prerequisites**: - A valid certificate issued through the Gateway exists - Certificate is not already revoked **Test Steps**: 1. Identify a test certificate to revoke 2. Submit revocation request with reason "Key Compromise" (code 1) 3. Wait for revocation to complete **Expected Results**: - Revocation succeeds - Certificate status changes to "Revoked" in Command - Certificate appears on CRL in Idnomic PKI - Revocation reason is correctly recorded **Verification**: - Check certificate status in Keyfactor Command - Verify certificate appears on Idnomic CRL with correct reason code - Confirm revocation timestamp is accurate - Validate certificate can no longer be used for authentication --- ### Test Case 8: Certificate Revocation - Multiple Reason Codes **Objective**: Verify that all supported revocation reason codes work correctly. **Prerequisites**: - Multiple test certificates are available for revocation - CA supports all standard revocation reasons **Test Steps**: 1. For each supported reason code (0, 1, 2, 3, 4, 5, 6, 9, 10): - Select a test certificate - Submit revocation with the specific reason code - Verify revocation succeeds 2. Check CRL for correct reason codes **Expected Results**: - All revocation requests succeed - Each certificate shows correct revocation reason in CRL - No errors occur for any reason code **Verification**: - Download and parse CRL from Idnomic PKI - Verify each revoked certificate has correct CRL reason code - Confirm all revocations are logged in both systems - Check that certificates with reason code 6 (Certificate Hold) can be resumed if supported --- ### Test Case 9: Profile Properties Validation **Objective**: Verify that profile-specific properties are correctly enforced during enrollment. **Prerequisites**: - Profiles with different configurations exist (key sizes, validity periods, etc.) - Zone parameter is correctly configured **Test Steps**: 1. Attempt enrollment with CSR matching profile requirements 2. Attempt enrollment with CSR not matching profile requirements (e.g., wrong key size) 3. Observe results **Expected Results**: - Valid enrollments succeed - Invalid enrollments fail with descriptive error messages - Profile constraints are properly enforced by Idnomic PKI **Verification**: - Review error messages for clarity - Verify Idnomic PKI rejects non-compliant requests - Check that valid certificates meet profile specifications - Confirm Gateway properly communicates validation errors --- ### Test Case 10: Client Certificate Expiration Handling **Objective**: Verify proper error handling when the Gateway client certificate expires or becomes invalid. **Prerequisites**: - Ability to test with expired or invalid client certificate - Valid backup client certificate available **Test Steps**: 1. Configure Gateway with expired client certificate 2. Attempt any operation (Ping, Enrollment, Sync) 3. Observe error handling 4. Replace with valid certificate and retry **Expected Results**: - Operations fail with clear error indicating certificate issue - Error message specifies certificate expiration or invalidity - After replacing certificate, operations succeed - No system instability occurs **Verification**: - Check error messages are user-friendly and actionable - Verify Gateway logs contain detailed certificate validation errors - Confirm system recovers gracefully after certificate replacement - Review Idnomic PKI logs for authentication failure records --- ### Test Case 11: Network Connectivity Failure **Objective**: Verify graceful handling of network connectivity issues to the Idnomic RA connector. **Prerequisites**: - Ability to simulate network failure (firewall rule, network disconnection, etc.) **Test Steps**: 1. Simulate network connectivity loss to RA connector 2. Attempt enrollment operation 3. Observe error handling 4. Restore network connectivity 5. Retry operation **Expected Results**: - Operation fails with clear network connectivity error - System does not crash or become unstable - After connectivity restoration, operations succeed - Appropriate timeout handling occurs **Verification**: - Review error messages for clarity - Check Gateway logs show connection attempt details - Verify timeout values are appropriate - Confirm no memory leaks or resource issues during failure --- ### Test Case 12: Concurrent Enrollment Requests **Objective**: Verify the Gateway can handle multiple simultaneous enrollment requests. **Prerequisites**: - CA is properly configured - Multiple test CSRs are available - Load testing capability exists **Test Steps**: 1. Submit 10 enrollment requests simultaneously 2. Monitor all requests to completion 3. Verify all enrollments succeed or fail appropriately **Expected Results**: - All requests are processed - No race conditions occur - Certificates are correctly issued for valid requests - System remains stable under load **Verification**: - Check all requests complete within reasonable time - Verify no certificate duplication occurs - Review Gateway logs for proper request handling - Confirm Idnomic PKI properly queued and processed requests - Validate certificate data integrity for all issued certificates --- ### Test Case 13: Large Certificate Synchronization **Objective**: Verify Gateway performance when synchronizing large numbers of certificates. **Prerequisites**: - Idnomic PKI has 1000+ certificates - Adequate system resources available **Test Steps**: 1. Trigger full synchronization of large certificate set 2. Monitor memory usage and performance 3. Verify synchronization completes successfully **Expected Results**: - Synchronization completes without timeout - Memory usage remains within acceptable limits - All certificates are synchronized accurately - System remains responsive during sync **Verification**: - Monitor Gateway memory and CPU usage during sync - Verify certificate count matches Idnomic PKI - Check for any timeout or performance warnings in logs - Validate random sample of synchronized certificates for accuracy --- ## License Copyright © 2025 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. \ No newline at end of file From fb4ccf6bbf7b48451ca9937d3bb535f32719168a Mon Sep 17 00:00:00 2001 From: Keyfactor Date: Fri, 7 Nov 2025 01:44:36 +0000 Subject: [PATCH 10/34] Update generated docs --- README.md | 105 ++++++++++++++++++++++++++++++++++++- docsource/configuration.md | 24 +++++++++ integration-manifest.json | 12 ++--- 3 files changed, 134 insertions(+), 7 deletions(-) create mode 100644 docsource/configuration.md diff --git a/README.md b/README.md index 9daeafb..a49b693 100644 --- a/README.md +++ b/README.md @@ -1 +1,104 @@ -test +

+ Idnomic PKI Gateway AnyCA Gateway REST Plugin +

+ +

+ +Integration Status: pilot +Release +Issues +GitHub Downloads (all assets, all releases) +

+ +

+ + + Support + + · + + Requirements + + · + + Installation + + · + + License + + · + + Related Integrations + +

+ + +TODO Overview is a required section + +## Compatibility + +The Idnomic PKI Gateway AnyCA Gateway REST plugin is compatible with the Keyfactor AnyCA Gateway REST 24.2.0 and later. + +## Support +The Idnomic PKI Gateway AnyCA Gateway REST plugin is supported by Keyfactor for Keyfactor customers. If you have a support issue, please open a support ticket with your Keyfactor representative. If you have a support issue, please open a support ticket via the Keyfactor Support Portal at https://support.keyfactor.com. + +> To report a problem or suggest a new feature, use the **[Issues](../../issues)** tab. If you want to contribute actual bug fixes or proposed enhancements, use the **[Pull requests](../../pulls)** tab. + +## Requirements + +TODO Requirements is a required section + +## Installation + +1. Install the AnyCA Gateway REST per the [official Keyfactor documentation](https://software.keyfactor.com/Guides/AnyCAGatewayREST/Content/AnyCAGatewayREST/InstallIntroduction.htm). + +2. On the server hosting the AnyCA Gateway REST, download and unzip the latest [Idnomic PKI Gateway AnyCA Gateway REST plugin](https://github.com/Keyfactor/idnomic-caplugin/releases/latest) from GitHub. + +3. Copy the unzipped directory (usually called `net6.0` or `net8.0`) to the Extensions directory: + + + ```shell + Depending on your AnyCA Gateway REST version, copy the unzipped directory to one of the following locations: + Program Files\Keyfactor\AnyCA Gateway\AnyGatewayREST\net6.0\Extensions + Program Files\Keyfactor\AnyCA Gateway\AnyGatewayREST\net8.0\Extensions + ``` + + > The directory containing the Idnomic PKI Gateway AnyCA Gateway REST plugin DLLs (`net6.0` or `net8.0`) can be named anything, as long as it is unique within the `Extensions` directory. + +4. Restart the AnyCA Gateway REST service. + +5. Navigate to the AnyCA Gateway REST portal and verify that the Gateway recognizes the Idnomic PKI Gateway plugin by hovering over the ⓘ symbol to the right of the Gateway on the top left of the portal. + +## Configuration + +1. Follow the [official AnyCA Gateway REST documentation](https://software.keyfactor.com/Guides/AnyCAGatewayREST/Content/AnyCAGatewayREST/AddCA-Gateway.htm) to define a new Certificate Authority, and use the notes below to configure the **Gateway Registration** and **CA Connection** tabs: + + * **Gateway Registration** + + TODO Gateway Registration is a required section + + * **CA Connection** + + Populate using the configuration fields collected in the [requirements](#requirements) section. + + * **EndpointAddress** - The SOAP endpoint address for the Idnomic RA service. For example, 'https://idnomic-server.com/ra-service'. + * **ClientCertLocation** - The file path to the client certificate used for mutual TLS authentication with the Idnomic service. + * **ClientCertPassword** - The password for the client certificate. + * **Enabled** - Flag to Enable or Disable gateway functionality. Disabling is primarily used to allow creation of the CA prior to configuration information being available. + +2. TODO Certificate Template Creation Step is a required section + +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. TODO Custom Enrollment Parameter Creation Step is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info + + + +## License + +Apache License 2.0, see [LICENSE](LICENSE). + +## Related Integrations + +See all [Keyfactor Any CA Gateways (REST)](https://github.com/orgs/Keyfactor/repositories?q=anycagateway). \ No newline at end of file diff --git a/docsource/configuration.md b/docsource/configuration.md new file mode 100644 index 0000000..502f91f --- /dev/null +++ b/docsource/configuration.md @@ -0,0 +1,24 @@ +## Overview + +TODO Overview is a required section + +## Requirements + +TODO Requirements is a required section + +## Gateway Registration + +TODO Gateway Registration is a required section + +## Certificate Template Creation Step + +TODO Certificate Template Creation Step is a required section + +## Custom Enrollment Parameter Creation Step + +TODO Custom Enrollment Parameter Creation Step is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info + +## Mechanics + +TODO Mechanics is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info + diff --git a/integration-manifest.json b/integration-manifest.json index 332c2dd..82c60c6 100644 --- a/integration-manifest.json +++ b/integration-manifest.json @@ -15,28 +15,28 @@ "ca_plugin_config": [ { "name": "EndpointAddress", - "description": "Full URL to the Idnomic RA connector SOAP endpoint. Example: https://idnomic-pki.example.com:8443/RA/connector.cgi" + "description": "The SOAP endpoint address for the Idnomic RA service. For example, 'https://idnomic-server.com/ra-service'." }, { "name": "ClientCertLocation", - "description": "Full file path to the client certificate PFX file on the Gateway server. Example: C:\\Certificates\\gateway-client.pfx" + "description": "The file path to the client certificate used for mutual TLS authentication with the Idnomic service." }, { "name": "ClientCertPassword", - "description": "Password for the client certificate PFX file. This certificate is used for mutual TLS authentication to the Idnomic PKI system." + "description": "The password for the client certificate." }, { "name": "Enabled", - "description": "Flag to enable or disable gateway functionality. Disabling is primarily used to allow creation of the CA prior to configuration information being available. Default: true" + "description": "Flag to Enable or Disable gateway functionality. Disabling is primarily used to allow creation of the CA prior to configuration information being available." } ], "enrollment_config": [ { "name": "Zone", - "description": "REQUIRED: The Idnomic PKI zone where certificates will be issued. Must exactly match a zone configured in the Idnomic PKI system (case-sensitive). Example: Production" + "description": "The Idnomic zone identifier for certificate enrollment. This parameter is required for enrollment operations." } ], "product_ids": [] } } -} +} \ No newline at end of file From 9ab7f0c184880a1a1d5aabd94cea584330bc7088 Mon Sep 17 00:00:00 2001 From: Brian Hill <76450501+bhillkeyfactor@users.noreply.github.com> Date: Thu, 6 Nov 2025 20:53:54 -0500 Subject: [PATCH 11/34] Update configuration.md --- docsource/configuration.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docsource/configuration.md b/docsource/configuration.md index 502f91f..96f9a0d 100644 --- a/docsource/configuration.md +++ b/docsource/configuration.md @@ -1,6 +1,19 @@ ## Overview -TODO Overview is a required section +The Idnomic PKI Gateway plugin extends the capabilities of Idnomic PKI (formerly OpenTrust PKI) to Keyfactor Command via the Keyfactor AnyCA Gateway. This plugin leverages the Idnomic SOAP-based connectors to provide comprehensive certificate lifecycle management. The plugin represents a fully featured AnyCA Plugin with the following capabilities: + +* **CA Sync**: + * Download all certificates issued by the Idnomic CA + * Support for incremental and full synchronization + * Filter certificates by issuance date +* **Certificate Enrollment**: + * Support certificate enrollment with new key pairs + * Dynamic template (profile) discovery from the CA + * Zone-based certificate issuance + * Support for PKCS#10 CSR format +* **Certificate Revocation**: + * Request revocation of previously issued certificates + * Support for standard CRL revocation reasons ## Requirements From 3a990751ba8b0e1b6b78101e90c361d2794f490a Mon Sep 17 00:00:00 2001 From: Keyfactor Date: Fri, 7 Nov 2025 01:56:09 +0000 Subject: [PATCH 12/34] Update generated docs --- README.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index a49b693..3026b48 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,20 @@

-TODO Overview is a required section +The Idnomic PKI Gateway plugin extends the capabilities of Idnomic PKI (formerly OpenTrust PKI) to Keyfactor Command via the Keyfactor AnyCA Gateway. This plugin leverages the Idnomic SOAP-based connectors to provide comprehensive certificate lifecycle management. The plugin represents a fully featured AnyCA Plugin with the following capabilities: + +* **CA Sync**: + * Download all certificates issued by the Idnomic CA + * Support for incremental and full synchronization + * Filter certificates by issuance date +* **Certificate Enrollment**: + * Support certificate enrollment with new key pairs + * Dynamic template (profile) discovery from the CA + * Zone-based certificate issuance + * Support for PKCS#10 CSR format +* **Certificate Revocation**: + * Request revocation of previously issued certificates + * Support for standard CRL revocation reasons ## Compatibility From e1bbee6ad8877af809e5705b752520104938d6b5 Mon Sep 17 00:00:00 2001 From: Brian Hill <76450501+bhillkeyfactor@users.noreply.github.com> Date: Thu, 6 Nov 2025 20:56:33 -0500 Subject: [PATCH 13/34] Update configuration.md --- docsource/configuration.md | 104 ++++++++++++++++++++++++++++++++++++- 1 file changed, 103 insertions(+), 1 deletion(-) diff --git a/docsource/configuration.md b/docsource/configuration.md index 96f9a0d..9f329d2 100644 --- a/docsource/configuration.md +++ b/docsource/configuration.md @@ -17,7 +17,109 @@ The Idnomic PKI Gateway plugin extends the capabilities of Idnomic PKI (formerly ## Requirements -TODO Requirements is a required section +### Idnomic PKI System Prerequisites + +Before configuring the AnyCA Gateway plugin, ensure the following prerequisites are met on your Idnomic PKI system: + +1. **Idnomic PKI Installation**: + - Idnomic PKI server must be installed and operational + - RA (Registration Authority) connector must be enabled and accessible + - SOAP interface must be configured and reachable + +2. **Client Certificate Authentication**: + - A client certificate must be issued for the AnyCA Gateway service to authenticate to Idnomic + - The certificate must be trusted by the Idnomic PKI system + - Certificate must be exported in PFX/PKCS#12 format with private key + +3. **Network Connectivity**: + - Gateway server must have network access to the Idnomic RA connector endpoint + - Default endpoint format: `https://:/RA/connector.cgi` + - TLS/SSL must be properly configured + +### Obtaining Required Configuration Information + +#### 1. RA Connector Endpoint Address + +The RA Connector endpoint is the SOAP service URL for the Registration Authority connector. + +**To find the endpoint address:** + +1. Contact your Idnomic PKI administrator +2. The standard format is: `https://:/RA/connector.cgi` +3. Verify the endpoint is accessible from the Gateway server +4. Confirm SOAP services are enabled on this endpoint + +**Example endpoint**: `https://idnomic-pki.example.com:8443/RA/connector.cgi` + +#### 2. Client Certificate for Authentication + +The Gateway authenticates to Idnomic using mutual TLS with a client certificate. + +**Steps to obtain and prepare the client certificate:** + +1. **Request a Client Certificate**: + - Contact your Idnomic PKI administrator + - Request a certificate suitable for SOAP client authentication + - Ensure the certificate includes the "Client Authentication" Extended Key Usage + +2. **Export the Certificate**: + - Export the certificate with its private key in PFX (PKCS#12) format + - Set a strong password for the PFX file + - Example filename: `gateway-client-cert.pfx` + +3. **Deploy the Certificate**: + - Copy the PFX file to a secure location on the Gateway server + - Recommended location: `C:\Program Files\Keyfactor\AnyGateway\Certificates\` (Windows) + - Or: `/opt/keyfactor/anygateway/certificates/` (Linux) + - Set appropriate file permissions to restrict access + - Record the full path and password for Gateway configuration + +#### 3. Certificate Profiles (Templates) + +Certificate profiles define the types of certificates that can be issued. The plugin automatically discovers available profiles from the Idnomic system. + +**To view available profiles:** + +1. The profiles are retrieved automatically when the CA is configured +2. Profiles appear in Keyfactor Command as "Product IDs" after CA registration +3. Each profile represents a certificate template configured in Idnomic PKI + +**Note**: Profile discovery uses the `list_profiles` SOAP operation. Ensure the client certificate has permissions to call this operation. + +#### 4. Zones + +Zones in Idnomic PKI represent organizational or security boundaries within the PKI hierarchy. Each certificate enrollment request must specify a zone. + +**Common zone examples**: +- `Default` +- `Production` +- `Test` +- `DMZ` +- Custom zones as configured in your Idnomic PKI + +**To identify available zones:** + +1. Contact your Idnomic PKI administrator for the list of configured zones +2. Zones may be visible through the `certificate_search_properties` operation +3. Document the zone names exactly as they appear in the system (case-sensitive) + +### Supported Revocation Reasons + +The plugin supports the following standard CRL revocation reasons: + +| Reason Code | Reason Name | Description | +|-------------|-------------|-------------| +| 0 | Unspecified | No specific reason provided | +| 1 | Key Compromise | Private key has been compromised | +| 2 | CA Compromise | Certificate Authority has been compromised | +| 3 | Affiliation Changed | Subject's affiliation has changed | +| 4 | Superseded | Certificate has been superseded by a new certificate | +| 5 | Cessation of Operation | Certificate is no longer needed | +| 6 | Certificate Hold | Temporary suspension (use with caution) | +| 9 | Privilege Withdrawn | Privileges have been withdrawn | +| 10 | AA Compromise | Attribute Authority has been compromised | + +**Note**: Not all Idnomic PKI configurations support all revocation reasons. Consult your Idnomic administrator for supported reasons in your environment. ## Gateway Registration From 4d0bb4a6e8c00d89147239a228d2209decd3be52 Mon Sep 17 00:00:00 2001 From: Brian Hill <76450501+bhillkeyfactor@users.noreply.github.com> Date: Thu, 6 Nov 2025 21:00:07 -0500 Subject: [PATCH 14/34] Update configuration.md --- docsource/configuration.md | 61 +++++++++++++++++++++++++++++++++++++- 1 file changed, 60 insertions(+), 1 deletion(-) diff --git a/docsource/configuration.md b/docsource/configuration.md index 9f329d2..5d651fa 100644 --- a/docsource/configuration.md +++ b/docsource/configuration.md @@ -123,7 +123,66 @@ The plugin supports the following standard CRL revocation reasons: ## Gateway Registration -TODO Gateway Registration is a required section +### CA Connection Configuration + +When registering the Idnomic CA in the AnyCA Gateway, you'll need to provide the following configuration parameters: + +| Parameter | Description | Required | Example | +|-----------|-------------|----------|---------| +| **EndpointAddress** | Full URL to the Idnomic RA connector SOAP endpoint | Yes | `https://idnomic.example.com:8443/RA/connector.cgi` | +| **ClientCertLocation** | Full file path to the client certificate PFX file on the Gateway server | Yes | `C:\Certificates\gateway-client.pfx` | +| **ClientCertPassword** | Password for the client certificate PFX file | Yes | `SecureP@ssw0rd` | +| **Enabled** | Whether the CA connection is enabled | No (default: true) | `true` or `false` | + +### Template (Product) Configuration + +Each certificate template discovered from Idnomic requires configuration when used for enrollment: + +| Parameter | Description | Required | Example | +|-----------|-------------|----------|---------| +| **Zone** | The Idnomic PKI zone where certificates will be issued | Yes | `Production` | + +**Important Notes**: +- Template names (Product IDs) are automatically discovered from Idnomic using the `list_profiles` operation +- The Zone parameter must exactly match a zone configured in your Idnomic PKI system +- Zone names are case-sensitive +- Each template can be configured with a different zone if needed + +### Configuration Example + +**CA Configuration in AnyCA Gateway**: +```json +{ + "EndpointAddress": "https://idnomic-pki.example.com:8443/RA/connector.cgi", + "ClientCertLocation": "C:\\Program Files\\Keyfactor\\AnyGateway\\Certificates\\gateway-client.pfx", + "ClientCertPassword": "MySecurePassword123!", + "Enabled": true +} +``` + +**Template Configuration** (for each profile): +```json +{ + "Zone": "Production" +} +``` + +### Gateway Registration Notes + +- Each defined Certificate Authority in the AnyCA Gateway REST can support one Idnomic CA endpoint +- If you have multiple Idnomic PKI instances or need to issue from different zones with different permissions, you must define multiple Certificate Authorities in the AnyCA Gateway +- Each CA configuration will manifest in Command as a separate CA entry +- The plugin uses SOAP-based communication exclusively; ensure the RA connector endpoint is properly configured for SOAP access +- Client certificate authentication is mandatory and cannot be disabled +- The "Enabled" flag allows you to temporarily disable a CA connection without removing the configuration + +### Security Considerations + +1. **Certificate Storage**: Store client certificates in a secure location with restricted file system permissions +2. **Password Management**: Use strong passwords for client certificate PFX files and consider using a secrets management system +3. **Network Security**: Ensure TLS/SSL is properly configured for the RA connector endpoint +4. **Least Privilege**: Request client certificates with minimal required permissions in the Idnomic PKI system +5. **Audit Logging**: Enable comprehensive logging in both the Gateway and Idnomic PKI for security monitoring ## Certificate Template Creation Step From b5bb76c9498ec15df077bc2c3e89230f2b139e69 Mon Sep 17 00:00:00 2001 From: Brian Hill <76450501+bhillkeyfactor@users.noreply.github.com> Date: Thu, 6 Nov 2025 21:03:31 -0500 Subject: [PATCH 15/34] Update configuration.md --- docsource/configuration.md | 382 ++++++++++++++++++++++++++++++++++++- 1 file changed, 376 insertions(+), 6 deletions(-) diff --git a/docsource/configuration.md b/docsource/configuration.md index 5d651fa..91609ad 100644 --- a/docsource/configuration.md +++ b/docsource/configuration.md @@ -184,15 +184,385 @@ Each certificate template discovered from Idnomic requires configuration when us 4. **Least Privilege**: Request client certificates with minimal required permissions in the Idnomic PKI system 5. **Audit Logging**: Enable comprehensive logging in both the Gateway and Idnomic PKI for security monitoring -## Certificate Template Creation Step +## Troubleshooting -TODO Certificate Template Creation Step is a required section +### Connection Issues +- Verify the RA connector endpoint URL is correct and accessible +- Check that the client certificate is valid and not expired +- Confirm the client certificate is trusted by the Idnomic PKI system +- Review Gateway logs for SOAP communication errors -## Custom Enrollment Parameter Creation Step +### Profile Discovery Issues +- Ensure the client certificate has permissions to call `list_profiles` +- Verify the RA connector is properly configured in Idnomic +- Check that profiles are published and available in the Idnomic system -TODO Custom Enrollment Parameter Creation Step is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info +### Enrollment Failures +- Verify the Zone parameter exactly matches a configured zone in Idnomic +- Confirm the selected profile supports the requested certificate attributes +- Check that the client certificate has enrollment permissions for the specified zone +- Review Idnomic PKI logs for detailed error messages -## Mechanics +### Synchronization Issues +- Confirm the client certificate has permissions to call `search_for_certificates` +- Verify network connectivity and timeout settings +- For large certificate databases, consider adjusting synchronization schedules -TODO Mechanics is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info +## Test Cases + +### Test Case 1: CA Connection Validation + +**Objective**: Verify that the Gateway can successfully connect to the Idnomic RA connector using client certificate authentication. + +**Prerequisites**: +- Idnomic PKI system is operational +- Valid client certificate (PFX) is available +- RA connector endpoint is accessible + +**Test Steps**: +1. Configure the CA in AnyCA Gateway with valid connection parameters +2. Click "Test Connection" or trigger the Ping operation +3. Observe the connection result + +**Expected Results**: +- Connection succeeds without errors +- Gateway logs show successful SOAP authentication +- No certificate validation errors occur + +**Verification**: +- Review Gateway logs for successful connection message +- Check Idnomic PKI logs for incoming authenticated connection +- Verify no SSL/TLS errors in either system + +--- + +### Test Case 2: Profile Discovery + +**Objective**: Verify that the Gateway can retrieve the list of available certificate profiles from Idnomic PKI. + +**Prerequisites**: +- CA connection is successfully configured +- At least one certificate profile is configured in Idnomic PKI +- Client certificate has permissions to call `list_profiles` + +**Test Steps**: +1. Save the CA configuration in AnyCA Gateway +2. Navigate to the template/product configuration section +3. Observe the list of available Product IDs + +**Expected Results**: +- List of profiles is populated automatically +- Profile names match those configured in Idnomic PKI +- No empty or null profile names appear + +**Verification**: +- Compare the list of profiles in Gateway with Idnomic PKI configuration +- Verify profile names are correctly displayed +- Check Gateway logs for successful `list_profiles` SOAP call + +--- + +### Test Case 3: Certificate Enrollment - Valid Request + +**Objective**: Verify successful certificate enrollment through the plugin. + +**Prerequisites**: +- CA and template are properly configured +- Valid Zone parameter is configured for the template +- Test CSR is available + +**Test Steps**: +1. Submit an enrollment request via Keyfactor Command +2. Specify the Idnomic CA and a valid template +3. Provide a valid PKCS#10 CSR +4. Wait for enrollment to complete + +**Expected Results**: +- Enrollment completes successfully +- Certificate is issued by Idnomic PKI +- Certificate is returned to Keyfactor Command +- Certificate appears in Command inventory + +**Verification**: +- Verify certificate details match the CSR +- Confirm certificate is present in Idnomic PKI database +- Check that certificate chain is properly constructed +- Validate certificate can be used for its intended purpose + +--- + +### Test Case 4: Certificate Enrollment - Invalid Zone + +**Objective**: Verify proper error handling when an invalid zone is specified. + +**Prerequisites**: +- CA and template are configured +- Zone parameter is set to a non-existent zone name + +**Test Steps**: +1. Submit an enrollment request with invalid Zone parameter +2. Observe the enrollment result + +**Expected Results**: +- Enrollment fails with clear error message +- Error message indicates invalid zone +- No certificate is issued +- System remains stable + +**Verification**: +- Check error message clarity and accuracy +- Verify Gateway logs contain detailed error information +- Confirm no partial enrollment occurred in Idnomic PKI + +--- + +### Test Case 5: Certificate Synchronization - Full Sync + +**Objective**: Verify full certificate synchronization from Idnomic PKI to Keyfactor Command. + +**Prerequisites**: +- CA is properly configured +- Multiple certificates exist in Idnomic PKI +- Synchronization is configured in Command + +**Test Steps**: +1. Trigger a full synchronization job +2. Wait for synchronization to complete +3. Verify synchronized certificate count + +**Expected Results**: +- All certificates from Idnomic PKI are synchronized +- Certificate details are accurate (subject, serial number, dates, etc.) +- No duplicate certificates appear +- Synchronization completes without errors + +**Verification**: +- Compare certificate count in Command vs. Idnomic PKI +- Spot-check several certificates for data accuracy +- Review synchronization logs for any warnings or errors +- Verify certificate chains are properly synchronized + +--- + +### Test Case 6: Certificate Synchronization - Incremental Sync + +**Objective**: Verify incremental synchronization only retrieves new certificates since last sync. + +**Prerequisites**: +- Initial full synchronization has been completed +- Timestamp of last sync is recorded +- New certificates have been issued since last sync + +**Test Steps**: +1. Note the timestamp of the last successful sync +2. Issue one or more new certificates in Idnomic PKI +3. Trigger an incremental synchronization +4. Observe synchronized certificates + +**Expected Results**: +- Only certificates issued after last sync are retrieved +- Sync completes faster than full sync +- All new certificates are properly synchronized +- Previously synchronized certificates are not duplicated + +**Verification**: +- Verify only recent certificates were processed +- Check sync duration is appropriate for certificate count +- Review Gateway logs to confirm incremental sync parameters +- Validate certificate data integrity + +--- + +### Test Case 7: Certificate Revocation - Key Compromise + +**Objective**: Verify certificate revocation with reason code 1 (Key Compromise). + +**Prerequisites**: +- A valid certificate issued through the Gateway exists +- Certificate is not already revoked + +**Test Steps**: +1. Identify a test certificate to revoke +2. Submit revocation request with reason "Key Compromise" (code 1) +3. Wait for revocation to complete + +**Expected Results**: +- Revocation succeeds +- Certificate status changes to "Revoked" in Command +- Certificate appears on CRL in Idnomic PKI +- Revocation reason is correctly recorded + +**Verification**: +- Check certificate status in Keyfactor Command +- Verify certificate appears on Idnomic CRL with correct reason code +- Confirm revocation timestamp is accurate +- Validate certificate can no longer be used for authentication + +--- + +### Test Case 8: Certificate Revocation - Multiple Reason Codes + +**Objective**: Verify that all supported revocation reason codes work correctly. + +**Prerequisites**: +- Multiple test certificates are available for revocation +- CA supports all standard revocation reasons + +**Test Steps**: +1. For each supported reason code (0, 1, 2, 3, 4, 5, 6, 9, 10): + - Select a test certificate + - Submit revocation with the specific reason code + - Verify revocation succeeds +2. Check CRL for correct reason codes + +**Expected Results**: +- All revocation requests succeed +- Each certificate shows correct revocation reason in CRL +- No errors occur for any reason code + +**Verification**: +- Download and parse CRL from Idnomic PKI +- Verify each revoked certificate has correct CRL reason code +- Confirm all revocations are logged in both systems +- Check that certificates with reason code 6 (Certificate Hold) can be resumed if supported + +--- + +### Test Case 9: Profile Properties Validation + +**Objective**: Verify that profile-specific properties are correctly enforced during enrollment. + +**Prerequisites**: +- Profiles with different configurations exist (key sizes, validity periods, etc.) +- Zone parameter is correctly configured + +**Test Steps**: +1. Attempt enrollment with CSR matching profile requirements +2. Attempt enrollment with CSR not matching profile requirements (e.g., wrong key size) +3. Observe results + +**Expected Results**: +- Valid enrollments succeed +- Invalid enrollments fail with descriptive error messages +- Profile constraints are properly enforced by Idnomic PKI + +**Verification**: +- Review error messages for clarity +- Verify Idnomic PKI rejects non-compliant requests +- Check that valid certificates meet profile specifications +- Confirm Gateway properly communicates validation errors + +--- + +### Test Case 10: Client Certificate Expiration Handling + +**Objective**: Verify proper error handling when the Gateway client certificate expires or becomes invalid. + +**Prerequisites**: +- Ability to test with expired or invalid client certificate +- Valid backup client certificate available + +**Test Steps**: +1. Configure Gateway with expired client certificate +2. Attempt any operation (Ping, Enrollment, Sync) +3. Observe error handling +4. Replace with valid certificate and retry + +**Expected Results**: +- Operations fail with clear error indicating certificate issue +- Error message specifies certificate expiration or invalidity +- After replacing certificate, operations succeed +- No system instability occurs + +**Verification**: +- Check error messages are user-friendly and actionable +- Verify Gateway logs contain detailed certificate validation errors +- Confirm system recovers gracefully after certificate replacement +- Review Idnomic PKI logs for authentication failure records + +--- + +### Test Case 11: Network Connectivity Failure + +**Objective**: Verify graceful handling of network connectivity issues to the Idnomic RA connector. + +**Prerequisites**: +- Ability to simulate network failure (firewall rule, network disconnection, etc.) + +**Test Steps**: +1. Simulate network connectivity loss to RA connector +2. Attempt enrollment operation +3. Observe error handling +4. Restore network connectivity +5. Retry operation + +**Expected Results**: +- Operation fails with clear network connectivity error +- System does not crash or become unstable +- After connectivity restoration, operations succeed +- Appropriate timeout handling occurs + +**Verification**: +- Review error messages for clarity +- Check Gateway logs show connection attempt details +- Verify timeout values are appropriate +- Confirm no memory leaks or resource issues during failure + +--- + +### Test Case 12: Concurrent Enrollment Requests + +**Objective**: Verify the Gateway can handle multiple simultaneous enrollment requests. + +**Prerequisites**: +- CA is properly configured +- Multiple test CSRs are available +- Load testing capability exists + +**Test Steps**: +1. Submit 10 enrollment requests simultaneously +2. Monitor all requests to completion +3. Verify all enrollments succeed or fail appropriately + +**Expected Results**: +- All requests are processed +- No race conditions occur +- Certificates are correctly issued for valid requests +- System remains stable under load + +**Verification**: +- Check all requests complete within reasonable time +- Verify no certificate duplication occurs +- Review Gateway logs for proper request handling +- Confirm Idnomic PKI properly queued and processed requests +- Validate certificate data integrity for all issued certificates + +--- + +### Test Case 13: Large Certificate Synchronization + +**Objective**: Verify Gateway performance when synchronizing large numbers of certificates. + +**Prerequisites**: +- Idnomic PKI has 1000+ certificates +- Adequate system resources available + +**Test Steps**: +1. Trigger full synchronization of large certificate set +2. Monitor memory usage and performance +3. Verify synchronization completes successfully + +**Expected Results**: +- Synchronization completes without timeout +- Memory usage remains within acceptable limits +- All certificates are synchronized accurately +- System remains responsive during sync + +**Verification**: +- Monitor Gateway memory and CPU usage during sync +- Verify certificate count matches Idnomic PKI +- Check for any timeout or performance warnings in logs +- Validate random sample of synchronized certificates for accuracy + +--- From cc86c558e6e461a295c93dfd14b40dad0ffb0d10 Mon Sep 17 00:00:00 2001 From: Keyfactor Date: Fri, 7 Nov 2025 02:05:45 +0000 Subject: [PATCH 16/34] Update generated docs --- README.md | 547 ++++++++++++++++++++++++++++++++++++- docsource/configuration.md | 4 + 2 files changed, 548 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 3026b48..4dbb7f8 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,109 @@ The Idnomic PKI Gateway AnyCA Gateway REST plugin is supported by Keyfactor for ## Requirements -TODO Requirements is a required section +### Idnomic PKI System Prerequisites + +Before configuring the AnyCA Gateway plugin, ensure the following prerequisites are met on your Idnomic PKI system: + +1. **Idnomic PKI Installation**: + - Idnomic PKI server must be installed and operational + - RA (Registration Authority) connector must be enabled and accessible + - SOAP interface must be configured and reachable + +2. **Client Certificate Authentication**: + - A client certificate must be issued for the AnyCA Gateway service to authenticate to Idnomic + - The certificate must be trusted by the Idnomic PKI system + - Certificate must be exported in PFX/PKCS#12 format with private key + +3. **Network Connectivity**: + - Gateway server must have network access to the Idnomic RA connector endpoint + - Default endpoint format: `https://:/RA/connector.cgi` + - TLS/SSL must be properly configured + +### Obtaining Required Configuration Information + +#### 1. RA Connector Endpoint Address + +The RA Connector endpoint is the SOAP service URL for the Registration Authority connector. + +**To find the endpoint address:** + +1. Contact your Idnomic PKI administrator +2. The standard format is: `https://:/RA/connector.cgi` +3. Verify the endpoint is accessible from the Gateway server +4. Confirm SOAP services are enabled on this endpoint + +**Example endpoint**: `https://idnomic-pki.example.com:8443/RA/connector.cgi` + +#### 2. Client Certificate for Authentication + +The Gateway authenticates to Idnomic using mutual TLS with a client certificate. + +**Steps to obtain and prepare the client certificate:** + +1. **Request a Client Certificate**: + - Contact your Idnomic PKI administrator + - Request a certificate suitable for SOAP client authentication + - Ensure the certificate includes the "Client Authentication" Extended Key Usage + +2. **Export the Certificate**: + - Export the certificate with its private key in PFX (PKCS#12) format + - Set a strong password for the PFX file + - Example filename: `gateway-client-cert.pfx` + +3. **Deploy the Certificate**: + - Copy the PFX file to a secure location on the Gateway server + - Recommended location: `C:\Program Files\Keyfactor\AnyGateway\Certificates\` (Windows) + - Or: `/opt/keyfactor/anygateway/certificates/` (Linux) + - Set appropriate file permissions to restrict access + - Record the full path and password for Gateway configuration + +#### 3. Certificate Profiles (Templates) + +Certificate profiles define the types of certificates that can be issued. The plugin automatically discovers available profiles from the Idnomic system. + +**To view available profiles:** + +1. The profiles are retrieved automatically when the CA is configured +2. Profiles appear in Keyfactor Command as "Product IDs" after CA registration +3. Each profile represents a certificate template configured in Idnomic PKI + +**Note**: Profile discovery uses the `list_profiles` SOAP operation. Ensure the client certificate has permissions to call this operation. + +#### 4. Zones + +Zones in Idnomic PKI represent organizational or security boundaries within the PKI hierarchy. Each certificate enrollment request must specify a zone. + +**Common zone examples**: +- `Default` +- `Production` +- `Test` +- `DMZ` +- Custom zones as configured in your Idnomic PKI + +**To identify available zones:** + +1. Contact your Idnomic PKI administrator for the list of configured zones +2. Zones may be visible through the `certificate_search_properties` operation +3. Document the zone names exactly as they appear in the system (case-sensitive) + +### Supported Revocation Reasons + +The plugin supports the following standard CRL revocation reasons: + +| Reason Code | Reason Name | Description | +|-------------|-------------|-------------| +| 0 | Unspecified | No specific reason provided | +| 1 | Key Compromise | Private key has been compromised | +| 2 | CA Compromise | Certificate Authority has been compromised | +| 3 | Affiliation Changed | Subject's affiliation has changed | +| 4 | Superseded | Certificate has been superseded by a new certificate | +| 5 | Cessation of Operation | Certificate is no longer needed | +| 6 | Certificate Hold | Temporary suspension (use with caution) | +| 9 | Privilege Withdrawn | Privileges have been withdrawn | +| 10 | AA Compromise | Attribute Authority has been compromised | + +**Note**: Not all Idnomic PKI configurations support all revocation reasons. Consult your Idnomic administrator for supported reasons in your environment. ## Installation @@ -89,7 +191,66 @@ TODO Requirements is a required section * **Gateway Registration** - TODO Gateway Registration is a required section + ### CA Connection Configuration + + When registering the Idnomic CA in the AnyCA Gateway, you'll need to provide the following configuration parameters: + + | Parameter | Description | Required | Example | + |-----------|-------------|----------|---------| + | **EndpointAddress** | Full URL to the Idnomic RA connector SOAP endpoint | Yes | `https://idnomic.example.com:8443/RA/connector.cgi` | + | **ClientCertLocation** | Full file path to the client certificate PFX file on the Gateway server | Yes | `C:\Certificates\gateway-client.pfx` | + | **ClientCertPassword** | Password for the client certificate PFX file | Yes | `SecureP@ssw0rd` | + | **Enabled** | Whether the CA connection is enabled | No (default: true) | `true` or `false` | + + ### Template (Product) Configuration + + Each certificate template discovered from Idnomic requires configuration when used for enrollment: + + | Parameter | Description | Required | Example | + |-----------|-------------|----------|---------| + | **Zone** | The Idnomic PKI zone where certificates will be issued | Yes | `Production` | + + **Important Notes**: + - Template names (Product IDs) are automatically discovered from Idnomic using the `list_profiles` operation + - The Zone parameter must exactly match a zone configured in your Idnomic PKI system + - Zone names are case-sensitive + - Each template can be configured with a different zone if needed + + ### Configuration Example + + **CA Configuration in AnyCA Gateway**: + ```json + { + "EndpointAddress": "https://idnomic-pki.example.com:8443/RA/connector.cgi", + "ClientCertLocation": "C:\\Program Files\\Keyfactor\\AnyGateway\\Certificates\\gateway-client.pfx", + "ClientCertPassword": "MySecurePassword123!", + "Enabled": true + } + ``` + + **Template Configuration** (for each profile): + ```json + { + "Zone": "Production" + } + ``` + + ### Gateway Registration Notes + + - Each defined Certificate Authority in the AnyCA Gateway REST can support one Idnomic CA endpoint + - If you have multiple Idnomic PKI instances or need to issue from different zones with different permissions, you must define multiple Certificate Authorities in the AnyCA Gateway + - Each CA configuration will manifest in Command as a separate CA entry + - The plugin uses SOAP-based communication exclusively; ensure the RA connector endpoint is properly configured for SOAP access + - Client certificate authentication is mandatory and cannot be disabled + - The "Enabled" flag allows you to temporarily disable a CA connection without removing the configuration + + ### Security Considerations + + 1. **Certificate Storage**: Store client certificates in a secure location with restricted file system permissions + 2. **Password Management**: Use strong passwords for client certificate PFX files and consider using a secrets management system + 3. **Network Security**: Ensure TLS/SSL is properly configured for the RA connector endpoint + 4. **Least Privilege**: Request client certificates with minimal required permissions in the Idnomic PKI system + 5. **Audit Logging**: Enable comprehensive logging in both the Gateway and Idnomic PKI for security monitoring * **CA Connection** @@ -104,8 +265,388 @@ TODO Requirements is a required section 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. TODO Custom Enrollment Parameter Creation Step is an optional section. If this section doesn't seem necessary on initial glance, please delete it. Refer to the docs on [Confluence](https://keyfactor.atlassian.net/wiki/x/SAAyHg) for more info +## Troubleshooting + +### Connection Issues +- Verify the RA connector endpoint URL is correct and accessible +- Check that the client certificate is valid and not expired +- Confirm the client certificate is trusted by the Idnomic PKI system +- Review Gateway logs for SOAP communication errors + +### Profile Discovery Issues +- Ensure the client certificate has permissions to call `list_profiles` +- Verify the RA connector is properly configured in Idnomic +- Check that profiles are published and available in the Idnomic system + +### Enrollment Failures +- Verify the Zone parameter exactly matches a configured zone in Idnomic +- Confirm the selected profile supports the requested certificate attributes +- Check that the client certificate has enrollment permissions for the specified zone +- Review Idnomic PKI logs for detailed error messages + +### Synchronization Issues +- Confirm the client certificate has permissions to call `search_for_certificates` +- Verify network connectivity and timeout settings +- For large certificate databases, consider adjusting synchronization schedules + +## Test Cases + +### Test Case 1: CA Connection Validation + +**Objective**: Verify that the Gateway can successfully connect to the Idnomic RA connector using client certificate authentication. + +**Prerequisites**: +- Idnomic PKI system is operational +- Valid client certificate (PFX) is available +- RA connector endpoint is accessible + +**Test Steps**: +1. Configure the CA in AnyCA Gateway with valid connection parameters +2. Click "Test Connection" or trigger the Ping operation +3. Observe the connection result + +**Expected Results**: +- Connection succeeds without errors +- Gateway logs show successful SOAP authentication +- No certificate validation errors occur + +**Verification**: +- Review Gateway logs for successful connection message +- Check Idnomic PKI logs for incoming authenticated connection +- Verify no SSL/TLS errors in either system + +--- + +### Test Case 2: Profile Discovery + +**Objective**: Verify that the Gateway can retrieve the list of available certificate profiles from Idnomic PKI. + +**Prerequisites**: +- CA connection is successfully configured +- At least one certificate profile is configured in Idnomic PKI +- Client certificate has permissions to call `list_profiles` + +**Test Steps**: +1. Save the CA configuration in AnyCA Gateway +2. Navigate to the template/product configuration section +3. Observe the list of available Product IDs + +**Expected Results**: +- List of profiles is populated automatically +- Profile names match those configured in Idnomic PKI +- No empty or null profile names appear + +**Verification**: +- Compare the list of profiles in Gateway with Idnomic PKI configuration +- Verify profile names are correctly displayed +- Check Gateway logs for successful `list_profiles` SOAP call + +--- + +### Test Case 3: Certificate Enrollment - Valid Request + +**Objective**: Verify successful certificate enrollment through the plugin. + +**Prerequisites**: +- CA and template are properly configured +- Valid Zone parameter is configured for the template +- Test CSR is available + +**Test Steps**: +1. Submit an enrollment request via Keyfactor Command +2. Specify the Idnomic CA and a valid template +3. Provide a valid PKCS#10 CSR +4. Wait for enrollment to complete + +**Expected Results**: +- Enrollment completes successfully +- Certificate is issued by Idnomic PKI +- Certificate is returned to Keyfactor Command +- Certificate appears in Command inventory + +**Verification**: +- Verify certificate details match the CSR +- Confirm certificate is present in Idnomic PKI database +- Check that certificate chain is properly constructed +- Validate certificate can be used for its intended purpose + +--- + +### Test Case 4: Certificate Enrollment - Invalid Zone + +**Objective**: Verify proper error handling when an invalid zone is specified. + +**Prerequisites**: +- CA and template are configured +- Zone parameter is set to a non-existent zone name + +**Test Steps**: +1. Submit an enrollment request with invalid Zone parameter +2. Observe the enrollment result + +**Expected Results**: +- Enrollment fails with clear error message +- Error message indicates invalid zone +- No certificate is issued +- System remains stable + +**Verification**: +- Check error message clarity and accuracy +- Verify Gateway logs contain detailed error information +- Confirm no partial enrollment occurred in Idnomic PKI + +--- + +### Test Case 5: Certificate Synchronization - Full Sync + +**Objective**: Verify full certificate synchronization from Idnomic PKI to Keyfactor Command. + +**Prerequisites**: +- CA is properly configured +- Multiple certificates exist in Idnomic PKI +- Synchronization is configured in Command + +**Test Steps**: +1. Trigger a full synchronization job +2. Wait for synchronization to complete +3. Verify synchronized certificate count + +**Expected Results**: +- All certificates from Idnomic PKI are synchronized +- Certificate details are accurate (subject, serial number, dates, etc.) +- No duplicate certificates appear +- Synchronization completes without errors + +**Verification**: +- Compare certificate count in Command vs. Idnomic PKI +- Spot-check several certificates for data accuracy +- Review synchronization logs for any warnings or errors +- Verify certificate chains are properly synchronized + +--- + +### Test Case 6: Certificate Synchronization - Incremental Sync + +**Objective**: Verify incremental synchronization only retrieves new certificates since last sync. + +**Prerequisites**: +- Initial full synchronization has been completed +- Timestamp of last sync is recorded +- New certificates have been issued since last sync + +**Test Steps**: +1. Note the timestamp of the last successful sync +2. Issue one or more new certificates in Idnomic PKI +3. Trigger an incremental synchronization +4. Observe synchronized certificates + +**Expected Results**: +- Only certificates issued after last sync are retrieved +- Sync completes faster than full sync +- All new certificates are properly synchronized +- Previously synchronized certificates are not duplicated + +**Verification**: +- Verify only recent certificates were processed +- Check sync duration is appropriate for certificate count +- Review Gateway logs to confirm incremental sync parameters +- Validate certificate data integrity + +--- + +### Test Case 7: Certificate Revocation - Key Compromise + +**Objective**: Verify certificate revocation with reason code 1 (Key Compromise). + +**Prerequisites**: +- A valid certificate issued through the Gateway exists +- Certificate is not already revoked + +**Test Steps**: +1. Identify a test certificate to revoke +2. Submit revocation request with reason "Key Compromise" (code 1) +3. Wait for revocation to complete + +**Expected Results**: +- Revocation succeeds +- Certificate status changes to "Revoked" in Command +- Certificate appears on CRL in Idnomic PKI +- Revocation reason is correctly recorded + +**Verification**: +- Check certificate status in Keyfactor Command +- Verify certificate appears on Idnomic CRL with correct reason code +- Confirm revocation timestamp is accurate +- Validate certificate can no longer be used for authentication + +--- + +### Test Case 8: Certificate Revocation - Multiple Reason Codes + +**Objective**: Verify that all supported revocation reason codes work correctly. + +**Prerequisites**: +- Multiple test certificates are available for revocation +- CA supports all standard revocation reasons + +**Test Steps**: +1. For each supported reason code (0, 1, 2, 3, 4, 5, 6, 9, 10): + - Select a test certificate + - Submit revocation with the specific reason code + - Verify revocation succeeds +2. Check CRL for correct reason codes + +**Expected Results**: +- All revocation requests succeed +- Each certificate shows correct revocation reason in CRL +- No errors occur for any reason code + +**Verification**: +- Download and parse CRL from Idnomic PKI +- Verify each revoked certificate has correct CRL reason code +- Confirm all revocations are logged in both systems +- Check that certificates with reason code 6 (Certificate Hold) can be resumed if supported + +--- + +### Test Case 9: Profile Properties Validation + +**Objective**: Verify that profile-specific properties are correctly enforced during enrollment. + +**Prerequisites**: +- Profiles with different configurations exist (key sizes, validity periods, etc.) +- Zone parameter is correctly configured + +**Test Steps**: +1. Attempt enrollment with CSR matching profile requirements +2. Attempt enrollment with CSR not matching profile requirements (e.g., wrong key size) +3. Observe results + +**Expected Results**: +- Valid enrollments succeed +- Invalid enrollments fail with descriptive error messages +- Profile constraints are properly enforced by Idnomic PKI + +**Verification**: +- Review error messages for clarity +- Verify Idnomic PKI rejects non-compliant requests +- Check that valid certificates meet profile specifications +- Confirm Gateway properly communicates validation errors + +--- + +### Test Case 10: Client Certificate Expiration Handling + +**Objective**: Verify proper error handling when the Gateway client certificate expires or becomes invalid. + +**Prerequisites**: +- Ability to test with expired or invalid client certificate +- Valid backup client certificate available + +**Test Steps**: +1. Configure Gateway with expired client certificate +2. Attempt any operation (Ping, Enrollment, Sync) +3. Observe error handling +4. Replace with valid certificate and retry + +**Expected Results**: +- Operations fail with clear error indicating certificate issue +- Error message specifies certificate expiration or invalidity +- After replacing certificate, operations succeed +- No system instability occurs + +**Verification**: +- Check error messages are user-friendly and actionable +- Verify Gateway logs contain detailed certificate validation errors +- Confirm system recovers gracefully after certificate replacement +- Review Idnomic PKI logs for authentication failure records + +--- + +### Test Case 11: Network Connectivity Failure + +**Objective**: Verify graceful handling of network connectivity issues to the Idnomic RA connector. + +**Prerequisites**: +- Ability to simulate network failure (firewall rule, network disconnection, etc.) + +**Test Steps**: +1. Simulate network connectivity loss to RA connector +2. Attempt enrollment operation +3. Observe error handling +4. Restore network connectivity +5. Retry operation + +**Expected Results**: +- Operation fails with clear network connectivity error +- System does not crash or become unstable +- After connectivity restoration, operations succeed +- Appropriate timeout handling occurs + +**Verification**: +- Review error messages for clarity +- Check Gateway logs show connection attempt details +- Verify timeout values are appropriate +- Confirm no memory leaks or resource issues during failure + +--- + +### Test Case 12: Concurrent Enrollment Requests + +**Objective**: Verify the Gateway can handle multiple simultaneous enrollment requests. + +**Prerequisites**: +- CA is properly configured +- Multiple test CSRs are available +- Load testing capability exists + +**Test Steps**: +1. Submit 10 enrollment requests simultaneously +2. Monitor all requests to completion +3. Verify all enrollments succeed or fail appropriately + +**Expected Results**: +- All requests are processed +- No race conditions occur +- Certificates are correctly issued for valid requests +- System remains stable under load + +**Verification**: +- Check all requests complete within reasonable time +- Verify no certificate duplication occurs +- Review Gateway logs for proper request handling +- Confirm Idnomic PKI properly queued and processed requests +- Validate certificate data integrity for all issued certificates + +--- + +### Test Case 13: Large Certificate Synchronization + +**Objective**: Verify Gateway performance when synchronizing large numbers of certificates. + +**Prerequisites**: +- Idnomic PKI has 1000+ certificates +- Adequate system resources available + +**Test Steps**: +1. Trigger full synchronization of large certificate set +2. Monitor memory usage and performance +3. Verify synchronization completes successfully + +**Expected Results**: +- Synchronization completes without timeout +- Memory usage remains within acceptable limits +- All certificates are synchronized accurately +- System remains responsive during sync + +**Verification**: +- Monitor Gateway memory and CPU usage during sync +- Verify certificate count matches Idnomic PKI +- Check for any timeout or performance warnings in logs +- Validate random sample of synchronized certificates for accuracy + +--- ## License diff --git a/docsource/configuration.md b/docsource/configuration.md index 91609ad..3249bff 100644 --- a/docsource/configuration.md +++ b/docsource/configuration.md @@ -566,3 +566,7 @@ Each certificate template discovered from Idnomic requires configuration when us --- +## Certificate Template Creation Step + +TODO Certificate Template Creation Step is a required section + From 9d045df602ac87c87e44d1ef484d980833cdcc5d Mon Sep 17 00:00:00 2001 From: Brian Hill <76450501+bhillkeyfactor@users.noreply.github.com> Date: Thu, 6 Nov 2025 21:19:16 -0500 Subject: [PATCH 17/34] Update configuration.md --- docsource/configuration.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docsource/configuration.md b/docsource/configuration.md index 3249bff..91609ad 100644 --- a/docsource/configuration.md +++ b/docsource/configuration.md @@ -566,7 +566,3 @@ Each certificate template discovered from Idnomic requires configuration when us --- -## Certificate Template Creation Step - -TODO Certificate Template Creation Step is a required section - From 4ef6671b750677b0975fe6422999a8e100ebebf1 Mon Sep 17 00:00:00 2001 From: Keyfactor Date: Fri, 7 Nov 2025 02:22:12 +0000 Subject: [PATCH 18/34] Update generated docs --- docsource/configuration.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docsource/configuration.md b/docsource/configuration.md index 91609ad..3249bff 100644 --- a/docsource/configuration.md +++ b/docsource/configuration.md @@ -566,3 +566,7 @@ Each certificate template discovered from Idnomic requires configuration when us --- +## Certificate Template Creation Step + +TODO Certificate Template Creation Step is a required section + From 9348a87497e15ee2f8167cb1cb56fb9e059da157 Mon Sep 17 00:00:00 2001 From: Brian Hill <76450501+bhillkeyfactor@users.noreply.github.com> Date: Fri, 7 Nov 2025 12:54:52 -0500 Subject: [PATCH 19/34] Update configuration.md --- docsource/configuration.md | 138 +------------------------------------ 1 file changed, 2 insertions(+), 136 deletions(-) diff --git a/docsource/configuration.md b/docsource/configuration.md index 3249bff..133cb4d 100644 --- a/docsource/configuration.md +++ b/docsource/configuration.md @@ -114,10 +114,6 @@ The plugin supports the following standard CRL revocation reasons: | 2 | CA Compromise | Certificate Authority has been compromised | | 3 | Affiliation Changed | Subject's affiliation has changed | | 4 | Superseded | Certificate has been superseded by a new certificate | -| 5 | Cessation of Operation | Certificate is no longer needed | -| 6 | Certificate Hold | Temporary suspension (use with caution) | -| 9 | Privilege Withdrawn | Privileges have been withdrawn | -| 10 | AA Compromise | Attribute Authority has been compromised | **Note**: Not all Idnomic PKI configurations support all revocation reasons. Consult your Idnomic administrator for supported reasons in your environment. @@ -148,25 +144,6 @@ Each certificate template discovered from Idnomic requires configuration when us - Zone names are case-sensitive - Each template can be configured with a different zone if needed -### Configuration Example - -**CA Configuration in AnyCA Gateway**: -```json -{ - "EndpointAddress": "https://idnomic-pki.example.com:8443/RA/connector.cgi", - "ClientCertLocation": "C:\\Program Files\\Keyfactor\\AnyGateway\\Certificates\\gateway-client.pfx", - "ClientCertPassword": "MySecurePassword123!", - "Enabled": true -} -``` - -**Template Configuration** (for each profile): -```json -{ - "Zone": "Production" -} -``` - ### Gateway Registration Notes - Each defined Certificate Authority in the AnyCA Gateway REST can support one Idnomic CA endpoint @@ -400,35 +377,7 @@ Each certificate template discovered from Idnomic requires configuration when us --- -### Test Case 8: Certificate Revocation - Multiple Reason Codes - -**Objective**: Verify that all supported revocation reason codes work correctly. - -**Prerequisites**: -- Multiple test certificates are available for revocation -- CA supports all standard revocation reasons - -**Test Steps**: -1. For each supported reason code (0, 1, 2, 3, 4, 5, 6, 9, 10): - - Select a test certificate - - Submit revocation with the specific reason code - - Verify revocation succeeds -2. Check CRL for correct reason codes - -**Expected Results**: -- All revocation requests succeed -- Each certificate shows correct revocation reason in CRL -- No errors occur for any reason code - -**Verification**: -- Download and parse CRL from Idnomic PKI -- Verify each revoked certificate has correct CRL reason code -- Confirm all revocations are logged in both systems -- Check that certificates with reason code 6 (Certificate Hold) can be resumed if supported - ---- - -### Test Case 9: Profile Properties Validation +### Test Case 8: Profile Properties Validation **Objective**: Verify that profile-specific properties are correctly enforced during enrollment. @@ -454,7 +403,7 @@ Each certificate template discovered from Idnomic requires configuration when us --- -### Test Case 10: Client Certificate Expiration Handling +### Test Case 9: Client Certificate Expiration Handling **Objective**: Verify proper error handling when the Gateway client certificate expires or becomes invalid. @@ -482,89 +431,6 @@ Each certificate template discovered from Idnomic requires configuration when us --- -### Test Case 11: Network Connectivity Failure - -**Objective**: Verify graceful handling of network connectivity issues to the Idnomic RA connector. - -**Prerequisites**: -- Ability to simulate network failure (firewall rule, network disconnection, etc.) - -**Test Steps**: -1. Simulate network connectivity loss to RA connector -2. Attempt enrollment operation -3. Observe error handling -4. Restore network connectivity -5. Retry operation - -**Expected Results**: -- Operation fails with clear network connectivity error -- System does not crash or become unstable -- After connectivity restoration, operations succeed -- Appropriate timeout handling occurs - -**Verification**: -- Review error messages for clarity -- Check Gateway logs show connection attempt details -- Verify timeout values are appropriate -- Confirm no memory leaks or resource issues during failure - ---- - -### Test Case 12: Concurrent Enrollment Requests - -**Objective**: Verify the Gateway can handle multiple simultaneous enrollment requests. - -**Prerequisites**: -- CA is properly configured -- Multiple test CSRs are available -- Load testing capability exists - -**Test Steps**: -1. Submit 10 enrollment requests simultaneously -2. Monitor all requests to completion -3. Verify all enrollments succeed or fail appropriately - -**Expected Results**: -- All requests are processed -- No race conditions occur -- Certificates are correctly issued for valid requests -- System remains stable under load - -**Verification**: -- Check all requests complete within reasonable time -- Verify no certificate duplication occurs -- Review Gateway logs for proper request handling -- Confirm Idnomic PKI properly queued and processed requests -- Validate certificate data integrity for all issued certificates - ---- - -### Test Case 13: Large Certificate Synchronization - -**Objective**: Verify Gateway performance when synchronizing large numbers of certificates. - -**Prerequisites**: -- Idnomic PKI has 1000+ certificates -- Adequate system resources available - -**Test Steps**: -1. Trigger full synchronization of large certificate set -2. Monitor memory usage and performance -3. Verify synchronization completes successfully - -**Expected Results**: -- Synchronization completes without timeout -- Memory usage remains within acceptable limits -- All certificates are synchronized accurately -- System remains responsive during sync - -**Verification**: -- Monitor Gateway memory and CPU usage during sync -- Verify certificate count matches Idnomic PKI -- Check for any timeout or performance warnings in logs -- Validate random sample of synchronized certificates for accuracy - ---- ## Certificate Template Creation Step From 2c53e833daa7ecc60272ede498645ca432e98204 Mon Sep 17 00:00:00 2001 From: Keyfactor Date: Fri, 7 Nov 2025 17:58:43 +0000 Subject: [PATCH 20/34] Update generated docs --- README.md | 139 +----------------------------------------------------- 1 file changed, 2 insertions(+), 137 deletions(-) diff --git a/README.md b/README.md index 4dbb7f8..a0602b0 100644 --- a/README.md +++ b/README.md @@ -157,10 +157,6 @@ The plugin supports the following standard CRL revocation reasons: | 2 | CA Compromise | Certificate Authority has been compromised | | 3 | Affiliation Changed | Subject's affiliation has changed | | 4 | Superseded | Certificate has been superseded by a new certificate | -| 5 | Cessation of Operation | Certificate is no longer needed | -| 6 | Certificate Hold | Temporary suspension (use with caution) | -| 9 | Privilege Withdrawn | Privileges have been withdrawn | -| 10 | AA Compromise | Attribute Authority has been compromised | **Note**: Not all Idnomic PKI configurations support all revocation reasons. Consult your Idnomic administrator for supported reasons in your environment. @@ -216,25 +212,6 @@ The plugin supports the following standard CRL revocation reasons: - Zone names are case-sensitive - Each template can be configured with a different zone if needed - ### Configuration Example - - **CA Configuration in AnyCA Gateway**: - ```json - { - "EndpointAddress": "https://idnomic-pki.example.com:8443/RA/connector.cgi", - "ClientCertLocation": "C:\\Program Files\\Keyfactor\\AnyGateway\\Certificates\\gateway-client.pfx", - "ClientCertPassword": "MySecurePassword123!", - "Enabled": true - } - ``` - - **Template Configuration** (for each profile): - ```json - { - "Zone": "Production" - } - ``` - ### Gateway Registration Notes - Each defined Certificate Authority in the AnyCA Gateway REST can support one Idnomic CA endpoint @@ -482,35 +459,7 @@ The plugin supports the following standard CRL revocation reasons: --- -### Test Case 8: Certificate Revocation - Multiple Reason Codes - -**Objective**: Verify that all supported revocation reason codes work correctly. - -**Prerequisites**: -- Multiple test certificates are available for revocation -- CA supports all standard revocation reasons - -**Test Steps**: -1. For each supported reason code (0, 1, 2, 3, 4, 5, 6, 9, 10): - - Select a test certificate - - Submit revocation with the specific reason code - - Verify revocation succeeds -2. Check CRL for correct reason codes - -**Expected Results**: -- All revocation requests succeed -- Each certificate shows correct revocation reason in CRL -- No errors occur for any reason code - -**Verification**: -- Download and parse CRL from Idnomic PKI -- Verify each revoked certificate has correct CRL reason code -- Confirm all revocations are logged in both systems -- Check that certificates with reason code 6 (Certificate Hold) can be resumed if supported - ---- - -### Test Case 9: Profile Properties Validation +### Test Case 8: Profile Properties Validation **Objective**: Verify that profile-specific properties are correctly enforced during enrollment. @@ -536,7 +485,7 @@ The plugin supports the following standard CRL revocation reasons: --- -### Test Case 10: Client Certificate Expiration Handling +### Test Case 9: Client Certificate Expiration Handling **Objective**: Verify proper error handling when the Gateway client certificate expires or becomes invalid. @@ -564,90 +513,6 @@ The plugin supports the following standard CRL revocation reasons: --- -### Test Case 11: Network Connectivity Failure - -**Objective**: Verify graceful handling of network connectivity issues to the Idnomic RA connector. - -**Prerequisites**: -- Ability to simulate network failure (firewall rule, network disconnection, etc.) - -**Test Steps**: -1. Simulate network connectivity loss to RA connector -2. Attempt enrollment operation -3. Observe error handling -4. Restore network connectivity -5. Retry operation - -**Expected Results**: -- Operation fails with clear network connectivity error -- System does not crash or become unstable -- After connectivity restoration, operations succeed -- Appropriate timeout handling occurs - -**Verification**: -- Review error messages for clarity -- Check Gateway logs show connection attempt details -- Verify timeout values are appropriate -- Confirm no memory leaks or resource issues during failure - ---- - -### Test Case 12: Concurrent Enrollment Requests - -**Objective**: Verify the Gateway can handle multiple simultaneous enrollment requests. - -**Prerequisites**: -- CA is properly configured -- Multiple test CSRs are available -- Load testing capability exists - -**Test Steps**: -1. Submit 10 enrollment requests simultaneously -2. Monitor all requests to completion -3. Verify all enrollments succeed or fail appropriately - -**Expected Results**: -- All requests are processed -- No race conditions occur -- Certificates are correctly issued for valid requests -- System remains stable under load - -**Verification**: -- Check all requests complete within reasonable time -- Verify no certificate duplication occurs -- Review Gateway logs for proper request handling -- Confirm Idnomic PKI properly queued and processed requests -- Validate certificate data integrity for all issued certificates - ---- - -### Test Case 13: Large Certificate Synchronization - -**Objective**: Verify Gateway performance when synchronizing large numbers of certificates. - -**Prerequisites**: -- Idnomic PKI has 1000+ certificates -- Adequate system resources available - -**Test Steps**: -1. Trigger full synchronization of large certificate set -2. Monitor memory usage and performance -3. Verify synchronization completes successfully - -**Expected Results**: -- Synchronization completes without timeout -- Memory usage remains within acceptable limits -- All certificates are synchronized accurately -- System remains responsive during sync - -**Verification**: -- Monitor Gateway memory and CPU usage during sync -- Verify certificate count matches Idnomic PKI -- Check for any timeout or performance warnings in logs -- Validate random sample of synchronized certificates for accuracy - ---- - ## License From 210a7fed86fe632f9caf271bd06a041e213238cb Mon Sep 17 00:00:00 2001 From: Brian Hill <76450501+bhillkeyfactor@users.noreply.github.com> Date: Fri, 7 Nov 2025 13:12:42 -0500 Subject: [PATCH 21/34] Update configuration.md --- docsource/configuration.md | 28 ---------------------------- 1 file changed, 28 deletions(-) diff --git a/docsource/configuration.md b/docsource/configuration.md index 133cb4d..52dc4df 100644 --- a/docsource/configuration.md +++ b/docsource/configuration.md @@ -403,34 +403,6 @@ Each certificate template discovered from Idnomic requires configuration when us --- -### Test Case 9: Client Certificate Expiration Handling - -**Objective**: Verify proper error handling when the Gateway client certificate expires or becomes invalid. - -**Prerequisites**: -- Ability to test with expired or invalid client certificate -- Valid backup client certificate available - -**Test Steps**: -1. Configure Gateway with expired client certificate -2. Attempt any operation (Ping, Enrollment, Sync) -3. Observe error handling -4. Replace with valid certificate and retry - -**Expected Results**: -- Operations fail with clear error indicating certificate issue -- Error message specifies certificate expiration or invalidity -- After replacing certificate, operations succeed -- No system instability occurs - -**Verification**: -- Check error messages are user-friendly and actionable -- Verify Gateway logs contain detailed certificate validation errors -- Confirm system recovers gracefully after certificate replacement -- Review Idnomic PKI logs for authentication failure records - ---- - ## Certificate Template Creation Step From be3d7973ea712204db6517b2ac1d81e38d31291c Mon Sep 17 00:00:00 2001 From: Keyfactor Date: Fri, 7 Nov 2025 18:16:14 +0000 Subject: [PATCH 22/34] Update generated docs --- README.md | 28 ---------------------------- 1 file changed, 28 deletions(-) diff --git a/README.md b/README.md index a0602b0..b98371c 100644 --- a/README.md +++ b/README.md @@ -485,34 +485,6 @@ The plugin supports the following standard CRL revocation reasons: --- -### Test Case 9: Client Certificate Expiration Handling - -**Objective**: Verify proper error handling when the Gateway client certificate expires or becomes invalid. - -**Prerequisites**: -- Ability to test with expired or invalid client certificate -- Valid backup client certificate available - -**Test Steps**: -1. Configure Gateway with expired client certificate -2. Attempt any operation (Ping, Enrollment, Sync) -3. Observe error handling -4. Replace with valid certificate and retry - -**Expected Results**: -- Operations fail with clear error indicating certificate issue -- Error message specifies certificate expiration or invalidity -- After replacing certificate, operations succeed -- No system instability occurs - -**Verification**: -- Check error messages are user-friendly and actionable -- Verify Gateway logs contain detailed certificate validation errors -- Confirm system recovers gracefully after certificate replacement -- Review Idnomic PKI logs for authentication failure records - ---- - ## License From 1bfe1d867f7803c25e54411bd368e6277abfffa4 Mon Sep 17 00:00:00 2001 From: Brian Hill <76450501+bhillkeyfactor@users.noreply.github.com> Date: Fri, 7 Nov 2025 14:04:29 -0500 Subject: [PATCH 23/34] Update configuration.md --- docsource/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docsource/configuration.md b/docsource/configuration.md index 52dc4df..b2eca29 100644 --- a/docsource/configuration.md +++ b/docsource/configuration.md @@ -22,7 +22,7 @@ The Idnomic PKI Gateway plugin extends the capabilities of Idnomic PKI (formerly Before configuring the AnyCA Gateway plugin, ensure the following prerequisites are met on your Idnomic PKI system: 1. **Idnomic PKI Installation**: - - Idnomic PKI server must be installed and operational + - Idnomic PKI server must be installed and operational. Only tested with 4.9.2 version of IDNOMIC. Other version may or may not work. - RA (Registration Authority) connector must be enabled and accessible - SOAP interface must be configured and reachable From cbad7856187e00e54bbf08e044c73588a6888c50 Mon Sep 17 00:00:00 2001 From: Keyfactor Date: Fri, 7 Nov 2025 19:06:52 +0000 Subject: [PATCH 24/34] Update generated docs --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b98371c..988e5f5 100644 --- a/README.md +++ b/README.md @@ -65,7 +65,7 @@ The Idnomic PKI Gateway AnyCA Gateway REST plugin is supported by Keyfactor for Before configuring the AnyCA Gateway plugin, ensure the following prerequisites are met on your Idnomic PKI system: 1. **Idnomic PKI Installation**: - - Idnomic PKI server must be installed and operational + - Idnomic PKI server must be installed and operational. Only tested with 4.9.2 version of IDNOMIC. Other version may or may not work. - RA (Registration Authority) connector must be enabled and accessible - SOAP interface must be configured and reachable From 908049ef5c5735d8b485f542400cd0c4b1bc2acb Mon Sep 17 00:00:00 2001 From: Brian Hill <76450501+bhillkeyfactor@users.noreply.github.com> Date: Tue, 11 Nov 2025 13:40:20 -0500 Subject: [PATCH 25/34] Create idnomic.md --- docsource/idnomic.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 docsource/idnomic.md diff --git a/docsource/idnomic.md b/docsource/idnomic.md new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/docsource/idnomic.md @@ -0,0 +1 @@ + From 79b0120d0597f949070ddf22d10c915a4a905164 Mon Sep 17 00:00:00 2001 From: Brian Hill <76450501+bhillkeyfactor@users.noreply.github.com> Date: Tue, 11 Nov 2025 13:41:00 -0500 Subject: [PATCH 26/34] Update configuration.md --- docsource/configuration.md | 394 ------------------------------------- 1 file changed, 394 deletions(-) diff --git a/docsource/configuration.md b/docsource/configuration.md index b2eca29..c31ba53 100644 --- a/docsource/configuration.md +++ b/docsource/configuration.md @@ -14,397 +14,3 @@ The Idnomic PKI Gateway plugin extends the capabilities of Idnomic PKI (formerly * **Certificate Revocation**: * Request revocation of previously issued certificates * Support for standard CRL revocation reasons - -## Requirements - -### Idnomic PKI System Prerequisites - -Before configuring the AnyCA Gateway plugin, ensure the following prerequisites are met on your Idnomic PKI system: - -1. **Idnomic PKI Installation**: - - Idnomic PKI server must be installed and operational. Only tested with 4.9.2 version of IDNOMIC. Other version may or may not work. - - RA (Registration Authority) connector must be enabled and accessible - - SOAP interface must be configured and reachable - -2. **Client Certificate Authentication**: - - A client certificate must be issued for the AnyCA Gateway service to authenticate to Idnomic - - The certificate must be trusted by the Idnomic PKI system - - Certificate must be exported in PFX/PKCS#12 format with private key - -3. **Network Connectivity**: - - Gateway server must have network access to the Idnomic RA connector endpoint - - Default endpoint format: `https://:/RA/connector.cgi` - - TLS/SSL must be properly configured - -### Obtaining Required Configuration Information - -#### 1. RA Connector Endpoint Address - -The RA Connector endpoint is the SOAP service URL for the Registration Authority connector. - -**To find the endpoint address:** - -1. Contact your Idnomic PKI administrator -2. The standard format is: `https://:/RA/connector.cgi` -3. Verify the endpoint is accessible from the Gateway server -4. Confirm SOAP services are enabled on this endpoint - -**Example endpoint**: `https://idnomic-pki.example.com:8443/RA/connector.cgi` - -#### 2. Client Certificate for Authentication - -The Gateway authenticates to Idnomic using mutual TLS with a client certificate. - -**Steps to obtain and prepare the client certificate:** - -1. **Request a Client Certificate**: - - Contact your Idnomic PKI administrator - - Request a certificate suitable for SOAP client authentication - - Ensure the certificate includes the "Client Authentication" Extended Key Usage - -2. **Export the Certificate**: - - Export the certificate with its private key in PFX (PKCS#12) format - - Set a strong password for the PFX file - - Example filename: `gateway-client-cert.pfx` - -3. **Deploy the Certificate**: - - Copy the PFX file to a secure location on the Gateway server - - Recommended location: `C:\Program Files\Keyfactor\AnyGateway\Certificates\` (Windows) - - Or: `/opt/keyfactor/anygateway/certificates/` (Linux) - - Set appropriate file permissions to restrict access - - Record the full path and password for Gateway configuration - -#### 3. Certificate Profiles (Templates) - -Certificate profiles define the types of certificates that can be issued. The plugin automatically discovers available profiles from the Idnomic system. - -**To view available profiles:** - -1. The profiles are retrieved automatically when the CA is configured -2. Profiles appear in Keyfactor Command as "Product IDs" after CA registration -3. Each profile represents a certificate template configured in Idnomic PKI - -**Note**: Profile discovery uses the `list_profiles` SOAP operation. Ensure the client certificate has permissions to call this operation. - -#### 4. Zones - -Zones in Idnomic PKI represent organizational or security boundaries within the PKI hierarchy. Each certificate enrollment request must specify a zone. - -**Common zone examples**: -- `Default` -- `Production` -- `Test` -- `DMZ` -- Custom zones as configured in your Idnomic PKI - -**To identify available zones:** - -1. Contact your Idnomic PKI administrator for the list of configured zones -2. Zones may be visible through the `certificate_search_properties` operation -3. Document the zone names exactly as they appear in the system (case-sensitive) - -### Supported Revocation Reasons - -The plugin supports the following standard CRL revocation reasons: - -| Reason Code | Reason Name | Description | -|-------------|-------------|-------------| -| 0 | Unspecified | No specific reason provided | -| 1 | Key Compromise | Private key has been compromised | -| 2 | CA Compromise | Certificate Authority has been compromised | -| 3 | Affiliation Changed | Subject's affiliation has changed | -| 4 | Superseded | Certificate has been superseded by a new certificate | - -**Note**: Not all Idnomic PKI configurations support all revocation reasons. Consult your Idnomic administrator for supported reasons in your environment. - -## Gateway Registration - -### CA Connection Configuration - -When registering the Idnomic CA in the AnyCA Gateway, you'll need to provide the following configuration parameters: - -| Parameter | Description | Required | Example | -|-----------|-------------|----------|---------| -| **EndpointAddress** | Full URL to the Idnomic RA connector SOAP endpoint | Yes | `https://idnomic.example.com:8443/RA/connector.cgi` | -| **ClientCertLocation** | Full file path to the client certificate PFX file on the Gateway server | Yes | `C:\Certificates\gateway-client.pfx` | -| **ClientCertPassword** | Password for the client certificate PFX file | Yes | `SecureP@ssw0rd` | -| **Enabled** | Whether the CA connection is enabled | No (default: true) | `true` or `false` | - -### Template (Product) Configuration - -Each certificate template discovered from Idnomic requires configuration when used for enrollment: - -| Parameter | Description | Required | Example | -|-----------|-------------|----------|---------| -| **Zone** | The Idnomic PKI zone where certificates will be issued | Yes | `Production` | - -**Important Notes**: -- Template names (Product IDs) are automatically discovered from Idnomic using the `list_profiles` operation -- The Zone parameter must exactly match a zone configured in your Idnomic PKI system -- Zone names are case-sensitive -- Each template can be configured with a different zone if needed - -### Gateway Registration Notes - -- Each defined Certificate Authority in the AnyCA Gateway REST can support one Idnomic CA endpoint -- If you have multiple Idnomic PKI instances or need to issue from different zones with different permissions, you must define multiple Certificate Authorities in the AnyCA Gateway -- Each CA configuration will manifest in Command as a separate CA entry -- The plugin uses SOAP-based communication exclusively; ensure the RA connector endpoint is properly configured for SOAP access -- Client certificate authentication is mandatory and cannot be disabled -- The "Enabled" flag allows you to temporarily disable a CA connection without removing the configuration - -### Security Considerations - -1. **Certificate Storage**: Store client certificates in a secure location with restricted file system permissions -2. **Password Management**: Use strong passwords for client certificate PFX files and consider using a secrets management system -3. **Network Security**: Ensure TLS/SSL is properly configured for the RA connector endpoint -4. **Least Privilege**: Request client certificates with minimal required permissions in the Idnomic PKI system -5. **Audit Logging**: Enable comprehensive logging in both the Gateway and Idnomic PKI for security monitoring - -## Troubleshooting - -### Connection Issues -- Verify the RA connector endpoint URL is correct and accessible -- Check that the client certificate is valid and not expired -- Confirm the client certificate is trusted by the Idnomic PKI system -- Review Gateway logs for SOAP communication errors - -### Profile Discovery Issues -- Ensure the client certificate has permissions to call `list_profiles` -- Verify the RA connector is properly configured in Idnomic -- Check that profiles are published and available in the Idnomic system - -### Enrollment Failures -- Verify the Zone parameter exactly matches a configured zone in Idnomic -- Confirm the selected profile supports the requested certificate attributes -- Check that the client certificate has enrollment permissions for the specified zone -- Review Idnomic PKI logs for detailed error messages - -### Synchronization Issues -- Confirm the client certificate has permissions to call `search_for_certificates` -- Verify network connectivity and timeout settings -- For large certificate databases, consider adjusting synchronization schedules - -## Test Cases - -### Test Case 1: CA Connection Validation - -**Objective**: Verify that the Gateway can successfully connect to the Idnomic RA connector using client certificate authentication. - -**Prerequisites**: -- Idnomic PKI system is operational -- Valid client certificate (PFX) is available -- RA connector endpoint is accessible - -**Test Steps**: -1. Configure the CA in AnyCA Gateway with valid connection parameters -2. Click "Test Connection" or trigger the Ping operation -3. Observe the connection result - -**Expected Results**: -- Connection succeeds without errors -- Gateway logs show successful SOAP authentication -- No certificate validation errors occur - -**Verification**: -- Review Gateway logs for successful connection message -- Check Idnomic PKI logs for incoming authenticated connection -- Verify no SSL/TLS errors in either system - ---- - -### Test Case 2: Profile Discovery - -**Objective**: Verify that the Gateway can retrieve the list of available certificate profiles from Idnomic PKI. - -**Prerequisites**: -- CA connection is successfully configured -- At least one certificate profile is configured in Idnomic PKI -- Client certificate has permissions to call `list_profiles` - -**Test Steps**: -1. Save the CA configuration in AnyCA Gateway -2. Navigate to the template/product configuration section -3. Observe the list of available Product IDs - -**Expected Results**: -- List of profiles is populated automatically -- Profile names match those configured in Idnomic PKI -- No empty or null profile names appear - -**Verification**: -- Compare the list of profiles in Gateway with Idnomic PKI configuration -- Verify profile names are correctly displayed -- Check Gateway logs for successful `list_profiles` SOAP call - ---- - -### Test Case 3: Certificate Enrollment - Valid Request - -**Objective**: Verify successful certificate enrollment through the plugin. - -**Prerequisites**: -- CA and template are properly configured -- Valid Zone parameter is configured for the template -- Test CSR is available - -**Test Steps**: -1. Submit an enrollment request via Keyfactor Command -2. Specify the Idnomic CA and a valid template -3. Provide a valid PKCS#10 CSR -4. Wait for enrollment to complete - -**Expected Results**: -- Enrollment completes successfully -- Certificate is issued by Idnomic PKI -- Certificate is returned to Keyfactor Command -- Certificate appears in Command inventory - -**Verification**: -- Verify certificate details match the CSR -- Confirm certificate is present in Idnomic PKI database -- Check that certificate chain is properly constructed -- Validate certificate can be used for its intended purpose - ---- - -### Test Case 4: Certificate Enrollment - Invalid Zone - -**Objective**: Verify proper error handling when an invalid zone is specified. - -**Prerequisites**: -- CA and template are configured -- Zone parameter is set to a non-existent zone name - -**Test Steps**: -1. Submit an enrollment request with invalid Zone parameter -2. Observe the enrollment result - -**Expected Results**: -- Enrollment fails with clear error message -- Error message indicates invalid zone -- No certificate is issued -- System remains stable - -**Verification**: -- Check error message clarity and accuracy -- Verify Gateway logs contain detailed error information -- Confirm no partial enrollment occurred in Idnomic PKI - ---- - -### Test Case 5: Certificate Synchronization - Full Sync - -**Objective**: Verify full certificate synchronization from Idnomic PKI to Keyfactor Command. - -**Prerequisites**: -- CA is properly configured -- Multiple certificates exist in Idnomic PKI -- Synchronization is configured in Command - -**Test Steps**: -1. Trigger a full synchronization job -2. Wait for synchronization to complete -3. Verify synchronized certificate count - -**Expected Results**: -- All certificates from Idnomic PKI are synchronized -- Certificate details are accurate (subject, serial number, dates, etc.) -- No duplicate certificates appear -- Synchronization completes without errors - -**Verification**: -- Compare certificate count in Command vs. Idnomic PKI -- Spot-check several certificates for data accuracy -- Review synchronization logs for any warnings or errors -- Verify certificate chains are properly synchronized - ---- - -### Test Case 6: Certificate Synchronization - Incremental Sync - -**Objective**: Verify incremental synchronization only retrieves new certificates since last sync. - -**Prerequisites**: -- Initial full synchronization has been completed -- Timestamp of last sync is recorded -- New certificates have been issued since last sync - -**Test Steps**: -1. Note the timestamp of the last successful sync -2. Issue one or more new certificates in Idnomic PKI -3. Trigger an incremental synchronization -4. Observe synchronized certificates - -**Expected Results**: -- Only certificates issued after last sync are retrieved -- Sync completes faster than full sync -- All new certificates are properly synchronized -- Previously synchronized certificates are not duplicated - -**Verification**: -- Verify only recent certificates were processed -- Check sync duration is appropriate for certificate count -- Review Gateway logs to confirm incremental sync parameters -- Validate certificate data integrity - ---- - -### Test Case 7: Certificate Revocation - Key Compromise - -**Objective**: Verify certificate revocation with reason code 1 (Key Compromise). - -**Prerequisites**: -- A valid certificate issued through the Gateway exists -- Certificate is not already revoked - -**Test Steps**: -1. Identify a test certificate to revoke -2. Submit revocation request with reason "Key Compromise" (code 1) -3. Wait for revocation to complete - -**Expected Results**: -- Revocation succeeds -- Certificate status changes to "Revoked" in Command -- Certificate appears on CRL in Idnomic PKI -- Revocation reason is correctly recorded - -**Verification**: -- Check certificate status in Keyfactor Command -- Verify certificate appears on Idnomic CRL with correct reason code -- Confirm revocation timestamp is accurate -- Validate certificate can no longer be used for authentication - ---- - -### Test Case 8: Profile Properties Validation - -**Objective**: Verify that profile-specific properties are correctly enforced during enrollment. - -**Prerequisites**: -- Profiles with different configurations exist (key sizes, validity periods, etc.) -- Zone parameter is correctly configured - -**Test Steps**: -1. Attempt enrollment with CSR matching profile requirements -2. Attempt enrollment with CSR not matching profile requirements (e.g., wrong key size) -3. Observe results - -**Expected Results**: -- Valid enrollments succeed -- Invalid enrollments fail with descriptive error messages -- Profile constraints are properly enforced by Idnomic PKI - -**Verification**: -- Review error messages for clarity -- Verify Idnomic PKI rejects non-compliant requests -- Check that valid certificates meet profile specifications -- Confirm Gateway properly communicates validation errors - ---- - - -## Certificate Template Creation Step - -TODO Certificate Template Creation Step is a required section - From 2016ac660937df4e0773889257f7093824e0e954 Mon Sep 17 00:00:00 2001 From: Brian Hill <76450501+bhillkeyfactor@users.noreply.github.com> Date: Tue, 11 Nov 2025 13:41:18 -0500 Subject: [PATCH 27/34] Update idnomic.md --- docsource/idnomic.md | 387 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 387 insertions(+) diff --git a/docsource/idnomic.md b/docsource/idnomic.md index 8b13789..b315d61 100644 --- a/docsource/idnomic.md +++ b/docsource/idnomic.md @@ -1 +1,388 @@ +## Requirements + +### Idnomic PKI System Prerequisites + +Before configuring the AnyCA Gateway plugin, ensure the following prerequisites are met on your Idnomic PKI system: + +1. **Idnomic PKI Installation**: + - Idnomic PKI server must be installed and operational. Only tested with 4.9.2 version of IDNOMIC. Other version may or may not work. + - RA (Registration Authority) connector must be enabled and accessible + - SOAP interface must be configured and reachable + +2. **Client Certificate Authentication**: + - A client certificate must be issued for the AnyCA Gateway service to authenticate to Idnomic + - The certificate must be trusted by the Idnomic PKI system + - Certificate must be exported in PFX/PKCS#12 format with private key + +3. **Network Connectivity**: + - Gateway server must have network access to the Idnomic RA connector endpoint + - Default endpoint format: `https://:/RA/connector.cgi` + - TLS/SSL must be properly configured + +### Obtaining Required Configuration Information + +#### 1. RA Connector Endpoint Address + +The RA Connector endpoint is the SOAP service URL for the Registration Authority connector. + +**To find the endpoint address:** + +1. Contact your Idnomic PKI administrator +2. The standard format is: `https://:/RA/connector.cgi` +3. Verify the endpoint is accessible from the Gateway server +4. Confirm SOAP services are enabled on this endpoint + +**Example endpoint**: `https://idnomic-pki.example.com:8443/RA/connector.cgi` + +#### 2. Client Certificate for Authentication + +The Gateway authenticates to Idnomic using mutual TLS with a client certificate. + +**Steps to obtain and prepare the client certificate:** + +1. **Request a Client Certificate**: + - Contact your Idnomic PKI administrator + - Request a certificate suitable for SOAP client authentication + - Ensure the certificate includes the "Client Authentication" Extended Key Usage + +2. **Export the Certificate**: + - Export the certificate with its private key in PFX (PKCS#12) format + - Set a strong password for the PFX file + - Example filename: `gateway-client-cert.pfx` + +3. **Deploy the Certificate**: + - Copy the PFX file to a secure location on the Gateway server + - Recommended location: `C:\Program Files\Keyfactor\AnyGateway\Certificates\` (Windows) + - Or: `/opt/keyfactor/anygateway/certificates/` (Linux) + - Set appropriate file permissions to restrict access + - Record the full path and password for Gateway configuration + +#### 3. Certificate Profiles (Templates) + +Certificate profiles define the types of certificates that can be issued. The plugin automatically discovers available profiles from the Idnomic system. + +**To view available profiles:** + +1. The profiles are retrieved automatically when the CA is configured +2. Profiles appear in Keyfactor Command as "Product IDs" after CA registration +3. Each profile represents a certificate template configured in Idnomic PKI + +**Note**: Profile discovery uses the `list_profiles` SOAP operation. Ensure the client certificate has permissions to call this operation. + +#### 4. Zones + +Zones in Idnomic PKI represent organizational or security boundaries within the PKI hierarchy. Each certificate enrollment request must specify a zone. + +**Common zone examples**: +- `Default` +- `Production` +- `Test` +- `DMZ` +- Custom zones as configured in your Idnomic PKI + +**To identify available zones:** + +1. Contact your Idnomic PKI administrator for the list of configured zones +2. Zones may be visible through the `certificate_search_properties` operation +3. Document the zone names exactly as they appear in the system (case-sensitive) + +### Supported Revocation Reasons + +The plugin supports the following standard CRL revocation reasons: + +| Reason Code | Reason Name | Description | +|-------------|-------------|-------------| +| 0 | Unspecified | No specific reason provided | +| 1 | Key Compromise | Private key has been compromised | +| 2 | CA Compromise | Certificate Authority has been compromised | +| 3 | Affiliation Changed | Subject's affiliation has changed | +| 4 | Superseded | Certificate has been superseded by a new certificate | + +**Note**: Not all Idnomic PKI configurations support all revocation reasons. Consult your Idnomic administrator for supported reasons in your environment. + +## Gateway Registration + +### CA Connection Configuration + +When registering the Idnomic CA in the AnyCA Gateway, you'll need to provide the following configuration parameters: + +| Parameter | Description | Required | Example | +|-----------|-------------|----------|---------| +| **EndpointAddress** | Full URL to the Idnomic RA connector SOAP endpoint | Yes | `https://idnomic.example.com:8443/RA/connector.cgi` | +| **ClientCertLocation** | Full file path to the client certificate PFX file on the Gateway server | Yes | `C:\Certificates\gateway-client.pfx` | +| **ClientCertPassword** | Password for the client certificate PFX file | Yes | `SecureP@ssw0rd` | +| **Enabled** | Whether the CA connection is enabled | No (default: true) | `true` or `false` | + +### Template (Product) Configuration + +Each certificate template discovered from Idnomic requires configuration when used for enrollment: + +| Parameter | Description | Required | Example | +|-----------|-------------|----------|---------| +| **Zone** | The Idnomic PKI zone where certificates will be issued | Yes | `Production` | + +**Important Notes**: +- Template names (Product IDs) are automatically discovered from Idnomic using the `list_profiles` operation +- The Zone parameter must exactly match a zone configured in your Idnomic PKI system +- Zone names are case-sensitive +- Each template can be configured with a different zone if needed + +### Gateway Registration Notes + +- Each defined Certificate Authority in the AnyCA Gateway REST can support one Idnomic CA endpoint +- If you have multiple Idnomic PKI instances or need to issue from different zones with different permissions, you must define multiple Certificate Authorities in the AnyCA Gateway +- Each CA configuration will manifest in Command as a separate CA entry +- The plugin uses SOAP-based communication exclusively; ensure the RA connector endpoint is properly configured for SOAP access +- Client certificate authentication is mandatory and cannot be disabled +- The "Enabled" flag allows you to temporarily disable a CA connection without removing the configuration + +### Security Considerations + +1. **Certificate Storage**: Store client certificates in a secure location with restricted file system permissions +2. **Password Management**: Use strong passwords for client certificate PFX files and consider using a secrets management system +3. **Network Security**: Ensure TLS/SSL is properly configured for the RA connector endpoint +4. **Least Privilege**: Request client certificates with minimal required permissions in the Idnomic PKI system +5. **Audit Logging**: Enable comprehensive logging in both the Gateway and Idnomic PKI for security monitoring + +## Troubleshooting + +### Connection Issues +- Verify the RA connector endpoint URL is correct and accessible +- Check that the client certificate is valid and not expired +- Confirm the client certificate is trusted by the Idnomic PKI system +- Review Gateway logs for SOAP communication errors + +### Profile Discovery Issues +- Ensure the client certificate has permissions to call `list_profiles` +- Verify the RA connector is properly configured in Idnomic +- Check that profiles are published and available in the Idnomic system + +### Enrollment Failures +- Verify the Zone parameter exactly matches a configured zone in Idnomic +- Confirm the selected profile supports the requested certificate attributes +- Check that the client certificate has enrollment permissions for the specified zone +- Review Idnomic PKI logs for detailed error messages + +### Synchronization Issues +- Confirm the client certificate has permissions to call `search_for_certificates` +- Verify network connectivity and timeout settings +- For large certificate databases, consider adjusting synchronization schedules + +## Test Cases + +### Test Case 1: CA Connection Validation + +**Objective**: Verify that the Gateway can successfully connect to the Idnomic RA connector using client certificate authentication. + +**Prerequisites**: +- Idnomic PKI system is operational +- Valid client certificate (PFX) is available +- RA connector endpoint is accessible + +**Test Steps**: +1. Configure the CA in AnyCA Gateway with valid connection parameters +2. Click "Test Connection" or trigger the Ping operation +3. Observe the connection result + +**Expected Results**: +- Connection succeeds without errors +- Gateway logs show successful SOAP authentication +- No certificate validation errors occur + +**Verification**: +- Review Gateway logs for successful connection message +- Check Idnomic PKI logs for incoming authenticated connection +- Verify no SSL/TLS errors in either system + +--- + +### Test Case 2: Profile Discovery + +**Objective**: Verify that the Gateway can retrieve the list of available certificate profiles from Idnomic PKI. + +**Prerequisites**: +- CA connection is successfully configured +- At least one certificate profile is configured in Idnomic PKI +- Client certificate has permissions to call `list_profiles` + +**Test Steps**: +1. Save the CA configuration in AnyCA Gateway +2. Navigate to the template/product configuration section +3. Observe the list of available Product IDs + +**Expected Results**: +- List of profiles is populated automatically +- Profile names match those configured in Idnomic PKI +- No empty or null profile names appear + +**Verification**: +- Compare the list of profiles in Gateway with Idnomic PKI configuration +- Verify profile names are correctly displayed +- Check Gateway logs for successful `list_profiles` SOAP call + +--- + +### Test Case 3: Certificate Enrollment - Valid Request + +**Objective**: Verify successful certificate enrollment through the plugin. + +**Prerequisites**: +- CA and template are properly configured +- Valid Zone parameter is configured for the template +- Test CSR is available + +**Test Steps**: +1. Submit an enrollment request via Keyfactor Command +2. Specify the Idnomic CA and a valid template +3. Provide a valid PKCS#10 CSR +4. Wait for enrollment to complete + +**Expected Results**: +- Enrollment completes successfully +- Certificate is issued by Idnomic PKI +- Certificate is returned to Keyfactor Command +- Certificate appears in Command inventory + +**Verification**: +- Verify certificate details match the CSR +- Confirm certificate is present in Idnomic PKI database +- Check that certificate chain is properly constructed +- Validate certificate can be used for its intended purpose + +--- + +### Test Case 4: Certificate Enrollment - Invalid Zone + +**Objective**: Verify proper error handling when an invalid zone is specified. + +**Prerequisites**: +- CA and template are configured +- Zone parameter is set to a non-existent zone name + +**Test Steps**: +1. Submit an enrollment request with invalid Zone parameter +2. Observe the enrollment result + +**Expected Results**: +- Enrollment fails with clear error message +- Error message indicates invalid zone +- No certificate is issued +- System remains stable + +**Verification**: +- Check error message clarity and accuracy +- Verify Gateway logs contain detailed error information +- Confirm no partial enrollment occurred in Idnomic PKI + +--- + +### Test Case 5: Certificate Synchronization - Full Sync + +**Objective**: Verify full certificate synchronization from Idnomic PKI to Keyfactor Command. + +**Prerequisites**: +- CA is properly configured +- Multiple certificates exist in Idnomic PKI +- Synchronization is configured in Command + +**Test Steps**: +1. Trigger a full synchronization job +2. Wait for synchronization to complete +3. Verify synchronized certificate count + +**Expected Results**: +- All certificates from Idnomic PKI are synchronized +- Certificate details are accurate (subject, serial number, dates, etc.) +- No duplicate certificates appear +- Synchronization completes without errors + +**Verification**: +- Compare certificate count in Command vs. Idnomic PKI +- Spot-check several certificates for data accuracy +- Review synchronization logs for any warnings or errors +- Verify certificate chains are properly synchronized + +--- + +### Test Case 6: Certificate Synchronization - Incremental Sync + +**Objective**: Verify incremental synchronization only retrieves new certificates since last sync. + +**Prerequisites**: +- Initial full synchronization has been completed +- Timestamp of last sync is recorded +- New certificates have been issued since last sync + +**Test Steps**: +1. Note the timestamp of the last successful sync +2. Issue one or more new certificates in Idnomic PKI +3. Trigger an incremental synchronization +4. Observe synchronized certificates + +**Expected Results**: +- Only certificates issued after last sync are retrieved +- Sync completes faster than full sync +- All new certificates are properly synchronized +- Previously synchronized certificates are not duplicated + +**Verification**: +- Verify only recent certificates were processed +- Check sync duration is appropriate for certificate count +- Review Gateway logs to confirm incremental sync parameters +- Validate certificate data integrity + +--- + +### Test Case 7: Certificate Revocation - Key Compromise + +**Objective**: Verify certificate revocation with reason code 1 (Key Compromise). + +**Prerequisites**: +- A valid certificate issued through the Gateway exists +- Certificate is not already revoked + +**Test Steps**: +1. Identify a test certificate to revoke +2. Submit revocation request with reason "Key Compromise" (code 1) +3. Wait for revocation to complete + +**Expected Results**: +- Revocation succeeds +- Certificate status changes to "Revoked" in Command +- Certificate appears on CRL in Idnomic PKI +- Revocation reason is correctly recorded + +**Verification**: +- Check certificate status in Keyfactor Command +- Verify certificate appears on Idnomic CRL with correct reason code +- Confirm revocation timestamp is accurate +- Validate certificate can no longer be used for authentication + +--- + +### Test Case 8: Profile Properties Validation + +**Objective**: Verify that profile-specific properties are correctly enforced during enrollment. + +**Prerequisites**: +- Profiles with different configurations exist (key sizes, validity periods, etc.) +- Zone parameter is correctly configured + +**Test Steps**: +1. Attempt enrollment with CSR matching profile requirements +2. Attempt enrollment with CSR not matching profile requirements (e.g., wrong key size) +3. Observe results + +**Expected Results**: +- Valid enrollments succeed +- Invalid enrollments fail with descriptive error messages +- Profile constraints are properly enforced by Idnomic PKI + +**Verification**: +- Review error messages for clarity +- Verify Idnomic PKI rejects non-compliant requests +- Check that valid certificates meet profile specifications +- Confirm Gateway properly communicates validation errors + +--- From fa4755cb9aa65332d8231a38915de56463fdc1e9 Mon Sep 17 00:00:00 2001 From: Keyfactor Date: Tue, 11 Nov 2025 18:44:09 +0000 Subject: [PATCH 28/34] Update generated docs --- README.md | 384 +------------------------------------ docsource/configuration.md | 13 ++ 2 files changed, 15 insertions(+), 382 deletions(-) diff --git a/README.md b/README.md index 988e5f5..5a28223 100644 --- a/README.md +++ b/README.md @@ -60,105 +60,7 @@ The Idnomic PKI Gateway AnyCA Gateway REST plugin is supported by Keyfactor for ## Requirements -### Idnomic PKI System Prerequisites - -Before configuring the AnyCA Gateway plugin, ensure the following prerequisites are met on your Idnomic PKI system: - -1. **Idnomic PKI Installation**: - - Idnomic PKI server must be installed and operational. Only tested with 4.9.2 version of IDNOMIC. Other version may or may not work. - - RA (Registration Authority) connector must be enabled and accessible - - SOAP interface must be configured and reachable - -2. **Client Certificate Authentication**: - - A client certificate must be issued for the AnyCA Gateway service to authenticate to Idnomic - - The certificate must be trusted by the Idnomic PKI system - - Certificate must be exported in PFX/PKCS#12 format with private key - -3. **Network Connectivity**: - - Gateway server must have network access to the Idnomic RA connector endpoint - - Default endpoint format: `https://:/RA/connector.cgi` - - TLS/SSL must be properly configured - -### Obtaining Required Configuration Information - -#### 1. RA Connector Endpoint Address - -The RA Connector endpoint is the SOAP service URL for the Registration Authority connector. - -**To find the endpoint address:** - -1. Contact your Idnomic PKI administrator -2. The standard format is: `https://:/RA/connector.cgi` -3. Verify the endpoint is accessible from the Gateway server -4. Confirm SOAP services are enabled on this endpoint - -**Example endpoint**: `https://idnomic-pki.example.com:8443/RA/connector.cgi` - -#### 2. Client Certificate for Authentication - -The Gateway authenticates to Idnomic using mutual TLS with a client certificate. - -**Steps to obtain and prepare the client certificate:** - -1. **Request a Client Certificate**: - - Contact your Idnomic PKI administrator - - Request a certificate suitable for SOAP client authentication - - Ensure the certificate includes the "Client Authentication" Extended Key Usage - -2. **Export the Certificate**: - - Export the certificate with its private key in PFX (PKCS#12) format - - Set a strong password for the PFX file - - Example filename: `gateway-client-cert.pfx` - -3. **Deploy the Certificate**: - - Copy the PFX file to a secure location on the Gateway server - - Recommended location: `C:\Program Files\Keyfactor\AnyGateway\Certificates\` (Windows) - - Or: `/opt/keyfactor/anygateway/certificates/` (Linux) - - Set appropriate file permissions to restrict access - - Record the full path and password for Gateway configuration - -#### 3. Certificate Profiles (Templates) - -Certificate profiles define the types of certificates that can be issued. The plugin automatically discovers available profiles from the Idnomic system. - -**To view available profiles:** - -1. The profiles are retrieved automatically when the CA is configured -2. Profiles appear in Keyfactor Command as "Product IDs" after CA registration -3. Each profile represents a certificate template configured in Idnomic PKI - -**Note**: Profile discovery uses the `list_profiles` SOAP operation. Ensure the client certificate has permissions to call this operation. - -#### 4. Zones - -Zones in Idnomic PKI represent organizational or security boundaries within the PKI hierarchy. Each certificate enrollment request must specify a zone. - -**Common zone examples**: -- `Default` -- `Production` -- `Test` -- `DMZ` -- Custom zones as configured in your Idnomic PKI - -**To identify available zones:** - -1. Contact your Idnomic PKI administrator for the list of configured zones -2. Zones may be visible through the `certificate_search_properties` operation -3. Document the zone names exactly as they appear in the system (case-sensitive) - -### Supported Revocation Reasons - -The plugin supports the following standard CRL revocation reasons: - -| Reason Code | Reason Name | Description | -|-------------|-------------|-------------| -| 0 | Unspecified | No specific reason provided | -| 1 | Key Compromise | Private key has been compromised | -| 2 | CA Compromise | Certificate Authority has been compromised | -| 3 | Affiliation Changed | Subject's affiliation has changed | -| 4 | Superseded | Certificate has been superseded by a new certificate | - -**Note**: Not all Idnomic PKI configurations support all revocation reasons. Consult your Idnomic administrator for supported reasons in your environment. +TODO Requirements is a required section ## Installation @@ -187,47 +89,7 @@ The plugin supports the following standard CRL revocation reasons: * **Gateway Registration** - ### CA Connection Configuration - - When registering the Idnomic CA in the AnyCA Gateway, you'll need to provide the following configuration parameters: - - | Parameter | Description | Required | Example | - |-----------|-------------|----------|---------| - | **EndpointAddress** | Full URL to the Idnomic RA connector SOAP endpoint | Yes | `https://idnomic.example.com:8443/RA/connector.cgi` | - | **ClientCertLocation** | Full file path to the client certificate PFX file on the Gateway server | Yes | `C:\Certificates\gateway-client.pfx` | - | **ClientCertPassword** | Password for the client certificate PFX file | Yes | `SecureP@ssw0rd` | - | **Enabled** | Whether the CA connection is enabled | No (default: true) | `true` or `false` | - - ### Template (Product) Configuration - - Each certificate template discovered from Idnomic requires configuration when used for enrollment: - - | Parameter | Description | Required | Example | - |-----------|-------------|----------|---------| - | **Zone** | The Idnomic PKI zone where certificates will be issued | Yes | `Production` | - - **Important Notes**: - - Template names (Product IDs) are automatically discovered from Idnomic using the `list_profiles` operation - - The Zone parameter must exactly match a zone configured in your Idnomic PKI system - - Zone names are case-sensitive - - Each template can be configured with a different zone if needed - - ### Gateway Registration Notes - - - Each defined Certificate Authority in the AnyCA Gateway REST can support one Idnomic CA endpoint - - If you have multiple Idnomic PKI instances or need to issue from different zones with different permissions, you must define multiple Certificate Authorities in the AnyCA Gateway - - Each CA configuration will manifest in Command as a separate CA entry - - The plugin uses SOAP-based communication exclusively; ensure the RA connector endpoint is properly configured for SOAP access - - Client certificate authentication is mandatory and cannot be disabled - - The "Enabled" flag allows you to temporarily disable a CA connection without removing the configuration - - ### Security Considerations - - 1. **Certificate Storage**: Store client certificates in a secure location with restricted file system permissions - 2. **Password Management**: Use strong passwords for client certificate PFX files and consider using a secrets management system - 3. **Network Security**: Ensure TLS/SSL is properly configured for the RA connector endpoint - 4. **Least Privilege**: Request client certificates with minimal required permissions in the Idnomic PKI system - 5. **Audit Logging**: Enable comprehensive logging in both the Gateway and Idnomic PKI for security monitoring + TODO Gateway Registration is a required section * **CA Connection** @@ -243,248 +105,6 @@ The plugin supports the following standard CRL revocation reasons: 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. -## Troubleshooting - -### Connection Issues -- Verify the RA connector endpoint URL is correct and accessible -- Check that the client certificate is valid and not expired -- Confirm the client certificate is trusted by the Idnomic PKI system -- Review Gateway logs for SOAP communication errors - -### Profile Discovery Issues -- Ensure the client certificate has permissions to call `list_profiles` -- Verify the RA connector is properly configured in Idnomic -- Check that profiles are published and available in the Idnomic system - -### Enrollment Failures -- Verify the Zone parameter exactly matches a configured zone in Idnomic -- Confirm the selected profile supports the requested certificate attributes -- Check that the client certificate has enrollment permissions for the specified zone -- Review Idnomic PKI logs for detailed error messages - -### Synchronization Issues -- Confirm the client certificate has permissions to call `search_for_certificates` -- Verify network connectivity and timeout settings -- For large certificate databases, consider adjusting synchronization schedules - -## Test Cases - -### Test Case 1: CA Connection Validation - -**Objective**: Verify that the Gateway can successfully connect to the Idnomic RA connector using client certificate authentication. - -**Prerequisites**: -- Idnomic PKI system is operational -- Valid client certificate (PFX) is available -- RA connector endpoint is accessible - -**Test Steps**: -1. Configure the CA in AnyCA Gateway with valid connection parameters -2. Click "Test Connection" or trigger the Ping operation -3. Observe the connection result - -**Expected Results**: -- Connection succeeds without errors -- Gateway logs show successful SOAP authentication -- No certificate validation errors occur - -**Verification**: -- Review Gateway logs for successful connection message -- Check Idnomic PKI logs for incoming authenticated connection -- Verify no SSL/TLS errors in either system - ---- - -### Test Case 2: Profile Discovery - -**Objective**: Verify that the Gateway can retrieve the list of available certificate profiles from Idnomic PKI. - -**Prerequisites**: -- CA connection is successfully configured -- At least one certificate profile is configured in Idnomic PKI -- Client certificate has permissions to call `list_profiles` - -**Test Steps**: -1. Save the CA configuration in AnyCA Gateway -2. Navigate to the template/product configuration section -3. Observe the list of available Product IDs - -**Expected Results**: -- List of profiles is populated automatically -- Profile names match those configured in Idnomic PKI -- No empty or null profile names appear - -**Verification**: -- Compare the list of profiles in Gateway with Idnomic PKI configuration -- Verify profile names are correctly displayed -- Check Gateway logs for successful `list_profiles` SOAP call - ---- - -### Test Case 3: Certificate Enrollment - Valid Request - -**Objective**: Verify successful certificate enrollment through the plugin. - -**Prerequisites**: -- CA and template are properly configured -- Valid Zone parameter is configured for the template -- Test CSR is available - -**Test Steps**: -1. Submit an enrollment request via Keyfactor Command -2. Specify the Idnomic CA and a valid template -3. Provide a valid PKCS#10 CSR -4. Wait for enrollment to complete - -**Expected Results**: -- Enrollment completes successfully -- Certificate is issued by Idnomic PKI -- Certificate is returned to Keyfactor Command -- Certificate appears in Command inventory - -**Verification**: -- Verify certificate details match the CSR -- Confirm certificate is present in Idnomic PKI database -- Check that certificate chain is properly constructed -- Validate certificate can be used for its intended purpose - ---- - -### Test Case 4: Certificate Enrollment - Invalid Zone - -**Objective**: Verify proper error handling when an invalid zone is specified. - -**Prerequisites**: -- CA and template are configured -- Zone parameter is set to a non-existent zone name - -**Test Steps**: -1. Submit an enrollment request with invalid Zone parameter -2. Observe the enrollment result - -**Expected Results**: -- Enrollment fails with clear error message -- Error message indicates invalid zone -- No certificate is issued -- System remains stable - -**Verification**: -- Check error message clarity and accuracy -- Verify Gateway logs contain detailed error information -- Confirm no partial enrollment occurred in Idnomic PKI - ---- - -### Test Case 5: Certificate Synchronization - Full Sync - -**Objective**: Verify full certificate synchronization from Idnomic PKI to Keyfactor Command. - -**Prerequisites**: -- CA is properly configured -- Multiple certificates exist in Idnomic PKI -- Synchronization is configured in Command - -**Test Steps**: -1. Trigger a full synchronization job -2. Wait for synchronization to complete -3. Verify synchronized certificate count - -**Expected Results**: -- All certificates from Idnomic PKI are synchronized -- Certificate details are accurate (subject, serial number, dates, etc.) -- No duplicate certificates appear -- Synchronization completes without errors - -**Verification**: -- Compare certificate count in Command vs. Idnomic PKI -- Spot-check several certificates for data accuracy -- Review synchronization logs for any warnings or errors -- Verify certificate chains are properly synchronized - ---- - -### Test Case 6: Certificate Synchronization - Incremental Sync - -**Objective**: Verify incremental synchronization only retrieves new certificates since last sync. - -**Prerequisites**: -- Initial full synchronization has been completed -- Timestamp of last sync is recorded -- New certificates have been issued since last sync - -**Test Steps**: -1. Note the timestamp of the last successful sync -2. Issue one or more new certificates in Idnomic PKI -3. Trigger an incremental synchronization -4. Observe synchronized certificates - -**Expected Results**: -- Only certificates issued after last sync are retrieved -- Sync completes faster than full sync -- All new certificates are properly synchronized -- Previously synchronized certificates are not duplicated - -**Verification**: -- Verify only recent certificates were processed -- Check sync duration is appropriate for certificate count -- Review Gateway logs to confirm incremental sync parameters -- Validate certificate data integrity - ---- - -### Test Case 7: Certificate Revocation - Key Compromise - -**Objective**: Verify certificate revocation with reason code 1 (Key Compromise). - -**Prerequisites**: -- A valid certificate issued through the Gateway exists -- Certificate is not already revoked - -**Test Steps**: -1. Identify a test certificate to revoke -2. Submit revocation request with reason "Key Compromise" (code 1) -3. Wait for revocation to complete - -**Expected Results**: -- Revocation succeeds -- Certificate status changes to "Revoked" in Command -- Certificate appears on CRL in Idnomic PKI -- Revocation reason is correctly recorded - -**Verification**: -- Check certificate status in Keyfactor Command -- Verify certificate appears on Idnomic CRL with correct reason code -- Confirm revocation timestamp is accurate -- Validate certificate can no longer be used for authentication - ---- - -### Test Case 8: Profile Properties Validation - -**Objective**: Verify that profile-specific properties are correctly enforced during enrollment. - -**Prerequisites**: -- Profiles with different configurations exist (key sizes, validity periods, etc.) -- Zone parameter is correctly configured - -**Test Steps**: -1. Attempt enrollment with CSR matching profile requirements -2. Attempt enrollment with CSR not matching profile requirements (e.g., wrong key size) -3. Observe results - -**Expected Results**: -- Valid enrollments succeed -- Invalid enrollments fail with descriptive error messages -- Profile constraints are properly enforced by Idnomic PKI - -**Verification**: -- Review error messages for clarity -- Verify Idnomic PKI rejects non-compliant requests -- Check that valid certificates meet profile specifications -- Confirm Gateway properly communicates validation errors - ---- - ## License diff --git a/docsource/configuration.md b/docsource/configuration.md index c31ba53..4f0689a 100644 --- a/docsource/configuration.md +++ b/docsource/configuration.md @@ -14,3 +14,16 @@ The Idnomic PKI Gateway plugin extends the capabilities of Idnomic PKI (formerly * **Certificate Revocation**: * Request revocation of previously issued certificates * Support for standard CRL revocation reasons + +## Requirements + +TODO Requirements is a required section + +## Gateway Registration + +TODO Gateway Registration is a required section + +## Certificate Template Creation Step + +TODO Certificate Template Creation Step is a required section + From dd5a6fd0544303ba2e06cce902d52110635fcbbc Mon Sep 17 00:00:00 2001 From: Brian Hill <76450501+bhillkeyfactor@users.noreply.github.com> Date: Tue, 11 Nov 2025 13:47:57 -0500 Subject: [PATCH 29/34] Update configuration.md --- docsource/configuration.md | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/docsource/configuration.md b/docsource/configuration.md index 4f0689a..1bae178 100644 --- a/docsource/configuration.md +++ b/docsource/configuration.md @@ -15,15 +15,3 @@ The Idnomic PKI Gateway plugin extends the capabilities of Idnomic PKI (formerly * Request revocation of previously issued certificates * Support for standard CRL revocation reasons -## Requirements - -TODO Requirements is a required section - -## Gateway Registration - -TODO Gateway Registration is a required section - -## Certificate Template Creation Step - -TODO Certificate Template Creation Step is a required section - From f1cc38d6ec85a20b7e156e54201a3af6260f499f Mon Sep 17 00:00:00 2001 From: Keyfactor Date: Tue, 11 Nov 2025 18:50:24 +0000 Subject: [PATCH 30/34] Update generated docs --- docsource/configuration.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docsource/configuration.md b/docsource/configuration.md index 1bae178..4f0689a 100644 --- a/docsource/configuration.md +++ b/docsource/configuration.md @@ -15,3 +15,15 @@ The Idnomic PKI Gateway plugin extends the capabilities of Idnomic PKI (formerly * Request revocation of previously issued certificates * Support for standard CRL revocation reasons +## Requirements + +TODO Requirements is a required section + +## Gateway Registration + +TODO Gateway Registration is a required section + +## Certificate Template Creation Step + +TODO Certificate Template Creation Step is a required section + From cd418fb931000626a78ad3005308e6a96bd852f5 Mon Sep 17 00:00:00 2001 From: Brian Hill <76450501+bhillkeyfactor@users.noreply.github.com> Date: Tue, 11 Nov 2025 13:53:51 -0500 Subject: [PATCH 31/34] Update configuration.md --- docsource/configuration.md | 385 ++++++++++++++++++++++++++++++++++++- 1 file changed, 381 insertions(+), 4 deletions(-) diff --git a/docsource/configuration.md b/docsource/configuration.md index 4f0689a..933f15c 100644 --- a/docsource/configuration.md +++ b/docsource/configuration.md @@ -17,13 +17,390 @@ The Idnomic PKI Gateway plugin extends the capabilities of Idnomic PKI (formerly ## Requirements -TODO Requirements is a required section +### Idnomic PKI System Prerequisites + +Before configuring the AnyCA Gateway plugin, ensure the following prerequisites are met on your Idnomic PKI system: + +1. **Idnomic PKI Installation**: + - Idnomic PKI server must be installed and operational. Only tested with 4.9.2 version of IDNOMIC. Other version may or may not work. + - RA (Registration Authority) connector must be enabled and accessible + - SOAP interface must be configured and reachable + +2. **Client Certificate Authentication**: + - A client certificate must be issued for the AnyCA Gateway service to authenticate to Idnomic + - The certificate must be trusted by the Idnomic PKI system + - Certificate must be exported in PFX/PKCS#12 format with private key + +3. **Network Connectivity**: + - Gateway server must have network access to the Idnomic RA connector endpoint + - Default endpoint format: `https://:/RA/connector.cgi` + - TLS/SSL must be properly configured + +### Obtaining Required Configuration Information + +#### 1. RA Connector Endpoint Address + +The RA Connector endpoint is the SOAP service URL for the Registration Authority connector. + +**To find the endpoint address:** + +1. Contact your Idnomic PKI administrator +2. The standard format is: `https://:/RA/connector.cgi` +3. Verify the endpoint is accessible from the Gateway server +4. Confirm SOAP services are enabled on this endpoint + +**Example endpoint**: `https://idnomic-pki.example.com:8443/RA/connector.cgi` + +#### 2. Client Certificate for Authentication + +The Gateway authenticates to Idnomic using mutual TLS with a client certificate. + +**Steps to obtain and prepare the client certificate:** + +1. **Request a Client Certificate**: + - Contact your Idnomic PKI administrator + - Request a certificate suitable for SOAP client authentication + - Ensure the certificate includes the "Client Authentication" Extended Key Usage + +2. **Export the Certificate**: + - Export the certificate with its private key in PFX (PKCS#12) format + - Set a strong password for the PFX file + - Example filename: `gateway-client-cert.pfx` + +3. **Deploy the Certificate**: + - Copy the PFX file to a secure location on the Gateway server + - Recommended location: `C:\Program Files\Keyfactor\AnyGateway\Certificates\` (Windows) + - Or: `/opt/keyfactor/anygateway/certificates/` (Linux) + - Set appropriate file permissions to restrict access + - Record the full path and password for Gateway configuration + +#### 3. Certificate Profiles (Templates) + +Certificate profiles define the types of certificates that can be issued. The plugin automatically discovers available profiles from the Idnomic system. + +**To view available profiles:** + +1. The profiles are retrieved automatically when the CA is configured +2. Profiles appear in Keyfactor Command as "Product IDs" after CA registration +3. Each profile represents a certificate template configured in Idnomic PKI + +**Note**: Profile discovery uses the `list_profiles` SOAP operation. Ensure the client certificate has permissions to call this operation. + +#### 4. Zones + +Zones in Idnomic PKI represent organizational or security boundaries within the PKI hierarchy. Each certificate enrollment request must specify a zone. + +**Common zone examples**: +- `Default` +- `Production` +- `Test` +- `DMZ` +- Custom zones as configured in your Idnomic PKI + +**To identify available zones:** + +1. Contact your Idnomic PKI administrator for the list of configured zones +2. Zones may be visible through the `certificate_search_properties` operation +3. Document the zone names exactly as they appear in the system (case-sensitive) + +### Supported Revocation Reasons + +The plugin supports the following standard CRL revocation reasons: + +| Reason Code | Reason Name | Description | +|-------------|-------------|-------------| +| 0 | Unspecified | No specific reason provided | +| 1 | Key Compromise | Private key has been compromised | +| 2 | CA Compromise | Certificate Authority has been compromised | +| 3 | Affiliation Changed | Subject's affiliation has changed | +| 4 | Superseded | Certificate has been superseded by a new certificate | + +**Note**: Not all Idnomic PKI configurations support all revocation reasons. Consult your Idnomic administrator for supported reasons in your environment. ## Gateway Registration -TODO Gateway Registration is a required section +### CA Connection Configuration + +When registering the Idnomic CA in the AnyCA Gateway, you'll need to provide the following configuration parameters: + +| Parameter | Description | Required | Example | +|-----------|-------------|----------|---------| +| **EndpointAddress** | Full URL to the Idnomic RA connector SOAP endpoint | Yes | `https://idnomic.example.com:8443/RA/connector.cgi` | +| **ClientCertLocation** | Full file path to the client certificate PFX file on the Gateway server | Yes | `C:\Certificates\gateway-client.pfx` | +| **ClientCertPassword** | Password for the client certificate PFX file | Yes | `SecureP@ssw0rd` | +| **Enabled** | Whether the CA connection is enabled | No (default: true) | `true` or `false` | + +### Template (Product) Configuration + +Each certificate template discovered from Idnomic requires configuration when used for enrollment: + +| Parameter | Description | Required | Example | +|-----------|-------------|----------|---------| +| **Zone** | The Idnomic PKI zone where certificates will be issued | Yes | `Production` | + +**Important Notes**: +- Template names (Product IDs) are automatically discovered from Idnomic using the `list_profiles` operation +- The Zone parameter must exactly match a zone configured in your Idnomic PKI system +- Zone names are case-sensitive +- Each template can be configured with a different zone if needed + +### Gateway Registration Notes + +- Each defined Certificate Authority in the AnyCA Gateway REST can support one Idnomic CA endpoint +- If you have multiple Idnomic PKI instances or need to issue from different zones with different permissions, you must define multiple Certificate Authorities in the AnyCA Gateway +- Each CA configuration will manifest in Command as a separate CA entry +- The plugin uses SOAP-based communication exclusively; ensure the RA connector endpoint is properly configured for SOAP access +- Client certificate authentication is mandatory and cannot be disabled +- The "Enabled" flag allows you to temporarily disable a CA connection without removing the configuration + +### Security Considerations + +1. **Certificate Storage**: Store client certificates in a secure location with restricted file system permissions +2. **Password Management**: Use strong passwords for client certificate PFX files and consider using a secrets management system +3. **Network Security**: Ensure TLS/SSL is properly configured for the RA connector endpoint +4. **Least Privilege**: Request client certificates with minimal required permissions in the Idnomic PKI system +5. **Audit Logging**: Enable comprehensive logging in both the Gateway and Idnomic PKI for security monitoring + +## Troubleshooting + +### Connection Issues +- Verify the RA connector endpoint URL is correct and accessible +- Check that the client certificate is valid and not expired +- Confirm the client certificate is trusted by the Idnomic PKI system +- Review Gateway logs for SOAP communication errors + +### Profile Discovery Issues +- Ensure the client certificate has permissions to call `list_profiles` +- Verify the RA connector is properly configured in Idnomic +- Check that profiles are published and available in the Idnomic system + +### Enrollment Failures +- Verify the Zone parameter exactly matches a configured zone in Idnomic +- Confirm the selected profile supports the requested certificate attributes +- Check that the client certificate has enrollment permissions for the specified zone +- Review Idnomic PKI logs for detailed error messages + +### Synchronization Issues +- Confirm the client certificate has permissions to call `search_for_certificates` +- Verify network connectivity and timeout settings +- For large certificate databases, consider adjusting synchronization schedules + +## Test Cases + +### Test Case 1: CA Connection Validation + +**Objective**: Verify that the Gateway can successfully connect to the Idnomic RA connector using client certificate authentication. + +**Prerequisites**: +- Idnomic PKI system is operational +- Valid client certificate (PFX) is available +- RA connector endpoint is accessible + +**Test Steps**: +1. Configure the CA in AnyCA Gateway with valid connection parameters +2. Click "Test Connection" or trigger the Ping operation +3. Observe the connection result + +**Expected Results**: +- Connection succeeds without errors +- Gateway logs show successful SOAP authentication +- No certificate validation errors occur + +**Verification**: +- Review Gateway logs for successful connection message +- Check Idnomic PKI logs for incoming authenticated connection +- Verify no SSL/TLS errors in either system + +--- + +### Test Case 2: Profile Discovery + +**Objective**: Verify that the Gateway can retrieve the list of available certificate profiles from Idnomic PKI. + +**Prerequisites**: +- CA connection is successfully configured +- At least one certificate profile is configured in Idnomic PKI +- Client certificate has permissions to call `list_profiles` + +**Test Steps**: +1. Save the CA configuration in AnyCA Gateway +2. Navigate to the template/product configuration section +3. Observe the list of available Product IDs + +**Expected Results**: +- List of profiles is populated automatically +- Profile names match those configured in Idnomic PKI +- No empty or null profile names appear + +**Verification**: +- Compare the list of profiles in Gateway with Idnomic PKI configuration +- Verify profile names are correctly displayed +- Check Gateway logs for successful `list_profiles` SOAP call + +--- + +### Test Case 3: Certificate Enrollment - Valid Request + +**Objective**: Verify successful certificate enrollment through the plugin. + +**Prerequisites**: +- CA and template are properly configured +- Valid Zone parameter is configured for the template +- Test CSR is available + +**Test Steps**: +1. Submit an enrollment request via Keyfactor Command +2. Specify the Idnomic CA and a valid template +3. Provide a valid PKCS#10 CSR +4. Wait for enrollment to complete + +**Expected Results**: +- Enrollment completes successfully +- Certificate is issued by Idnomic PKI +- Certificate is returned to Keyfactor Command +- Certificate appears in Command inventory + +**Verification**: +- Verify certificate details match the CSR +- Confirm certificate is present in Idnomic PKI database +- Check that certificate chain is properly constructed +- Validate certificate can be used for its intended purpose + +--- + +### Test Case 4: Certificate Enrollment - Invalid Zone + +**Objective**: Verify proper error handling when an invalid zone is specified. + +**Prerequisites**: +- CA and template are configured +- Zone parameter is set to a non-existent zone name + +**Test Steps**: +1. Submit an enrollment request with invalid Zone parameter +2. Observe the enrollment result + +**Expected Results**: +- Enrollment fails with clear error message +- Error message indicates invalid zone +- No certificate is issued +- System remains stable + +**Verification**: +- Check error message clarity and accuracy +- Verify Gateway logs contain detailed error information +- Confirm no partial enrollment occurred in Idnomic PKI + +--- + +### Test Case 5: Certificate Synchronization - Full Sync + +**Objective**: Verify full certificate synchronization from Idnomic PKI to Keyfactor Command. + +**Prerequisites**: +- CA is properly configured +- Multiple certificates exist in Idnomic PKI +- Synchronization is configured in Command + +**Test Steps**: +1. Trigger a full synchronization job +2. Wait for synchronization to complete +3. Verify synchronized certificate count + +**Expected Results**: +- All certificates from Idnomic PKI are synchronized +- Certificate details are accurate (subject, serial number, dates, etc.) +- No duplicate certificates appear +- Synchronization completes without errors + +**Verification**: +- Compare certificate count in Command vs. Idnomic PKI +- Spot-check several certificates for data accuracy +- Review synchronization logs for any warnings or errors +- Verify certificate chains are properly synchronized + +--- + +### Test Case 6: Certificate Synchronization - Incremental Sync + +**Objective**: Verify incremental synchronization only retrieves new certificates since last sync. + +**Prerequisites**: +- Initial full synchronization has been completed +- Timestamp of last sync is recorded +- New certificates have been issued since last sync + +**Test Steps**: +1. Note the timestamp of the last successful sync +2. Issue one or more new certificates in Idnomic PKI +3. Trigger an incremental synchronization +4. Observe synchronized certificates + +**Expected Results**: +- Only certificates issued after last sync are retrieved +- Sync completes faster than full sync +- All new certificates are properly synchronized +- Previously synchronized certificates are not duplicated + +**Verification**: +- Verify only recent certificates were processed +- Check sync duration is appropriate for certificate count +- Review Gateway logs to confirm incremental sync parameters +- Validate certificate data integrity + +--- + +### Test Case 7: Certificate Revocation - Key Compromise + +**Objective**: Verify certificate revocation with reason code 1 (Key Compromise). + +**Prerequisites**: +- A valid certificate issued through the Gateway exists +- Certificate is not already revoked + +**Test Steps**: +1. Identify a test certificate to revoke +2. Submit revocation request with reason "Key Compromise" (code 1) +3. Wait for revocation to complete + +**Expected Results**: +- Revocation succeeds +- Certificate status changes to "Revoked" in Command +- Certificate appears on CRL in Idnomic PKI +- Revocation reason is correctly recorded + +**Verification**: +- Check certificate status in Keyfactor Command +- Verify certificate appears on Idnomic CRL with correct reason code +- Confirm revocation timestamp is accurate +- Validate certificate can no longer be used for authentication + +--- + +### Test Case 8: Profile Properties Validation + +**Objective**: Verify that profile-specific properties are correctly enforced during enrollment. + +**Prerequisites**: +- Profiles with different configurations exist (key sizes, validity periods, etc.) +- Zone parameter is correctly configured + +**Test Steps**: +1. Attempt enrollment with CSR matching profile requirements +2. Attempt enrollment with CSR not matching profile requirements (e.g., wrong key size) +3. Observe results + +**Expected Results**: +- Valid enrollments succeed +- Invalid enrollments fail with descriptive error messages +- Profile constraints are properly enforced by Idnomic PKI + +**Verification**: +- Review error messages for clarity +- Verify Idnomic PKI rejects non-compliant requests +- Check that valid certificates meet profile specifications +- Confirm Gateway properly communicates validation errors -## Certificate Template Creation Step +--- -TODO Certificate Template Creation Step is a required section From 8dc31a02fdf0116bab6827953ad5353dea42b67f Mon Sep 17 00:00:00 2001 From: Keyfactor Date: Tue, 11 Nov 2025 18:56:06 +0000 Subject: [PATCH 32/34] Update generated docs --- README.md | 384 ++++++++++++++++++++++++++++++++++++- docsource/configuration.md | 3 + 2 files changed, 385 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 5a28223..988e5f5 100644 --- a/README.md +++ b/README.md @@ -60,7 +60,105 @@ The Idnomic PKI Gateway AnyCA Gateway REST plugin is supported by Keyfactor for ## Requirements -TODO Requirements is a required section +### Idnomic PKI System Prerequisites + +Before configuring the AnyCA Gateway plugin, ensure the following prerequisites are met on your Idnomic PKI system: + +1. **Idnomic PKI Installation**: + - Idnomic PKI server must be installed and operational. Only tested with 4.9.2 version of IDNOMIC. Other version may or may not work. + - RA (Registration Authority) connector must be enabled and accessible + - SOAP interface must be configured and reachable + +2. **Client Certificate Authentication**: + - A client certificate must be issued for the AnyCA Gateway service to authenticate to Idnomic + - The certificate must be trusted by the Idnomic PKI system + - Certificate must be exported in PFX/PKCS#12 format with private key + +3. **Network Connectivity**: + - Gateway server must have network access to the Idnomic RA connector endpoint + - Default endpoint format: `https://:/RA/connector.cgi` + - TLS/SSL must be properly configured + +### Obtaining Required Configuration Information + +#### 1. RA Connector Endpoint Address + +The RA Connector endpoint is the SOAP service URL for the Registration Authority connector. + +**To find the endpoint address:** + +1. Contact your Idnomic PKI administrator +2. The standard format is: `https://:/RA/connector.cgi` +3. Verify the endpoint is accessible from the Gateway server +4. Confirm SOAP services are enabled on this endpoint + +**Example endpoint**: `https://idnomic-pki.example.com:8443/RA/connector.cgi` + +#### 2. Client Certificate for Authentication + +The Gateway authenticates to Idnomic using mutual TLS with a client certificate. + +**Steps to obtain and prepare the client certificate:** + +1. **Request a Client Certificate**: + - Contact your Idnomic PKI administrator + - Request a certificate suitable for SOAP client authentication + - Ensure the certificate includes the "Client Authentication" Extended Key Usage + +2. **Export the Certificate**: + - Export the certificate with its private key in PFX (PKCS#12) format + - Set a strong password for the PFX file + - Example filename: `gateway-client-cert.pfx` + +3. **Deploy the Certificate**: + - Copy the PFX file to a secure location on the Gateway server + - Recommended location: `C:\Program Files\Keyfactor\AnyGateway\Certificates\` (Windows) + - Or: `/opt/keyfactor/anygateway/certificates/` (Linux) + - Set appropriate file permissions to restrict access + - Record the full path and password for Gateway configuration + +#### 3. Certificate Profiles (Templates) + +Certificate profiles define the types of certificates that can be issued. The plugin automatically discovers available profiles from the Idnomic system. + +**To view available profiles:** + +1. The profiles are retrieved automatically when the CA is configured +2. Profiles appear in Keyfactor Command as "Product IDs" after CA registration +3. Each profile represents a certificate template configured in Idnomic PKI + +**Note**: Profile discovery uses the `list_profiles` SOAP operation. Ensure the client certificate has permissions to call this operation. + +#### 4. Zones + +Zones in Idnomic PKI represent organizational or security boundaries within the PKI hierarchy. Each certificate enrollment request must specify a zone. + +**Common zone examples**: +- `Default` +- `Production` +- `Test` +- `DMZ` +- Custom zones as configured in your Idnomic PKI + +**To identify available zones:** + +1. Contact your Idnomic PKI administrator for the list of configured zones +2. Zones may be visible through the `certificate_search_properties` operation +3. Document the zone names exactly as they appear in the system (case-sensitive) + +### Supported Revocation Reasons + +The plugin supports the following standard CRL revocation reasons: + +| Reason Code | Reason Name | Description | +|-------------|-------------|-------------| +| 0 | Unspecified | No specific reason provided | +| 1 | Key Compromise | Private key has been compromised | +| 2 | CA Compromise | Certificate Authority has been compromised | +| 3 | Affiliation Changed | Subject's affiliation has changed | +| 4 | Superseded | Certificate has been superseded by a new certificate | + +**Note**: Not all Idnomic PKI configurations support all revocation reasons. Consult your Idnomic administrator for supported reasons in your environment. ## Installation @@ -89,7 +187,47 @@ TODO Requirements is a required section * **Gateway Registration** - TODO Gateway Registration is a required section + ### CA Connection Configuration + + When registering the Idnomic CA in the AnyCA Gateway, you'll need to provide the following configuration parameters: + + | Parameter | Description | Required | Example | + |-----------|-------------|----------|---------| + | **EndpointAddress** | Full URL to the Idnomic RA connector SOAP endpoint | Yes | `https://idnomic.example.com:8443/RA/connector.cgi` | + | **ClientCertLocation** | Full file path to the client certificate PFX file on the Gateway server | Yes | `C:\Certificates\gateway-client.pfx` | + | **ClientCertPassword** | Password for the client certificate PFX file | Yes | `SecureP@ssw0rd` | + | **Enabled** | Whether the CA connection is enabled | No (default: true) | `true` or `false` | + + ### Template (Product) Configuration + + Each certificate template discovered from Idnomic requires configuration when used for enrollment: + + | Parameter | Description | Required | Example | + |-----------|-------------|----------|---------| + | **Zone** | The Idnomic PKI zone where certificates will be issued | Yes | `Production` | + + **Important Notes**: + - Template names (Product IDs) are automatically discovered from Idnomic using the `list_profiles` operation + - The Zone parameter must exactly match a zone configured in your Idnomic PKI system + - Zone names are case-sensitive + - Each template can be configured with a different zone if needed + + ### Gateway Registration Notes + + - Each defined Certificate Authority in the AnyCA Gateway REST can support one Idnomic CA endpoint + - If you have multiple Idnomic PKI instances or need to issue from different zones with different permissions, you must define multiple Certificate Authorities in the AnyCA Gateway + - Each CA configuration will manifest in Command as a separate CA entry + - The plugin uses SOAP-based communication exclusively; ensure the RA connector endpoint is properly configured for SOAP access + - Client certificate authentication is mandatory and cannot be disabled + - The "Enabled" flag allows you to temporarily disable a CA connection without removing the configuration + + ### Security Considerations + + 1. **Certificate Storage**: Store client certificates in a secure location with restricted file system permissions + 2. **Password Management**: Use strong passwords for client certificate PFX files and consider using a secrets management system + 3. **Network Security**: Ensure TLS/SSL is properly configured for the RA connector endpoint + 4. **Least Privilege**: Request client certificates with minimal required permissions in the Idnomic PKI system + 5. **Audit Logging**: Enable comprehensive logging in both the Gateway and Idnomic PKI for security monitoring * **CA Connection** @@ -105,6 +243,248 @@ TODO Requirements is a required section 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. +## Troubleshooting + +### Connection Issues +- Verify the RA connector endpoint URL is correct and accessible +- Check that the client certificate is valid and not expired +- Confirm the client certificate is trusted by the Idnomic PKI system +- Review Gateway logs for SOAP communication errors + +### Profile Discovery Issues +- Ensure the client certificate has permissions to call `list_profiles` +- Verify the RA connector is properly configured in Idnomic +- Check that profiles are published and available in the Idnomic system + +### Enrollment Failures +- Verify the Zone parameter exactly matches a configured zone in Idnomic +- Confirm the selected profile supports the requested certificate attributes +- Check that the client certificate has enrollment permissions for the specified zone +- Review Idnomic PKI logs for detailed error messages + +### Synchronization Issues +- Confirm the client certificate has permissions to call `search_for_certificates` +- Verify network connectivity and timeout settings +- For large certificate databases, consider adjusting synchronization schedules + +## Test Cases + +### Test Case 1: CA Connection Validation + +**Objective**: Verify that the Gateway can successfully connect to the Idnomic RA connector using client certificate authentication. + +**Prerequisites**: +- Idnomic PKI system is operational +- Valid client certificate (PFX) is available +- RA connector endpoint is accessible + +**Test Steps**: +1. Configure the CA in AnyCA Gateway with valid connection parameters +2. Click "Test Connection" or trigger the Ping operation +3. Observe the connection result + +**Expected Results**: +- Connection succeeds without errors +- Gateway logs show successful SOAP authentication +- No certificate validation errors occur + +**Verification**: +- Review Gateway logs for successful connection message +- Check Idnomic PKI logs for incoming authenticated connection +- Verify no SSL/TLS errors in either system + +--- + +### Test Case 2: Profile Discovery + +**Objective**: Verify that the Gateway can retrieve the list of available certificate profiles from Idnomic PKI. + +**Prerequisites**: +- CA connection is successfully configured +- At least one certificate profile is configured in Idnomic PKI +- Client certificate has permissions to call `list_profiles` + +**Test Steps**: +1. Save the CA configuration in AnyCA Gateway +2. Navigate to the template/product configuration section +3. Observe the list of available Product IDs + +**Expected Results**: +- List of profiles is populated automatically +- Profile names match those configured in Idnomic PKI +- No empty or null profile names appear + +**Verification**: +- Compare the list of profiles in Gateway with Idnomic PKI configuration +- Verify profile names are correctly displayed +- Check Gateway logs for successful `list_profiles` SOAP call + +--- + +### Test Case 3: Certificate Enrollment - Valid Request + +**Objective**: Verify successful certificate enrollment through the plugin. + +**Prerequisites**: +- CA and template are properly configured +- Valid Zone parameter is configured for the template +- Test CSR is available + +**Test Steps**: +1. Submit an enrollment request via Keyfactor Command +2. Specify the Idnomic CA and a valid template +3. Provide a valid PKCS#10 CSR +4. Wait for enrollment to complete + +**Expected Results**: +- Enrollment completes successfully +- Certificate is issued by Idnomic PKI +- Certificate is returned to Keyfactor Command +- Certificate appears in Command inventory + +**Verification**: +- Verify certificate details match the CSR +- Confirm certificate is present in Idnomic PKI database +- Check that certificate chain is properly constructed +- Validate certificate can be used for its intended purpose + +--- + +### Test Case 4: Certificate Enrollment - Invalid Zone + +**Objective**: Verify proper error handling when an invalid zone is specified. + +**Prerequisites**: +- CA and template are configured +- Zone parameter is set to a non-existent zone name + +**Test Steps**: +1. Submit an enrollment request with invalid Zone parameter +2. Observe the enrollment result + +**Expected Results**: +- Enrollment fails with clear error message +- Error message indicates invalid zone +- No certificate is issued +- System remains stable + +**Verification**: +- Check error message clarity and accuracy +- Verify Gateway logs contain detailed error information +- Confirm no partial enrollment occurred in Idnomic PKI + +--- + +### Test Case 5: Certificate Synchronization - Full Sync + +**Objective**: Verify full certificate synchronization from Idnomic PKI to Keyfactor Command. + +**Prerequisites**: +- CA is properly configured +- Multiple certificates exist in Idnomic PKI +- Synchronization is configured in Command + +**Test Steps**: +1. Trigger a full synchronization job +2. Wait for synchronization to complete +3. Verify synchronized certificate count + +**Expected Results**: +- All certificates from Idnomic PKI are synchronized +- Certificate details are accurate (subject, serial number, dates, etc.) +- No duplicate certificates appear +- Synchronization completes without errors + +**Verification**: +- Compare certificate count in Command vs. Idnomic PKI +- Spot-check several certificates for data accuracy +- Review synchronization logs for any warnings or errors +- Verify certificate chains are properly synchronized + +--- + +### Test Case 6: Certificate Synchronization - Incremental Sync + +**Objective**: Verify incremental synchronization only retrieves new certificates since last sync. + +**Prerequisites**: +- Initial full synchronization has been completed +- Timestamp of last sync is recorded +- New certificates have been issued since last sync + +**Test Steps**: +1. Note the timestamp of the last successful sync +2. Issue one or more new certificates in Idnomic PKI +3. Trigger an incremental synchronization +4. Observe synchronized certificates + +**Expected Results**: +- Only certificates issued after last sync are retrieved +- Sync completes faster than full sync +- All new certificates are properly synchronized +- Previously synchronized certificates are not duplicated + +**Verification**: +- Verify only recent certificates were processed +- Check sync duration is appropriate for certificate count +- Review Gateway logs to confirm incremental sync parameters +- Validate certificate data integrity + +--- + +### Test Case 7: Certificate Revocation - Key Compromise + +**Objective**: Verify certificate revocation with reason code 1 (Key Compromise). + +**Prerequisites**: +- A valid certificate issued through the Gateway exists +- Certificate is not already revoked + +**Test Steps**: +1. Identify a test certificate to revoke +2. Submit revocation request with reason "Key Compromise" (code 1) +3. Wait for revocation to complete + +**Expected Results**: +- Revocation succeeds +- Certificate status changes to "Revoked" in Command +- Certificate appears on CRL in Idnomic PKI +- Revocation reason is correctly recorded + +**Verification**: +- Check certificate status in Keyfactor Command +- Verify certificate appears on Idnomic CRL with correct reason code +- Confirm revocation timestamp is accurate +- Validate certificate can no longer be used for authentication + +--- + +### Test Case 8: Profile Properties Validation + +**Objective**: Verify that profile-specific properties are correctly enforced during enrollment. + +**Prerequisites**: +- Profiles with different configurations exist (key sizes, validity periods, etc.) +- Zone parameter is correctly configured + +**Test Steps**: +1. Attempt enrollment with CSR matching profile requirements +2. Attempt enrollment with CSR not matching profile requirements (e.g., wrong key size) +3. Observe results + +**Expected Results**: +- Valid enrollments succeed +- Invalid enrollments fail with descriptive error messages +- Profile constraints are properly enforced by Idnomic PKI + +**Verification**: +- Review error messages for clarity +- Verify Idnomic PKI rejects non-compliant requests +- Check that valid certificates meet profile specifications +- Confirm Gateway properly communicates validation errors + +--- + ## License diff --git a/docsource/configuration.md b/docsource/configuration.md index 933f15c..bf8ab9c 100644 --- a/docsource/configuration.md +++ b/docsource/configuration.md @@ -403,4 +403,7 @@ Each certificate template discovered from Idnomic requires configuration when us --- +## Certificate Template Creation Step + +TODO Certificate Template Creation Step is a required section From f91fa2dd07d5f055092b7e75f3d28f11264211f9 Mon Sep 17 00:00:00 2001 From: Brian Hill <76450501+bhillkeyfactor@users.noreply.github.com> Date: Tue, 11 Nov 2025 14:47:07 -0500 Subject: [PATCH 33/34] Update configuration.md --- docsource/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docsource/configuration.md b/docsource/configuration.md index bf8ab9c..13f4bd2 100644 --- a/docsource/configuration.md +++ b/docsource/configuration.md @@ -405,5 +405,5 @@ Each certificate template discovered from Idnomic requires configuration when us ## Certificate Template Creation Step -TODO Certificate Template Creation Step is a required section +Create Templates that Match Corresponding products in Idnomic From b4087a01aedf4541e8e9853bead8d86f0d69753d Mon Sep 17 00:00:00 2001 From: Keyfactor Date: Tue, 11 Nov 2025 19:49:40 +0000 Subject: [PATCH 34/34] Update generated docs --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 988e5f5..41f7b62 100644 --- a/README.md +++ b/README.md @@ -238,7 +238,7 @@ The plugin supports the following standard CRL revocation reasons: * **ClientCertPassword** - The password for the client certificate. * **Enabled** - Flag to Enable or Disable gateway functionality. Disabling is primarily used to allow creation of the CA prior to configuration information being available. -2. TODO Certificate Template Creation Step is a required section +2. Create Templates that Match Corresponding products in Idnomic 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.