diff --git a/Section-1-Operating-with-AWS-KMS.md b/Section-1-Operating-with-AWS-KMS.md index 26b1ff4..4c07b8e 100644 --- a/Section-1-Operating-with-AWS-KMS.md +++ b/Section-1-Operating-with-AWS-KMS.md @@ -47,7 +47,7 @@ $ aws kms create-key The response from above command should be an error message like the one below. ``` -An error occurred (AccessDeniedException) when calling the CreateKey operation: User: arn:aws:sts::account-id:assumed-role/KMSWorkshop-InstaceInitRole/instanceid is not authorized to perform: kms:CreateKey on resource: +An error occurred (AccessDeniedException) when calling the CreateKey operation: User: arn:aws:sts::account-id:assumed-role/KMSWorkshop-InstanceInitRole/instanceid is not authorized to perform: kms:CreateKey on resource: ``` This is because the initial role we have assigned to the instance does not include the capability to create keys. We need to add a policy to the role in order to enable us to perform certain actions with AWS KMS during the workshop. @@ -154,9 +154,9 @@ If you go back to the AWS console and navigate to the IAM service. Click in the <**Figure-15**> -Key alias are very useful. They are easier to remenber when operating with keys. Most importantly, when rotation keys, as we will see later in this section, we will not have to update our code to update the new KeyIDs or ARN references. By using alias in our code to call the CMKs by them, and updating the alias CMKs to point to the newly generated key, the amount of change in our code gets minimized. +Key aliases are very useful. They are easier to remember when operating with keys. Most importantly, when rotating keys, as we will see later in this section, we will not have to update our code to update the new KeyIDs or ARN references. By using alias in our code to call the CMKs by them, and updating the alias CMKs to point to the newly generated key, the amount of change in our code gets minimized. -Let's create it an alias, "**FirstCMK**", with the command aws kms create-alias. +Let's create an alias, "**FirstCMK**", with the command aws kms create-alias. Remember to replace 'your-key-id' with the value obtained from previous command (aws kms create-key). @@ -191,9 +191,9 @@ In order to experiment how to import your own key material, we are going to take * Of course, we need the key material itself. Normally, it will come from an enterprise HSM or any sort of key management system. As per the workshop, we will create one with the library **OpenSSL**. This is the key material that will be wrapped and imported, as described in previous point. -* Finally, we will call the import API, to import it under the empty CMK we created in the first step. Note, this is a very sensible operation and we might or might not have permission to do so. If we don´t, we will needed to create them, based on the **Least Privilege** best practice. +* Finally, we will call the import API, to import it under the empty CMK we created in the first step. Note, this is a very sensitive operation and we might or might not have permission to do so. If we don´t, we will needed to create them, based on the **Least Privilege** best practice. -Let's go through to the steps in deep: +Let's go through to the steps in depth: @@ -249,7 +249,7 @@ total 8 -rw-rw-r-- 1 ec2-user ec2-user 2345 Oct  2 20:43 token.b64 ``` -We are ready to decode the b64 format. We will use the [OpenSSL](https://openssl.org/library), issuing the following command that will produce a binary file with the same filename but extenion .bin: +We are ready to decode the b64 format. We will use the [OpenSSL](https://openssl.org/library), issuing the following command that will produce a binary file with the same filename but extension .bin: ``` $ openssl enc -d -base64 -A -in pkey.b64 -out pkey.bin @@ -283,7 +283,7 @@ We now will wrap this key material with the public key obatined from AWS KMS bef $ openssl rsautl -encrypt -in genkey.bin -oaep -inkey pkey.bin -keyform DER -pubin -out WrappedKeyMaterial.bin ``` -This command takes the generated key material and encrypt it with the public key we downloaded from AWS KMS. Then, saves the output in another file named **WrappedKeyMaterial.bin**. +This command takes the generated key material and encrypts it with the public key we downloaded from AWS KMS. Then, saves the output in another file named **WrappedKeyMaterial.bin**. #### Step 4 - Import your key material @@ -303,7 +303,7 @@ All going well, the above command must have failed with the following error mess ``` when calling the ImportKeyMaterial operation: User: arn:aws:sts:::assumed-role/is not authorized to perform: kms:ImportKeyMaterial on resource: arn:aws:kms:eu-west-1:account-id:key/key-id ``` -As you can read in the error message, even though our instance has a "Power user" role, it is still missing some capabilities. We are following Least Privilege practices, therefore we are only providing the role the permissions it needs. In this case, we need to provide it with accesss to the "**ImportKeyMaterial**" operation. +As you can read in the error message, even though our instance has a "Power user" role, it is still missing some capabilities. We are following Least Privilege practices, therefore we are only providing the role the permissions it needs. In this case, we need to provide it with access to the "**ImportKeyMaterial**" operation. We need to go back to the IAM service into the AWS console and add this permission to the role we are working with "**KMSWorkshop-InstanceInitRole**". Go back to the console, navigate to the IAM service. Look and click on the left column, the "**Policies**" section. Then hit "**Create Policy**" button. Search and select for the service "KMS" among all displayed on the screen. You will land in the policy creator/editor for KMS, as in image below: @@ -331,7 +331,7 @@ Finally, select resources "**Any**" and click "**Review Policy**". In this step, give the policy a name, for example "**KMS-Workshop-ImportMaterialPermissions**" and hit "**Create Policy**". With this, go back to the "**Roles**" section again (left side of the console within IAM service). -Search again for "**KMS**" to find the role **KMSWorkshop-InstaceInitRole**, as we did in the second step when creating a CMK with no import material. Click on it. +Search again for "**KMS**" to find the role **KMSWorkshop-InstanceInitRole**, as we did in the second step when creating a CMK with no import material. Click on it. To attach the new policy we have just created to the role. Hit the button "**Attach policies**". @@ -339,8 +339,8 @@ To attach the new policy we have just created to the role. Hit the button "**Att <**Figure-9**> -an new screen will appear. Search for the policy we created by "**KMS**", you should find its name "**KMS-Workshop-ImportMaterialPermissions**", As you can see in image below. Then select it and hit the "**Attach Policy**" button. -The Role now has pemissions to import the key material. +A new screen will appear. Search for the policy we created by "**KMS**", you should find its name "**KMS-Workshop-ImportMaterialPermissions**", As you can see in image below. Then select it and hit the "**Attach Policy**" button. +The Role now has permissions to import the key material. ![Figure-10](/res/S1F10%20KMSApolicy.png) @@ -361,7 +361,7 @@ We might want to set an alias for this new key as well. We will use the alias "* $ aws kms create-alias --alias-name alias/ImportedCMK --target-key-id 'external-key-id' ``` -If you go back into the AWS console, browse to the IAM service and select "**Encryption Keys**" to open the KMS console. Remember to make sure you have selected the right region (picture below- upper red bounding box). The new imported key with its alias is shown and it is ready to use. +If you go back into the AWS console, browse to the IAM service and select "**Encryption Keys**" to open the KMS console. Remember to make sure you have selected the right region (picture below- upper orange bounding box). The new imported key with its alias is shown and it is ready to use. ![Figure-11](/res/S1F11.png) @@ -400,10 +400,9 @@ In AWS KMS there are different ways to rotate keys according to the way they wer ### Step 1 - CMKs generated with AWS key material -For CMKs created with AWS key material, you can opt-in to automatically rotate the key every year -AWS KMS generates new cryptographic material for the CMK every year. In this case, AWS KMS also saves the CMK's older cryptographic material so it can be used to decrypt data that it encrypted. +For CMKs created with AWS key material, you can opt-in to automatically rotate the key every year. In this case AWS KMS generates new cryptographic material for the CMK. In addition, AWS KMS also saves the CMK's older cryptographic material so it can be used to decrypt data that it encrypted. -Automatic key rotation preserves the properties of the CMK: key ID, key ARN, region, policies, and permissions, do not change when the key is rotated, so you don´t have to manually update the alias of the CMK to point to a newly generated CMK. +Automatic key rotation preserves the properties of the CMK: key ID, key ARN, region, policies, and permissions. As these do not change when the key is rotated you don´t have to manually update the alias of the CMK to point to a newly generated CMK. Let's opt-in to automatically rotate the CMK key we created before with AWS key material, remenber its alias was "**FirstCMK**", the KeyID was "**your-key-id**". @@ -440,7 +439,7 @@ At this point of the workshop you should be able to do it with no issues. One ti <**Figure-16**> -For resources select both "**alias**" and "**key**". You can name the policy "**KMSWorshop-RotationDisableOps**". +For resources select both "**alias**" and "**key**". You can name the policy "**KMSWorkshop-RotationDisableOps**". Try the command again after you attached the policy to the role. All the applications that were using "FirstCMK" key alias, are now using the new key. In this way, we did not have to manually change the "KeyId" or key ARN one by one in all occurrences of our code were the CMK is invoked. @@ -449,9 +448,9 @@ The old key remains in AWS KMS (until you delete it). When you use the CMK to de ### Step 2 - Rotating CMKs generated with your own key material -With the CMKs generated with your own key material, automatic rotation is not possible. You have to manually create a new key, with your own material, and again: Either update the alias of the CMK (recommendable) or change your code to point to the new key. It seems much easier just to change alias pointer. +With the CMKs generated with your own key material, automatic rotation is not possible. You have to manually create a new key, with your own material, and again: either update the alias of the CMK (recommended) or change your code to point to the new key. It seems much easier just to change alias pointer. -In order to do so, we would need to create a new key with imported key material, as we did with to cfreate the CMK "ImportedCMK" with external origin and then udpate the alias "**ImportedCMK**". **NOTE:** Timewise, you are **not required** to do it as part of the workshop, as the procedure is already covered. +In order to do so, we would need to create a new key with imported key material, as we did to create the CMK "ImportedCMK" with external origin and then update the alias "**ImportedCMK**". **NOTE:** Timewise, you are **not required** to do it as part of the workshop, as the procedure is already covered. In case you would like to rotate the CMK created with your own key material, follow the procedure in the section above "[Generate CMK with your own key material](https://github.com/aws-samples/aws-kms-workshop/blob/master/Section-1-Operating-with-AWS-KMS.md#generate-cmks-with-your-own-key-material)". Once you have created a new CMK with you new imported key material, update the alias "**ImportedCMK**" to point to the new key you have provided. Replace **KeyID** in command below with the KeyID of your newly created CMK. @@ -460,7 +459,7 @@ Once you have created a new CMK with you new imported key material, update the a $ aws kms update-alias --alias ImportedCMK --target-key-id KeyID ``` -For CMKs created by AWS and using AWS key material: AWS Managed CMKs, the rotation is automatically happening every three years. See [this link](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html) of AWS KMS documentation.to the documentation for more info on key rotation. +For CMKs created by AWS and using AWS key material: AWS Managed CMKs, the rotation is automatically happening every three years. See [this link](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html) of AWS KMS documentation for more information on key rotation. --- @@ -471,7 +470,7 @@ Deleting customer master keys is a very sensitive operation.  You should delete Providing the right permissions for key deletion are an important part of best practices working with AWS KMS, as we will see in next section. -If you are not sure that you need to delete the key, you might want to disable the key only. Execute the following command to change the state of our first key "**FirstCMK**" to disabled. You will have to replace "**your-key-id**" with your corresponding KeyId or ARN (**NOTE:**) Key Aliases are not supported for this operation. +If you are not sure that you need to delete the key, you might want to disable the key only. Execute the following command to change the state of our first key "**FirstCMK**" to disabled. You will have to replace "**your-key-id**" with your corresponding KeyId or ARN. **NOTE:** Key Aliases are not supported for this operation. ``` $ aws kms disable-key --key-id your-key-id @@ -482,7 +481,7 @@ Let's re-enable it to keep using it. In order to do so, execute the following co $ aws kms enable-key --key-id your-key-id ``` For the deletion operation, AWS KMS enforces a waiting period. To delete a CMK in AWS KMS you have to schedule a key deletion. -You can set the waiting period from a minimum of 7 days up to a maximum of 30 days. The default waiting period is 30 days. Let's schedule key deletion in seven days, use the following command. Please, replace "**your-key-id**" with the corresponding KeyID or ARN for the first CMK you created with the firt AWS KMS command in this workshop, the one is not currently being point at by the alias. +You can set the waiting period from a minimum of 7 days up to a maximum of 30 days. The default waiting period is 30 days. Let's schedule key deletion in seven days, use the following command. Please, replace "**your-key-id**" with the corresponding KeyID or ARN for the first CMK you created with the first AWS KMS command in this workshop, the one is not currently being point at by the alias. ``` $ aws kms schedule-key-deletion --key-id your-key-id --pending-window-in-days 7 { @@ -494,7 +493,7 @@ $ aws kms schedule-key-deletion --key-id your-key-id --pending-window-in-days 7 Working with CMKs that have been generated with your own key material is a bit different because you can schedule a key deletion but you can also delete key material on demand. Therefore, for deletion of key material, you can schedule a date and wait for the key material to expire or you delete it manually. -If you may want to delete it **immediately**, you could issue a command like the one below to delete the key material you have imported, rendering the key unusable. You should replace "your-key-id" with your corresponding KeyID or ARN. +If you want to delete it **immediately**, you could issue a command like the one below to delete the key material you have imported, rendering the key unusable. You should replace "your-key-id" with your corresponding KeyID or ARN. **The command below is for information purposes, don´t execute it as part of the workshop**. @@ -502,9 +501,9 @@ If for any reason you delete the key we generated with our own key material "**I ## Just for information ``` -$ delete-imported-key-material --key-id your-key-id. +$ aws kms delete-imported-key-material --key-id your-key-id. ``` Congratulations, you have now completed this section of the workshop. You can now go to the second section of the workshop: [Encryption with AWS KMS](https://github.com/aws-samples/aws-kms-workshop/blob/master/Section-2-Encryption-with-AWS-KMS.md) - + diff --git a/Section-2-Encryption-with-AWS-KMS.md b/Section-2-Encryption-with-AWS-KMS.md index 6381285..a4b59f9 100644 --- a/Section-2-Encryption-with-AWS-KMS.md +++ b/Section-2-Encryption-with-AWS-KMS.md @@ -16,7 +16,7 @@ The section is divided in the following parts: ## How Envelope Encryption works in practice AWS KMS is able to encrypt and decrypt up to 4 kilobytes (4096 bytes) of data. With other volumes of data, normally you will use a data key to perform encryption operations outside KMS through envelope encryption. -Envelope encryption refers to the practice of protecting the data by encrypting it with a data key, and encrypting the data key itself with a another encryption key, a CMK under KMS in this case. +Envelope encryption refers to the practice of protecting the data by encrypting it with a data key, and encrypting the data key itself with another encryption key, a CMK under KMS in this case. See the following figure from [AWS KMS documentation](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#enveloping). ![alt text](/res/S2F1.png) @@ -25,11 +25,15 @@ See the following figure from [AWS KMS documentation](https://docs.aws.amazon.co AWS KMS is also capable of generating **data keys** to encrypt data from CMKs. -**Note:** Data keys are only generated by AWS KMS, not stored or used to encrypt by AWS KMS itself. +**NOTE:** Data keys are only generated by AWS KMS, not stored or used to encrypt by AWS KMS itself. -Data keys are very different from a CMK, which never leaves AWS KMS and is only used in memory. Besides, data keys can be obtained in plain text or encrypted. +Data keys are very different from a CMK, which never leaves AWS KMS and is only used in memory. Data keys can be obtained in plain text or encrypted. -Once the data is encrypted and stored with a data key, the data key is stored encrypted with the data itself, while the plaintext version of the data key is deleted (for security best practices). +As an example, a client application using the AWS Encryption SDK can execute the following steps: + +1. A request is made under a CMK for a new data key. An encrypted data key and a plaintext version of the data key are returned. +2. Within the AWS Encryption SDK, the plaintext data key is used to encrypt the message. The plaintext data key is then deleted from memory. +3. The encrypted data key and the encrypted message are combined into a single ciphertext byte array. Therefore, to decrypt the data, the CMK needs to decrypt the encrypted data key and then, with the data key in plain text, the decrypt operation can take place. This adds a tier of protection to your data and better manageability. If a data key is compromised, only the service or data using that particular data key is compromised, no other data. If only one key was used for all data encryption across the platform and it gets compromised, the whole platform data would be also compromised. @@ -42,7 +46,7 @@ Let's see envelope encryption in action with AWS KMS. First thing we will do is to create a file with the data we want to encrypt under envelop encryption. A sample "secret" text file in this case with the text "Sample Secret Text to Encrypt". ``` -$ sudo echo "Sample Secret Text to Encrypt" > samplesecret.txt +$ echo "Sample Secret Text to Encrypt" > samplesecret.txt ``` @@ -52,16 +56,16 @@ Next, we ask AWS KMS to generate a data key referencing a CMK. The CMK is refere ``` $ aws kms generate-data-key --key-id alias/ImportedCMK --key-spec AES_256 --encryption-context project=workshop ``` -You will notice that the command will fail to run. Our current Role with Power User permissions does not have enough privileges to generate a data key. As per least privilege best practices, we are providing permissions as needed in policies attached to the role that can be easily tracked and dettached when such permission for that user is not needed any more. +You will notice that the command will fail to run. Our current Role with Power User permissions does not have enough privileges to generate a data key. As per least privilege best practices, we are providing permissions as needed in policies attached to the role that can be easily tracked and detached when such permission for that user is not needed any more. We need to provide with permission to generate a data key. -The process is the same as we have seen twice in the previos section of the workshop, please go back to it if you need to in the following link: "[Create the import material and encrypt it for the import](https://github.com/aws-samples/aws-kms-workshop/blob/master/Section-1-Operating-with-AWS-KMS.md#step-4---import-your-key-material)" +The process is the same as we have seen twice in the previous section of the workshop, please go back to it if you need to in the following link: "[Create the import material and encrypt it for the import](https://github.com/aws-samples/aws-kms-workshop/blob/master/Section-1-Operating-with-AWS-KMS.md#step-4---import-your-key-material)" Basically, you need to go back to the AWS console, in the services area navigate to IAM and go to "**Policies**". We are going to create a new policy and attach it to the Power user role. As we did in the previous section, click on new "**Create Policy**", Select KMS as the service, go to the Actions area. -In the "Write" section, select "**GenerateDataKey**" operation. Aditionally select "**Encrypt**", "**Decrypt**" and the tagging operations **as you can see in image below**, we will need them for the nexts steps. and "**Any**" as resource. +In the "Write" section, select "**GenerateDataKey**" operation. Additionally select "**Encrypt**", "**Decrypt**" and the tagging operations **as you can see in image below**, we will need them for the nexts steps. and "**Any**" as resource. ![alt text](/res/S2F16.png) @@ -70,14 +74,14 @@ In the "Write" section, select "**GenerateDataKey**" operation. Aditionally sele -Click on "**Review Policy**" and then give the policy a name, for example "**KMSWorkshop-AditionalPermissions**". +Click on "**Review Policy**" and then give the policy a name, for example "**KMSWorkshop-AdditionalPermissions**". -You can click now in "**Create Policy**". Once created, attach it to the role **KMSWorkshop-InstaceInitRole**. +You can click now in "**Create Policy**". Once created, attach it to the role **KMSWorkshop-InstanceInitRole**. Once the policy is attached, if you try the same command again, it will succeed now. The command will return a JSON output with: * the plaintext data key - Plaintext key in b64 encoding * the KeyId used to encrypt plaintext data key -* A CiphetextBlob which is the encrypted data key generated, in base64 enconding. +* A CiphertextBlob which is the encrypted data key generated, in base64 enconding. Write these values down, we are going to needed them shortly. @@ -186,8 +190,8 @@ $  openssl enc -d -aes256 -in encryptedSecret.txt -k fileb://datakeyPlainText.t Sample Secret Text to Encrypt ``` -Good job, We have the secret text "Sample Secret Text to Encrypt" decrypted. -The data to encrypted and decrypted by your applications would use envelope encryption in a similar way. It is a powerful mechanism, enabled by AWS KMS CMKs, to protect in two tiers, the integrity and confidentiality of your data. +Good job, we have the secret text "Sample Secret Text to Encrypt" decrypted. +The data to be encrypted and decrypted by your applications would use envelope encryption in a similar way. It is a powerful mechanism, enabled by AWS KMS CMKs, to protect in two tiers, the integrity and confidentiality of your data. By completing this part of the workshop you now have a better understanding of what envelope ecnryption is, let's now see how it applies for AWS services working with AWS KMS. @@ -198,9 +202,9 @@ By completing this part of the workshop you now have a better understanding of w In AWS there are main two main procedures to protect your data at rest: **Client Side Encryption (CSE)** and **Server Side Encryption (SSE)**. -For example in Amazon S3, You can encrypt your data before uploading it into the Amazon S3 Service (client side encryption) or encrypt once the data is there (server side encryption). More details in this [link to the S3 documentation](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingEncryption.html). A similar approach can be taken in other services like Amazon DynamoDB, see [details here](https://docs.aws.amazon.com/dynamodb-encryption-client/latest/devguide/client-server-side.html). +For example in Amazon S3, you can encrypt your data before uploading it into the Amazon S3 Service (client side encryption) or encrypt once the data is there (server side encryption). More details in this [link to the S3 documentation](https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingEncryption.html). A similar approach can be taken in other services like Amazon DynamoDB, see [details here](https://docs.aws.amazon.com/dynamodb-encryption-client/latest/devguide/client-server-side.html). -The envelope **encryption mechanism** just described in previous section is the mechanism behind the Server Side Encryption that takes place in the AWS services that use AWS KMS. There are very good descriptions on how AWS KMS is being used by different AWS services in this part of the [AWS KMS documentation here](https://docs.aws.amazon.com/kms/latest/developerguide/service-integration.html). +The **envelope encryption mechanism** just described in previous section is the mechanism behind the Server Side Encryption that takes place in the AWS services that use AWS KMS. There are very good descriptions on how AWS KMS is being used by different AWS services in this part of the [AWS KMS documentation here](https://docs.aws.amazon.com/kms/latest/developerguide/service-integration.html). For the workshop, let's see an example of attaching a disk to our working instance. We will encrypt it with AWS KMS and the CMK we have created importing our key material, its alias was "**ImportedCMK**". @@ -211,7 +215,7 @@ We start by going into the AWS console. Navigate to Amazon EC2 service. Look in <**Figure-2**> -Now in the upper area, you can click on "**Create Volume**" to create a new Amazon EBS disk. Once in the volume creation screen, and for the workshorp, you can leave the defaults in most fields- Except for the following: Ensure you have selected the same "**Availability zone**" as your EC2 instance is running on (It is easy to find out: you can look into the EC2 service, Instances area in the left pane, select your instance and locate the information "Availability Zone" below). The disk can only be attached to instances in the same availability zone. +Now in the upper area, you can click on "**Create Volume**" to create a new Amazon EBS disk. Once in the volume creation screen, and for the workshop, you can leave the defaults in most fields - except for the following: Ensure you have selected the same "**Availability zone**" as your EC2 instance is running on (It is easy to find out: you can look into the EC2 service, Instances area in the left pane, select your instance and locate the information "Availability Zone" below). The disk can only be attached to instances in the same availability zone. Ensure also that you have clicked the "**Encryption**" checkbox. Then select the CMK you want to use from AWS KMS. Let's select the CMK that we have imported with our own key material, the alias was: **ImportedCMK**. @@ -219,7 +223,7 @@ Ensure also that you have clicked the "**Encryption**" checkbox. Then select the <**Figure-3**> -Create a tag for the volume, for example a key-pair like: **Name-WorkshopEBS**. +Create a tag for the volume, for example a key-pair like: **Name: WorkshopEBS**. Click on "**Create volume**" at the right bottom of the screen. The volume will start being created and will be ready to be attached to the instance in a few seconds. We have now a encrypted volume that can be attached to our instance. @@ -257,14 +261,14 @@ In the first topic of this section of the workshop (How Envelope Encryption work While you can code all the primitives and commands to implement encryption on the client side, AWS has a SDK, the [AWS Encryption SDK](https://docs.aws.amazon.com/es_es/encryption-sdk/latest/developer-guide/introduction.html). This SDK uses envelope encryption and it is integrated with AWS KMS. It will implement most of the operations we have seen before as simple API calls. AWS KMS can become a Master Key provider for the AWS Encryption SDK, however you may use other Master Key provider with the SDK. -I recommend to take a look at the AWS Encryption SDK. Also, some AWS services have specific encryption SDKs, like the on in Amazon DynamoDB: the "DynamoDB Encryption Client", you can take a look [in this link](https://docs.aws.amazon.com/dynamodb-encryption-client/latest/devguide/what-is-ddb-encrypt.html). +I recommend to take a look at the AWS Encryption SDK. Also, some AWS services have specific encryption SDKs, like the one in Amazon DynamoDB: the "DynamoDB Encryption Client", you can take a look [in this link](https://docs.aws.amazon.com/dynamodb-encryption-client/latest/devguide/what-is-ddb-encrypt.html). ---- ### Encryption using AWS KMS with no Data Key -You can also use the a CMK in AWS KMS to encrypt and decrypt a secret directly, without the generation of a Data Key and hence, without the envelope encryption process. Remember, AWS KMS is able to encrypt and decrypt up to 4 kilobytes (4096 bytes) of data. We can use the CLI or APIs. +You can also use a CMK in AWS KMS to encrypt and decrypt a secret directly, without the generation of a Data Key and hence, without the envelope encryption process. Remember, AWS KMS is able to encrypt and decrypt up to 4 kilobytes (4096 bytes) of data. We can use the CLI or APIs. In this example, we will use the CLI to encrypt a secret and decrypt using the CMK itself. **Note:** this encryption operation takes place in AWS KMS itself. When a data key is generated via the CMK, the encryption and decryption process with that data key **happens outside AWS KMS**. diff --git a/Section-3-Working-with-Web-App.md b/Section-3-Working-with-Web-App.md index 3a84f15..246737b 100644 --- a/Section-3-Working-with-Web-App.md +++ b/Section-3-Working-with-Web-App.md @@ -69,7 +69,7 @@ Upload it through the WebApp. You should get to a page informing that the operation was successul. -Now, go back ("**press back link in Success page**) and check that it is the file is showing up in the main serfver's page. You can now click on it, to download it and display it. +Now, go back ("**press back link in Success page**) and check that it is the file is showing up in the main server's page. You can now click on it, to download it and display it. If you refresh the page in your browser, you will notice the same file appears now as a local file with prefix "localfile". The Web App is designed to create also a further local cache. @@ -163,7 +163,7 @@ Key policies are the primary resource for controlling "who" has access to do "wh You have a full description about them in the following [AWS KMS link](https://docs.aws.amazon.com/kms/latest/developerguide/key-policies.html), in case you want to go deeper - and for the importance of the topic, you should. We are going to work with some practical examples. -Up to now, the assigned IAM role ("**KMSWorkshop-InstaceInitRole**") of our working instance allows us to perform many things in AWS KMS. Following best practices like "**Least Privilege**" and "**Separation of Duties**", it can be, for example, that our instance is meant to be used only for uploading data with server side encryption, but not decrypt it and download it. +Up to now, the assigned IAM role ("**KMSWorkshop-InstanceInitRole**") of our working instance allows us to perform many things in AWS KMS. Following best practices like "**Least Privilege**" and "**Separation of Duties**", it can be, for example, that our instance is meant to be used only for uploading data with server side encryption, but not decrypt it and download it. Maybe the download and decrypt operation needs to be done from another instance with more specific security constraints. How can we comply with these requirements? We will use two main resources: @@ -181,7 +181,7 @@ $ aws kms list-key-policies --key-id your-key-id     ] } ``` -**NOTE:** Remember that if you run into trouble with this command and get errors complaining about "import awscli.clidriver", a verions mismatch with AWS CLI installed by boto3, then use the following command to go back to normal: +**NOTE:** Remember that if you run into trouble with this command and get errors complaining about "import awscli.clidriver", a versions mismatch with AWS CLI installed by boto3, then use the following command to go back to normal: ``` $ sudo yum downgrade aws-cli.noarch python27-botocore -y @@ -220,7 +220,7 @@ This has policy has two important effects (more information in [this link](https * Enables IAM policies to allow access to the CMK. Giving the AWS account full access to the CMK does this; it enables you to use IAM policies to give IAM users and roles in the account access to the CMK. It does not by itself give any IAM users or roles access to the CMK, but it enables you to use IAM policies to do so. Let's modify the permission of the role assigned to the instance, **allowing it only to encrypt, but not decrypt**. -Let's use the console. Open the AWS Console. Navigate to IAM service, left column "Roles" and search for the role currently assigned to the instance: **KMSWorkshop-InstaceInitRole**. +Let's use the console. Open the AWS Console. Navigate to IAM service, left column "Roles" and search for the role currently assigned to the instance: **KMSWorkshop-InstanceInitRole**. Within the role, locate the policy we attached when working in the second section of the workshop, we named it "**KMSWorkshop-AditionalPermissions**". Click the button "**Edit Policy**". Expand the Actions-Access Level-Write section and remove the check box on "**Decrypt**". Review policy and save it. @@ -242,7 +242,7 @@ Now try to upload a new file to S3. It will succeed it. Now try and download it. Now this role is able to encrypt but not to decrypt. Furthermore, we want to enforce "**Least Privilege**" access and ensure that the encryption Role, providing capability to encrypt, is only used from our account, and not subject to Cross-Account Role access policies that could grant access to the CMK. For that, we will use a handy Key policy. -We need to identify our current role "**KMSWorkshop-InstaceInitRole**" ARN in order to link it to the key policy. Go back to the console, IAM service, click Roles. Search for the role currently assigned to the instance: **KMSWorkshop-InstaceInitRole** and click on it. In the upper part of the screen you have the associated ARN. As part of the Role ARN you have your account Id. This is the generic structure: +We need to identify our current role "**KMSWorkshop-InstanceInitRole**" ARN in order to link it to the key policy. Go back to the console, IAM service, click Roles. Search for the role currently assigned to the instance: **KMSWorkshop-InstanceInitRole** and click on it. In the upper part of the screen you have the associated ARN. As part of the Role ARN you have your account Id. This is the generic structure: ``` arn:aws:iam::ACCOUNT-ID-WITHOUT-HYPHENS:role/ROLE-NAME @@ -319,7 +319,7 @@ With this policy we will ensure that only instances that have the appropriate ro "Sid": "Allow for Use only within our Account", "Effect": "Deny", "NotPrincipal": { - "AWS": [ "arn:aws:iam::your-acount-id:role/KMSWorkshop-InstaceInitRole", "arn:aws:iam::your-acount-id:root"] + "AWS": [ "arn:aws:iam::your-acount-id:role/KMSWorkshop-InstanceInitRole", "arn:aws:iam::your-acount-id:root"] }, "Action": "kms:*", "Resource": "*", @@ -350,7 +350,7 @@ As an example, conditions can work with **encryption context** to be able to res ``` We could use that to add a condition in AWS KMS Key Policy like "**kms:EncryptionContextKey**". -There is a full example in the [documentation here](https://docs.aws.amazon.com/kms/latest/developerguide/policy-conditions.html#conditions-kms-encryption-context-keys). Make sure you click the link and check that you undertand how the key policy is enforced using encryption context as condition. +There is a full example in the [documentation here](https://docs.aws.amazon.com/kms/latest/developerguide/policy-conditions.html#conditions-kms-encryption-context-keys). Make sure you click the link and check that you understand how the key policy is enforced using encryption context as condition. Finally, let's try to add another layer of security via **MFA**. In the key policy we might request that the users that are going to use the CMK have passed through a MFA process. MFA is enforced through a condition as seen below: @@ -389,7 +389,7 @@ MFA is enforced through a condition as seen below: } ``` -In this key policy, we don´t allow certain very sensitive operations to take place, unless the user or the role has gone through a MFA authentication process in the last 5 minutes (300 seconds). Make sure you understand the policy. After the examples seen by now, you should be able to understsand how it works. We will not enforce as in the workshop we are working with roles and not with users. However the overall concept is the same. +In this key policy, we don´t allow certain very sensitive operations to take place, unless the user or the role has gone through a MFA authentication process in the last 5 minutes (300 seconds). Make sure you understand the policy. After the examples seen by now, you should be able to understand how it works. We will not enforce as in the workshop we are working with roles and not with users. However the overall concept is the same. --- @@ -401,7 +401,7 @@ A VPC endpoint enables you to privately connect your VPC to supported AWS servic When you use a VPC endpoint, **communication between your VPC and AWS KMS is conducted entirely within the AWS network**. You can even specify the VPC endpoint in [AWS KMS API operations](https://docs.aws.amazon.com/kms/latest/APIReference/) and [AWS CLI commands](https://docs.aws.amazon.com/kms/latest/APIReference/). -In order not to make the workshop two extensive **it is not required to set up the VPC Endpoint**. We will mention it, so you know what you can do with it. +In order not to make the workshop too extensive **it is not required to set up the VPC Endpoint**. We will mention it, so you know what you can do with it. As a reference: the VPC endpoint can easily be created from the console, you can follow the steps in this [link to the documentation](https://docs.aws.amazon.com/kms/latest/developerguide/kms-vpc-endpoint.html). Once an endpoint is created you can enforce communication through it with commands as seen below, where parameter "**--endpoint-url**" is added. @@ -434,7 +434,7 @@ A sample policy would be like the one below. Please ensure you understand the co "Sid": "Allow for Use only within our VPC", "Effect": "Deny", "Principal": { - "AWS": "arn:aws:iam::your-account-id:role/KMSWorkshop-InstaceInitRole" + "AWS": "arn:aws:iam::your-account-id:role/KMSWorkshop-InstanceInitRole" }, "Action": [ "kms:Encrypt", @@ -462,8 +462,8 @@ With that key policy, an extra layer of protection the key would be established, ### Key Tagging -Tagging is an important strategy for managning CMKs in AWS KMS. -You can add, change, and delete tags for customer managed CMKs. Each tag consists of a tag key and a tag valuethat you define. +Tagging is an important strategy for managing CMKs in AWS KMS. +You can add, change, and delete tags for customer managed CMKs. Each tag consists of a tag key and a tag value that you define. You can add tags to a CMK when you first create them. Then, add, edit, and delete tags at any time.  To add a tag to the CMK we have been working with, you can use the console or the CLI. Let's tag our CMK "**ImportedCMK**", with a project it may belong to, just an a example. diff --git a/Section-4-Monitoring-AWS-KMS.md b/Section-4-Monitoring-AWS-KMS.md index 062ea20..c7072a9 100644 --- a/Section-4-Monitoring-AWS-KMS.md +++ b/Section-4-Monitoring-AWS-KMS.md @@ -1,13 +1,13 @@ # Monitoring and Logging in AWS KMS Monitoring is an important part of understanding the availability, state, and usage of your customer master keys (CMKs) in AWS KMS and maintaining the reliability and performance of your AWS solutions.  -As as baseline, in AWS KMS you may want to monitor: +As a baseline, in AWS KMS you may want to monitor: * Activity related to cryptographic operations, such as Encrypt or Decrypt. -* Activity related to management operations on the CMKs: EnableKey, ImportKeyMarterial,etc… +* Activity related to management operations on the CMKs: EnableKey, ImportKeyMaterial, etc… * Activity on other events and metrics, such as key expiration, key rotation or time remaining until imported key material expiration. -To monitor that activity we will the AWS service [AWS CloudTrail](https://aws.amazon.com/cloudtrail/) and [Amazon CloudWatch](https://aws.amazon.com/cloudwatch/), escecially its logs, events and alarms. +To monitor that activity we will use the AWS services [AWS CloudTrail](https://aws.amazon.com/cloudtrail/) and [Amazon CloudWatch](https://aws.amazon.com/cloudwatch/), especially its logs, events and alarms. --- ### AWS KMS and AWS CloudTrail @@ -26,16 +26,16 @@ This action has been logged in AWS CloudTrail, and we can obtain its details. Le Go back to the AWS console in your browser, navigate to "**CloudTrail**" service and select "**Event history**" on the right panel. You have the full history of events and they can be filtered for a fine grained view. -To establish a filter, go to filter area, select "**Event name**", and set the name as "**GenerateDataKey**". Press "**Enter**" while still on the "**Enter Event Name**", leaving "**Select time range**" as it is. Alterntively, you could select a time range if you wish. +To establish a filter, go to filter area, select "**Event name**", and set the name as "**GenerateDataKey**". Press "**Enter**" while still on the "**Enter Event Name**", leaving "**Select time range**" as it is. Alternatively, you could select a time range if you wish. You will have a display of the GenerateDataKey operations that you have performed during the workshop. You can see image below as a reference: ![alt text](/res/S4F1.png) <**Figure-1**> -If you open any of the request in the list, you will have further details of the operation that took place and. For example take a look at the "**User name**" value responsible for the requests and write it down, we will use it later. These parameters provides us with a full view of who, what, how and when an operation took place. +If you open any of the request in the list, you will have further details of the operation that took place. For example take a look at the "**User name**" value responsible for the requests and write it down, we will use it later. These parameters provide us with a full view of who, what, how and when an operation took place. -In CloudTrail you can not only filter by event names on AWS KMS operations. There are other filter parameters that you can use. For example, you can use filtering by "**Event source**", that would allow you understand which AWS service has made request. +In CloudTrail you can not only filter by event names on AWS KMS operations. There are other filter parameters that you can use. For example, you can use filtering by "**Event source**", that would allow you to understand which AWS service has made a request. The filter parameter "**User name**" allows you to filter by the identity of the user referenced in the event. Another useful parameter is the "**AWS Access Key**". With it, you can filter by the AWS access key ID that was used to sign the request. If the request was made with temporary credentials, the access key ID of the temporary credential is what will show up as the access key. @@ -95,7 +95,7 @@ Now just provide a name to the rule and hit "**Create Rule**". You have just created a rule that will help you audit AWS KMS usage. Everytime a Data Key is generated, you wil be notified in the email address you provided. If everything went well you should receive an email notifying you of the operation that took place. -**Note:** Don´t forget to hae confirmed your subcripution to SNS topic (you should have recevied an email). +**Note:** Don´t forget to hae confirmed your subscription to SNS topic (you should have recevied an email). We have established a notification for a specific operation. For a comprehensive list of the log entries that AWS KMS generates in AWS CloudTrail, please check the following [section of the AWS KMS documentation](https://docs.aws.amazon.com/kms/latest/developerguide/logging-using-cloudtrail.html). @@ -120,7 +120,7 @@ In this case, we only have a metric coming from AWS KMS so it should be easy for You can use the SNS topic that we created before: "**snsworkshop**". The process is well described in previous link, so it is not reproduced here in the workshop's instructions. -In case you need more details about building the alarm, please look into how to build an alarm from AWS KMS metrics in the followin [section of the AWS KMS documentation](https://docs.aws.amazon.com/kms/latest/developerguide/monitoring-cloudwatch.html#key-material-expiration-alarm). +In case you need more details about building the alarm, please look into how to build an alarm from AWS KMS metrics in the following [section of the AWS KMS documentation](https://docs.aws.amazon.com/kms/latest/developerguide/monitoring-cloudwatch.html#key-material-expiration-alarm). --- diff --git a/WebApp.py b/WebApp.py index 2639adb..c372f69 100644 --- a/WebApp.py +++ b/WebApp.py @@ -59,7 +59,7 @@ def do_HEAD(self): def do_POST(self): """Serve a POST request.""" r, info = self.deal_post_data() - print r, info, "by: ", self.client_address + print(r, info, "by: ", self.client_address) f = StringIO() f.write('') f.write("\nUpload Result Page\n") @@ -169,7 +169,9 @@ def send_head(self): pathsplit = path.split('/') s3path = pathsplit[-1] #remake the path without the 'S3' tag - path = pathsplit[0]+ '/' + pathsplit[1]+ '/' + pathsplit[2] + '/' +pathsplit[3]+ '/' + "localfile-"+pathsplit[-1] + #path = pathsplit[0]+ '/' + pathsplit[1]+ '/' + pathsplit[2] + '/' +pathsplit[3]+ '/' + "localfile-"+pathsplit[-1] + # Serve content from our CWD - not ideal, but simple + path = os.getcwd() + '/' + "localfile-"+pathsplit[-1] KEY = str(s3path) try: my_bucket.download_file(KEY, "localfile-"+KEY) diff --git a/WebAppEncSSE.py b/WebAppEncSSE.py index b87f9b3..564eb23 100644 --- a/WebAppEncSSE.py +++ b/WebAppEncSSE.py @@ -60,7 +60,7 @@ def do_HEAD(self): def do_POST(self): """Serve a POST request.""" r, info = self.deal_post_data() - print r, info, "by: ", self.client_address + print(r, info, "by: ", self.client_address) f = StringIO() f.write('') f.write("\nUpload Result Page\n") @@ -177,7 +177,9 @@ def send_head(self): pathsplit = path.split('/') s3path = pathsplit[-1] #remake the path without the 'S3' tag - path = pathsplit[0]+ '/' + pathsplit[1]+ '/' + pathsplit[2] + '/' +pathsplit[3]+ '/' + "localfile-"+pathsplit[-1] + #path = pathsplit[0]+ '/' + pathsplit[1]+ '/' + pathsplit[2] + '/' +pathsplit[3]+ '/' + "localfile-"+pathsplit[-1] + # Serve content from our CWD - not ideal, but simple + path = os.getcwd() + '/' + "localfile-"+pathsplit[-1] KEY = str(s3path) try: my_bucket.download_file(KEY, "localfile-"+KEY)