Enterprise Data Custody

Introduction

Nametag allows you to specify AWS S3 buckets which we will use to store data on your behalf. In this guide we will create S3 buckets in your AWS account for storing data and a role that authorizes Nametag to access those buckets.

Note: Enterprise data custody is managed on a per-environment basis. If you have multiple environments, you must configure each environment separately.

Once you have enabled this feature, all new data collected will be stored in your bucket, but existing data will not be migrated.

1. Create S3 buckets

You must create S3 buckets in your account for each Nametag region. The Nametag regions are:

AWS Region Nametag Region
us-east-2 us
eu-west-1 eu

Example: Create the buckets with the AWS CLI

aws s3api create-bucket \
	--region us-east-2 \
	--bucket "BUCKET-US" \
	--create-bucket-configuration "LocationConstraint=us-east-2" \
	--acl private
aws s3api create-bucket \
	--region eu-west-1 \
	--bucket "BUCKET-EU" \
	--create-bucket-configuration "LocationConstraint=eu-west-1" \
	--acl private

Note: You may with to apply your organizations logging, encryption and other access policies to these buckets. Applying those configurations is beyond the scope of this guide.

Note: Even if you do not intend to use Nametag in a particular region, you must create buckets in all the regions listed.

2. Create a cross-account role

Next, create a cross-account role that authorizes our AWS account limited access to your AWS account. Our AWS account ID is 464164016791. To improve security, we recommend that you restrict access to the role to only sessions there the ExternalID matches what we specify. Nametag sets an external ID of the form nametag-storage-ENV when assuming the role you specify.

You can find your ENV in the Nametag console under Configuration > OAuth > Client ID. (The ENV and OAuth 2.0 client ID are the same thing).

Note: Your role must be called NametagStorage because the AWS IAM policies in Nametag’s AWS account only allow our service to invoke sts:AssumeRole on roles named NametagStorage.

Example: Create a cross account role with the AWS CLI

aws iam create-role \
	--role-name NametagStorage \
	--assume-role-policy-document '{
            "Version": "2012-10-17",
            "Statement": [
                {
                    "Effect": "Allow",
                    "Principal": {
                        "AWS": "arn:aws:iam::464164016791:root"
                    },
                    "Action": "sts:AssumeRole",
                    "Condition": {
                        "StringEquals": {
                            "sts:ExternalId": "nametag-storage-ENV"
                        }
                    }
                }
            ]
        }'

3. Specify permissions for the cross account role

Next we will attach a policy that authorizes the role you created, and thus Nametag to access to your buckets. The following policies must be specified:

  • s3:PutObject and s3:PutObjectAcl to write data to the buckets.
  • s3:GetObject to read data from the buckets.
  • s3:DeleteObject to delete data from the buckets.
  • s3:ListBucket to confirm basic information about the bucket.
  • s3:GetBucketLocation to confirm the region of the bucket.

Example: Attaching a policy to the cross account role with the AWS CLI

aws iam put-role-policy \
	--role-name NametagStorage \
	--policy-name StorageAccess \
	--policy-document '{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadWrite",
      "Action": [
        "s3:PutObject",
        "s3:PutObjectAcl",
        "s3:GetObject",
        "s3:DeleteObject"
      ],
      "Effect": "Allow",
      "Resource": [
      	"arn:aws:s3:::BUCKET-US/*",
      	"arn:aws:s3:::BUCKET-EU/*"
      ]
    },
    {
      "Sid": "Bucket",
      "Action": [
        "s3:ListBucket",
        "s3:GetBucketLocation"
      ],
      "Effect": "Allow",
      "Resource": [
      	"arn:aws:s3:::BUCKET-US",
      	"arn:aws:s3:::BUCKET-EU"
      ]
    }
  ]
}'

3. Configure Nametag to use the buckets

The final step is to configure Nametag to use the buckets using the Nametag API. If you don’t have an API key, you can generate one from the Nametag console under Configure > API keys. It must have the Admin role

Example: Configure Nametag via the API

curl -u ":API_KEY" -X PATCH https://nametag.co/api/envs -d '{
  "storage": {
		"s3_bucket_us": "BUCKET-US",
		"s3_bucket_eu": "BUCKET-EU",
		"aws_role_arn": "arn:aws:iam::YOUR-AWS-ACCOUNT-ID:role/NametagStorage"
	}
}'

To disable enterprise data custody, set the storage field to an empty object:

Example: Disable enterprise data custody via the API

curl -u ":API_KEY" -X PATCH https://nametag.co/api/envs -d '{
  "storage": {}
}'

Internals

Nametag stores evidence we collect from end-users, as well as data derived from that evidence, in object storage. The kinds of data that are stored in object storage include:

  • Images of the user’s ID document.
  • Images of the user’s face.
  • Diagnostic and trace information about the scan process.
  • Redacted versions of the images.
  • Versions of the images at various scales.
  • Profile photos.

A typical ID scan wil generate 7 - 10 objects.

When storing an object, we generate a random path for the object, a random AES key, and a random nonce. The AES key and nonce are used to encrypt the object data in AES-GCM mode.