Skip to content

Commit 0f65298

Browse files
author
Keyfactor
committed
Update generated docs
1 parent 64b82c1 commit 0f65298

1 file changed

Lines changed: 142 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 142 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,21 @@
3434
</p>
3535

3636

37-
TODO Overview is a required section
37+
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:
38+
39+
* **CA Sync**:
40+
* Download all certificates issued by the HydrantId CA
41+
* Support for incremental and full synchronization
42+
* Automatic extraction of end-entity certificates from PEM chains
43+
* **Certificate Enrollment**:
44+
* Support certificate enrollment with new key pairs
45+
* Dynamic policy (profile) discovery from the CA
46+
* Intelligent renewal vs. re-issue logic based on certificate expiration
47+
* Support for PKCS#10 CSR format
48+
* Configurable certificate validity periods
49+
* **Certificate Revocation**:
50+
* Request revocation of previously issued certificates
51+
* Support for standard CRL revocation reasons
3852

3953
## Compatibility
4054

@@ -47,7 +61,113 @@ The HID Global AnyCA Gateway REST plugin is supported by Keyfactor for Keyfactor
4761
4862
## Requirements
4963

50-
TODO Requirements is a required section
64+
### HydrantId System Prerequisites
65+
66+
Before configuring the AnyCA Gateway plugin, ensure the following prerequisites are met:
67+
68+
1. **HydrantId Account**:
69+
- Active HydrantId account with API access enabled
70+
- Access to the HydrantId management portal
71+
- HydrantId Certificate Authority Service configured and operational
72+
73+
2. **API Credentials**:
74+
- HydrantId API Authentication ID (AuthId)
75+
- HydrantId API Authentication Key (AuthKey)
76+
- These credentials must have permissions for:
77+
- Certificate enrollment (CSR submission)
78+
- Certificate retrieval
79+
- Certificate revocation
80+
- Policy/profile listing
81+
82+
3. **Network Connectivity**:
83+
- Gateway server must have HTTPS access to the HydrantId API endpoint
84+
- Default endpoint format: `https://<environment>.hydrantid.com`
85+
- Example: `https://acm-stage.hydrantid.com` or `https://acm.hydrantid.com`
86+
- TLS 1.2 or higher must be supported
87+
88+
### Obtaining Required Configuration Information
89+
90+
#### 1. HydrantId Base URL
91+
92+
The HydrantId Base URL is the root endpoint for the HydrantId API.
93+
94+
**Common HydrantId environments:**
95+
- Production: `https://acm.hydrantid.com`
96+
- Staging: `https://acm-stage.hydrantid.com`
97+
- Custom instances may have different URLs
98+
99+
**To obtain your Base URL:**
100+
1. Contact your HydrantId account representative
101+
2. Check your HydrantId account documentation
102+
3. Verify the URL is accessible from the Gateway server
103+
104+
#### 2. API Authentication Credentials
105+
106+
The Gateway authenticates to HydrantId using Hawk authentication protocol with an AuthId and AuthKey pair.
107+
108+
**Steps to obtain API credentials:**
109+
110+
1. **Access HydrantId Portal**:
111+
- Log in to your HydrantId management portal
112+
- Navigate to API or Integration settings
113+
114+
2. **Generate API Credentials**:
115+
- Request API credentials from your HydrantId administrator
116+
- You will receive:
117+
- **AuthId**: A unique identifier for your API client
118+
- **AuthKey**: A secret key used for HMAC-based authentication
119+
- Store these credentials securely
120+
121+
3. **Verify Permissions**:
122+
- Ensure the API credentials have the following permissions:
123+
- Certificate enrollment (POST /api/v2/csr)
124+
- Certificate renewal (POST /api/v2/certificates/{id}/renew)
125+
- Certificate retrieval (GET /api/v2/certificates)
126+
- Certificate revocation (PATCH /api/v2/certificates/{id})
127+
- Policy listing (GET /api/v2/policies)
128+
129+
#### 3. Certificate Policies
130+
131+
Certificate policies define the types of certificates that can be issued. The plugin automatically discovers available policies from the HydrantId system.
132+
133+
**Policy discovery:**
134+
- Policies are automatically retrieved when the CA is configured
135+
- Policies appear in Keyfactor Command as "Product IDs" after CA registration
136+
- Each policy represents a certificate template configured in HydrantId
137+
138+
**To view available policies:**
139+
1. Policies are retrieved automatically using the GET /api/v2/policies endpoint
140+
2. Ensure the API credentials have permissions to list policies
141+
3. Policies will be displayed during CA configuration in the Gateway
142+
143+
#### 4. Certificate Validity Configuration
144+
145+
For each certificate template, you can configure:
146+
147+
| Parameter | Description | Example Values |
148+
|-----------|-------------|----------------|
149+
| **ValidityPeriod** | Time unit for certificate lifetime | `Days`, `Months`, `Years` |
150+
| **ValidityUnits** | Numeric value for the validity period | `365` (for days), `12` (for months), `2` (for years) |
151+
| **RenewalDays** | Days before expiration to trigger renewal vs. re-issue | `30`, `60`, `90` |
152+
153+
**Renewal vs. Re-issue Logic:**
154+
- If a certificate is within the RenewalDays window before expiration, the plugin performs a **renewal**
155+
- If a certificate is outside the RenewalDays window, the plugin performs a **re-issue** (new enrollment)
156+
157+
### Supported Revocation Reasons
158+
159+
The plugin supports the following standard CRL revocation reasons:
160+
161+
| Reason Code | Reason Name | HydrantId API Value |
162+
|-------------|-------------|---------------------|
163+
| 0 | Unspecified | `Unspecified` |
164+
| 1 | Key Compromise | `KeyCompromise` |
165+
| 2 | CA Compromise | `CaCompromise` |
166+
| 3 | Affiliation Changed | `AffiliationChanged` |
167+
| 4 | Superseded | `Superseded` |
168+
| 5 | Cessation of Operation | `CessationOfOperation` |
169+
170+
**Note**: Verify with your HydrantId administrator which revocation reasons are supported in your environment.
51171

52172
## Installation
53173

@@ -93,6 +213,26 @@ TODO Requirements is a required section
93213
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
94214
95215
216+
## Installation
217+
218+
1. Install the AnyCA Gateway REST per the [official Keyfactor documentation](https://software.keyfactor.com/Guides/AnyCAGatewayREST/Content/AnyCAGatewayREST/InstallIntroduction.htm).
219+
220+
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.
221+
222+
3. Copy the unzipped directory (usually called `net6.0` or `net8.0`) to the Extensions directory:
223+
224+
```shell
225+
Depending on your AnyCA Gateway REST version, copy the unzipped directory to one of the following locations:
226+
Program Files\Keyfactor\AnyCA Gateway\AnyGatewayREST\net6.0\Extensions
227+
Program Files\Keyfactor\AnyCA Gateway\AnyGatewayREST\net8.0\Extensions
228+
```
229+
230+
> 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.
231+
232+
4. Restart the AnyCA Gateway REST service.
233+
234+
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.
235+
96236
97237
## License
98238

0 commit comments

Comments
 (0)