Skip to content

KMS

Jump to bottom
Debendra Oli edited this page Apr 11, 2024 · 9 revisions

Currently only aws kms is supported.

The kms is used to encrypt and decrypt the keystore files.

Currently the relay encrypts the keystore password and stores it in the keystore file. The relay decrypts the password from the keystore file and uses it to sign the messages.

The purpose of encrypting the password is to prevent the password from being exposed in the keystore file. This is to prevent the password from being exposed in case the keystore file is compromised. Also the ability to quickly change the password without having to change the keystore file.

Local KMS

The local kms is veru helpful for testing the relay without having to use the aws kms.

The primary use of local kms is recommended for testing the relay without having to use the aws kms.

The more information on the local kms can be found here.

AWS KMS

The relay uses the AWS credentials stored in the ~/.aws/credentials file. The relay uses the default profile to access the AWS credentials. The relay also needs the AWS region to be set in the ~/.aws/config file. The relay uses the default region to access the AWS region.

The aws credentials and region configuration are also accepted as environment variables and given preference over the configuration files. This behaviour is according to the AWS SDK for Go.

Prerequisites

  • AWS CLI: This is an essential tool used to interact with AWS services. To install AWS CLI on your system, refer to the AWS CLI Official Website.

  • Check if aws cli is configured correctly.

    aws sts get-caller-identity

    If the above command returns the account id, the aws cli is configured correctly.

Configuration

  1. Create a iam role for kms assuming the role from the ec2 instance that will be running the relay.

    kms-role-trust-policy.json

    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "ec2.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
    aws iam create-role --role-name centralized-relay-kms --assume-role-policy-document file://kms-role-trust-policy.json

  2. Create policy for kms access.

    Create kms-policy.json.

    {
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "kms:GetPublicKey",
                "kms:Decrypt",
                "kms:ListKeyPolicies",
                "kms:GetKeyPolicy",
                "kms:ListResourceTags",
                "kms:CreateCustomKeyStore",
                "kms:ReEncrypt*",
                "kms:TagResource",
                "kms:Encrypt",
                "kms:GetKeyRotationStatus",
                "kms:CreateAlias",
                "kms:DescribeKey",
                "kms:CreateKey",
                "kms:ConnectCustomKeyStore"
            ],
            "Resource": "*"
        }
    ]
}
    aws iam put-role-policy --role-name centralized-relay-kms --policy-name centralized-relay-kms --policy-document file://kms-policy.json

    Note the policy arn from the output of the above command.

  3. Attach the policy to the role created in step 1.

    aws iam attach-role-policy --role-name centralized-relay-kms --policy-arn <policy-arn>

  4. Create Instance profile.

    aws iam create-instance-profile --instance-profile-name centralized-relay-kms

  5. Add role to instance policy

    aws iam add-role-to-instance-profile --instance-profile-name centralized-relay-kms --role-name centralized-relay-kms

  6. Attach instance profile to the ec2 instance.

    Create an ec2 instance from aws console and note the instance id.

    aws ec2 associate-iam-instance-profile --instance-id <instance-id> --iam-instance-profile Name=centralized-relay-kms

  7. Create a kms key.

    centralized-relay keystore init

    This will create a kms key and store the key id in the config file kms-key-id field.

    verify using the following command.

    centralized-relay config show

Troubleshooting

  1. If you get the following error while running the relay.

    panic: failed to decrypt keystore: AccessDeniedException: User: arn:aws:sts::xxxxxxxxxxxx:assumed-role/centralized-relay-kms-role/i-xxxxxxxxxxxx is not authorized to perform: kms:Decrypt on resource: arn:aws:kms:us-east-1:xxxxxxxxxxxx:key/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

    This means that the role created in step 1 is not able to access the kms key created in step 4. To fix this, attach the kms policy created in step 2 to the role created in step 1.

    aws iam attach-role-policy --role-name centralized-relay-kms-role --policy-arn <policy-arn>

  2. If you get the following error while running the relay.

    panic: failed to decrypt keystore: InvalidCiphertextException: null

    This means that the kms key created in step 4 is not the same as the one stored in the config file. To fix this, run the following command.

    centralized-relay keystore init

  3. If you get the following error while running the relay.

    panic: failed to decrypt keystore: AccessDeniedException: User: arn:aws:sts::xxxxxxxxxxxx:assumed-role/centralized-relay-kms-role/i-xxxxxxxxxxxx is not authorized to perform: kms:CreateKey on resource: arn:aws:kms:us-east-1:xxxxxxxxxxxx:key/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

    This means that the role created in step 1 is not able to access the kms key created in step 4. To fix this, attach the kms policy created in step 2 to the role created in step 1.

    aws iam attach-role-policy --role-name centralized-relay-kms-role --policy-arn <policy-arn>

  4. If you get the host https://kms..amazonaws.com not found error.

    panic: failed to decrypt keystore: InvalidEndpointException: Unable to load credentials from service endpoint

    This means that the region is not detected correctly. To fix this, run the relayer command with the region environment variable.

    AWS_REGION=<region> centralized-relay keystore init
Clone this wiki locally