Skip to content

Corrected a few typos and changed the WebApp to derive its path for l… #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Corrected a few typos and changed the WebApp to derive its path for l… #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0898d41
Corrected a few typos and changed the WebApp to derive its path for l…
jasfohasufagusfa Mar 4, 2019
82c14af
Update Section-1-Operating-with-AWS-KMS.md
DanBerr Jun 2, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 23 additions & 24 deletions Section-1-Operating-with-AWS-KMS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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).


Expand Down Expand Up @@ -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:



Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -331,16 +331,16 @@ 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**".

![Figure-9](/res/S1F9%20KMSARole.png)
<**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)
Expand All @@ -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)

Expand Down Expand Up @@ -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**".

Expand Down Expand Up @@ -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.

Expand All @@ -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.
Expand All @@ -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.

---

Expand All @@ -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
Expand All @@ -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
{
Expand All @@ -494,17 +493,17 @@ $ 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**.

If for any reason you delete the key we generated with our own key material "**ImportedCMK**", later you would have to import again your key material into the CMK and into the same alias to get it back to an usable state.

## 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)


Loading