Skip to content

Commit d592a94

Browse files
mkachkmkachk
committed
Merge branch 'EKU-Fixes' of https://github.com/Keyfactor/aws-pca-caplugin into EKU-Fixes
2 parents 284f1fe + f105f72 commit d592a94

1 file changed

Lines changed: 355 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 355 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,355 @@
1+
<h1 align="center" style="border-bottom: none">
2+
AWSPCA CAPlugin AnyCA Gateway REST Plugin
3+
</h1>
4+
5+
<p align="center">
6+
<!-- Badges -->
7+
<img src="https://img.shields.io/badge/integration_status-pilot-3D1973?style=flat-square" alt="Integration Status: pilot" />
8+
<a href="https://github.com/Keyfactor/aws-pca-caplugin/releases"><img src="https://img.shields.io/github/v/release/Keyfactor/aws-pca-caplugin?style=flat-square" alt="Release" /></a>
9+
<img src="https://img.shields.io/github/issues/Keyfactor/aws-pca-caplugin?style=flat-square" alt="Issues" />
10+
<img src="https://img.shields.io/github/downloads/Keyfactor/aws-pca-caplugin/total?style=flat-square&label=downloads&color=28B905" alt="GitHub Downloads (all assets, all releases)" />
11+
</p>
12+
13+
<p align="center">
14+
<!-- TOC -->
15+
<a href="#support">
16+
<b>Support</b>
17+
</a>
18+
·
19+
<a href="#requirements">
20+
<b>Requirements</b>
21+
</a>
22+
·
23+
<a href="#installation">
24+
<b>Installation</b>
25+
</a>
26+
·
27+
<a href="#license">
28+
<b>License</b>
29+
</a>
30+
·
31+
<a href="https://github.com/orgs/Keyfactor/repositories?q=anycagateway">
32+
<b>Related Integrations</b>
33+
</a>
34+
</p>
35+
36+
37+
This integration allows for the Synchronization, Enrollment, and Revocation of certificates from the AWS ACM PCA. This is the AnyGateway REST version.
38+
39+
## Compatibility
40+
41+
The AWSPCA CAPlugin AnyCA Gateway REST plugin is compatible with the Keyfactor AnyCA Gateway REST 25.4.0 and later.
42+
43+
## Support
44+
The AWSPCA CAPlugin 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.
45+
46+
> 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.
47+
48+
## Requirements
49+
50+
This integration is tested and confirmed as working for Anygateway REST 24.4 and above. Notice: Keyfactor Anygateway REST 24.4 requires the use of .Net 8.
51+
52+
## Installation
53+
54+
1. Install the AnyCA Gateway REST per the [official Keyfactor documentation](https://software.keyfactor.com/Guides/AnyCAGatewayREST/Content/AnyCAGatewayREST/InstallIntroduction.htm).
55+
56+
2. On the server hosting the AnyCA Gateway REST, download and unzip the latest [AWSPCA CAPlugin AnyCA Gateway REST plugin](https://github.com/Keyfactor/aws-pca-caplugin/releases/latest) from GitHub.
57+
58+
3. Copy the unzipped directory (usually called `net6.0` or `net8.0`) to the Extensions directory:
59+
60+
61+
```shell
62+
Depending on your AnyCA Gateway REST version, copy the unzipped directory to one of the following locations:
63+
Program Files\Keyfactor\AnyCA Gateway\AnyGatewayREST\net6.0\Extensions
64+
Program Files\Keyfactor\AnyCA Gateway\AnyGatewayREST\net8.0\Extensions
65+
```
66+
67+
> The directory containing the AWSPCA CAPlugin AnyCA Gateway REST plugin DLLs (`net6.0` or `net8.0`) can be named anything, as long as it is unique within the `Extensions` directory.
68+
69+
4. Restart the AnyCA Gateway REST service.
70+
71+
5. Navigate to the AnyCA Gateway REST portal and verify that the Gateway recognizes the AWSPCA CAPlugin plugin by hovering over the ⓘ symbol to the right of the Gateway on the top left of the portal.
72+
73+
## Configuration
74+
75+
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:
76+
77+
* **Gateway Registration**
78+
79+
Download the **PCA root certificate** from AWS and have it ready to import into the Gateway **in `.pem` format**.
80+
81+
* **CA Connection**
82+
83+
Populate using the configuration fields collected in the [requirements](#requirements) section.
84+
85+
* **RoleArn** - Destination Role ARN to use for AWS auth. Supports the [profile] prefix when using Default SDK auth, e.g. [myprofile]arn:aws:iam::123456789012:role/MyRole.
86+
* **Region** - AWS Region (single region only, e.g. us-east-1).
87+
* **CAArn** - AWS ACM PCA Certificate Authority ARN. Example: arn:aws:acm-pca:us-east-1:123456789012:certificate-authority/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
88+
* **S3Bucket** - S3 bucket name used for PCA audit reports (inventory). The AWS identity in the Role context must have read/write permissions to this bucket.
89+
* **UseDefaultSdkAuth** - Use AWS SDK default credential inference (supports EC2 instance role, environment variables, shared credentials, etc.). If RoleArn is prefixed with [profile], that profile is prioritized.
90+
* **DefaultSdkAssumeRole** - If UseDefaultSdkAuth is true, setting this to true will perform AssumeRole into RoleArn using the inferred SDK credentials.
91+
* **UseOAuth** - Use OAuth OIDC authentication to obtain a token, then AssumeRole into RoleArn.
92+
* **OAuthScope** - OAuth scope to request.
93+
* **OAuthGrantType** - OAuth grant type to request (commonly client_credentials).
94+
* **OAuthUrl** - OAuth token endpoint URL.
95+
* **OAuthClientId** - OAuth client id (secret).
96+
* **OAuthClientSecret** - OAuth client secret (secret).
97+
* **UseIAM** - Use IAM user access key/secret to AssumeRole into RoleArn.
98+
* **IAMUserAccessKey** - IAM user access key (secret).
99+
* **IAMUserAccessSecret** - IAM user access secret (secret).
100+
* **ExternalId** - Optional sts:ExternalId to supply on AssumeRole calls.
101+
* **Enabled** - Flag to Enable or Disable gateway functionality. Disabling is primarily used to allow creation of the CA prior to configuration information being available.
102+
103+
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. The AWSPCA CAPlugin plugin supports the following product IDs:
104+
105+
* **EndEntity**
106+
* **EndEntityClientAuth**
107+
* **EndEntityServerAuth**
108+
* **CodeSigning**
109+
110+
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.
111+
112+
4. In Keyfactor Command (v12.3+), for each imported Certificate Template, follow the [official documentation](https://software.keyfactor.com/Core-OnPrem/Current/Content/ReferenceGuide/Configuring%20Template%20Options.htm) to define enrollment fields for each of the following parameters:
113+
114+
* **LifetimeDays** - OPTIONAL: The number of days of validity to use when requesting certs. If not provided, default is 365
115+
* **SigningAlgorithm** - Required: AWS ACM PCA certificate signature algorithm to use when issuing certificates. Value is an AWS PCA SigningAlgorithm enum name (case-insensitive), e.g. SHA256WITHRSA, SHA384WITHRSA, SHA256WITHECDSA. If omitted, the plugin selects a default compatible with the CA key algorithm.
116+
117+
118+
## Authentication (Access Key + Secret)
119+
120+
The CAPlugin currently supports **one** authentication method: **AWS Access Key ID + Secret Access Key**.
121+
**OAuth** and **Default SDK authentication** will be enabled in later updates. There is functionality present via the **Keyfactor AWS Authentication** library, but these alternate methods are currently ***untested***.
122+
123+
### What you need ready
124+
125+
Before configuring the CAPlugin, have the following prepared:
126+
127+
#### 1) IAMUserAccessKey and IAMUserAccessSecret
128+
- **Access Key ID** (example format: `AKIAIOSFODNN7EXAMPLE`)
129+
- **Secret Access Key** (example format: `wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY`)
130+
131+
#### 2) A target IAM Role the Gateway will run as (recommended)
132+
Example:
133+
- `arn:aws:iam::123456789012:role/Keyfactor-AnyGateway-AcmPcaRole`
134+
135+
**Role expectations:**
136+
- The role must have permissions for:
137+
- **ACM PCA operations** (Issue/Get/Revoke/Describe + CA certificate chain retrieval)
138+
- **Audit report creation & status polling** (Create/Describe audit reports)
139+
- **S3 bucket access** to read/write audit report objects
140+
141+
#### 3) Permissions on the assumed role
142+
The assumed role must have permissions for the AWS services the Gateway needs. This typically includes:
143+
- `acm-pca:*` actions required for enrollment + revocation workflows
144+
- Audit report actions (`acm-pca:CreateCertificateAuthorityAuditReport`, `acm-pca:DescribeCertificateAuthorityAuditReport`)
145+
- S3 bucket and object access for the audit report destination bucket
146+
147+
**See the example IAM policies below in this README section**
148+
149+
#### 4) Region
150+
Know the **AWS region** the connector should use (for service endpoints), e.g.:
151+
- `us-east-1`
152+
153+
> Region must match the region of your **ACM Private CA**.
154+
155+
#### 5) CA ARN
156+
Have the **Certificate Authority ARN** for the PCA you want to integrate with.
157+
158+
Example format:
159+
- `arn:aws:acm-pca:<region>:<account-id>:certificate-authority/<ca-uuid>`
160+
161+
Example:
162+
- `arn:aws:acm-pca:us-east-2:123456789012:certificate-authority/11111111-2222-3333-4444-555555555555`
163+
164+
#### 6) S3 Bucket
165+
Choose an S3 bucket to store / retrieve ACM PCA audit reports.
166+
167+
You should have:
168+
- **Bucket name** (example: `keyfactor-acmpca-audit-reports`, not the full bucket ARN!)
169+
170+
171+
> The role needs `s3:ListBucket` / `s3:GetBucketLocation` at the bucket ARN, and `s3:GetObject` / `s3:PutObject` on the object ARN pattern.
172+
173+
#### 7) PCA Root Cert
174+
Download the **PCA root certificate** from AWS and have it ready to import into the Gateway **in `.pem` format**.
175+
176+
### Enabling all this in the Gateway Configuration Portal
177+
178+
#### 1) Register the Gateway CA and upload the Root CA certificate
179+
1. Navigate to **Gateway Registration**.
180+
2. Upload the **Root CA Certificate** you downloaded earlier (PEM).
181+
182+
#### 2) Configure the CA connection settings
183+
1. Navigate to **CAConnection**.
184+
2. Populate:
185+
- `RoleArn` (example: `arn:aws:iam::123456789012:role/Keyfactor-AnyGateway-AcmPcaRole`)
186+
- `Region` (example: `us-east-2`)
187+
- `CAArn` (example: `arn:aws:acm-pca:us-east-2:123456789012:certificate-authority/11111111-2222-3333-4444-555555555555`)
188+
- `S3Bucket` (example: `keyfactor-acmpca-audit-reports`)
189+
- `IAMUserAccessKey` (example: `AKIA...`)
190+
- `IAMUserAccessSecret` (example: `wJalrXU...`)
191+
192+
3. Set these auth toggles:
193+
- `UseDefaultSdkAuth` = `false`
194+
- `UseOAuth` = `false`
195+
- `UseIAM` = `true`
196+
197+
---
198+
199+
### Example IAM policies for the assumed role
200+
201+
The following examples are intended as **copy/adapt templates**.
202+
203+
#### Example 1: Minimal PCA issuance/retrieval/revocation
204+
205+
```json
206+
{
207+
"Version": "2012-10-17",
208+
"Statement": [
209+
{
210+
"Sid": "PrivateCABasicOps",
211+
"Effect": "Allow",
212+
"Action": [
213+
"acm-pca:IssueCertificate",
214+
"acm-pca:GetCertificate",
215+
"acm-pca:RevokeCertificate",
216+
"acm-pca:DescribeCertificateAuthority",
217+
"acm-pca:GetCertificateAuthorityCertificate"
218+
],
219+
"Resource": "arn:aws:acm-pca:<region>:<account-id>:certificate-authority/<ca-uuid>"
220+
}
221+
]
222+
}
223+
```
224+
225+
#### Example 2: PCA issuance + audit reports + S3 audit bucket access
226+
227+
```json
228+
{
229+
"Version": "2012-10-17",
230+
"Statement": [
231+
{
232+
"Sid": "PrivateCAIssueAndFetch",
233+
"Effect": "Allow",
234+
"Action": [
235+
"acm-pca:IssueCertificate",
236+
"acm-pca:GetCertificate",
237+
"acm-pca:DescribeCertificateAuthority",
238+
"acm-pca:GetCertificateAuthorityCertificate"
239+
],
240+
"Resource": [
241+
"arn:aws:acm-pca:<region>:<account-id>:certificate-authority/<ca-uuid>"
242+
]
243+
},
244+
{
245+
"Sid": "PrivateCAAuditReportOps",
246+
"Effect": "Allow",
247+
"Action": [
248+
"acm-pca:CreateCertificateAuthorityAuditReport",
249+
"acm-pca:DescribeCertificateAuthorityAuditReport"
250+
],
251+
"Resource": "*"
252+
},
253+
{
254+
"Sid": "AuditReportBucketAccessForCaller",
255+
"Effect": "Allow",
256+
"Action": [
257+
"s3:GetBucketLocation",
258+
"s3:ListBucket"
259+
],
260+
"Resource": "arn:aws:s3:::<audit-bucket-name>"
261+
},
262+
{
263+
"Sid": "AuditReportObjectAccessForCaller",
264+
"Effect": "Allow",
265+
"Action": [
266+
"s3:GetObject",
267+
"s3:PutObject"
268+
],
269+
"Resource": "arn:aws:s3:::<audit-bucket-name>/*"
270+
}
271+
]
272+
}
273+
```
274+
---
275+
276+
### Example policy for bucket
277+
```json
278+
{
279+
"Version": "2012-10-17",
280+
"Statement": [
281+
{
282+
"Sid": "AllowACMPCAWriteAuditReports",
283+
"Effect": "Allow",
284+
"Principal": {
285+
"Service": "acm-pca.amazonaws.com"
286+
},
287+
"Action": "s3:PutObject",
288+
"Resource": "arn:aws:s3:::<audit-bucket-name>/*",
289+
"Condition": {
290+
"StringEquals": {
291+
"aws:SourceAccount": "<account-id>"
292+
},
293+
"ArnLike": {
294+
"aws:SourceArn": "arn:aws:acm-pca:<region>:<account-id>:certificate-authority/<ca-uuid>"
295+
}
296+
}
297+
}
298+
]
299+
}
300+
```
301+
302+
---
303+
304+
## Signing algorithm selection (ACM PCA)
305+
306+
The connector supports an optional **template / product parameter** named `SigningAlgorithm` that controls the **certificate signature algorithm**
307+
passed to AWS ACM PCA `IssueCertificate`.
308+
309+
- If **not set**, the plugin will **auto-select** a compatible default based on the CA `KeyAlgorithm` returned by
310+
`DescribeCertificateAuthority`.
311+
- If **set**, the plugin validates the value and **rejects incompatible combinations** before calling AWS.
312+
313+
### Where to configure
314+
315+
Set `SigningAlgorithm` on the **AnyGateway template** (product parameters), alongside `LifetimeDays`.
316+
317+
### Valid `SigningAlgorithm` values (AWS PCA)
318+
319+
- RSA family: `SHA256WITHRSA`, `SHA384WITHRSA`, `SHA512WITHRSA`
320+
- ECDSA family: `SHA256WITHECDSA`, `SHA384WITHECDSA`, `SHA512WITHECDSA`
321+
- SM2: `SM3WITHSM2`
322+
- ML-DSA (post-quantum): `ML_DSA_44`, `ML_DSA_65`, `ML_DSA_87`
323+
324+
### Allowed CA key algorithm <-> signing algorithm combinations
325+
326+
The CA key algorithm is the PCA CA **KeyAlgorithm** (not the subject key in the CSR). The signing algorithm must match the CA key family.
327+
328+
| CA KeyAlgorithm | Allowed SigningAlgorithm values |
329+
|---|---|
330+
| `RSA_2048`, `RSA_3072`, `RSA_4096` | `SHA256WITHRSA`, `SHA384WITHRSA`, `SHA512WITHRSA` |
331+
| `EC_prime256v1`, `EC_secp384r1`, `EC_secp521r1` | `SHA256WITHECDSA`, `SHA384WITHECDSA`, `SHA512WITHECDSA` |
332+
| `SM2` | `SM3WITHSM2` |
333+
| `ML_DSA_44` | `ML_DSA_44` |
334+
| `ML_DSA_65` | `ML_DSA_65` |
335+
| `ML_DSA_87` | `ML_DSA_87` |
336+
337+
### Auto-selection defaults
338+
339+
When `SigningAlgorithm` is omitted, the plugin selects:
340+
341+
- RSA CAs -> `SHA256WITHRSA`
342+
- EC P-256 -> `SHA256WITHECDSA`
343+
- EC P-384 -> `SHA384WITHECDSA`
344+
- EC P-521 -> `SHA512WITHECDSA`
345+
- SM2 -> `SM3WITHSM2`
346+
- ML-DSA -> exact-match (`ML_DSA_44/65/87`)
347+
348+
349+
## License
350+
351+
Apache License 2.0, see [LICENSE](LICENSE).
352+
353+
## Related Integrations
354+
355+
See all [Keyfactor Any CA Gateways (REST)](https://github.com/orgs/Keyfactor/repositories?q=anycagateway).

0 commit comments

Comments
 (0)