From 98581fa7028599f7b526c26c2d80a7f778b3c0a4 Mon Sep 17 00:00:00 2001 From: Brian Hill <76450501+bhillkeyfactor@users.noreply.github.com> Date: Tue, 2 Dec 2025 13:28:22 -0500 Subject: [PATCH] feat: release 1.0 (#1) The HID Global HydrantId AnyCA Gateway REST plugin extends the capabilities of HydrantId Certificate Authority Service to Keyfactor Command via the Keyfactor AnyCA Gateway. This plugin leverages the HydrantId REST API with Hawk authentication 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 HydrantId CA * Support for incremental and full synchronization * Automatic extraction of end-entity certificates from PEM chains * **Certificate Enrollment**: * Support certificate enrollment with new key pairs * Dynamic policy (profile) discovery from the CA * Intelligent renewal vs. re-issue logic based on certificate expiration * Support for PKCS#10 CSR format * Configurable certificate validity periods * **Certificate Revocation**: * Request revocation of previously issued certificates * Support for standard CRL revocation reasons --------- Co-authored-by: Keyfactor --- CHANGELOG.md | 13 +- HydrantCAProxy/HydrantIdCAPlugin.csproj | 4 +- README.md | 267 ++++++++++++++++------ docsource/configuration.md | 287 ++++++++++++++---------- integration-manifest.json | 5 +- 5 files changed, 383 insertions(+), 193 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7134f25..0d35e57 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,13 +1,2 @@ -๏ปฟ# v2.0.0 -* Migrate `packages.config` to `PackageReference` format -* Upgrade packages to support Keyfactor AnyCA Gateway DCOM v24.2 - * Upgrade `Keyfactor.AnyGateway.SDK` to `24.2.0-PRERELEASE-47446` -* Add support for [GCP CAS Certificate Templates](https://cloud.google.com/certificate-authority-service/docs/policy-controls) -* Enable configuration of CA Pool-based or CA-specific certificate enrollment. If the `CAId` is specified, certificates are enrolled with the CA specified by `CAId`. Otherwise, GCP CAS selects a CA in the CA Pool based on policy. - -# v1.1.0 - - Remove template references from README - - Small bug fixes - # v1.0.0 -* Initial Release. Support for Google GA CA Service. Sync, Enroll, and Revocation. +* Initial Release. Sync, Enroll, and Revocation. diff --git a/HydrantCAProxy/HydrantIdCAPlugin.csproj b/HydrantCAProxy/HydrantIdCAPlugin.csproj index 5243e31..48b20b9 100644 --- a/HydrantCAProxy/HydrantIdCAPlugin.csproj +++ b/HydrantCAProxy/HydrantIdCAPlugin.csproj @@ -1,6 +1,6 @@ ๏ปฟ - net6.0 + net6.0;net8.0 disable true false @@ -18,4 +18,4 @@ Always - \ No newline at end of file + diff --git a/README.md b/README.md index 58e4ac1..de674de 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,13 @@

- HydrantId AnyCA Gateway REST Plugin + HID Global AnyCA Gateway REST Plugin

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

@@ -34,97 +34,161 @@

-HydrantId operates a PKI as a service platform for customers around the globe. The AnyGateway solution for HydrantId is designed to allow Keyfactor Command: +The HID Global HydrantId AnyCA Gateway REST plugin extends the capabilities of HydrantId Certificate Authority Service to Keyfactor Command via the Keyfactor AnyCA Gateway. This plugin leverages the HydrantId REST API with Hawk authentication 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 connected Enterprise tier CAs in HydrantId (full sync). -* Certificate enrollment for all published HydrantId Certificate SKUs: - * Support certificate enrollment (new keys/certificate). -* Certificate revocation: - * Request revocation of a previously issued certificate. +* **CA Sync**: + * Download all certificates issued by the HydrantId CA + * Support for incremental and full synchronization + * Automatic extraction of end-entity certificates from PEM chains +* **Certificate Enrollment**: + * Support certificate enrollment with new key pairs + * Dynamic policy (profile) discovery from the CA + * Intelligent renewal vs. re-issue logic based on certificate expiration + * Support for PKCS#10 CSR format + * Configurable certificate validity periods +* **Certificate Revocation**: + * Request revocation of previously issued certificates + * Support for standard CRL revocation reasons ## Compatibility -The HydrantId AnyCA Gateway REST plugin is compatible with the Keyfactor AnyCA Gateway REST 24.2 and later. +The HID Global AnyCA Gateway REST plugin is compatible with the Keyfactor AnyCA Gateway REST 24.2 and later. ## Support -The HydrantId 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. +The HID Global 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 -### ๐Ÿ” HydrantID API Key Setup Guide +### HydrantId System Prerequisites -This guide explains how to generate and use an API Key ID and Secret in HydrantID for authenticated API access. +Before configuring the AnyCA Gateway plugin, ensure the following prerequisites are met: ---- +1. **HydrantId Account**: + - Active HydrantId account with API access enabled + - Access to the HydrantId management portal + - HydrantId Certificate Authority Service configured and operational -#### ๐Ÿ“ Where to Find API Key Management +2. **API Credentials**: + - HydrantId API Authentication ID (AuthId) + - HydrantId API Authentication Key (AuthKey) + - These credentials must have permissions for: + - Certificate enrollment (CSR submission) + - Certificate retrieval + - Certificate revocation + - Policy/profile listing -1. **Log in** to your HydrantID instance. - - Example: https://acm-stage.hydrantid.com +3. **Network Connectivity**: + - Gateway server must have HTTPS access to the HydrantId API endpoint + - Default endpoint format: `https://.hydrantid.com` + - Example: `https://acm-stage.hydrantid.com` or `https://acm.hydrantid.com` + - TLS 1.2 or higher must be supported -2. Click your **user profile icon** (top right) and select **"Profile"**. +### Obtaining Required Configuration Information -3. In the **Profile** page, scroll to the section labeled `API Keys`. +#### 1. HydrantId Base URL ---- +The HydrantId Base URL is the root endpoint for the HydrantId API. -#### โž• Add a New API Key +**Common HydrantId environments:** +- Production: `https://acm.hydrantid.com` +- Staging: `https://acm-stage.hydrantid.com` +- Custom instances may have different URLs -1. Click **"ADD API KEY"** (top right of the API Keys section). -2. A new API Key will be generated with: - - A unique **API ID** - - A **Secret API Key** โ€” copy it immediately as it is only shown once. +**To obtain your Base URL:** +1. Contact your HydrantId account representative +2. Check your HydrantId account documentation +3. Verify the URL is accessible from the Gateway server ---- +#### 2. API Authentication Credentials -#### ๐Ÿงพ Notes on API Keys +The Gateway authenticates to HydrantId using Hawk authentication protocol with an AuthId and AuthKey pair. -- **ID** = what you'll pass in the HAWK `id` field -- **Key** = secret used to generate HAWK signature -- Each key shows `Created` and `Last Used` timestamps for traceability +**Steps to obtain API credentials:** ---- +1. **Access HydrantId Portal**: + - Log in to your HydrantId management portal + - Navigate to API or Integration settings -#### ๐Ÿ” Using the API ID and Key with HAWK +2. **Generate API Credentials**: + - Request API credentials from your HydrantId administrator + - You will receive: + - **AuthId**: A unique identifier for your API client + - **AuthKey**: A secret key used for HMAC-based authentication + - Store these credentials securely -HydrantID uses [HAWK Authentication](https://github.com/hueniverse/hawk) to secure its API. +3. **Verify Permissions**: + - Ensure the API credentials have the following permissions: + - Certificate enrollment (POST /api/v2/csr) + - Certificate renewal (POST /api/v2/certificates/{id}/renew) + - Certificate retrieval (GET /api/v2/certificates) + - Certificate revocation (PATCH /api/v2/certificates/{id}) + - Policy listing (GET /api/v2/policies) -##### Required Fields in Authorization Header: -```text -Hawk id="API_ID", ts="TIMESTAMP", nonce="RANDOM", mac="HMAC_SIGNATURE" +#### 3. Certificate Policies -### Root CA Configuration +Certificate policies define the types of certificates that can be issued. The plugin automatically discovers available policies from the HydrantId system. -Both the Keyfactor Command and AnyCA Gateway REST servers must trust the root CA, and if applicable, any subordinate CAs for all features to work as intended. Download the CA Certificate (and chain, if applicable) from HydrantId, and import them into the appropriate certificate store on the AnyCA Gateway REST server. +**Policy discovery:** +- Policies are automatically retrieved when the CA is configured +- Policies appear in Keyfactor Command as "Product IDs" after CA registration +- Each policy represents a certificate template configured in HydrantId -* **Windows** - If the AnyCA Gateway REST is running on a Windows host, the root CA and applicable subordinate CAs must be imported into the Windows certificate store. The certificates can be imported using the Microsoft Management Console (MMC) or PowerShell. -* **Linux** - If the AnyCA Gateway REST is running on a Linux host, the root CA and applicable subordinate CAs must be present in the root CA certificate store. The location of this store varies per distribution, but is most commonly `/etc/ssl/certs/ca-certificates.crt`. The following is documentation on some popular distributions. - * [Ubuntu - Managing CA certificates](https://ubuntu.com/server/docs/install-a-root-ca-certificate-in-the-trust-store) - * [RHEL 9 - Using shared system certificates](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/9/html/securing_networks/using-shared-system-certificates_securing-networks#using-shared-system-certificates_securing-networks) - * [Fedora - Using Shared System Certificates](https://docs.fedoraproject.org/en-US/quick-docs/using-shared-system-certificates/) +**To view available policies:** +1. Policies are retrieved automatically using the GET /api/v2/policies endpoint +2. Ensure the API credentials have permissions to list policies +3. Policies will be displayed during CA configuration in the Gateway -> The root CA and intermediate CAs must be trusted by both the Command server _and_ AnyCA Gateway REST server. +#### 4. Certificate Validity Configuration + +For each certificate template, you can configure: + +| Parameter | Description | Example Values | +|-----------|-------------|----------------| +| **ValidityPeriod** | Time unit for certificate lifetime | `Days`, `Months`, `Years` | +| **ValidityUnits** | Numeric value for the validity period | `365` (for days), `12` (for months), `2` (for years) | +| **RenewalDays** | Days before expiration to trigger renewal vs. re-issue | `30`, `60`, `90` | + +**Renewal vs. Re-issue Logic:** +- If a certificate is within the RenewalDays window before expiration, the plugin performs a **renewal** +- If a certificate is outside the RenewalDays window, the plugin performs a **re-issue** (new enrollment) + +### Supported Revocation Reasons + +The plugin supports the following standard CRL revocation reasons: + +| Reason Code | Reason Name | HydrantId API Value | +|-------------|-------------|---------------------| +| 0 | Unspecified | `Unspecified` | +| 1 | Key Compromise | `KeyCompromise` | +| 2 | CA Compromise | `CaCompromise` | +| 3 | Affiliation Changed | `AffiliationChanged` | +| 4 | Superseded | `Superseded` | +| 5 | Cessation of Operation | `CessationOfOperation` | + +**Note**: Verify with your HydrantId administrator which revocation reasons are supported in your environment. ## 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 [HydrantId AnyCA Gateway REST plugin](https://github.com/Keyfactor/hydrantid-cagateway/releases/latest) from GitHub. +2. On the server hosting the AnyCA Gateway REST, download and unzip the latest [HID Global AnyCA Gateway REST plugin](https://github.com/Keyfactor/hydrantid-caplugin/releases/latest) from GitHub. + +3. Copy the unzipped directory (usually called `net6.0` or `net8.0`) to the Extensions directory: -3. Copy the unzipped directory (usually called `net6.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 HydrantId AnyCA Gateway REST plugin DLLs (`net6.0`) can be named anything, as long as it is unique within the `Extensions` directory. + > The directory containing the HID Global 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 HydrantId plugin by hovering over the โ“˜ symbol to the right of the Gateway on the top left of the portal. +5. Navigate to the AnyCA Gateway REST portal and verify that the Gateway recognizes the HID Global plugin by hovering over the โ“˜ symbol to the right of the Gateway on the top left of the portal. ## Configuration @@ -132,7 +196,62 @@ Both the Keyfactor Command and AnyCA Gateway REST servers must trust the root CA * **Gateway Registration** - The Gateway Registration tab configures the root or issuing CA certificate for the respective CA in HydrantId. The certificate selected here should be the issuing CA identified in the [Root CA Configuration](#root-ca-configuration) step. + ### CA Connection Configuration + + When registering the HydrantId CA in the AnyCA Gateway, you'll need to provide the following configuration parameters: + + | Parameter | Description | Required | Example | + |-----------|-------------|----------|---------| + | **HydrantIdBaseUrl** | Full URL to the HydrantId API endpoint | Yes | `https://acm.hydrantid.com` or `https://acm-stage.hydrantid.com` | + | **HydrantIdAuthId** | API Authentication ID provided by HydrantId | Yes | `your-auth-id` | + | **HydrantIdAuthKey** | API Authentication Key provided by HydrantId | Yes | `your-secret-auth-key` | + + ### Gateway Registration Notes + + - Each defined Certificate Authority in the AnyCA Gateway REST can support one HydrantId API endpoint + - If you have multiple HydrantId environments or accounts, 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 Hawk authentication protocol for all API communications + - Authentication uses HMAC-SHA256 for secure API access + - The plugin automatically handles: + - Policy/template discovery + - Certificate status mapping + - End-entity certificate extraction from PEM chains + - Enrollment completion polling (30-second timeout) + + ### Security Considerations + + 1. **Credential Storage**: Store API credentials securely and restrict access to the Gateway configuration + 2. **Secret Management**: Consider using a secrets management system for AuthKey storage + 3. **Network Security**: Ensure TLS/SSL is properly configured for all API communications + 4. **Least Privilege**: Request API credentials with minimal required permissions + 5. **Audit Logging**: Enable comprehensive logging in both the Gateway and HydrantId for security monitoring + 6. **Credential Rotation**: Regularly rotate API credentials according to your security policy + + **CA Connection** + + Populate using the configuration fields collected in the [requirements](#requirements) section. + + * **HydrantIdBaseUrl** - The base URL for the HydrantId API endpoint. For example, `https://acm.hydrantid.com` or `https://acm-stage.hydrantid.com`. + * **HydrantIdAuthId** - The API Authentication ID provided by HydrantId for API access. + * **HydrantIdAuthKey** - The API Authentication Key (secret) provided by HydrantId for API access. + + 2. **Certificate Template Configuration** + + After adding the CA to the Gateway, configure each certificate template: + + 1. Navigate to the Templates/Products section for the newly added CA + 2. For each template (policy) discovered from HydrantId, configure: + - **ValidityPeriod**: Select `Days`, `Months`, or `Years` + - **ValidityUnits**: Enter the numeric value (e.g., `365` for one year in days) + - **RenewalDays**: Enter the renewal window in days (e.g., `30`) + + Example configurations: + - **1-Year Certificate (Days)**: ValidityPeriod=`Days`, ValidityUnits=`365`, RenewalDays=`30` + - **2-Year Certificate (Years)**: ValidityPeriod=`Years`, ValidityUnits=`2`, RenewalDays=`60` + - **6-Month Certificate (Months)**: ValidityPeriod=`Months`, ValidityUnits=`6`, RenewalDays=`30` + + 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. * **CA Connection** @@ -142,20 +261,22 @@ Both the Keyfactor Command and AnyCA Gateway REST servers must trust the root CA * **HydrantIdAuthId** - The AuthId Obtained from HydrantId. * **HydrantIdAuthKey** - The AuthKey Obtained from HydrantId. -2. Define [Certificate Profiles](https://software.keyfactor.com/Guides/AnyCAGatewayREST/Content/AnyCAGatewayREST/AddCP-Gateway.htm) and [Certificate Templates](https://software.keyfactor.com/Guides/AnyCAGatewayREST/Content/AnyCAGatewayREST/AddCA-Gateway.htm) for the Certificate Authority as required. One Certificate Profile must be defined per Certificate Template. It's recommended that each Certificate Profile be named after the Product ID. +2. ### Template (Product) Configuration + + Each certificate template (policy) discovered from HydrantId requires configuration for enrollment: - The GCP CAS AnyCA Gateway REST plugin downloads all Certificate Templates in the configured GCP Region/Project and interprets them as 'Product IDs' in the Gateway Portal. + | Parameter | Description | Required | Example | + |-----------|-------------|----------|---------| + | **ValidityPeriod** | Time unit for certificate lifetime | Yes | `Days`, `Months`, or `Years` | + | **ValidityUnits** | Numeric value for the validity period | Yes | `365` (for 1 year in days), `12` (for 1 year in months), `2` (for 2 years) | + | **RenewalDays** | Days before expiration to trigger renewal | Yes | `30` (renew within 30 days of expiration) | - > For example, if the connected GCP project has the following Certificate Templates: - > - > * `ServerAuth` - > * `ClientAuth` - > - > The `Edit Templates` > `Product ID` dialog dropdown will show the following available 'ProductIDs': - > - > * `Default` -> Don't use a certificate template when enrolling certificates with this Template. - > * `ServerAuth` -> Use the `ServerAuth` certificate template in GCP when enrolling certificates with this Template. - > * `ClientAuth` -> Use the `ClientAuth` certificate template in GCP when enrolling certificates with this Template. + **Important Notes:** + - Template names (Product IDs) are automatically discovered from HydrantId using the GET /api/v2/policies endpoint + - The ValidityPeriod and ValidityUnits combine to determine the certificate lifetime + - RenewalDays determines the behavior for certificate renewal: + - Within window: Performs a renewal operation (maintains certificate lineage) + - Outside window: Performs a re-issue operation (new certificate enrollment) 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. @@ -166,6 +287,26 @@ Both the Keyfactor Command and AnyCA Gateway REST servers must trust the root CA * **RenewalDays** - The window that determines whether it is a renewal vs a re-issue. +## 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 [HID Global HydrantId AnyCA Gateway REST plugin](https://github.com/Keyfactor/hydrantid-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 HID Global HydrantId 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 HID Global HydrantId plugin by hovering over the โ“˜ symbol to the right of the Gateway on the top left of the portal. + ## License diff --git a/docsource/configuration.md b/docsource/configuration.md index a333d02..0a31dd2 100644 --- a/docsource/configuration.md +++ b/docsource/configuration.md @@ -1,166 +1,225 @@ ## Overview -HID operates a PKI-as-a-service platform for customers around the globe. The AnyGateway solution for HID allows Keyfactor Command to perform: +The HID Global HydrantId AnyCA Gateway REST plugin extends the capabilities of HydrantId Certificate Authority Service to Keyfactor Command via the Keyfactor AnyCA Gateway. This plugin leverages the HydrantId REST API with Hawk authentication 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 HydrantId CA + * Support for incremental and full synchronization + * Automatic extraction of end-entity certificates from PEM chains +* **Certificate Enrollment**: + * Support certificate enrollment with new key pairs + * Dynamic policy (profile) discovery from the CA + * Intelligent renewal vs. re-issue logic based on certificate expiration + * Support for PKCS#10 CSR format + * Configurable certificate validity periods +* **Certificate Revocation**: + * Request revocation of previously issued certificates + * Support for standard CRL revocation reasons -- **CA Sync**: - - Download all certificates issued by connected Enterprise-tier CAs in HID (full sync). -- **Certificate Enrollment**: - - Support certificate enrollment (new keys/certificate). - - Intelligent handling of Renewal vs Reissue based on certificate expiration. -- **Certificate Revocation**: - - Request revocation of previously issued certificates with mapped revocation reasons. +## Requirements ---- +### HydrantId System Prerequisites -## Requirements +Before configuring the AnyCA Gateway plugin, ensure the following prerequisites are met: -### ๐Ÿ” HID API Key Setup Guide +1. **HydrantId Account**: + - Active HydrantId account with API access enabled + - Access to the HydrantId management portal + - HydrantId Certificate Authority Service configured and operational -This guide explains how to generate and use an API Key ID and Secret in HID for authenticated API access. +2. **API Credentials**: + - HydrantId API Authentication ID (AuthId) + - HydrantId API Authentication Key (AuthKey) + - These credentials must have permissions for: + - Certificate enrollment (CSR submission) + - Certificate retrieval + - Certificate revocation + - Policy/profile listing -#### ๐Ÿ“ Where to Find API Key Management +3. **Network Connectivity**: + - Gateway server must have HTTPS access to the HydrantId API endpoint + - Default endpoint format: `https://.hydrantid.com` + - Example: `https://acm-stage.hydrantid.com` or `https://acm.hydrantid.com` + - TLS 1.2 or higher must be supported -1. **Log in** to your HID instance. - - Example: https://acm-stage.hydrantid.com -2. Click your **user profile icon** (top right) and select **"Profile"**. -3. In the **Profile** page, scroll to the section labeled `API Keys`. +### Obtaining Required Configuration Information -#### โž• Add a New API Key +#### 1. HydrantId Base URL -1. Click **"ADD API KEY"** (top right of the API Keys section). -2. A new API Key will be generated with: - - A unique **API ID** - - A **Secret API Key** โ€” copy it immediately as it is only shown once. +The HydrantId Base URL is the root endpoint for the HydrantId API. -#### ๐Ÿงพ Notes on API Keys +**Common HydrantId environments:** +- Production: `https://acm.hydrantid.com` +- Staging: `https://acm-stage.hydrantid.com` +- Custom instances may have different URLs -- **ID** = what you'll pass in the HAWK `id` field -- **Key** = secret used to generate HAWK signature -- Each key shows `Created` and `Last Used` timestamps for traceability +**To obtain your Base URL:** +1. Contact your HydrantId account representative +2. Check your HydrantId account documentation +3. Verify the URL is accessible from the Gateway server -#### ๐Ÿ” Using the API ID and Key with HAWK +#### 2. API Authentication Credentials -HID uses [HAWK Authentication](https://github.com/hueniverse/hawk) to secure its API. +The Gateway authenticates to HydrantId using Hawk authentication protocol with an AuthId and AuthKey pair. -##### Required Fields in Authorization Header: -```text -Hawk id="API_ID", ts="TIMESTAMP", nonce="RANDOM", mac="HMAC_SIGNATURE" -``` +**Steps to obtain API credentials:** -Each HTTP request dynamically constructs a HAWK header using: -- API ID -- Secret API Key -- Current timestamp -- Cryptographically random nonce -- SHA-256 algorithm +1. **Access HydrantId Portal**: + - Log in to your HydrantId management portal + - Navigate to API or Integration settings -### Root CA Configuration +2. **Generate API Credentials**: + - Request API credentials from your HydrantId administrator + - You will receive: + - **AuthId**: A unique identifier for your API client + - **AuthKey**: A secret key used for HMAC-based authentication + - Store these credentials securely -Both the Keyfactor Command and AnyCA Gateway REST servers must trust the root CA, and any applicable intermediate CAs for HID. +3. **Verify Permissions**: + - Ensure the API credentials have the following permissions: + - Certificate enrollment (POST /api/v2/csr) + - Certificate renewal (POST /api/v2/certificates/{id}/renew) + - Certificate retrieval (GET /api/v2/certificates) + - Certificate revocation (PATCH /api/v2/certificates/{id}) + - Policy listing (GET /api/v2/policies) ---- +#### 3. Certificate Policies -## Gateway Registration +Certificate policies define the types of certificates that can be issued. The plugin automatically discovers available policies from the HydrantId system. -The Gateway Registration tab configures the root or issuing CA certificate for the respective CA in HID. -The certificate selected here should match the issuing CA identified in the [Root CA Configuration](#root-ca-configuration) step. +**Policy discovery:** +- Policies are automatically retrieved when the CA is configured +- Policies appear in Keyfactor Command as "Product IDs" after CA registration +- Each policy represents a certificate template configured in HydrantId ---- +**To view available policies:** +1. Policies are retrieved automatically using the GET /api/v2/policies endpoint +2. Ensure the API credentials have permissions to list policies +3. Policies will be displayed during CA configuration in the Gateway -## Certificate Template Creation Step +#### 4. Certificate Validity Configuration + +For each certificate template, you can configure: + +| Parameter | Description | Example Values | +|-----------|-------------|----------------| +| **ValidityPeriod** | Time unit for certificate lifetime | `Days`, `Months`, `Years` | +| **ValidityUnits** | Numeric value for the validity period | `365` (for days), `12` (for months), `2` (for years) | +| **RenewalDays** | Days before expiration to trigger renewal vs. re-issue | `30`, `60`, `90` | + +**Renewal vs. Re-issue Logic:** +- If a certificate is within the RenewalDays window before expiration, the plugin performs a **renewal** +- If a certificate is outside the RenewalDays window, the plugin performs a **re-issue** (new enrollment) -Define [Certificate Profiles](https://software.keyfactor.com/Guides/AnyCAGatewayREST/Content/AnyCAGatewayREST/AddCP-Gateway.htm) and [Certificate Templates](https://software.keyfactor.com/Guides/AnyCAGatewayREST/Content/AnyCAGatewayREST/AddCA-Gateway.htm) for the Certificate Authority as required. +### Supported Revocation Reasons -Naming Recommendations: -- Each Certificate Profile should be named after its Product ID. +The plugin supports the following standard CRL revocation reasons: -Behavior: -- The plugin maps HID Policy Names directly to Product IDs in the Gateway Portal. +| Reason Code | Reason Name | HydrantId API Value | +|-------------|-------------|---------------------| +| 0 | Unspecified | `Unspecified` | +| 1 | Key Compromise | `KeyCompromise` | +| 2 | CA Compromise | `CaCompromise` | +| 3 | Affiliation Changed | `AffiliationChanged` | +| 4 | Superseded | `Superseded` | +| 5 | Cessation of Operation | `CessationOfOperation` | -Example: -| HID Template | Product ID | -|:------------------|:-----------| -| `AutoEnrollment - ECDSA` | AutoEnrollment - ECDSA | -| `AutoEnrollment - RSA - 7 Day` | AutoEnrollment - RSA - 7 Day | +**Note**: Verify with your HydrantId administrator which revocation reasons are supported in your environment. -Selecting "Default" bypasses specifying a template. +## Installation ---- +1. Install the AnyCA Gateway REST per the [official Keyfactor documentation](https://software.keyfactor.com/Guides/AnyCAGatewayREST/Content/AnyCAGatewayREST/InstallIntroduction.htm). -# Mechanics +2. On the server hosting the AnyCA Gateway REST, download and unzip the latest [HID Global HydrantId AnyCA Gateway REST plugin](https://github.com/Keyfactor/hydrantid-caplugin/releases/latest) from GitHub. -## Enrollment/Renewal/Reissuance +3. Copy the unzipped directory (usually called `net6.0` or `net8.0`) to the Extensions directory: -All certificate enrollment operations are submitted as "new" requests. However, the plugin supports intelligent handling: + ```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 + ``` -- **New Enrollment**: - - Submits a new CSR against the selected HID Policy. -- **Renewal vs Reissue**: - - Uses the prior certificate's serial number (`PriorCertSN`) to retrieve the existing certificate. - - Compares the expiration date against the current time. - - If expiration is **within** `RenewalDays` (default 30 days): Submit a **Renewal** request. - - If expiration is **outside** `RenewalDays`: Submit a **Reissue** request (new CSR, same policy). + > The directory containing the HID Global HydrantId AnyCA Gateway REST plugin DLLs (`net6.0` or `net8.0`) can be named anything, as long as it is unique within the `Extensions` directory. -Template parameters: -| Parameter | Purpose | -|:---|:---| -| `RenewalDays` | Number of days before expiration considered a renewal window | -| `ValidityPeriod` | Period length (Days/Months/Years) | -| `ValidityUnits` | Value for the chosen period type | +4. Restart the AnyCA Gateway REST service. -## Certificate Synchronization +5. Navigate to the AnyCA Gateway REST portal and verify that the Gateway recognizes the HID Global HydrantId plugin by hovering over the โ“˜ symbol to the right of the Gateway on the top left of the portal. -The plugin uses the `/api/v2/certificates` endpoint to perform full synchronization: +## Gateway Registration + +### CA Connection Configuration + +When registering the HydrantId CA in the AnyCA Gateway, you'll need to provide the following configuration parameters: + +| Parameter | Description | Required | Example | +|-----------|-------------|----------|---------| +| **HydrantIdBaseUrl** | Full URL to the HydrantId API endpoint | Yes | `https://acm.hydrantid.com` or `https://acm-stage.hydrantid.com` | +| **HydrantIdAuthId** | API Authentication ID provided by HydrantId | Yes | `your-auth-id` | +| **HydrantIdAuthKey** | API Authentication Key provided by HydrantId | Yes | `your-secret-auth-key` | -- **Paging**: - - Fetches certificates in batches of 100 (default page size). -- **Filtering**: - - Only certificates with statuses `Generated` or `Revoked` are processed. -- **Retry Logic**: - - Up to **5 retry attempts** are made on API failures during synchronization before failing the job. -- **Certificate Parsing**: - - PEM chains are split into individual certificates. +### Gateway Registration Notes -> Note: HID's API does not allow filtering certificates by CA, so all certificates from the tenant are synced. +- Each defined Certificate Authority in the AnyCA Gateway REST can support one HydrantId API endpoint +- If you have multiple HydrantId environments or accounts, 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 Hawk authentication protocol for all API communications +- Authentication uses HMAC-SHA256 for secure API access +- The plugin automatically handles: +- Policy/template discovery +- Certificate status mapping +- End-entity certificate extraction from PEM chains +- Enrollment completion polling (30-second timeout) -## Certificate Revocation +### Security Considerations -Revocation requests are sent via a PATCH to the `/api/v2/certificates/{id}` endpoint. +1. **Credential Storage**: Store API credentials securely and restrict access to the Gateway configuration +2. **Secret Management**: Consider using a secrets management system for AuthKey storage +3. **Network Security**: Ensure TLS/SSL is properly configured for all API communications +4. **Least Privilege**: Request API credentials with minimal required permissions +5. **Audit Logging**: Enable comprehensive logging in both the Gateway and HydrantId for security monitoring +6. **Credential Rotation**: Regularly rotate API credentials according to your security policy -**Mapped Revocation Reasons**: +**CA Connection** -| Keyfactor Reason (RFC 5280) | HID Reason | -|:---|:---| -| 0 (Unspecified) | Unspecified | -| 1 (KeyCompromise) | KeyCompromise | -| 2 (CACompromise) | CACompromise | -| 3 (AffiliationChanged) | AffiliationChanged | -| 4 (Superseded) | Superseded | -| 5 (CessationOfOperation) | CessationOfOperation | -| 6 (CertificateHold) | CertificateHold | -| 8 (RemoveFromCRL) | RemoveFromCRL | -| 9 (PrivilegeWithdrawn) | PrivilegeWithdrawn | -| 10 (AACompromise) | AACompromise | +Populate using the configuration fields collected in the [requirements](#requirements) section. -## Connection Information Validation +* **HydrantIdBaseUrl** - The base URL for the HydrantId API endpoint. For example, `https://acm.hydrantid.com` or `https://acm-stage.hydrantid.com`. +* **HydrantIdAuthId** - The API Authentication ID provided by HydrantId for API access. +* **HydrantIdAuthKey** - The API Authentication Key (secret) provided by HydrantId for API access. -The following fields are required when connecting the Gateway to HID: +2. **Certificate Template Configuration** -- `HydrantIdBaseUrl` -- `HydrantIdAuthId` -- `HydrantIdAuthKey` + After adding the CA to the Gateway, configure each certificate template: -Missing or empty fields will cause the plugin initialization to fail. + 1. Navigate to the Templates/Products section for the newly added CA + 2. For each template (policy) discovered from HydrantId, configure: + - **ValidityPeriod**: Select `Days`, `Months`, or `Years` + - **ValidityUnits**: Enter the numeric value (e.g., `365` for one year in days) + - **RenewalDays**: Enter the renewal window in days (e.g., `30`) ---- + Example configurations: + - **1-Year Certificate (Days)**: ValidityPeriod=`Days`, ValidityUnits=`365`, RenewalDays=`30` + - **2-Year Certificate (Years)**: ValidityPeriod=`Years`, ValidityUnits=`2`, RenewalDays=`60` + - **6-Month Certificate (Months)**: ValidityPeriod=`Months`, ValidityUnits=`6`, RenewalDays=`30` + +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. + +## Certificate Template Creation Step -# Additional Notes +### Template (Product) Configuration -- After enrollment, the plugin polls HID's `/csr/{id}/certificate` endpoint for up to **30 seconds** to retrieve the newly issued certificate. -- If the certificate is still unavailable, the enrollment will be marked **Pending** in Command and should be retried. -- The plugin uses the Keyfactor standard logging infrastructure (`Keyfactor.Logging`). + Each certificate template (policy) discovered from HydrantId requires configuration for enrollment: -# ๐Ÿ“Œ Related Documentation + | Parameter | Description | Required | Example | + |-----------|-------------|----------|---------| + | **ValidityPeriod** | Time unit for certificate lifetime | Yes | `Days`, `Months`, or `Years` | + | **ValidityUnits** | Numeric value for the validity period | Yes | `365` (for 1 year in days), `12` (for 1 year in months), `2` (for 2 years) | + | **RenewalDays** | Days before expiration to trigger renewal | Yes | `30` (renew within 30 days of expiration) | -- [HAWK Authentication Specification](https://github.com/hueniverse/hawk) -- [HID API Documentation](https://support.hydrantid.com/hc/en-us) + **Important Notes:** + - Template names (Product IDs) are automatically discovered from HydrantId using the GET /api/v2/policies endpoint + - The ValidityPeriod and ValidityUnits combine to determine the certificate lifetime + - RenewalDays determines the behavior for certificate renewal: + - Within window: Performs a renewal operation (maintains certificate lineage) + - Outside window: Performs a re-issue operation (new certificate enrollment) diff --git a/integration-manifest.json b/integration-manifest.json index ded1f3c..e859acb 100644 --- a/integration-manifest.json +++ b/integration-manifest.json @@ -1,7 +1,8 @@ { "$schema": "https://keyfactor.github.io/v2/integration-manifest-schema.json", "name": "HID Global AnyCA REST plugin", - "release_dir": "HydrantCAProxy/bin/Release/net6.0", + "release_dir": "HydrantCAProxy/bin/Release", + "release_project": "HydrantCAProxy/HydrantIdCAPlugin.csproj", "description": "AnyCA Gateway REST plugin that extends HydrantId Certificate Authority Service to Keyfactor Command", "status": "production", "integration_type": "anyca-plugin", @@ -41,4 +42,4 @@ ] } } -} +} \ No newline at end of file