Skip to content

Commit 2016ac6

Browse files
bhillkeyfactorbhillkeyfactor
authored
Update idnomic.md
1 parent 79b0120 commit 2016ac6

1 file changed

Lines changed: 387 additions & 0 deletions

File tree

‎docsource/idnomic.md‎

Lines changed: 387 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,388 @@
1+
## Requirements
2+
3+
### Idnomic PKI System Prerequisites
4+
5+
Before configuring the AnyCA Gateway plugin, ensure the following prerequisites are met on your Idnomic PKI system:
6+
7+
1. **Idnomic PKI Installation**:
8+
- Idnomic PKI server must be installed and operational. Only tested with 4.9.2 version of IDNOMIC. Other version may or may not work.
9+
- RA (Registration Authority) connector must be enabled and accessible
10+
- SOAP interface must be configured and reachable
11+
12+
2. **Client Certificate Authentication**:
13+
- A client certificate must be issued for the AnyCA Gateway service to authenticate to Idnomic
14+
- The certificate must be trusted by the Idnomic PKI system
15+
- Certificate must be exported in PFX/PKCS#12 format with private key
16+
17+
3. **Network Connectivity**:
18+
- Gateway server must have network access to the Idnomic RA connector endpoint
19+
- Default endpoint format: `https://<server>:<port>/RA/connector.cgi`
20+
- TLS/SSL must be properly configured
21+
22+
### Obtaining Required Configuration Information
23+
24+
#### 1. RA Connector Endpoint Address
25+
26+
The RA Connector endpoint is the SOAP service URL for the Registration Authority connector.
27+
28+
**To find the endpoint address:**
29+
30+
1. Contact your Idnomic PKI administrator
31+
2. The standard format is: `https://<hostname>:<port>/RA/connector.cgi`
32+
3. Verify the endpoint is accessible from the Gateway server
33+
4. Confirm SOAP services are enabled on this endpoint
34+
35+
**Example endpoint**: `https://idnomic-pki.example.com:8443/RA/connector.cgi`
36+
37+
#### 2. Client Certificate for Authentication
38+
39+
The Gateway authenticates to Idnomic using mutual TLS with a client certificate.
40+
41+
**Steps to obtain and prepare the client certificate:**
42+
43+
1. **Request a Client Certificate**:
44+
- Contact your Idnomic PKI administrator
45+
- Request a certificate suitable for SOAP client authentication
46+
- Ensure the certificate includes the "Client Authentication" Extended Key Usage
47+
48+
2. **Export the Certificate**:
49+
- Export the certificate with its private key in PFX (PKCS#12) format
50+
- Set a strong password for the PFX file
51+
- Example filename: `gateway-client-cert.pfx`
52+
53+
3. **Deploy the Certificate**:
54+
- Copy the PFX file to a secure location on the Gateway server
55+
- Recommended location: `C:\Program Files\Keyfactor\AnyGateway\Certificates\` (Windows)
56+
- Or: `/opt/keyfactor/anygateway/certificates/` (Linux)
57+
- Set appropriate file permissions to restrict access
58+
- Record the full path and password for Gateway configuration
59+
60+
#### 3. Certificate Profiles (Templates)
61+
62+
Certificate profiles define the types of certificates that can be issued. The plugin automatically discovers available profiles from the Idnomic system.
63+
64+
**To view available profiles:**
65+
66+
1. The profiles are retrieved automatically when the CA is configured
67+
2. Profiles appear in Keyfactor Command as "Product IDs" after CA registration
68+
3. Each profile represents a certificate template configured in Idnomic PKI
69+
70+
**Note**: Profile discovery uses the `list_profiles` SOAP operation. Ensure the client certificate has permissions to call this operation.
71+
72+
#### 4. Zones
73+
74+
Zones in Idnomic PKI represent organizational or security boundaries within the PKI hierarchy. Each certificate enrollment request must specify a zone.
75+
76+
**Common zone examples**:
77+
- `Default`
78+
- `Production`
79+
- `Test`
80+
- `DMZ`
81+
- Custom zones as configured in your Idnomic PKI
82+
83+
**To identify available zones:**
84+
85+
1. Contact your Idnomic PKI administrator for the list of configured zones
86+
2. Zones may be visible through the `certificate_search_properties` operation
87+
3. Document the zone names exactly as they appear in the system (case-sensitive)
88+
89+
### Supported Revocation Reasons
90+
91+
The plugin supports the following standard CRL revocation reasons:
92+
93+
| Reason Code | Reason Name | Description |
94+
|-------------|-------------|-------------|
95+
| 0 | Unspecified | No specific reason provided |
96+
| 1 | Key Compromise | Private key has been compromised |
97+
| 2 | CA Compromise | Certificate Authority has been compromised |
98+
| 3 | Affiliation Changed | Subject's affiliation has changed |
99+
| 4 | Superseded | Certificate has been superseded by a new certificate |
100+
101+
**Note**: Not all Idnomic PKI configurations support all revocation reasons. Consult your Idnomic administrator for supported reasons in your environment.
102+
103+
## Gateway Registration
104+
105+
### CA Connection Configuration
106+
107+
When registering the Idnomic CA in the AnyCA Gateway, you'll need to provide the following configuration parameters:
108+
109+
| Parameter | Description | Required | Example |
110+
|-----------|-------------|----------|---------|
111+
| **EndpointAddress** | Full URL to the Idnomic RA connector SOAP endpoint | Yes | `https://idnomic.example.com:8443/RA/connector.cgi` |
112+
| **ClientCertLocation** | Full file path to the client certificate PFX file on the Gateway server | Yes | `C:\Certificates\gateway-client.pfx` |
113+
| **ClientCertPassword** | Password for the client certificate PFX file | Yes | `SecureP@ssw0rd` |
114+
| **Enabled** | Whether the CA connection is enabled | No (default: true) | `true` or `false` |
115+
116+
### Template (Product) Configuration
117+
118+
Each certificate template discovered from Idnomic requires configuration when used for enrollment:
119+
120+
| Parameter | Description | Required | Example |
121+
|-----------|-------------|----------|---------|
122+
| **Zone** | The Idnomic PKI zone where certificates will be issued | Yes | `Production` |
123+
124+
**Important Notes**:
125+
- Template names (Product IDs) are automatically discovered from Idnomic using the `list_profiles` operation
126+
- The Zone parameter must exactly match a zone configured in your Idnomic PKI system
127+
- Zone names are case-sensitive
128+
- Each template can be configured with a different zone if needed
129+
130+
### Gateway Registration Notes
131+
132+
- Each defined Certificate Authority in the AnyCA Gateway REST can support one Idnomic CA endpoint
133+
- 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
134+
- Each CA configuration will manifest in Command as a separate CA entry
135+
- The plugin uses SOAP-based communication exclusively; ensure the RA connector endpoint is properly configured for SOAP access
136+
- Client certificate authentication is mandatory and cannot be disabled
137+
- The "Enabled" flag allows you to temporarily disable a CA connection without removing the configuration
138+
139+
### Security Considerations
140+
141+
1. **Certificate Storage**: Store client certificates in a secure location with restricted file system permissions
142+
2. **Password Management**: Use strong passwords for client certificate PFX files and consider using a secrets management system
143+
3. **Network Security**: Ensure TLS/SSL is properly configured for the RA connector endpoint
144+
4. **Least Privilege**: Request client certificates with minimal required permissions in the Idnomic PKI system
145+
5. **Audit Logging**: Enable comprehensive logging in both the Gateway and Idnomic PKI for security monitoring
146+
147+
## Troubleshooting
148+
149+
### Connection Issues
150+
- Verify the RA connector endpoint URL is correct and accessible
151+
- Check that the client certificate is valid and not expired
152+
- Confirm the client certificate is trusted by the Idnomic PKI system
153+
- Review Gateway logs for SOAP communication errors
154+
155+
### Profile Discovery Issues
156+
- Ensure the client certificate has permissions to call `list_profiles`
157+
- Verify the RA connector is properly configured in Idnomic
158+
- Check that profiles are published and available in the Idnomic system
159+
160+
### Enrollment Failures
161+
- Verify the Zone parameter exactly matches a configured zone in Idnomic
162+
- Confirm the selected profile supports the requested certificate attributes
163+
- Check that the client certificate has enrollment permissions for the specified zone
164+
- Review Idnomic PKI logs for detailed error messages
165+
166+
### Synchronization Issues
167+
- Confirm the client certificate has permissions to call `search_for_certificates`
168+
- Verify network connectivity and timeout settings
169+
- For large certificate databases, consider adjusting synchronization schedules
170+
171+
## Test Cases
172+
173+
### Test Case 1: CA Connection Validation
174+
175+
**Objective**: Verify that the Gateway can successfully connect to the Idnomic RA connector using client certificate authentication.
176+
177+
**Prerequisites**:
178+
- Idnomic PKI system is operational
179+
- Valid client certificate (PFX) is available
180+
- RA connector endpoint is accessible
181+
182+
**Test Steps**:
183+
1. Configure the CA in AnyCA Gateway with valid connection parameters
184+
2. Click "Test Connection" or trigger the Ping operation
185+
3. Observe the connection result
186+
187+
**Expected Results**:
188+
- Connection succeeds without errors
189+
- Gateway logs show successful SOAP authentication
190+
- No certificate validation errors occur
191+
192+
**Verification**:
193+
- Review Gateway logs for successful connection message
194+
- Check Idnomic PKI logs for incoming authenticated connection
195+
- Verify no SSL/TLS errors in either system
196+
197+
---
198+
199+
### Test Case 2: Profile Discovery
200+
201+
**Objective**: Verify that the Gateway can retrieve the list of available certificate profiles from Idnomic PKI.
202+
203+
**Prerequisites**:
204+
- CA connection is successfully configured
205+
- At least one certificate profile is configured in Idnomic PKI
206+
- Client certificate has permissions to call `list_profiles`
207+
208+
**Test Steps**:
209+
1. Save the CA configuration in AnyCA Gateway
210+
2. Navigate to the template/product configuration section
211+
3. Observe the list of available Product IDs
212+
213+
**Expected Results**:
214+
- List of profiles is populated automatically
215+
- Profile names match those configured in Idnomic PKI
216+
- No empty or null profile names appear
217+
218+
**Verification**:
219+
- Compare the list of profiles in Gateway with Idnomic PKI configuration
220+
- Verify profile names are correctly displayed
221+
- Check Gateway logs for successful `list_profiles` SOAP call
222+
223+
---
224+
225+
### Test Case 3: Certificate Enrollment - Valid Request
226+
227+
**Objective**: Verify successful certificate enrollment through the plugin.
228+
229+
**Prerequisites**:
230+
- CA and template are properly configured
231+
- Valid Zone parameter is configured for the template
232+
- Test CSR is available
233+
234+
**Test Steps**:
235+
1. Submit an enrollment request via Keyfactor Command
236+
2. Specify the Idnomic CA and a valid template
237+
3. Provide a valid PKCS#10 CSR
238+
4. Wait for enrollment to complete
239+
240+
**Expected Results**:
241+
- Enrollment completes successfully
242+
- Certificate is issued by Idnomic PKI
243+
- Certificate is returned to Keyfactor Command
244+
- Certificate appears in Command inventory
245+
246+
**Verification**:
247+
- Verify certificate details match the CSR
248+
- Confirm certificate is present in Idnomic PKI database
249+
- Check that certificate chain is properly constructed
250+
- Validate certificate can be used for its intended purpose
251+
252+
---
253+
254+
### Test Case 4: Certificate Enrollment - Invalid Zone
255+
256+
**Objective**: Verify proper error handling when an invalid zone is specified.
257+
258+
**Prerequisites**:
259+
- CA and template are configured
260+
- Zone parameter is set to a non-existent zone name
261+
262+
**Test Steps**:
263+
1. Submit an enrollment request with invalid Zone parameter
264+
2. Observe the enrollment result
265+
266+
**Expected Results**:
267+
- Enrollment fails with clear error message
268+
- Error message indicates invalid zone
269+
- No certificate is issued
270+
- System remains stable
271+
272+
**Verification**:
273+
- Check error message clarity and accuracy
274+
- Verify Gateway logs contain detailed error information
275+
- Confirm no partial enrollment occurred in Idnomic PKI
276+
277+
---
278+
279+
### Test Case 5: Certificate Synchronization - Full Sync
280+
281+
**Objective**: Verify full certificate synchronization from Idnomic PKI to Keyfactor Command.
282+
283+
**Prerequisites**:
284+
- CA is properly configured
285+
- Multiple certificates exist in Idnomic PKI
286+
- Synchronization is configured in Command
287+
288+
**Test Steps**:
289+
1. Trigger a full synchronization job
290+
2. Wait for synchronization to complete
291+
3. Verify synchronized certificate count
292+
293+
**Expected Results**:
294+
- All certificates from Idnomic PKI are synchronized
295+
- Certificate details are accurate (subject, serial number, dates, etc.)
296+
- No duplicate certificates appear
297+
- Synchronization completes without errors
298+
299+
**Verification**:
300+
- Compare certificate count in Command vs. Idnomic PKI
301+
- Spot-check several certificates for data accuracy
302+
- Review synchronization logs for any warnings or errors
303+
- Verify certificate chains are properly synchronized
304+
305+
---
306+
307+
### Test Case 6: Certificate Synchronization - Incremental Sync
308+
309+
**Objective**: Verify incremental synchronization only retrieves new certificates since last sync.
310+
311+
**Prerequisites**:
312+
- Initial full synchronization has been completed
313+
- Timestamp of last sync is recorded
314+
- New certificates have been issued since last sync
315+
316+
**Test Steps**:
317+
1. Note the timestamp of the last successful sync
318+
2. Issue one or more new certificates in Idnomic PKI
319+
3. Trigger an incremental synchronization
320+
4. Observe synchronized certificates
321+
322+
**Expected Results**:
323+
- Only certificates issued after last sync are retrieved
324+
- Sync completes faster than full sync
325+
- All new certificates are properly synchronized
326+
- Previously synchronized certificates are not duplicated
327+
328+
**Verification**:
329+
- Verify only recent certificates were processed
330+
- Check sync duration is appropriate for certificate count
331+
- Review Gateway logs to confirm incremental sync parameters
332+
- Validate certificate data integrity
333+
334+
---
335+
336+
### Test Case 7: Certificate Revocation - Key Compromise
337+
338+
**Objective**: Verify certificate revocation with reason code 1 (Key Compromise).
339+
340+
**Prerequisites**:
341+
- A valid certificate issued through the Gateway exists
342+
- Certificate is not already revoked
343+
344+
**Test Steps**:
345+
1. Identify a test certificate to revoke
346+
2. Submit revocation request with reason "Key Compromise" (code 1)
347+
3. Wait for revocation to complete
348+
349+
**Expected Results**:
350+
- Revocation succeeds
351+
- Certificate status changes to "Revoked" in Command
352+
- Certificate appears on CRL in Idnomic PKI
353+
- Revocation reason is correctly recorded
354+
355+
**Verification**:
356+
- Check certificate status in Keyfactor Command
357+
- Verify certificate appears on Idnomic CRL with correct reason code
358+
- Confirm revocation timestamp is accurate
359+
- Validate certificate can no longer be used for authentication
360+
361+
---
362+
363+
### Test Case 8: Profile Properties Validation
364+
365+
**Objective**: Verify that profile-specific properties are correctly enforced during enrollment.
366+
367+
**Prerequisites**:
368+
- Profiles with different configurations exist (key sizes, validity periods, etc.)
369+
- Zone parameter is correctly configured
370+
371+
**Test Steps**:
372+
1. Attempt enrollment with CSR matching profile requirements
373+
2. Attempt enrollment with CSR not matching profile requirements (e.g., wrong key size)
374+
3. Observe results
375+
376+
**Expected Results**:
377+
- Valid enrollments succeed
378+
- Invalid enrollments fail with descriptive error messages
379+
- Profile constraints are properly enforced by Idnomic PKI
380+
381+
**Verification**:
382+
- Review error messages for clarity
383+
- Verify Idnomic PKI rejects non-compliant requests
384+
- Check that valid certificates meet profile specifications
385+
- Confirm Gateway properly communicates validation errors
386+
387+
---
1388

0 commit comments

Comments
 (0)