{{announcement.body}}
{{announcement.title}}

AWS KMS Use Case With Serverless Application Model (SAM): An End To End Solution

DZone 's Guide to

AWS KMS Use Case With Serverless Application Model (SAM): An End To End Solution

This article demonstrates how to use AWS Key Management Service with Serverless Application Model for beginners. It has an hands on lab with full solution.

· Cloud Zone ·
Free Resource

The Basics

AWS KMS is a Key Management Service that lets you create Cryptographic keys that you can use to encrypt and decrypt data and also other keys. You can read more about it here.

Important Points About Keys

Please note that the CMK generated can only be used to encrypt a small amount of data like passwords, RSA keys. You can use AWS KMS customer master keys (CMKs) to generate, encrypt, and decrypt data keys. However, AWS KMS does not store, manage, or track your data keys, or perform cryptographic operations with data keys.

You must use and manage data keys outside of AWS KMS. KMS API uses AWS KMS customer master key (CMK) in the encryption operations and they cannot accept more than 4 KB (4096 bytes) of data. To encrypt application data, use the server-side encryption features of an AWS service, or a client-side encryption library, such as the AWS Encryption SDK or the Amazon S3 encryption client.

Scenario

We want to create signup and login forms for a website. Passwords should be encrypted and stored in the AWS DynamoDB database.

What Do We Need?

  1. KMS key to encrypt and decrypt data
  2. DynamoDB table to store password.
  3. Lambda functions & APIs to process Login and Sign up forms. 4.Sign up/ Login forms in HTML

Let's Implement it as Serverless Application Model (SAM)!

Lets first create the Key that we will use to encrypt and decrypt the password.

YAML
 




x
44


 
1
KmsKey:
2
    Type: AWS::KMS::Key
3
    Properties: 
4
      Description: CMK for encrypting and decrypting
5
      KeyPolicy:
6
        Version: '2012-10-17'
7
        Id: key-default-1
8
        Statement:
9
        - Sid: Enable IAM User Permissions
10
          Effect: Allow
11
          Principal:
12
            AWS: !Sub arn:aws:iam::${AWS::AccountId}:root
13
          Action: kms:*
14
          Resource: '*'
15
        - Sid: Allow administration of the key
16
          Effect: Allow
17
          Principal:
18
            AWS: !Sub arn:aws:iam::${AWS::AccountId}:user/${KeyAdmin}
19
          Action:
20
          - kms:Create*
21
          - kms:Describe*
22
          - kms:Enable*
23
          - kms:List*
24
          - kms:Put*
25
          - kms:Update*
26
          - kms:Revoke*
27
          - kms:Disable*
28
          - kms:Get*
29
          - kms:Delete*
30
          - kms:ScheduleKeyDeletion
31
          - kms:CancelKeyDeletion
32
          Resource: '*'
33
        - Sid: Allow use of the key
34
          Effect: Allow
35
          Principal:
36
            AWS: !Sub arn:aws:iam::${AWS::AccountId}:user/${KeyUser}
37
          Action:
38
          - kms:DescribeKey
39
          - kms:Encrypt
40
          - kms:Decrypt
41
          - kms:ReEncrypt*
42
          - kms:GenerateDataKey
43
          - kms:GenerateDataKeyWithoutPlaintext
44
          Resource: '*'



The important thing in the above snippet is the KeyPolicy. KMS requires a Key Administrator and Key User. As a best practice, your Key Administrator and Key User should be 2 separate users in your Organisation. We are allowing all permissions to the root users. So if your key Administrator leaves the organization, the root user will be able to delete this key. As you can see KeyAdmin can manage the key but not use it and KeyUser can only use the key. ${KeyAdmin} and ${KeyUser} are parameters in the SAM template. You would be asked to provide values for these parameters during SAM Deploy.

Parameters: KeyAdmin: Type: String KeyUser: Type: String 

default arguments 

Next, we will create a DynamoDB table. The partition key will be the user id. This is enough. You can add attributes as required.

YAML
 




xxxxxxxxxx
1
13


 
1
myDynamoDBTable: 
2
    Type: AWS::DynamoDB::Table
3
    Properties: 
4
      BillingMode: PAY_PER_REQUEST 
5
      AttributeDefinitions: 
6
        - 
7
          AttributeName: "userid"
8
          AttributeType: "S"
9
       
10
      KeySchema: 
11
        - 
12
          AttributeName: "userid"
13
          KeyType: "HASH"



Now, let's create the API and Lambda handler that will process the Signup and Login requests.

YAML
 




x
76


1
ApiGatewaySignupApi:
2
    Type: AWS::Serverless::Api
3
    Properties:
4
      StageName: Prod
5
    Auth:
6
     UsagePlan:
7
      CreateUsagePlan: PER_API
8
      Description: Usage plan for this API
9
      Quota:
10
       Limit: 500
11
       Period: MONTH
12
      Throttle:
13
       BurstLimit: 100
14
       RateLimit: 50
15
  SignupFunction:
16
    Type: AWS::Serverless::Function
17
    Properties:
18
      Environment:
19
        Variables:
20
          userTable: !Ref myDynamoDBTable
21
          keyid: !Ref KmsKey
22
      CodeUri: Lambda/
23
      Handler: signup.lambda_handler
24
      Runtime: python3.8
25
      Policies:
26
       - DynamoDBCrudPolicy:
27
          TableName: !Ref myDynamoDBTable
28
       - KMSEncryptPolicy:
29
          KeyId: !Ref KmsKey 
30
       - KMSDecryptPolicy:
31
          KeyId: !Ref KmsKey
32
      Events:
33
        getCounter:
34
          Type: Api
35
          Properties:
36
            Path: /signup
37
            Method: POST
38
            RestApiId: !Ref ApiGatewaySignupApi
39
  ApiGatewayLoginApi:
40
    Type: AWS::Serverless::Api
41
    Properties:
42
      StageName: Prod
43
    Auth:
44
     UsagePlan:
45
      CreateUsagePlan: PER_API
46
      Description: Usage plan for this API
47
      Quota:
48
       Limit: 500
49
       Period: MONTH
50
      Throttle:
51
       BurstLimit: 100
52
       RateLimit: 50
53
  LoginFunction:
54
    Type: AWS::Serverless::Function
55
    Properties:
56
      Environment:
57
        Variables:
58
          userTable: !Ref myDynamoDBTable
59
          keyid: !Ref KmsKey
60
      CodeUri: Lambda/
61
      Handler: login.lambda_handler
62
      Runtime: python3.8
63
      Policies:
64
        - DynamoDBCrudPolicy:
65
            TableName: !Ref myDynamoDBTable
66
        - KMSEncryptPolicy:
67
            KeyId: !Ref KmsKey 
68
        - KMSDecryptPolicy:
69
            KeyId: !Ref KmsKey
70
      Events:
71
        getCounter:
72
          Type: Api
73
          Properties:
74
            Path: /login
75
            Method: POST
76
            RestApiId: !Ref ApiGatewayLoginApi



Here, we are creating 2 Lambda handlers, one that handles signup, and the other handles the login. We are limiting the usage of API under Auth property. This is to prevent abuse of our API. We are setting two environment variables, one for the database table name and another for KMS key name. We are not hard-coding the table/key names instead we let cloud formation to name it and we set it as environment variables with auto-generated values.

This will prevent name conflicts of resources and you can run multiple versions of your whole cloud environment. Then we set a policy that allows Lambda to access DynamoDB and the key. You can find 'out of the box' SAM policy templates here. With Events, we create the API Gateway resources. The final part of the SAM template is the Output section.

YAML
 




xxxxxxxxxx
1
13


 
1
Outputs:
2
  ApiGatewaySignupApi:
3
    Description: "API Gateway endpoint URL for Prod stage for Hello World function"
4
    Value: !Sub "https://${ApiGatewaySignupApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/signup/"
5
  SignupFunction:
6
    Description: "Sign Up Lambda Function ARN"
7
    Value: !GetAtt SignupFunction.Arn
8
  ApiGatewayLoginApi:
9
    Description: "API Gateway endpoint URL for Prod stage for Hello World function"
10
    Value: !Sub "https://${ApiGatewayLoginApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/login/"
11
  LoginFunction:
12
    Description: "Login Lambda Function ARN"
13
    Value: !GetAtt LoginFunction.Arn



We output 2 important URLs in the above section, ApiGatewayLoginApi, and ApiGatewaySignupApi, We use these URLs in the fronted HTML form's action attribute. See below:

HTML
 




xxxxxxxxxx
1
11


 
1
<html>
2
   <head></head>
3
   <body>
4
      <h1>Sign Up</h1>
5
      <form action="https://51v5ifsje1.execute-api.us-east-2.amazonaws.com/Prod/signup/" enctype="application/x-www-form-urlencoded" method="POST">
6
         <label>Username:</label><input type="text" name="uname" id="uname"> </input><br><br>
7
         <label>Password:</label><input type="password" name="password" id="password"> </input><br><br>
8
         <input type="submit"></input>
9
      </form>
10
   </body>
11
</html>


HTML
 




xxxxxxxxxx
1
11


 
1
<html>
2
  <head></head>
3
  <body>
4
    <h1>Login</h1>
5
    <form action="https://4ezqeugqlf.execute-api.us-east-2.amazonaws.com/Prod/login/" enctype="application/x-www-form-urlencoded" method="POST">
6
      <label>username:</label><input type="text" name="uname" id="uname"> </input><br><br>
7
      <label>password:</label><input type="password" name="password" id="password"> </input><br><br>
8
      <input type="submit"></submit>
9
    </form>
10
  </body>
11
</html>



In HTML, we are using encoding type as "enctype="application/x-www-form-urlencoded". With this type of encoding, the form data is sent in below format

username=doryfish&password=nemo 

The last piece in the puzzle is the Lambda handlers. Let's check it out. Python uses Boto3 to access AWS.

Python
 




xxxxxxxxxx
1
51


 
1
import json
2
from urllib.parse import parse_qs
3
import urllib.parse
4
import boto3
5
import logging
6
import os
7
import base64
8
 
          
9
log = logging.getLogger()
10
log.setLevel(logging.INFO)
11
 
          
12
def lambda_handler(event, context):
13
    log.info(event)
14
    log.info(event.get("body"))
15
    qs = parse_qs(event.get("body"))
16
    log.info(qs)
17
    uname = qs.get("uname")[0] 
18
    pwd = qs.get("password")[0]
19
 
20
    dynamodb = boto3.resource('dynamodb')
21
    table = dynamodb.Table(os.environ['userTable'])
22
 
          
23
    log.info('key id:'+os.environ['keyid'])
24
    key = os.environ['keyid']
25
    client = boto3.client('kms')
26
    #Encrypt password
27
    response = client.encrypt(
28
    Plaintext=pwd,
29
    KeyId=key
30
    )
31
    log.info(response['CiphertextBlob'])
32
    b64_pass = str(base64.b64encode(response['CiphertextBlob']),'utf-8')
33
    log.info(b64_pass)
34
   
35
    response = table.update_item(
36
        Key={
37
            'userid': uname
38
        },
39
        AttributeUpdates={
40
            'password': {
41
                'Value': b64_pass,
42
            }
43
            }
44
        )
45
    data = {}
46
    data['status'] = 'Signup Success'
47
    json_data = json.dumps(data)    
48
    return {
49
        'statusCode': 200,
50
        'body': json_data
51
    }



The first two statements are logging statements, this is useful in debugging and the log statements will be logged in CloudWatch logs. The parse_qs module is used to read the form of data from the event object. Data are returned as a dictionary. The dictionary keys are the unique query variable names and the values are lists of values for each name. Hence, in the next 2 statements, we get the first value for each type — username and password.

We retrieve the DynamoDB table using the table name from the environment variable - userTable. Environment variables in Lambda can be accessed using os.environ['key']. Now we got the username and password. Its time to encrypt the password and store it in DB. The password to encrypt is passed to the Plaintext attribute of the encrypted request and key id is retrieved from the environment variable. CiphertextBlob is the encrypted binary value in the response object. For example:

Java
 




x


 
1
b'\x01\x02\x02\x00x\x9dN"\xa4\xf9\xfe\xb4\xc7&\x01\xdc\xb6J\xdf\xf1\xdc\xf2;)|7\x1b\'{8\xe6(\x80Q\xe5\x11\x8c\x010w"-\x11w\x10b\x9d\xd0w\xa7+\xd1\xa5\xc5\x00\x00\x00e0c\x06\t*\x86H\x86\xf7\r\x01\x07\x06\xa0V0T\x02\x01\x000O\x06\t*\x86H\x86\xf7\r\x01\x07\x010\x1e\x06\t`\x86H\x01e\x03\x04\x01.0\x11\x04\x0ca\xb4\xaa\x00\x10\xc0\xd1\xa6r\x07\xce\xc7\x02\x01\x10\x80"@\nL\xde<\x03s\xc6\xe0g\x80\xd4\x87\x8e\x1e\t\xa2\xac\x10\xfek\xb6\x1d\xf3\x87\x910\xabf\xd1d}x\xdb' 



Now we convert this binary value to ASCII text using

str(base64.b64encode(response['CiphertextBlob']),'utf-8') 

and the result we store it in the database.

Java
 




xxxxxxxxxx
1


 
1
AQICAHidTiKk+f60xyYB3LZK3/Hc8jspfDcbJ3s45iiAUeURjAEwdyItEXcQYp3Qd6cr0aXFAAAAZTBjBgkqhkiG9w0BBwagVjBUAgEAME8GCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMYbSqABDA0aZyB87HAgEQgCJACkzePANzxuBngNSHjh4JoqwQ/mu2HfOHkTCrZtFkfXjb 
2
 
          



In Login Lambda handler, username and password are retrieved from the request like we did in Sign Up.

Python
 




xxxxxxxxxx
1
56


1
import json
2
from urllib.parse import parse_qs
3
import urllib.parse
4
import boto3
5
import secrets
6
import logging
7
import os
8
import base64
9
 
          
10
log = logging.getLogger()
11
log.setLevel(logging.INFO)
12
 
          
13
def lambda_handler(event, context):
14
  
15
    log.info(event.get("body"))
16
    qs = parse_qs(event.get("body"))
17
  
18
    uname = qs.get("uname")[0] 
19
    pwd = qs.get("password")[0]
20
    
21
    dynamodb = boto3.resource('dynamodb')
22
 
          
23
    table = dynamodb.Table(os.environ['userTable'])
24
    response = table.get_item(Key={'userid': uname})
25
    json_str =  json.dumps( response['Item'])
26
 
          
27
    #using json.loads will turn your data into a python dictionary
28
    resp_dict = json.loads(json_str)
29
    dbpass = resp_dict.get("password")
30
    
31
    #Decrypt password
32
    log.info('key id:'+os.environ['keyid'])
33
    key = os.environ['keyid']
34
    client = boto3.client('kms')
35
   
36
    response = client.decrypt(
37
    CiphertextBlob=(base64.b64decode(dbpass)),
38
    KeyId=key
39
    )
40
    log.info("Decrypted value")
41
    decryptedPass = response['Plaintext'].decode('UTF-8')
42
    
43
    response = {}
44
   
45
    if decryptedPass == pwd : 
46
      response['status'] = 'Login Success'
47
      return {
48
        'statusCode': 200,
49
        'body': json.dumps(response) 
50
      }
51
    else:
52
     response['status'] = 'Login Failed'
53
     return {
54
        'statusCode': 200,
55
        'body': json.dumps(response) 
56
      }



In decrypt requests, the encrypted password string from the database is converted into binary using base64.b64decode(dbpass) and passed to the CiphertextBlob attribute. A decrypted password is returned as bytes in the Plaintext attribute of the response. The password is encoded in UTF-8 to get the final decrypted password. The decrypted password is then compared with the password from the request and if it matches, 'Login Success' response is sent back.

Phew! Finally, we are done coding. Let's test it out. 

Let's do SAM build and Deploy. 

build and deploy

deploying 

Stack creation complete!


stack creation

Testing

Note that we are not deploying HTML forms as a static site on S3 but we will locally open the forms in the browser and hit the APIs. Add username/password, hit submit. sign up

Sign Up is Successful! signup success

Item in the database. Password is encrypted password Now, Login using the same username and passwordsubmit password

Login Success! 


login success

Source Code: github.com/rajanpanchal/aws-kms-signup-login 

In the next post, we will extend this example to use AWS STS!

Topics:
amazon web services, aws, aws tutorial, cloud, encryption, hands-on learning, how-to guides, serverless, serverless application model, tutorial

Published at DZone with permission of Rajan Panchal . See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}