Merge pull request #166 from ts-amz/add-acmpca-to-certificatevendor

Add acmpca to certificatevendor

Author: ts-amz

source/packages/services/certificatevendor/README.md

@@ -4,7 +4,8 @@
 
 The certificate vendor manages the rotation of certificates involving a number of moving parts across CDF and AWS IoT.
 
-There are two flows for certificate rotation. In the fist case, device certificates are pre-created and registered before the rotation request. In this case the device requests a new certificate and is vended an S3 presigned URL in order to download the certificate package. In the second case, the device provides the certificate vendor module a CSR. In this way the device can request an updated certificate while keeping the private key on the device. The certificate vendor then uses a CA certificate registered with AWS IoT to create a device certificate from the CSR and return this certificate to the device.
+There are two flows for certificate rotation. In the fist case, device certificates are pre-created and registered before the rotation request. In this case the device requests a new certificate and is vended an S3 presigned URL in order to download the certificate package. In the second case, the device provides the certificate vendor module a CSR. In this way the device can request an updated certificate while keeping the private key on the device.
+There are two options for CSR case. One option is to use ACM PCA to issue the certificate, and another option is to create a certificate from a CA certificate registered with AWS IoT, and CA private key sorted in EC2 Parameter store.
 
 ## Architecture
 
@@ -20,8 +21,41 @@ A certificate package comprising of the certificate, public key and private key
 
 ### Certificate Creation with a device CSR
 
+#### Certiicate Creation with CA private key
+
 A CA certificate needs to be registered with AWS IoT. In addtion, the CA private key needs to be encrypted and stored in EC2 Parameter store so the certificate vendor module can sign device certificates using the CA.
 
+#### Certificate Creation from ACMPCA
+
+AWS Private Certificate Authority needs to be prepared and private CA needs to be created as prerequisite.
+The private CA needs to be registered with AWS IoT. The example registration step is as follows.
+
+```
+1. Create Verification CSR
+  $ openssl genrsa -out verificationCert.key 2048
+2. Get IoT Core Registration Code
+  $ aws iot get-registration-code
+3. Create CSR. Insert the registration code in Common Name.
+  $ openssl req -new -key verificationCert.key -out verificationCert.csr
+4. Request to issue certificate to ACM PCA for verification. It will return certificate ARN.
+  $ aws acm-pca issue-certificate \
+  --region ap-northeast-1  \
+  --certificate-authority-arn arn:aws:acm-pca:ap-northeast-1:XXXXXXXXXXX:certificate-authority/12345678910 \
+  --csr fileb://verificationCert.csr  \
+  --signing-algorithm SHA256WITHRSA \
+  --validity Value=365,Type="DAYS"
+5. Call get-certificate to get certificate
+  $ aws acm-pca get-certificate --region ap-northeast-1 \
+--certificate-authority-arn arn:aws:acm-pca:ap-northeast-1:XXXXXXXXXXX:certificate-authority/12345678910 \
+--certificate-arn arn:aws:acm-pca:ap-northeast-1:XXXXXXXXXXX:certificate-authority/12345678910
+6. Store the Certificate as verify.crt. Transform \n into return code.
+7. Register to IoT Core by using Verification CSR and Root CA certification.
+  $ aws iot register-ca-certificate --ca-certificate file://Certificate.pem --verification-certificate file://Verify.crt --region ap-northeast-1 --set-as-active
+```
+
+The registered CA Certificate ID and PCA Authority Arn need to be entered
+in the inquiry prompt in the installer or request body as parameters.
+
 ## Deployment
 
 The following resources are automatically created as part of the deployment and utilized by this flow:
@@ -139,6 +173,40 @@ MQTT PUBLISH BODY:
 }
 ```
 
+Example MQTT message body sent from the device to the AWS IoT Gateway to retrieve a certificate based on a provided CSR. That use ACM PCA to issue a new certificate:
+
+```sh
+MQTT SUBSCRIBE TOPIC:     cdf/certificates/thing001/get/+
+MQTT PUBLISH TOPIC:       cdf/certificates/thing001/get
+MQTT PUBLISH BODY:
+{
+    "csr":"-----BEGIN CERTIFICATE REQUEST-----\nCSR CONTENT\n-----END CERTIFICATE REQUEST-----"
+    "acmpcaParameters" :{ // If not specified, the values specified in the installer will be used.
+        // Mandatory. Either provide the ACM PCA CA ARN to issue the device certificate,
+        //      or an alias that points to said AWS ACM PCA CA ARN:
+        "acmpcaCaArn": "?",
+        "acmpcaCaAlias": "?",
+
+        // Mandatory. Either provide the AWS IoT CA ID of the ACM PCA CA registered with AWS IoT,
+        //      or an alias that points to said AWS IoT CA ID:
+        "awsiotCaID": "?",
+        "awsiotCaAlias": "?",
+
+        // Optional. Certificate information to apply:
+        "certInfo": {                       // optional.
+            "commonName": "?",              // optional
+            "organization": "?",            // optional
+            "organizationalUnit": "?",      // optional
+            "locality": "?",                // optional
+            "stateName": "?",               // optional
+            "country": "?",                 // optional
+            "emailAddress": "?",            // optional
+            "daysExpiry": ?                 // optional
+        }
+    }
+}
+```
+
 Upon receiving the request, the CDF Certificate Vendor module validates that the device is approved to received a new certificate. The registry to be used, whether the AWS IoT Device Registry or the CDF Asset Library module, is configured as part of the initial deployment. This reference implementation determines whether something is approved by checking its existence. If these behavior needs to be enhanced, refer to `src/registry/assetlibrary.service.ts` / `src/registry/deviceregistry.service.ts`
 
 If approved, the CDF Certificate Vendor module checks for the presence of a CSR in the request. If provided, the CSR is used to create a new device certificate and returned to the device. If not present, teh CDF Certificate Vendor module proceeds to download the S3 Object Metadata associated with the certificate package to retrieve the `certificateId`, activates the certificate within AWS IoT, then constructs and returns a pre-signed url to the device for secure downloading of the certificate package. Finally the device status is updated to activated.

source/packages/services/certificatevendor/infrastructure/cfn-certificatevendor.yml

@@ -64,12 +64,25 @@ Parameters:
   RotatedCertificatePolicy:
     Type: String
     Default: ''
+  AcmpcaEnabled:
+    Type: String
+    Default: 'false'
+  AcmpcaCaArn:
+    Type: String
+    Default: ''
+  AcmpcaSigningAlgorithm:
+    Type: String
+    Default: 'SHA256WITHRSA'
+  ACMPCACrossAccountRoleArn:
+    Description: If ACM PCA functionality is to be used, and a ACM PCA is located within a different AWS Account, specify the cross-account IAM Role ARN.
+    Type: String
+    Default: ''
 
 Conditions:
   ThingGroupNameProvided: !Not [!Equals [!Ref ThingGroupName, '']]
   KmsKeyProvided: !Not [!Equals [!Ref KmsKeyId, '']]
   KmsKeyNotProvided: !Equals [!Ref KmsKeyId, '']
-
+  ACMPCACrossAccountAccessRequired: !Not [!Equals [!Ref ACMPCACrossAccountRoleArn, '']]
 Resources:
   MQTTGetRule:
     Type: 'AWS::IoT::TopicRule'
@@ -149,6 +162,7 @@ Resources:
       ManagedPolicyArns:
         - !Ref ApplicationPolicies
         - !Ref ApplicationCsrPolicies
+        - !Ref ACMPolicy
         - arn:aws:iam::aws:policy/AWSLambdaExecute
         - arn:aws:iam::aws:policy/AWSXrayWriteOnlyAccess
     Condition: KmsKeyProvided
@@ -261,6 +275,25 @@ Resources:
             Effect: Allow
             Resource: !Sub 'arn:aws:iot:${AWS::Region}:${AWS::AccountId}:cert/*'
 
+  ACMPolicy:
+    Type: AWS::IAM::ManagedPolicy
+    Properties:
+      Description: 'cdf-bulkcerts policy for accessing ACM PCA'
+      Path: '/cdf/provisioning/'
+      PolicyDocument:
+        Version: '2012-10-17'
+        Statement:
+          - Action:
+              - 'acm-pca:IssueCertificate'
+              - 'acm-pca:GetCertificate'
+            Effect: Allow
+            Resource: '*'
+          # optional cross-account role access for ACM PCA
+          - Fn::If:
+              - ACMPCACrossAccountAccessRequired
+              - !Ref ACMPCACrossAccountRoleArn
+              - Ref: AWS::NoValue
+
   LambdaFunction:
     Type: AWS::Serverless::Function
     Properties:
@@ -287,7 +320,11 @@ Resources:
           AWS_S3_CERTIFICATES_BUCKET: !Ref BucketName
           CERTIFICATES_CACERTIFICATEID: !Ref CaCertificateId
           POLICIES_ROTATEDCERTIFICATEPOLICY: !Ref RotatedCertificatePolicy
+          ACMPCA_ENABLED: !Ref AcmpcaEnabled
+          ACMPCA_CA_ARN: !Ref AcmpcaCaArn
+          ACMPCA_SIGNING_ALGORITHM: !Ref AcmpcaSigningAlgorithm
           AWS_ACCOUNTID: !Ref AWS::AccountId
+          ACM_PCA_CROSS_ACCOUNT_ROLE_ARN: !Ref ACMPCACrossAccountRoleArn
       Tracing: Active
 
   IotEndpoint:

source/packages/services/certificatevendor/src/certificates/certificates.models.ts

@@ -16,6 +16,28 @@ export interface CertificateRequestModel {
     certId: string;
     csr?: string;
     previousCertificateId?: string;
+    acmpcaParameters?: ACMPCAParameters;
+}
+
+export interface ACMPCAParameters {
+    acmpcaCaArn?: string;
+    acmpcaCaAlias?: string;
+
+    awsiotCaID?: string;
+    awsiotCaAlias?: string;
+
+    certInfo?: CertInfo;
+}
+
+export interface CertInfo {
+    commonName?: string;
+    organization?: string;
+    organizationalUnit?: string;
+    locality?: string;
+    stateName?: string;
+    country?: string;
+    emailAddress?: string;
+    daysExpiry?: number;
 }
 
 export interface CertificateResponseModel {

source/packages/services/certificatevendor/src/certificates/certificates.service.spec.ts

@@ -21,6 +21,7 @@ let mockedIot: AWS.Iot;
 let mockedIotData: AWS.IotData;
 let mockedS3: AWS.S3;
 let mockedSSM: AWS.SSM;
+let mockedACMPCA: AWS.ACMPCA;
 const accountId = '12345678';
 const region = 'us-west-2';
 const s3Bucket = 'myBucket';
@@ -37,6 +38,9 @@ const useDefaultPolicy = true;
 const rotateCertPolicy = 'UnitTestDevicePolicy';
 const certificateExpiryDays = 100;
 const deletePreviousCertificate = false;
+const acmpcaCaArn = 'arn:aws:acm-pca:ap-northeast-1:12345678910:certificate-authority/abcdefghi';
+const acmpcaEnabled = false;
+const acmpcaSigningAlgorithm = 'SHA256WITHRSA';
 const certId = 'cert123456';
 let defaultPolicyInstance: CertificateService;
 let inheritPolicyInstance: CertificateService;
@@ -59,6 +63,7 @@ describe('CertificatesService', () => {
         mockedIot = new AWS.Iot();
         mockedIotData = new AWS.IotData({ endpoint: 'mocked' });
         mockedSSM = new AWS.SSM();
+        mockedACMPCA = new AWS.ACMPCA();
 
         const mockedS3Factory = () => {
             return mockedS3;
@@ -72,6 +77,9 @@ describe('CertificatesService', () => {
         const mockedSsmFactory = () => {
             return mockedSSM;
         };
+        const mockedAcmpcaFactory = () => {
+            return mockedACMPCA;
+        };
 
         defaultPolicyInstance = new CertificateService(
             accountId,
@@ -90,11 +98,15 @@ describe('CertificatesService', () => {
             rotateCertPolicy,
             certificateExpiryDays,
             deletePreviousCertificate,
+            acmpcaCaArn,
+            acmpcaEnabled,
+            acmpcaSigningAlgorithm,
             mockedRegistryManager,
             mockedIotFactory,
             mockedIotDataFactory,
             mockedS3Factory,
-            mockedSsmFactory
+            mockedSsmFactory,
+            mockedAcmpcaFactory
         );
 
         inheritPolicyInstance = new CertificateService(
@@ -114,11 +126,15 @@ describe('CertificatesService', () => {
             rotateCertPolicy,
             certificateExpiryDays,
             deletePreviousCertificate,
+            acmpcaCaArn,
+            acmpcaEnabled,
+            acmpcaSigningAlgorithm,
             mockedRegistryManager,
             mockedIotFactory,
             mockedIotDataFactory,
             mockedS3Factory,
-            mockedSsmFactory
+            mockedSsmFactory,
+            mockedAcmpcaFactory
         );
     });