Readme is unclear

[str3tch]

hi there,

I am finding the Readme instructions somewhat lacking in clarity.

There are many things that are not explained. For instance, I do not know where I am meant to get my arn to use on the encrypt command line.

For instance, the following json snippet is quoted, but there is no explanation of where to get those arn kms values from. I am stuck. Please can you give a more detailed, step by step tutorial on the Readme.

{
  ...
  "custom": {
    "secrets": {
      "kms": {
        "default": "arn:aws:kms:us-east-1:123456789012:alias/MyAliasName",
        "prod": "arn:aws:kms:us-east-1:123456789012:alias/ProdAliasName"
      },
      "kmsfile": {
        "default": "arn:aws:kms:us-east-1:123456789012:alias/MyAliasName",
        "preprod": "arn:aws:kms:us-east-1:123456789012:alias/ProdAliasName"
      }
    }
  }
  ...
}

A suggestion for the tutorial is to use the iamRoleArnLambda string from the meta/resources folder, and how to use serverless-secrets to encrypt this, so that the _meta folder can be committed.

step by step guide please.. currently I think it assumes that everyone knows how to use kms. I don't and I'm stuck on how to get the kms arn.

cheers!

[shortjared]

Great q!

To get KMS arn, the easiest way is probably in the console, you will probably have to create a new KMS key if you don't already have one... I will try to clear this all up a bit more as you suggested.

For now, here is a quick way to find the KMS arn...

Go to the IAM section in the console... hit encryption keys

Either click an existing one (cannot be an aws/ one) or create a new one, then on the details for the key, grab the ARN

[str3tch]

Thanks for the tip.I now have the arn, but still I am totally confused on how to use this tool.

A step by step guide would be useful, as would detailed explanation of the arguments to the command line.

There is too much knowledge assumed in the readme.md.

for instance:

example arn: arn:aws:kms:us-east-1:123456789012:alias/ProdAliasName)

to what does the region refer to? Does this mean I need to re-encrypt everything for each region and stage that I deploy to? How would I use this in practise, how do I recommend it's use to my developers who are working on the same project in different branches? Do I pass the same kms arn key to all developers in my team to use?

Hopefully you can put some simple steps in the readme, as I am unable to use it at the moment.

Cheers!

[str3tch]

Also the readme is currently in the wrong order, it talks about decryption before encryption - which is not the way someone would use it :)

[shortjared]

To what does the region refer to?

I am not completely sure what this question is referencing. The arn:aws:kms:us-east-1:123456789012:alias/ProdAliasName contians the region of the KMS key, just as part of the arn. It references the region that the key exists in and what api endpoints to call. Mostly I don't think you need to worry about region stuff as long as you are plugging in the correct arns.

Does this mean I need to re-encrypt everything for each region and stage that I deploy to?

You would not have to, but it would be encouraged for performance.

How would I use this in practise, how do I recommend it's use to my developers who are working on the same project in different branches?

You could give your developers "encryption" permissions on your given keys (or give them a dev / staging KMS key, and reserve a production KMS key for your projects leaders).

Do I pass the same kms arn key to all developers in my team to use?

Ideally yes. Unless you implicitly trust all of your developers, I would consider giving them their own key for dev / staging. And use a separate one for Production that developers do not have access to.

It's still on my list to put together a good tutorial.

[chriswire]

+1 on the need for a clear and complete step-by-step tutorial. For example, start with a minimal sls project and introduce just 1 secret, accessing the value in the handler.

We would like to explore using the package, but need better guidance and illustration of details.

thanks.

[hassankhan]

I would suggest adding a section about how to set up KMS using CloudFormation. I added the following to get me going, but I'm pretty sure it's not ideal:

"KmsPolicyLambda": {
  "Type" : "AWS::KMS::Key",
  "Properties" : {
    "Description" : "A Customer Master Key for ${project}",
    "KeyPolicy" : {
      "Version": "2012-10-17",
      "Id": "key-${project}",
      "Statement": [
        {
          "Sid": "Enable IAM User Permissions",
          "Effect": "Allow",
          "Principal": {
            "AWS": "arn:aws:iam::${accountId}:root"
          },
          "Action": "kms:*",
          "Resource": "*"
        },
        {
          "Sid": "Allow use of the key",
          "Effect": "Allow",
          "Action": [
            "kms:Encrypt",
            "kms:Decrypt",
            "kms:ReEncrypt*",
            "kms:GenerateDataKey*",
            "kms:DescribeKey"
          ],
          "Resource": "*"
        }
      ]
    }
  },
  "DependsOn": [
    "IamRoleLambda"
  ]
}

You'd have to change ${accountId} manually to match your AWS account ID, but other than that it should work.

[shortjared]

Closing. Plugin is being deprecated.