#AWS REST API

The issuer API can leverage AWS key management service to hook into the "cryptography as a service" or "encryption as a service" features provided by AWS. With that, the issuer API can sign and verify credentials whilst keeping the secrets (signing keys) in an external secure environment.

If you are new to AWS kms make sure to check out the guides here. The rest of this document assumes you already know how AWS KMS works, and you have it setup.

#Method : Using AWS access keys and secret keys

#Prerequisites

• AWS Account: You need an active AWS account. If you don't have one, create it at AWS Console.

#Create AWS Access Keys and Secret Keys

To securely interact with AWS services such as KMS, you need to configure your AWS access and secret keys. Here’s how to generate and configure these credentials:

1. Log in to your AWS Management Console.
2. Navigate to IAM (Identity and Access Management).
3. In the left sidebar, click on Users, then choose your username.
4. Go to the Security credentials tab.
5. Under Access keys, click Create access key.
6. Copy both the Access Key ID and Secret Access Key. Store them securely.

#Key generation

To create the key you can use the onboard endpoint provided by the issuer API and provide the necessary parameters to create the key in the AWS KMS service.

#Creation via Issuer API

curl -X 'POST' \
  'https://issuer.portal.walt-test.cloud/onboard/issuer' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": {
    "backend": "aws-rest-api",
    "keyType": "secp256r1",
    "config": {
       "auth": {
        "accessKeyId": "AKIAW......U2TQU5F",
        "secretAccessKey": "6YDrEN1t+......I3OCwSc7Sr",
        "region": "eu-central-1"
      }
    }
  },
  "did": {
    "method": "jwk"
  }
}'

{
  "key": {
    "backend": "aws-rest-api",
    "keyType": "secp256r1",
    "config": {
      "auth": {
        "accessKeyId": "AKIAW......U2TQU5F",
        "secretAccessKey": "6YDrEN1t+......I3OCwSc7Sr",
        "region": "eu-central-1"
      }
    }
  },
  "did": {
    "method": "jwk"
  }
}

#Key Usage

Once you have successfully created a key that is one of the supported types listed above, you can use it in sign and issue operations offered by the issuer API.

If you've already had a look at our /sign, /issue, /batchIssue endpoints, you have seen that they all follow a similar request body structure, where the key that should be used for signing credentials is provided via the issuerKey property. Now instead of providing the key as JWK, we provide a reference to a key stored in Vault with the required parameters and access credentials.

Below you can see an example of issuerKey object referencing a key stored in AWS.

{
  "issuerKey": {
    "type": "aws-rest-api",
    "config": {
      "auth": {
        "accessKeyId": "AKIAW......U2TQU5F",
        "secretAccessKey": "6YDrEN1t+......I3OCwSc7Sr",
        "region": "eu-central-1"
      }
    },
    "id": "324ebf67-6bcc-4439-8b81-260bf0a82532",
    "_publicKey": "{\"kty\":\"EC\",\"crv\":\"P-256\",\"x\":\"RfvJGDXOjz3NOSKgZ0VlijXST8S-j96DrG0C1AMNAK8\",\"y\":\"vSt2q7yIy0-AhAirMuuDmUScxkgf4JVfId-vTETraQA\"}",
    "_keyType": "secp256r1"
  },
  "issuerDid": "did:jwk:eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2IiwieCI6IlJmdkpHRFhPanozTk9TS2daMFZsaWpYU1Q4Uy1qOTZEckcwQzFBTU5BSzgiLCJ5IjoidlN0MnE3eUl5MC1BaEFpck11dURtVVNjeGtnZjRKVmZJZC12VEVUcmFRQSJ9"
}

#Method : Instance Authentication

#Prerequisites

• AWS Account: You need an active AWS account. If you don't have one, create it at AWS Console.

#Set Up an IAM Role for the EC2 Instance

To authenticate your instance with AWS, You can Set Up an IAM Role for the EC2 Instance in AWS Console by following the steps below:

1. Log in to your AWS Management Console.
2. Navigate to IAM (Identity and Access Management).
3. In the left sidebar, click on Roles.
4. Click on Create Role.
5. Select EC2 as the service that will use this role.
6. Click on Next: Permissions.
7. Attach the necessary permissions to the role.
8. Click on Next: Tags.
9. Add tags if necessary.
10. Click on Next: Review.
11. Enter a name for the role.
12. Click on Create Role.
13. Attach the role to the EC2 instance.
14. Navigate to the EC2 instance in the AWS Management Console.
15. Click on Actions > Security > Modify IAM Role.
16. Select the role you created.
17. Click on Save.
18. The EC2 instance is now authenticated with AWS.
19. You can now use the AWS SDK to interact with AWS services.

When you have set up the IAM role for the EC2 instance, you can use it to authenticate with AWS services.

#Key generation

To create the key you can use the onboard endpoint provided by the issuer API and provide the necessary parameters to create the key in the AWS KMS service.

#Creation via Issuer API

curl -X 'POST' \
  'https://issuer.portal.walt-test.cloud/onboard/issuer' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "key": {
    "backend": "aws-rest-api",
    "keyType": "secp256r1",
    "config": {
         "auth": {
          "roleName": "AccessRole",
          "region": "eu-central-1"
        }
    },
  },
  "did": {
    "method": "jwk"
  }
}'

{
  "key": {
    "backend": "aws-rest-api",
    "keyType": "secp256r1",
    "config": {
      "auth": {
        "roleName": "AccessRole",
        "region": "eu-central-1"
      }
    }
  },
  "did": {
    "method": "jwk"
  }
}

#Key Usage

Once you have successfully created a key that is one of the supported types listed above, you can use it in sign and issue operations offered by the issuer API.

If you've already had a look at our /sign, /issue, /batchIssue endpoints, you have seen that they all follow a similar request body structure, where the key that should be used for signing credentials is provided via the issuerKey property. Now instead of providing the key as JWK, we provide a reference to a key stored in Vault with the required parameters and access credentials.

Below you can see an example of issuerKey object referencing a key stored in AWS.

{
  "issuerKey": {
    "type": "aws-rest-api",
    "config": {
      "auth": {
        "roleName": "AccessRole",
        "region": "eu-central-1"
      }
    },
    "id": "324ebf67-6bcc-4439-8b81-260bf0a82532",
    "_publicKey": "{\"kty\":\"EC\",\"crv\":\"P-256\",\"x\":\"RfvJGDXOjz3NOSKgZ0VlijXST8S-j96DrG0C1AMNAK8\",\"y\":\"vSt2q7yIy0-AhAirMuuDmUScxkgf4JVfId-vTETraQA\"}",
    "_keyType": "secp256r1"
  },
  "issuerDid": "did:jwk:eyJrdHkiOiJFQyIsImNydiI6IlAtMjU2IiwieCI6IlJmdkpHRFhPanozTk9TS2daMFZsaWpYU1Q4Uy1qOTZEckcwQzFBTU5BSzgiLCJ5IjoidlN0MnE3eUl5MC1BaEFpck11dURtVVNjeGtnZjRKVmZJZC12VEVUcmFRQSJ9"
}