AWS Setup

The configuration in AWS can be one of two ways, depending on where you choose to store the private key used for the Digital Signature:

• AWS S3 + KMS
• AWS CloudHSM

Lambda Function for Webhooks

1. Navigate to Services - Lambda. Create clearbankFunction Lambda function.
   

2. Create Function.

3. Upload the .zip file clearbankFunction.
   After uploading, you should find the following files in the Lambda function Code source:
   

4. In order to verify the webhooks from ClearBank, it is necessary to have the public key from ClearBank institution. You can get it from Webhook Management:

The public key needs to be uploaded in AWS in a file named publicKey.pem that is available to the forClearBank lambda function:

In this file you need to copy and paste the key you downloaded from ClearBank. It should look similar to this:

5. Update the environment variables (should contain the MPO process details - Webhook Listener [AWS] (Secret key, API login and process ID) and company_id which will receive the webhooks and sign back the Nonce response). Click Save.
   

6. Update the allocated memory from Lambda function (e.g: clearBankFunction) - Basic Settings - Memory (MB). If you expect many requests to be sent, then allocate the default memory 2048 MB with a 10 seconds delay for the process.
   

AWS Secret setup

The AWS secret should be defined in order to store the authorization token and the secret key used to authenticate requests coming from MPO to AWS.

Firstly, you need to access the AWS Secrets Manager service: Afterwards, you need to create a new secret like this:

Please note that value1 and value2 from the screenshot above should match the authorizationTokenAWS and secretKey values from MPO ClearBank config!

In the end, you should have a new secret stored in AWS:

Digital Signature Lambda Functions

→Lambda Function for Digital Signature using AWS S3 and KMS solution

1. Navigate to Services - Lambda. Create digitalSignature Lambda function.
2. When no execution role exists, create a new execution role by selecting the option Create a new role with basic Lambda permissions. In addition, Lambda function also needs to have permissions to read the Secret value for the AWS secret, i.e.:
   
3. Create Function.
4. Upload the .zip file digitalSignature.
   
5. Add an environment variable to point to the AWS secret previously defined.

→Lambda Function for Digital Signature using AWS CloudHSM solution

In case you use the Digital Signature based on AWS CloudHSM private key, you need to follow the steps documented at https://docs.google.com/document/d/1H6CZiU0YZHuU1JMsTdg0MSIHyM12OB7AmPEYq6K8mFc/edit#heading=h.e0ewvaxju46u.

After setting the Lambda function according to the above documentation, there are 2 more steps in order to interact with the AWS secret:

1. Create an additional environment variable to the Lambda function, that needs to point to the AWS secret created previously:

2. Verify the permissions of the Lambda function role - Lambda function needs to have permissions to read the Secret value for the AWS secret, i.e.:

→Lambda Function for Authorization Token

This Lambda function is required to authenticate the requests coming to the API Gateway for Digital Signature (ensuring that they come from MPO). To create and configure this function, you need to follow these steps:

1. Navigate to Services - Lambda. Create authorizer Lambda function.
   
2. Choose a role that gives the Lambda function access to AWS Secret Manager (see step 2 of Lambda Function for Digital Signature using CloudHSM solution)
3. Create Function.
4. Upload the .zip file authorizer.
   
5. Add the SECRET_ID environment variable: This should point to the secret created in the section AWS Secret Setup.

API Gateways

→API Gateway for Webhooks

1. Navigate to Services - API Gateway and create the endpoint path (click on Create API button and select Rest API - Build).
   
2. Open your new API. Go to Resources - Actions and click on button Create Resource.
   
3. Create synchronous endpoint by selecting the previous resource created (e.g: /gateway). Click on Actions - Create Method - POST. Select the POST method and add the lambda function (e.g: forClearBank).
   
4. Select Method Request section from API Gateway (POST). Add Request Validator - Validate query string parameters and headers under Settings.
5. Select Integration Request section from API Gateway (POST). Add Mapping Templates - application/json.
   The following code needs to be placed at the mapping templates:

{
    "body":"$util.escapeJavaScript($input.body).replaceAll("\\'","'").replaceAll("\'","'")",
    "headers":{
        #foreach($param in $input.params().header.keySet())
        "$param": "$util.escapeJavaScript($input.params().header.get($param))"
        #if($foreach.hasNext),#end
        #end
    }
}

6. Select Method Response section from API Gateway (POST). Map success response message for ClearBank and add DigitalSignature header.
   Map 401 response (Unauthorized) having Response body model Error.
7. Select Integration Response section from API Gateway (POST). Map ClearBank DigitalSignature header and success response message.
   

##  See http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html
## WARNING: Every character matters in this form (including spaces)! Do not change a bit!
#set($inputRoot = $input.json('$.Nonce')){"Nonce":$inputRoot}

Response codes:

Accepted -> 200 response code
Rejected -> 401 response code

Map 401 response code having the “AUTHORIZATION ERROR” Lambda error regex and the mapping template below:

{
  "errorMessage" : "$input.path('$.errorMessage')"
}

8. Deploy API from Actions menu.
   
9. Copy the Invoke URL (required for ClearBank webhooks linkage) available under Stages section.
   

→API Gateway for Digital Signature

1. Navigate to Services - API Gateway and create the endpoint path (click on Create API button and select Rest API - Build).
2. Open your new API. Go to Resources - Actions and click on button Create Resource.
3. Create synchronous endpoint by selecting the previous resource created (e.g: /gateway). Click on Actions - Create Method - POST. Select the POST method and add the lambda function (e.g: digitalSignature).
4. Link the authorizer lambda function to Digital Signature API Gateway from Authorizer section.
   
   
   
5. Select Method Request section from API Gateway (POST). Add the Authorization as HTTP Request Header and the following Settings parameters:
   • Authorization - select the authorizer token created as a lambda function authorizer (e.g: AuthorizerSM).
     
   • Request Validator - Validate query string parameters and headers.
     
6. Select Integration Request section from API Gateway (POST). Add Mapping Templates - application/json.
   

{
    "body":$input.json("$"),
    "queryparams":{
        #foreach($param in $input.params().querystring.keySet())
        "$param": "$util.escapeJavaScript($input.params().querystring.get($param))"
        #if($foreach.hasNext),#end
        #end
    },
    "headers":{
        #foreach($param in $input.params().header.keySet())
        "$param": "$util.escapeJavaScript($input.params().header.get($param))"
        #if($foreach.hasNext),#end
        #end
    }
}

7. Select Method Response section from API Gateway (POST). Map ClearBank success response message and add DigitalSignature header.
   For error messages, map Response Body model to Error:
8. Select Integration Response section from API Gateway (POST). Map ClearBank DigitalSignature header and success response message.
   

##  See http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html
#set($inputRoot = $input.json('$'))
$inputRoot

For method response status 400, map ERROR response message like below:

{
  "errorMessage" : "$input.path('$.errorMessage')"
}

9. Deploy API from Actions menu.
   
10. Copy the Invoke URL (required for MPO setup) available under Stages section.
    

Certificate and Token

→Generate Certificate

1. Navigate to Services - Lambda, search and select DigitalSignature function.
   
2. From function code rename index file (e.g: index_1).
3. From function code rename generate CSR file into index. Click first on Deploy then on Test.
4. From the reponse create the .csr file. Copy the certificate which starts from -----BEGIN CERTIFICATE REQUEST----- and ends in -----END CERTIFICATE REQUEST----- (without single quotas). Save the file with extension .csr.
5. From the reponse create the .pem file. Copy the Private Key which starts from -----BEGIN PRIVATE KEY----- and ends in -----END PRIVATE KEY----- (without single quotas). Save the file with extension .pem.
6. Rename the file index to generate CSR and the index_1 file from Step 2 to index.

→Generate Token

1. Navigate to ClearBank UI - Certificates and Tokens- Generate API Token.
   
2. Upload the csr file previously created (certificate that was created in Certificate and Token - Generate Certificate section, Step 4).
3. Provide a Token Name and select the Expiration Date. Generate.
   
4. Copy the API Token generated.

Key Management Service (KMS)

Note: this step can be skipped ifCloudHSM solution is used.

→KMS for Digital Signature Encryption

1. Navigate to Services - Key Management Service (KMS) and create a new key (click on Create a Key as key type Symmetric).
2. Choose an alias for the key and, optionally description, tag key, tag value.
   
3. Choose key administrators and select the IAM users and roles that can use the CMK in cryptographic operations.
   

Note: Multiple selections can be done, important is to add the Role under the digitalSignature Lambda function is executed and the User (the key administrator).

4. Review Key policy and Finish.
   

→S3 Bucket

1. Navigate to Services - S3. Select Buckets option and create a new bucket (click on Create bucket).
   
2. In the Configure options screen check Automatically encrypt objects when they are stored in S3 and choose the KMS key previously created.
   
3. In the Set Permissions screen, check option Block all public access.
   
4. Review the configurations and check encryption.
   
5. Upload the private key (file extension .pem) to the created bucket (key that was created in Certificate and Token - Generate Certificate section, Step 5).
   
6. Set Read/Write permissions, select Standard class and set the AWS KMS master-key as Encryption type and choose the KMS key previously created.
   
7. Review settings and upload the file.
   

Note: ClearBank .pem private key should have been generated previously, as described at Generate Certificate section

→Grant access of Digital Signature Lambda function to the encrypted AWS S3

1. Navigate to Services - Lambda, search and select DigitalSignature function. Open Permissions tab.
   
2. Check that AmazonS3ReadOnlyAccess policy is attached to DigitalSignature Lambda function execution role.
   
3. Update the environment variables. Click Save.
   

Note: If AmazonS3ReadOnlyAccess policy is not attached to Lambda function execution role, it’s necessary that an Admin(AWS) performs these actions:

4. Check that DigitalSignature Lambda execution role is attached to the KMS key. Navigate to Services - Key Management Service and search for the KMS key.
   

→Update Digital Signature Lambda function

1. Navigate to the Services > Lambda > DigitalSignature function.
   
2. Add two environment variables:

• CB_BUCKET -> AWS encrypted bucket (as defined in the S3 Bucket section)
• CB_KEY_FILE -> the file name where the key is store in the bucket (as defined in the S3 Bucket section - .pem file)